Designing Good Tools

The model reads your tool like a manual

A tool's name, description and parameter docs are the only things the model knows about it. Clear names, one purpose per tool, and descriptions that say when to use it (and when not) matter more than clever code. Return concise results with only the fields needed.

The agent's hands

Tools let an agent act. Good tool design and tight permissions decide how useful and how safe it is.

A tool definition

Note the specific description and the typed, documented parameter. A good error message tells the model how to retry.

{
  "name": "get_order_status",
  "description": "Look up the status of one order by its numeric ID. Use for questions about shipping or delivery. Does not modify orders.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "integer", "description": "The order ID, e.g. 10482" }
    },
    "required": ["order_id"]
  }
}

Errors are instructions

Return "order_id 99999 not found; ask the user to check the number" rather than a stack trace. The model reads the error and decides what to do next.

Quick check: What helps a model choose the right tool most?

• A short, clear description of what it does and when to use it
• A very long tool name
• Hidden side effects
• Returning huge outputs