D2 · Tool Design & MCP › Cluster 2 · Designing Great Tools

2.3 · Naming & Granularity

Few rich tools > many thin ones

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 toolsFew rich tools
Examplecreate_pr, review_pr, merge_prmanage_pr(action, …)
SelectionAmbiguous — several look rightOne obvious tool; pick the action
Context costN descriptions + N schemas1 description + 1 schema
ChainingModel must sequence trivial callsRelated steps live behind one tool
🔑 The exam framing: a few well-scoped tools beat many overlapping ones. Overlap is what makes Claude pick the wrong tool — the fix starts at the granularity level.

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.

Right-sizing rule: a tool should map to a task the user cares about, not to a single low-level API call. Name it after the task (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

flowchart TD START["Set of API actions"] --> Q{"How related are they?"} Q -->|"variants of one resource
(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 action field
  • Harder to gate/audit distinct operations individually (see D1 · 5.4)
Consolidate related operations. Don't merge actions with different risk profiles just to cut tool count — an irreversible delete still deserves its own gate-able seam.

EXAM TRAPS

Trap: "One tool per API endpoint is cleanest." → It maximizes overlap and selection ambiguity. Consolidate related operations into fewer tools with an action parameter.
Trap: Forcing Claude to chain trivial calls. → Sequencing get_id → get_x(id) every time wastes turns. Where steps always co-occur, compose them into one higher-level tool.
Trap: Vague names like search or weather. → Names should be specific and task-oriented (search_customer_database); the name seeds selection before the description is read.
Trap: Over-consolidating unrelated or differently-risky actions. → Merging a read and an irreversible delete behind one tool removes the per-action gate. Consolidate related ops only.

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.