Tool Calling Patterns for Reliable Agents

Design tools like APIs for a new teammate

The model only knows a tool through its name, description and parameter schema. Write them as you would document an API for a capable engineer who has never seen your system.

{
  "name": "run_readonly_sql",
  "description": "Run a read-only SQL query against the analytics warehouse. Use for counts, sums and lookups. Returns at most 200 rows. Never use for DDL or writes.",
  "input_schema": {
    "type": "object",
    "properties": {
      "sql": { "type": "string", "description": "A single SELECT statement." },
      "reason": { "type": "string", "description": "One sentence: what question this query answers." }
    },
    "required": ["sql", "reason"]
  }
}

Patterns that improve reliability

• Few, well-scoped tools beat many overlapping ones
• Return errors as data, with a hint: {"error": "column 'amt' not found; available: amount, status"} — the model can recover
• Bound outputs (row limits, truncation notes) so results fit in context
• Validate inputs server-side — never trust the model to respect the schema alone
• Make side effects explicit — separate preview_change from apply_change, and require approval for the second

Multi-step structure

Operate it like software

Log every tool call with inputs, outputs, latency and cost. Build an evaluation set of tasks with expected outcomes, and re-run it whenever you change prompts, tools or models.