Agentic AI Wiki
Deep-Dives / Tool & Capability Design

Tool & Capability Design

Designing tools an agent can actually use — granularity, schemas, error messages, recovery, antipatterns.

  1. Designing Tools Agents Can Use
    Tools 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.
  2. Tool Granularity & Composition
    Coarse 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.
  3. Schemas, Contracts & Defaults
    The 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.
  4. Error Messages as Prompts
    A 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.
  5. Tool Docs & Discoverability
    Selection is text-only retrieval over names and descriptions: namespace by service, say when-and-when-not, show one example — and remember discoverability is inversely related to inventory.
  6. Tool-Design Anti-Patterns
    The 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.
  7. 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).
  8. Advanced Tool Orchestration
    Anthropic 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.
  9. Structured Outputs vs Tool Calls
    Two ways to constrain the model — same constrained decoding underneath, different ergonomics. Anthropic's native structured outputs GA in 2026; when to use each.
  10. JSON Schema Subsets per Vendor
    What'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.
  11. Streaming Tool Calls in Practice
    Per-vendor delta accumulation, the OpenAI GPT-4.1-nano duplicate-call bug, Gemini aggregatable arguments, Anthropic streaming with parallel calls.
  12. Code as Action
    Having 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.