Designing Tool Schemas Agents Can Use Reliably

Tool schemas are where an agent’s intentions meet a real system. A vague tool description can turn a reasonable request into a bad API call; a careful schema gives the agent a narrow path it can follow.

Name the action like a person would

Use a specific verb and object: find_order_status is easier to select than manage_orders. Describe what the tool does, what it does not do, and whether it reads data or changes it.

Keep one business action per tool. Combining search, update, and notification in one function makes it hard to reason about permissions, confirmations, retries, and audit logs.

Make inputs hard to misunderstand

• Use strict types and enums for values with a known set.
• Mark required fields clearly and explain the format of dates, identifiers, and amounts.
• Prefer named objects over a single free-form string.
• Put validation rules next to the field that needs them.
• Return structured results with stable field names and explicit empty states.

If a tool needs an order number, do not let a model substitute a customer name and hope the backend sorts it out. Fail early with an error that tells the agent what information is missing.

Design for approval and retries

Tell the caller whether the action is reversible, idempotent, or destructive. A tool that sends a message or changes a booking should expose a preview or confirmation step. A retried request should not create two refunds or two appointments.

Keep side effects behind a separate action where possible. Searching for a draft and submitting the draft are different moments with different risk. That separation also makes human review much easier.

Return useful failure

“Request failed” is not useful to an agent or a person. Return a safe error category such as missing permission, invalid input, temporary outage, or business rule. Include a next step when one exists, but never leak secrets or internal stack traces.

Test the schema with normal requests, incomplete requests, malicious values, duplicate calls, and stale records. The goal is not to make the model clever enough to overcome a weak tool. The goal is to make the safe path the easiest path.