Deep-Dives / Tool & Capability Design
Tool & Capability Design
Designing tools an agent can actually use — granularity, schemas, error messages, recovery, antipatterns.
- Designing Tools Agents Can UseTools are the agent's entire API: design for a model that reads only the description and is confidently wrong, not for an engineer who read the source.
- Tool Granularity & CompositionCoarse tools hide decisions and concentrate blast radius, fine tools multiply round-trips and bloat the list — and tool explosion is now a measured ~24-point selection-accuracy loss.
- Schemas, Contracts & DefaultsThe schema is the instruction set: make illegal states unrepresentable, make safety-relevant fields required, and let the path of least specification be the path of least harm.
- Error Messages as PromptsA tool error is a just-in-time prompt: name the cause, echo the bad value, prescribe the corrected call, and say retryable-or-terminal — or breed a runaway retry loop.
- Tool Docs & DiscoverabilityClaude Code defers MCP tool definitions by default, and the search that has to match your tool reads only the first 4,096 characters even though a deferred description may run to 16,384 — so the description is two documents with two different readers. Put the domain nouns and the boundary against the nearest neighbour first, the worked invocation after, and treat alwaysLoad as the decision that actually matters.
- Tool-Design Anti-PatternsThe four that sink most agents — kitchen-sink tool, stringly-typed args, silent failure, leaky abstraction — each spotted in a minute, each with a trace signature and a mechanical fix.
- Tool Calling Vendor Matrix (2026)OpenAI (Chat Completions vs Responses API, parallel_tool_calls, custom tools with Lark/regex grammar) vs Anthropic (Programmatic Tool Calling, Tool Search Tool, Tool Use Examples) vs Gemini (OpenAPI subset, tool_choice any, multimodal function responses).
- Advanced Tool OrchestrationAnthropic Tool Search Tool (85% token reduction); Programmatic Tool Calling (Claude writes Python in a sandbox that calls tools, only final results enter context); Tool Use Examples.
- Structured Outputs vs Tool CallsTwo ways to constrain the model — same constrained decoding underneath, different ergonomics. Anthropic's native structured outputs GA in 2026; when to use each.
- JSON Schema Subsets per VendorWhat's actually enforceable per vendor — no minLength/maxLength/minimum/maximum on Anthropic; OpenAPI subset on Gemini; strict mode requires additionalProperties:false + all required on OpenAI.
- Streaming Tool Calls in PracticePer-vendor delta accumulation, the OpenAI GPT-4.1-nano duplicate-call bug, Gemini aggregatable arguments, Anthropic streaming with parallel calls.
- Code as ActionHaving the model write code that calls tools took one reported workflow from 150,000 tokens to 2,000 by keeping intermediate data out of context — and the thing it spends is the action log, because policy enforcement, approval gates and audit all key on tool calls that a program never emits.
- Shaping Tool ResultsA tool definition costs a few hundred tokens once per turn; one unshaped result costs forty thousand and is re-sent on every turn after — and it is also the largest untrusted text block in the window. Project, rank-then-truncate, paginate, hand back a handle; one envelope and one harness-enforced ceiling for every tool.
- Skills vs Subagents vs MCP vs Hooks: Which to UseHook for what must happen every time, MCP to reach a system, skill for know-how, subagent to keep noisy work out of context, instruction file for what every turn needs; a plugin only ships them. The deciding axis is who pulls the trigger, not context cost.
- Tool Annotations Are Hints, Not GatesMCP's four hints default pessimistically — readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true — while the spec says to treat them as untrusted unless the server is. Put those together and the honest server that ships no annotations gets a confirmation dialog on every call while the one asserting readOnlyHint runs silently, so the interface rewards assertion. Build the risk class client-side keyed on (endpoint, package digest, tool name), pin it at install, and demote the hint to a pre-fill plus a drift alarm — including in the retry policy, where a wrong idempotentHint sends the message twice.