CONCEPT Consolidate related operations into fewer tools
The instinct to give every action its own tool — create_pr, review_pr,
merge_pr, close_pr — is a trap. Anthropic's guidance is the opposite:
consolidate related operations into fewer, more capable tools, typically by folding the
variants into a single tool with an action parameter. Fewer tools means less selection
ambiguity — Claude has fewer near-identical descriptions to disambiguate — and a tool surface that's
easier to navigate.
| Many thin tools | Few rich tools | |
|---|---|---|
| Example | create_pr, review_pr, merge_pr | manage_pr(action, …) |
| Selection | Ambiguous — several look right | One obvious tool; pick the action |
| Context cost | N descriptions + N schemas | 1 description + 1 schema |
| Chaining | Model must sequence trivial calls | Related steps live behind one tool |
CONCEPT Don't make Claude chain trivial calls
The other failure mode is tools that are too thin. If answering one user question forces Claude to
call get_user_id → get_orders(id) → get_order_detail(order) in sequence,
every hop is a round trip that adds latency, tokens, and a chance to go off track. Where those steps always run
together, fold them into one higher-level tool that does the composite job and returns the
answer. Reserve separate tools for steps that genuinely branch.
find_customer_orders), not the plumbing
(db_query).CONCEPT Clear, meaningful names
Names must match ^[a-zA-Z0-9_-]{1,64}$ and should be specific and self-explanatory:
get_current_weather beats weather; search_customer_database beats
search. The name is a compact identifier that seeds Claude's expectation before it reads the
description — a good name plus a detailed description select together. (Cross-tool disambiguation via
namespacing is 2.4.)
DIAGRAM Right-sizing the tool surface
(create/review/merge PR)"| CONS["🟢 Consolidate:
one tool + action param"] Q -->|"always run in sequence
(id → orders → detail)"| COMPOSE["🟢 Compose:
one higher-level tool"] Q -->|"genuinely independent
& branch differently"| SEPARATE["🔵 Keep separate,
well-scoped tools"] CONS --> WIN["Fewer overlaps → less
selection ambiguity"] COMPOSE --> WIN SEPARATE --> WIN classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef info fill:#cfe2ff,stroke:#0d6efd,color:#084298; class CONS ok; class COMPOSE ok; class SEPARATE info;
CODE Three thin tools → one consolidated tool
Fold the PR variants into a single tool with an action enum. Claude selects the tool once, then
chooses the action — far less ambiguous than three lookalike descriptions.
// ❌ Thin, overlapping — Claude must disambiguate 3 similar tools [ { "name": "create_pr", ... }, { "name": "review_pr", ... }, { "name": "merge_pr", ... } ] // ✅ One capable tool with an action parameter { "name": "manage_pull_request", "description": "Create, review, or merge a GitHub pull request. Choose the " "operation via 'action'. Use for any change to a PR's lifecycle; not " "for issues or commits.", "input_schema": { "type": "object", "properties": { "action": { "type": "string", "enum": ["create", "review", "merge"], "description": "Which PR operation to perform." }, "repo": { "type": "string", "description": "owner/name, e.g. acme/api" }, "number": { "type": "integer", "description": "PR number (review/merge)" } }, "required": ["action", "repo"] } }
TRADE-OFFS Consolidation vs. splitting
✅ Fewer, richer tools
- Less selection ambiguity, fewer overlaps
- Smaller total context footprint (2.5)
- Related steps don't require trivial chaining
⚠️ Over-consolidation
- A "do-everything" tool with a giant branching schema
- Unrelated actions crammed behind one
actionfield - Harder to gate/audit distinct operations individually (see D1 · 5.4)
delete still deserves its own gate-able seam.EXAM TRAPS
action parameter.get_id →
get_x(id) every time wastes turns. Where steps always co-occur, compose them into one
higher-level tool.search or weather. → Names should be
specific and task-oriented (search_customer_database); the name seeds selection before the
description is read.PRACTICE
Q1 · You have create_pr, review_pr, merge_pr. What does Anthropic recommend, and why?
Consolidate them into one tool with an action parameter
(manage_pull_request). Fewer, more capable tools reduce selection ambiguity and shrink the tool
surface Claude must navigate.
Q2 · When is a tool too thin?
When answering one question forces Claude to chain several trivial calls that always run together (get_id → get_orders → get_detail). Compose those into a single higher-level tool that returns the answer; keep tools separate only where the steps genuinely branch.
Q3 · Give the exam one-liner on granularity.
A few well-scoped tools beat many overlapping ones. Consolidate related operations, compose always-sequential steps, name tools after tasks — and don't merge actions with different risk profiles just to cut the count.