# Tool Calling Patterns for Reliable Agents

> Designing tool schemas, handling errors, and structuring multi-step and multi-agent work so agents stay predictable.

- Source: https://akshaythakare.com/notes/agentic-ai/tool-calling-patterns
- Topic: Agentic AI
- Level: intermediate
- Reading time: 2 min
- Tags: agentic-ai, tool-calling, design
- Updated: 2026-10-11

## 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.

```json
{
  "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

| Pattern | Idea |
| --- | --- |
| ReAct-style loop | Interleave reasoning and tool calls until done |
| Plan then execute | Draft a plan, then run steps; re-plan on surprises |
| Orchestrator–workers | A lead agent delegates focused sub-tasks to sub-agents and merges results |
| Evaluator–optimizer | One model drafts, another critiques against criteria, repeat |

## 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.