Design around outcomes, not tables
'Convert this appointment into a job' is a tool. 'Insert a row into jobs' is not — it leaves the model responsible for the six other things that must happen alongside it.
Every step you leave out of the tool becomes a step the model has to guess at.
Rules for arguments
- Prefer canonical identifiers over names the model might mis-transcribe.
- Keep required arguments few; make optional behaviour explicit.
- Use enums for anything with a fixed set of valid values.
- Never accept a raw query or filter string from the model.
- Validate on the server even though the schema already constrains it.
Make failure informative
A tool that returns an empty result on failure will be retried blindly. A tool that returns a typed error — not found, not permitted, missing prerequisite — lets the model correct itself or stop and ask.
Include what was missing and what would make the call succeed.
Idempotency and retries
Network calls fail and agents retry. If a retry can create a second invoice, the tool is unsafe.
The usual fix is a reservation step: the first call reserves an operation key, the second finalises it, and a repeat of either is a no-op that returns the original result.
Gate the dangerous ones
Sending, signing, charging and deleting deserve a preview-then-confirm pattern. The preview describes the exact effect; the confirmation token authorises only that effect and expires quickly.