Design agent tools for reliable calls and reviewable results
An agent tool is a small API contract inside a larger, uncertain loop. The model has to decide when to call it, supply valid arguments, read the result, and choose what to do next. A tool that is convenient for a human operator can still be difficult for an agent to use safely if its name is vague, its input mixes unrelated actions, or its response hides the evidence needed for the next step.
Good tool design reduces unnecessary model judgment. It makes the safe action clear, gives the agent a narrow result it can use, and keeps consequential operations behind explicit boundaries.
Give one tool one stable job
Start with a verb and an object that describe one operation. get_order, search_documents, and create_draft_invoice tell the agent more than handle_order. A catch-all tool with an action parameter often becomes a private protocol: the model must remember which combinations are valid and how each branch returns errors.
Split actions when their authority or output differs. Reading an account, changing its plan, and issuing a refund should not be three modes of the same tool merely because they use an account ID. Separate names make policy, logging, approval, and evaluation easier.
Anthropic's tool-use guidance recommends clear names and descriptions, well-defined parameters, and responses that give the model the information it needs. MCP follows the same direction: a tool has a name, description, input schema, and result. The schema is part of the product surface, not implementation detail.
Keep input schemas small and typed
Require only the arguments needed for the operation. Prefer enums, bounded numbers, and explicit object shapes over a single free-form options string. Tell the agent which identifier is expected and where it came from.
{
"name": "get_deployment",
"description": "Return the current status and recent events for one non-production deployment.",
"input_schema": {
"type": "object",
"properties": {
"deployment_id": {
"type": "string",
"description": "ID returned by create_preview_deployment."
}
},
"required": ["deployment_id"],
"additionalProperties": false
}
}
The description names both a boundary and an input provenance rule. It tells the model not to guess an ID and prevents a caller from slipping in undeclared fields. If a parameter has a business constraint, state it in the schema or tool description instead of hoping the system prompt carries it through every turn.
Do not ask a tool to parse a whole user request when the model can extract a typed argument first. Text-to-SQL, shell commands, and filter languages have their place, but they need a constrained grammar, scoped credentials, and careful review. A raw query field is not a substitute for an API design.
Return the next useful fact
A tool result should answer the question that led to the call and include a durable handle for deeper evidence. A search tool can return a compact list of titles, IDs, and short excerpts. A follow-up get_document tool can retrieve the full content only when the agent needs it. That pattern keeps context focused and gives logs a clean trail of why more data was fetched.
Use stable identifiers and machine-readable fields alongside a short human-readable summary. Avoid returning a large HTML page, an entire database row, or a stack trace when a status, error code, and reference are enough. The context-budget guide explains why raw tool output should not remain in an agent's working set after its decision is recorded.
Make errors actionable. NOT_FOUND plus the requested ID is better than "request failed." A validation error should identify the field and expected format. A permission error should say the operation was denied without revealing sensitive policy data. Do not turn every exception into a successful-looking text response; the application needs a reliable failure signal.
Keep writes deliberate and reversible
Read tools can usually be easy to call. Write tools need more structure. A safe flow separates preparation from commitment:
create_invoice_draftreturns a draft ID and calculated totals.get_invoice_draftlets the agent inspect that draft.submit_invoicerequires the draft ID and an explicit confirmation value.
The exact confirmation mechanism depends on the host, but the boundary should be visible in the tool contract. Keep irreversible effects, external messages, purchases, deployments, and credential changes behind approval or a separate commit action. The least-privilege checklist covers the permission layer; a deliberate tool sequence makes that layer easier to apply.
Idempotency matters too. If a client retries after a timeout, a create operation should not silently create two records. Accept an idempotency key or return a durable operation ID that a status tool can query. Record who initiated the operation and which arguments were accepted.
Test the contract with real tasks
Tool quality is visible in agent trajectories. Build a small test set where the agent must choose the right tool, handle an empty result, recover from a validation error, and stop before a restricted write. The coding-agent evaluation guide describes how to grade the whole run, not only a final sentence.
Review traces for predictable problems: calls with invented IDs, repeated calls that return the same error, overbroad searches, argument fields the model ignores, and large results that crowd out the next action. Fix the contract before adding more prompt text. A clearer tool name or smaller result often removes a failure mode that a longer instruction only masks.
For a model comparison, hold the tool schema, permissions, fixtures, and task constant. ISH chat can compare the conversational side, while the ISH API dashboard supports repeatable API tests. The comparison should measure how models use the same interface, not how much hidden context one client supplied.
