Designing Foolproof Tool Schemas

Tools are the hands and eyes of an agent. If your tool definitions are ambiguous, the agent will guess or hallucinate arguments. Great tool definitions rely on strict JSON schema specifications with concise field descriptions and enum constraints.

Three Rules for Tool Definitions

• Atomic responsibility: One tool should do one thing well. Prefer `search_docs` and `fetch_doc_by_id` over a massive `do_everything_with_docs` tool.
• Explicit constraints: If a date must be ISO-8601, state 'ISO-8601 string (e.g. 2026-09-18)' directly in the parameter description.
• Typed errors: When an API fails, return a clear, diagnostic string (e.g. 'Error: User ID 404 not found') rather than throwing an unhandled exception.

{
  "name": "calculate_tax",
  "description": "Calculates total sales tax given a subtotal in cents and a 2-letter state code.",
  "parameters": {
    "type": "object",
    "properties": {
      "subtotalCents": { "type": "integer", "minimum": 0 },
      "state": { "type": "string", "pattern": "^[A-Z]{2}$" }
    },
    "required": ["subtotalCents", "state"]
  }
}