Practical guide · Agent engineering
How to design tools for AI agents
A reliable agent tool gives the model one clear operation, accepts a small set of typed arguments, enforces identity and permissions in code, and returns enough structured evidence for the next decision. Treat the schema as a public interface for an imperfect caller. Make invalid states hard to express, side effects safe to retry, and failures explicit.
Published November 20, 2026 · 6 minute read
The short answer
Start with a user job and expose the smallest operation that completes it. Give the tool a distinct verb, say when to use it and when to avoid it, constrain every argument with types and enums, validate again on the server, and return a compact result with stable identifiers and an explicit status. Keep authorization, approval, rate limits, and idempotency outside the model. Test whether the agent chooses the right tool, supplies valid arguments, handles tool errors, and reaches the correct final state.
Start with the operation, not the API
An internal API often exposes implementation details that make sense to its original callers. An agent needs a task-oriented boundary. A generic request(method, path, body) tool forces the model to rediscover routes, payloads, and permissions. A tool such as get_order_status(order_id) names one job and gives the harness one place to enforce policy.
OpenAI's function-calling guide recommends predictable functions, enums that prevent invalid states, detailed parameter descriptions, and code-owned values when the application already knows an argument. It also suggests keeping the initially active tool set small and measuring selection accuracy as the set grows.
| Design question | Prefer | Avoid |
|---|---|---|
| Operation | One user-visible job | A generic API or SQL escape hatch |
| Inputs | Typed fields and bounded enums | Free-form strings that encode several choices |
| Known context | Inject identity and selected record in code | Ask the model to repeat trusted IDs |
| Side effects | Idempotency key and approval policy | Retrying an untracked write |
| Results | Stable status, identifiers, and next actions | Raw backend responses or full database rows |
| Failure | Typed, retryable, and terminal errors | A successful-looking text message |
A worked tool schema
This read-only order tool has one required identifier and a constrained detail level. The application derives the tenant and user from authenticated session state. The model never chooses either security boundary.
{
"type": "function",
"name": "get_order_status",
"description": "Get the current status of one order the signed-in customer may view. Use this for delivery or fulfilment questions. Do not use it to cancel, refund, or edit an order.",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"pattern": "^ord_[a-zA-Z0-9]+$",
"description": "The stable order ID shown to the customer, for example ord_7K2P."
},
"detail": {
"type": "string",
"enum": ["summary", "shipment_events"],
"description": "Use summary unless the customer asks for tracking history."
}
},
"required": ["order_id", "detail"],
"additionalProperties": false
},
"strict": true
}
Anthropic's tool-definition guide puts particular weight on descriptions that explain purpose, selection conditions, parameter effects, and limitations. It recommends input examples for complex or format-sensitive schemas, meaningful namespacing, and concise high-signal results.
Write descriptions for selection
A useful description answers four questions: what the tool does, the evidence that should trigger it, nearby requests it must not handle, and what the result means. Those distinctions matter most when two tools overlap. If search_orders finds an ID and get_order_status reads one known order, say that directly in both descriptions.
- Use action names that remain distinct when shown without the description.
- Describe formats beside each parameter instead of relying on examples elsewhere in the prompt.
- Use enums for closed choices and separate booleans only when every combination is valid.
- Split tools when operations have different permissions, approval rules, or failure behavior.
- Combine operations that always happen together and cannot produce a useful intermediate result.
Gemini's function-calling documentation gives similar guidance: specific names and descriptions, strong types, an active set around 10 to 20 tools, server-side validation, error handling, and appropriate authentication.
Design the result as carefully as the input
Return the fields needed for the next decision and leave out internal payload noise. A stable result for the example might include status, order_id, fulfilment_state, estimated_delivery_on, and a list of shipment events. Add a machine-readable error code, a retryable flag, and a safe message when execution fails.
Keep untrusted tool content marked as data. Retrieved pages, emails, documents, and third-party API text can contain instructions aimed at the model. The harness should preserve provenance, cap result size, strip fields the task does not need, and prevent tool output from changing system policy or permissions.
Put write safety in the harness
The server must authenticate the caller, resolve tenant scope, authorize the target, validate the schema, apply business rules, and record the outcome. A valid model-generated call is still only a request. It does not prove that the user may perform the action.
For writes, assign a stable operation ID before execution and pass it as an idempotency key where possible. Persist the downstream receipt. A timeout after the remote service accepts the call is an unknown outcome, so a blind retry can duplicate a message, refund, booking, or deployment. Consequential calls should use the AI agent approval-gate workflow and bind the decision to the exact normalized arguments.
Test selection before production
Create cases for direct requests, ambiguous wording, missing arguments, invalid IDs, overlapping tools, requests that need no tool, unauthorized targets, tool timeouts, partial failures, and repeated writes. Score the final state first, then tool selection, argument validity, retries, latency, cost, and policy compliance.
- Run each case against the smallest useful tool set and record a baseline.
- Add nearby tools one at a time to expose selection collisions.
- Change descriptions without changing implementations, then compare matched trials.
- Inject each declared error and verify that the agent retries only retryable failures.
- Inspect traces for calls that succeeded technically but did not complete the user's task.
- Add every production failure to the agent test-set workflow.
Tool-design checklist
- One distinct user job has one clear operation.
- The name, selection conditions, exclusions, inputs, and result are documented.
- Types, enums, required fields, patterns, and object boundaries reject invalid states.
- Trusted identity, tenant, and selected-record context come from application state.
- The server revalidates arguments, authorization, and business rules.
- Results are compact, structured, provenance-aware, and bounded.
- Writes have approval policy, atomic execution, idempotency, and receipts.
- Selection, no-tool, error, adversarial, and repeated-write cases run in evals.