Fable Brain

Writing Effective Tools for Agents

5 min read

Writing Effective Tools for Agents

Anthropic’s tool-design doctrine is to ship a few consolidated, workflow-shaped tools with evaluated descriptions and token-efficient responses, not one thin wrapper per API endpoint.

What it is

  • The September 2025 engineering post on writing tools for agents is Anthropic’s canonical tool-design guidance; its thesis is “Agents are only as effective as the tools we give them” (https://www.anthropic.com/engineering/writing-tools-for-agents).
  • It sits inside a wider doctrine. Building Effective Agents (2024-12-19) separates workflows, where LLMs and tools follow predefined code paths, from agents, where the model dynamically directs its own process and tool usage.
  • The context engineering post (2025-09-29) treats every tool response as spend from a finite attention budget and targets “the smallest possible set of high-signal tokens” (https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
  • The Claude Agent SDK exposes the same tools, agent loop, and context management that power Claude Code as Python and TypeScript libraries, so this guidance applies directly to SDK-built agents.

How it works

  • Consolidate. Build a small set of workflow-targeted tools rather than wrapping every API endpoint one to one.
  • Namespace. Group related tools under shared prefixes so agents can tell overlapping services apart.
  • Shape responses. Return high-signal, token-efficient payloads, because verbose output competes with everything else in the window for attention.
  • Evaluate descriptions. Treat names and descriptions as prompts, and refine them through evaluation runs rather than intuition.
  • Anchor tools in the agent loop of gather context, take action, verify work; verification via rules-based feedback, visual checks, or LLM-as-judge is the lever that makes agents reliable.
  • Prefer agentic search first. Start context-gathering with transparent bash-style tools such as grep before layering on semantic search, because it is more transparent and maintainable.
  • Production illustration from the claude.ai capture: the harness defines 24 inline tools in JSONSchema format, spanning computer use, retrieval, consumer widgets, MCP plumbing, memory edits, and visualization (System Prompt Export 2026-07, L1711-3392).
  • The capture defers rarely needed suites. Google Calendar (8 tools), Google Drive (8), and Gmail (12) are listed by name only, and “ALL tools listed below are deferred” (System Prompt Export 2026-07, L3238-3283).
  • Descriptions carry routing hints: fetch_sports_data states “PREFER using this tool over web search for data, scores, stats” (System Prompt Export 2026-07, L1882-1884).
  • Descriptions carry turn semantics: ask_user_input_v0 states “After calling this, your turn is done” (System Prompt Export 2026-07, L1713-1738).
  • Tools can gate each other: suggest_connectors may only run after a prior search_mcp_registry call or an auth error (System Prompt Export 2026-07, L2940-2957).

Best practice

  • Start with direct LLM API calls and add tools or agentic complexity only when it demonstrably improves outcomes. EVIDENCE-BASED
  • Build a few consolidated, workflow-targeted tools instead of wrapping every endpoint. EVIDENCE-BASED
  • Namespace related tools so agents distinguish overlapping services. EVIDENCE-BASED
  • Return high-signal, token-efficient responses and strip boilerplate from payloads. EVIDENCE-BASED
  • Refine tool names and descriptions through evaluation with agents in the loop. EVIDENCE-BASED
  • Give context-gathering agents agentic search, grep-like bash tools, before semantic search. EVIDENCE-BASED
  • Defer large or rarely used tool suites behind a loader such as tool_search, as the claude.ai harness does with Google Workspace. EVIDENCE-BASED
  • Encode turn-ending, gating, and routing behavior directly in the tool description, mirroring the export’s widget tools. PRACTITIONER

Pitfalls

  • One-to-one endpoint wrappers produce overlapping, ambiguous tools that agents misroute between.
  • Verbose tool responses burn the attention budget; accuracy and recall degrade as token count grows.
  • Framework abstractions that obscure prompts and tool definitions hinder debugging; Anthropic’s first principle for agent builders is simplicity.
  • Calling a deferred tool without loading its schema first fails, per the export’s deferral block (System Prompt Export 2026-07, L3238-3283).
  • Multi-agent systems consume roughly 15x the tokens of a normal chat, so a badly shaped tool response gets amplified across every subagent.

Sources

Next actions

  • Audit one connected MCP server against the consolidation and namespacing rules.
  • Sketch a small description-evaluation harness for the tools this vault’s flows depend on.
  • Compare the export’s widget descriptions with Claude Code tool descriptions once a Claude Code capture exists.

Graph View

Backlinks