Tool Use & Function Calling

Tool Schema Is a Prompt: Description Matters 10× More Than Name

Background & Principles

How does a tool definition actually enter the model? Anthropic's Tool Use Overview spells it out: every registered tool is serialized into a structured text block appended to the system prompt. From the model's perspective, tools=[...] is not a "function registry" — it's a document it must read and understand. From that document, the model must decide: when to call, which one to call, what arguments, and when not to call.

That explains several frequently observed effects:

• Expanding description from one line to five lifts accuracy materially — you're handing the model not just a name, but use cases.
• Each parameter's own description (not its name) clarifying units, formats, and edges helps more than renaming start_date → start_date_iso8601. The model reads descriptions; it doesn't really "read" snake_case names.
• Adding "when to pick this value" notes on enum entries beats a bare ["fast","accurate","creative"] by 2–3× selection accuracy.

Mechanism: once the tools block is in KV cache, every generated token attends back to that text. The more specific and scenario-grounded the description, the more conditioning the model has at the two key decisions — "should I call?" and "which one?". This isn't magic; it's a physical property of attention.

Hands-on Example

Same weather tool, two ways of writing it — and a wildly different hit rate:

# —— BAD: schema treated as a function signature ——
{
  "name": "get_weather",
  "description": "Get weather",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {"type":"string"},
      "unit":     {"type":"string", "enum":["c","f"]}
    }
  }
}

# —— GOOD: schema treated as prompt ——
{
  "name": "get_weather",
  "description": "Look up the CURRENT weather (now ± 1h) for a single city.
    Use ONLY for present-time questions like 'is it raining in Tokyo now'.
    DO NOT use for: forecasts >24h ahead (use get_forecast), historical
    weather (use get_weather_history), or air quality (use get_aqi).",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name in English, optionally followed by
          country, e.g. 'Tokyo', 'Paris, FR'. Do not pass GPS coords."
      },
      "unit": {
        "type": "string", "enum": ["celsius","fahrenheit"],
        "description": "Temperature unit. Default to celsius unless the user
          explicitly mentions °F or asks in a US locale context."
      }
    },
    "required": ["location"]
  }
}

Three upgrades that matter: (1) description states use cases + counter-examples (DO NOT use for…) — the cheapest fix for cross-tool mis-selection; (2) every parameter has its own description with format, constraints, and default inference rules; (3) enum values are full names (celsius not c) — readability = model comprehension. Treat these three as a checklist and run every tool through it.

More Tools Make Models Dumber: The Real Selection-Collapse Curve

Background & Principles

A commonly ignored engineering fact: tool count and accuracy are not monotonic — they form an inverted U. Zero tools: nothing to do. 3–7 orthogonal tools: peak agent performance. 20+ tools: the model gets confused, mis-selects, skips the right call, and uses wrong arguments. The Berkeley Function Calling Leaderboard (BFCL) multi-turn scenarios show this curve; Anthropic's Building Effective Agents says it explicitly: "Tool definitions deserve as much prompt engineering attention as your main prompt."

Why the collapse? Three real reasons:

• Token budget: each tool definition is ~100–300 tokens. 20 tools = 4–6K tokens in system prompt — squeezes context and pollutes attention.
• Semantic confusion: more tools = inevitable semantic near-duplicates (search_docs / find_in_docs / lookup_documentation); the model oscillates.
• Decision path explosion: N tools means N counter-examples ("don't call") for attention to track. Capacity gets spread thin and every decision is shakier.

That's also why Claude Code's core tool registry has only ~10 atomic tools (Read / Edit / Write / Bash / Grep / Glob / Task / WebFetch / WebSearch / TodoWrite) — anything else attaches on demand via MCP, never resident.

Hands-on Example

If your MCP / agent has already stacked 30+ tools, apply the 3-step "tool diet":

# Step 1: rank by call frequency, look at the long tail
sqlite3 agent.db "SELECT tool_name, COUNT(*) c FROM tool_calls 
  GROUP BY tool_name ORDER BY c DESC;"
#  Long-tail tools (< 1% of calls) can almost always be deleted or merged

# Step 2: find semantic twins and merge
#  search_files / find_files / list_matching → merge into search_files(pattern, mode)

# Step 3: split by scenario, not by API
#  BAD:  get_user_by_id / get_user_by_email / get_user_by_username
#  GOOD: get_user(query: {id?|email?|username?})  ← one tool, self-describing input

One counter-intuitive trick: dynamic tool surfaces. Cursor and Claude Code expose different tool sets in different modes — plan mode physically hides Write/Edit, so the model never has to distribute selection pressure across read vs. write. You can do the same: switch the registered tool set in your harness by task type — research tasks get web/fetch, coding tasks get read/edit/bash.

Atomic vs Composite: Tool Granularity Determines Reliability

Background & Principles

Handing an agent edit_file(path, old, new) is a different worldview from handing it refactor_function(path, fn_name, new_impl). The first is an atomic tool — the model composes; the second is a composite / macro tool — a single call performs multi-step business logic. This is the most important and most overlooked trade-off in tool design:

• Atomic tools: highly composable, reusable, cover unknown tasks; but the model has to plan multiple steps, leans hard on reasoning, and failure modes diversify.
• Composite tools: one call finishes the business flow — high reliability, easy to eval; but the codebase grows, coverage narrows, every new task wants a new tool.

Claude Code chose the atomic-leaning path: Read / Edit / Write / Bash — Unix-philosophy small tools, with composition done by the model. This lets it handle any coding task but demands strong planning capability — which is why it underperforms on weaker models. Traditional RPA goes composite-heavy: a dedicated tool per process (process_invoice / onboard_employee) — reliable but brittle, every new process requires new code.

In real engineering the two should coexist in layers: atomic tools at the bottom for "exploration / debugging / one-off tasks", composite tools on top for "high-frequency / reliability-sensitive / well-understood tasks".

Hands-on Example

Real scenario: an agent cutting a release on a git repo. Atomic vs. composite:

# —— Atomic path: 4 low-level tools, model composes ——
tools = [run_bash, read_file, write_file, git_command]
#  agent must plan: bump version → update changelog → commit → tag → push
#  Pro: if the plan needs to change (run tests before bump), agent adapts. Works on new repos.
#  Con: 1–2 out of 10 runs: wrong order / missing tag / committed to wrong branch

# —— Composite path: one macro tool ——
tools = [{
  "name": "release",
  "description": "Run the full release flow: bump version, regenerate
    CHANGELOG, commit with 'chore: release vX.Y.Z', tag, push branch+tag.
    Aborts on any failing step. Use when user asks to 'cut a release' or
    'publish a new version'. Does NOT publish to npm—call npm_publish after.",
  "input_schema": {"type":"object",
    "properties":{"bump":{"type":"string","enum":["patch","minor","major"]}},
    "required":["bump"]}
}]
#  Pro: 100 runs, same flow. Easy to eval.
#  Con: doesn't transfer to a different repo. Agent can't adapt to exceptions.

Decision tree in practice:

1. Task runs ≥ 5 times/day with stable steps → write a composite tool, freeze domain knowledge into code.
2. Task is occasional and varies each time → atomic tools, let the model compose.
3. Task is on a critical path with no error tolerance (production deploy, payments) → composite + strong schema validation + double-confirm.
4. Task is exploratory / debug → atomic, maximize flexibility.

Parallel Tool Calls: The Most Wasted Free Lunch

Background & Principles

Since Sonnet 3.5, Claude can return multiple tool_use blocks in a single assistant turn; OpenAI's GPT-4o / o3 do the same. The harness just needs to recognize multiple tool_uses, execute them concurrently, and concatenate the tool_results into the next turn. The dividend is massive:

• Read 5 files and summarize: serial = 5 × (LLM RTT + tool latency); parallel = 1 × (LLM RTT + max(tool latency)).
• Three independent API lookups (weather + flights + hotels) cut wall-clock by 2/3.
• On expensive models (Opus 4.7) it pays double — each saved turn skips a multi-thousand-token prefill.

But four engineering preconditions actually need to hold; miss one and it silently degrades to serial:

1. System prompt explicitly encourages it: the model defaults conservative — without "prefer parallel", it'll call sequentially. Claude Code's system prompt literally says "make all of the independent calls in the same response".
2. Tools must be independent: the model can only parallelize independent work. Parallelizing read + edit is wrong — edit depends on read.
3. Harness actually concurrent: many harnesses hardcode a for loop over tool_uses. The model emitted them in parallel; the runtime serialized them. Switch to asyncio.gather / a thread pool.
4. Permission gate is non-blocking: if every tool needs human approval, "parallel" becomes serial dialog. Auto-allow obviously-safe tools.

Hands-on Example

Upgrade the §3 atomic harness to concurrent execution:

import asyncio, anthropic
client = anthropic.AsyncAnthropic()

async def dispatch(block):                              # a single tool, async
    handler = TOOLS[block.name]["handler_async"]
    try:
        out = await handler(block.input)
    except Exception as e:
        out = f"ERROR: {type(e).__name__}: {e}"
    return {"type":"tool_result", "tool_use_id":block.id, "content":str(out)}

async def agent(task, max_iters=20):
    msgs = [{"role":"user","content":task}]
    sys  = ("You are a careful agent. "
            "IMPORTANT: when multiple tool calls are independent, "     # ← key line
            "emit them in the SAME response so they run in parallel.")
    for _ in range(max_iters):
        r = await client.messages.create(model=MODEL, system=sys,
                tools=SCHEMAS, messages=msgs, max_tokens=4096)
        msgs.append({"role":"assistant", "content":r.content})
        if r.stop_reason == "end_turn": return r
        uses = [b for b in r.content if b.type == "tool_use"]
        results = await asyncio.gather(*[dispatch(b) for b in uses])  # ← concurrent
        msgs.append({"role":"user", "content": results})

Measured: ask the agent "read README.md / package.json / .github/workflows/ci.yml and tell me what kind of project this is" — serial ~9s, parallel ~3.5s, with effectively no accuracy delta. The gap widens with more files.