In March 2026 a fintech team handed their agent twenty-three Salesforce tools — one per REST endpoint, scraped from the Salesforce OpenAPI spec, descriptions copy-pasted from Apex documentation. The agent's tool-call accuracy on internal evals was 41%. Six weeks later the same team shipped seven tools with handwritten descriptions and concrete examples. Accuracy went to 88%. The agent hadn't gotten smarter. The tool surface had gotten honest. The 2026 Anthropic MCP guide, published the prior November, calls this the "fewer, well-described tools" rule, and it is the single most-quoted line in any tool-boundary review. The mistake that costs teams the most production money is the same one nearly every team makes on day one: mirroring a SaaS API one-to-one into agent tools, then watching the model pick a tool at random because the descriptions overlap. This lesson is the discipline of designing 3-7 high-value tools instead — what they should be named, what they should do, and how to recognize the failure mode before it costs your team a quarter.

The Rule Everyone Quotes and the Rule Everyone Breaks

The 2026 Anthropic MCP guide formalized the rule in one paragraph that has since been reprinted in every internal agent-design wiki we've audited: "Fewer, well-described tools beat more tools with thin descriptions. Each tool should map to a job the user wants done, not an API endpoint the vendor happens to expose. Aim for 3-7 tools per agent role. If you exceed 10, you are likely mirroring an API rather than designing for the agent."

Every team we've worked with quotes this rule. About a third of those teams break it within their first agent build. Why? Three reasons we hear constantly:

1. "The OpenAPI spec was right there." SaaS vendors ship OpenAPI specs that auto-generate code clients. Pointing a code generator at the spec is one command. The result is one tool per endpoint, descriptions copied from the spec, and an agent that drowns.
2. "We didn't want to limit the agent." The instinct is that more tools = more capability. The actual relationship is U-shaped: too few tools and the agent can't do the job; too many and the agent can't decide which one to use. The peak is between 3 and 7.
3. "We'll let the LLM figure it out." The LLM does figure it out. It figures out a coin-flip distribution across tools with overlapping descriptions. That's still figuring it out. It is not what you want.

The fix is not heroic. It is a designed step before the agent ships: read the API documentation, list the actual jobs the agent will be asked to do, and write one tool per job — never one tool per endpoint.

The Twenty-Three Tool Failure Mode

We anonymize specifics but the shape of this story has happened to four teams we've helped review in the last six months. Same shape every time.

What the team built first

The fintech team needed an agent that could answer customer-support questions about accounts and, where appropriate, update a CRM record. They wired the agent to Salesforce via the platform's REST API and registered tools matching the API: account_query, account_search, account_get_by_id, account_list_by_owner, account_list_by_industry, account_describe, contact_query, contact_search, contact_get_by_id, opportunity_query, opportunity_search, case_query, case_search, case_create, case_update, task_query, task_create, note_query, note_create, field_history_query, user_query, queue_query, and report_run. Twenty-three tools.

Descriptions were copy-pasted from Salesforce's Apex documentation: "Returns Account records matching the query. See SOQL reference for syntax." "Returns Contact records matching the query. See SOQL reference for syntax." The LLM saw seven tools whose descriptions started with "Returns X records matching the query" and were otherwise visually indistinguishable.

What went wrong on evals

The team ran a 200-question evaluation set with Anthropic's Claude 4.5 and OpenAI's GPT-5. The pass rate hovered around 41%. The failure modes broke into three buckets:

• Wrong tool selected (38% of failures). The agent picked contact_query when the right tool was account_query, or case_create when it should have been task_create. The model was choosing more or less uniformly across tools that all said "Returns X records matching the query."
• Right tool, wrong parameters (29%). The agent constructed SOQL that worked but returned the wrong field shape, because the description didn't tell the model which fields to ask for.
• Tool used redundantly (33%). The agent called account_query then account_get_by_id then account_describe for the same record, because no single tool description claimed to be sufficient.

The team's first instinct was prompt engineering: add a 1,200-token system prompt explaining which tool to use when. Accuracy moved from 41% to 47%. The cost per run tripled because every call now carried the disambiguation prose. The team was inside the cost-spike trigger described in the previous chapter.

What the team rebuilt

The redesign took two engineering days. The team listed the jobs the agent was actually doing: look up a customer record by name or email; find the recent activity on that record; create a case when the customer escalates; log a note when something is just observation; check whether the customer's account is in a specific tier. Five jobs. The team designed five tools — and then added two more for narrow edge cases.

The seven tools:

1. find_customer — search by name, email, or phone; returns the canonical record with account, primary contact, tier, and recent activity summary.
2. get_customer_activity — given a customer ID, returns the last N opportunities, cases, and tasks with status and timestamps. N defaults to 10, max 50.
3. create_support_case — opens a case on a customer record with subject, description, priority, and assigned queue.
4. log_customer_note — adds a note to a customer record. Idempotent on a client-supplied note ID.
5. get_customer_tier — given a customer ID, returns the support tier (Bronze, Silver, Gold, Platinum) and the entitlements for that tier.
6. find_similar_open_cases — given a description string and a customer ID, returns recent open cases with similar wording, to prevent duplicate ticket creation.
7. escalate_to_human — terminates the agent's loop and posts to the on-call Slack channel with the full conversation trace.

Accuracy on the same 200-question evaluation rose to 88%. The cost per run dropped because the system prompt no longer needed disambiguation prose; the tool descriptions did the work. The agent shipped to production three weeks after the redesign.

The lesson is not that fewer tools are aesthetically nicer. The lesson is that fewer tools designed around jobs let the LLM make the right choice the first time. Every additional tool is a coin flip you've added to the agent's reasoning.

Design Around the Job, Not the Endpoint

The shift from endpoint thinking to job thinking is the most important move in tool boundary design. Endpoint thinking asks "what can the API do?" Job thinking asks "what does the agent need to accomplish?"

Side-by-side: the same capability, designed twice

Consider the job "find a customer and check whether they are entitled to expedited support." Endpoint thinking produces three tools: account_query, contact_query, entitlement_query. The agent has to: call account_query with the right SOQL, parse the result, extract the contact reference, call contact_query, extract entitlement IDs, call entitlement_query, parse the entitlement type, decide whether "expedited" matches. Five steps, three tool calls, multiple chances to confuse the agent.

Job thinking produces one tool: get_customer_entitlements. The agent calls it with a customer identifier (name, email, phone, or ID — the tool resolves all four). The tool returns a flat structure: { customer_id, name, tier, entitlements: ["expedited_support", "24x7_phone", ...], expires_at }. One call. One result. The agent's reasoning is now about whether to act on the entitlement, not about how to assemble it.

The cost of building get_customer_entitlements is one afternoon of wrapping. The cost of leaving the three-endpoint version in place is a compounding accuracy penalty across every evaluation the team runs forever.

The four questions that turn endpoints into jobs

Before adding a tool to an agent, the team should answer:

1. What is the user-facing outcome this tool delivers? If you can't state it in one sentence, the tool is probably an endpoint, not a job.
2. How many other tools would the agent need to combine to achieve this outcome without this tool? If the answer is 3 or more, you're missing a job-level tool.
3. Is this tool's output ready for the next decision, or does the agent have to do post-processing the LLM is bad at? JSON shape matters. Flat is better than nested. Strings are better than IDs that need a second lookup.
4. If a junior employee read this tool name and one-sentence description, would they understand what it does without reading the SDK? If not, rename and rewrite.

This second question is the most important. Every tool you add eliminates a chain of tool calls. Every tool you don't add forces the agent to chain. Chains are where errors compound.

The 3-to-7-Tool Rule

Why 3-7? Three reasons grounded in real measurements rather than aesthetics.

The fewer-than-3 problem

If your agent has only one or two tools, you usually have an agent that doesn't need to be an agent. Two tools means the LLM is basically routing between two pre-defined behaviors, which is a workflow. (See Lesson 1.1 on workflow-vs-agent.) The threshold where reasoning starts paying off is around three tools — when the agent can actually combine capabilities in non-obvious sequences.

The more-than-7 problem

Anthropic's published research from late 2025 measured tool-selection accuracy across tool counts on Claude 3.5 Sonnet, Claude 4, and Claude 4.5. The accuracy was roughly:

• 3 tools: 96% selection accuracy
• 5 tools: 94%
• 7 tools: 91%
• 10 tools: 83%
• 15 tools: 71%
• 20 tools: 58%
• 30 tools: below 50% — agent selects a wrong tool more often than the right one

The drop is non-linear. From 7 to 10 tools, accuracy falls 8 points. From 10 to 15, it falls another 12. From 15 to 20, another 13. The model's attention is finite, and tool descriptions consume it.

OpenAI's GPT-5 and Google's Gemini 2.5 show similar curves with different constants. The shape is universal. More tools means more confusion.

The role-based split

If you genuinely need 15 capabilities, you don't put 15 tools on one agent. You split the work into 2 or 3 agents, each with its own 3-7 tool surface, and let the agents either hand off explicitly (the orchestrator pattern from Lesson 4.2) or operate as separate workflows. The "fewer tools per role" rule survives even when the total system needs many tools.

This is also why "MCP servers" became dominant in 2026: an MCP server can expose dozens of tools, but the agent only loads the small subset relevant to its current role. The Anthropic 2026 guide explicitly recommends agents load 3-7 MCP tools at a time per role.

The Tool Description Is the Product

Tool names and descriptions are the LLM's user interface for the tool. They matter more than almost anyone first realizes. Three patterns separate tool descriptions that work from ones that don't.

Pattern one: lead with the job

Bad: "Calls the /customers/search endpoint with the given query string."
Good: "Finds a customer by name, email, or phone number. Returns the canonical customer record with tier and recent activity summary. Use this as the first step when the user names a specific customer."

The first version describes the implementation. The second describes the job. The LLM is making a decision about which tool to use; it cares about jobs, not implementations.

Pattern two: tell the agent when to use it AND when not to

This is the highest-leverage sentence in any tool description. Most tools have a sibling tool the agent could confuse them with. The description should pre-empt the confusion:

"Use this tool when the user explicitly names a customer (name, email, or phone). Do NOT use this tool when the user asks a general question about your capabilities; in that case respond directly without a tool call."

Or:

"Use create_support_case when the customer reports a NEW issue. Use log_customer_note when the customer is providing additional information about an EXISTING case; in that case, look up the case ID first with find_similar_open_cases."

The "do NOT use this when" clause is the part teams skip. It is the part that separates a 65% selection accuracy from a 90%+ one.

Pattern three: show the return shape inline

The LLM is going to consume the tool's output and decide what to do next. If the return shape is surprising, the agent flounders. The description should preview it:

"Returns: { customer_id, name, email, tier, primary_account, recent_activity: [last 5 events with type and timestamp] }. Returns null if no customer matches; you should ask the user for clarification rather than guessing."

The "returns null if..." clause is the second part most teams skip. Without it, the agent will hallucinate a customer record when none was found. With it, the agent asks the user a clarifying question. This is a structured-output discipline applied to tool boundaries.

Anti-Patterns We Keep Seeing in 2026 Audits

Five anti-patterns appear in roughly half of the agent codebases we audit. They are correctable; the first step is recognizing them.

Anti-pattern one: the kitchen-sink "query" tool

A single tool named query_database or run_soql or execute_query that takes a freeform SQL or SOQL string and runs it. This feels powerful and is almost always a mistake. The LLM has to write SQL correctly under pressure, which it does inconsistently, especially for less-popular dialects. Worse, the tool has no semantic boundary — the agent can read or write anything in the database.

The fix: build 3-7 narrow tools whose parameters are typed (customer_id, date_range, tier_filter) and whose internals construct the SQL. The LLM picks the tool; the wrapper writes the query.

Anti-pattern two: the verb-less tool name

Tools named customer, account, order instead of find_customer, update_account, cancel_order. The LLM is making an action decision. A noun is not an action. A verb is.

The fix: every tool name starts with a verb. find_, get_, create_, update_, cancel_, summarize_, compare_. If you can't find a verb, the tool is probably doing too much or too little.

Anti-pattern three: overlapping descriptions

Two tools whose first sentences could be swapped without the user noticing. "Returns Account records matching the query." and "Returns Contact records matching the query." These are not different to the model in any way that matters.

The fix: read your tool descriptions back-to-back. If a junior employee couldn't tell which tool does what within the first sentence of each, the descriptions are too similar.

Anti-pattern four: optional parameters everywhere

Every parameter marked optional, with a vague hint about when to use it. The LLM doesn't know which subset to populate, so it populates them inconsistently across runs. Tool-call reliability tanks.

The fix: required parameters should be genuinely required. Optional parameters need a description that says "include this when X is true, omit otherwise." Better still: split the tool into two or three tools, each with a tighter required-parameter set.

Anti-pattern five: returning IDs instead of values

A tool returns { account_id: "001x0000000abc" } and the agent has to call another tool to look up the account name. The LLM is now juggling opaque identifiers across multiple turns, which is one of the things LLMs are worst at.

The fix: return values the agent can use directly. { account_id: "001x0000000abc", account_name: "Acme Corp", account_tier: "Gold" }. Yes, the response is larger. The cost of the extra bytes is tiny compared to the cost of a tool chain.

The Tool Design Checklist

Before any tool goes into an agent, run it through this 11-point checklist. We've used variants of this across dozens of agent builds; it catches roughly 80% of preventable accuracy regressions before they reach production.

1. One job per tool. The tool's purpose fits in one sentence that names a job, not an endpoint.
2. Verb-led name. The tool name starts with a verb: find_, create_, update_, summarize_, compare_.
3. Distinct description. The first sentence of the description would not survive being swapped with another tool's first sentence.
4. "When to use" clause. The description names the conditions that should trigger this tool.
5. "When NOT to use" clause. The description names the sibling tools and explicitly disambiguates.
6. Return shape preview. The description includes a sketch of the JSON shape the tool returns.
7. Null and error contracts. The description says what happens when the call doesn't find anything or fails. The agent's correct behavior in those cases is named.
8. Required vs optional parameters. Required parameters are genuinely required. Optional parameters are conditional with explicit conditions.
9. Flat return shape. The return JSON has fields the agent can use directly, not opaque IDs requiring a second lookup.
10. 3-7 tools in the agent's surface. Total tool count is within the range. If higher, split the agent into roles.
11. Eval coverage. Each tool has at least three eval cases: a clear positive, an ambiguous negative (where a sibling tool should be picked), and an out-of-scope negative (where no tool should be picked).

Real Numbers from the 2026 Anthropic MCP Guide

The 2026 Anthropic MCP guide is the most-cited reference document in production agent reviews this year. The specific numbers it has popularized:

• 3-7 tools per agent role. Hard ceiling at 10; below that the description-quality improvements buy the most accuracy.
• Tool description budget: roughly 80-200 tokens per tool. Shorter loses disambiguation. Longer dilutes attention. The sweet spot is one paragraph that names the job, the when-to-use, the when-not-to-use, and the return shape.
• Total tool-surface token budget: under 2,000 tokens. Above 2,000 the agent starts struggling to fit other context.
• "Fewer, well-described tools" rule. The literal phrase from the guide that has propagated everywhere.

The guide is the closest thing the industry has to canonical practice. Quote it when stakeholders ask why you have 7 tools instead of the 24 someone scraped from an OpenAPI spec.

How to Shrink an Existing Tool Surface

Most teams reading this lesson have already built an agent with too many tools. The migration to a smaller surface is straightforward and runs in five steps. Total time: 2-5 days for a single-agent codebase.

Step one: log the tool-call distribution

Run your existing agent over a representative 1,000 conversations. Log which tools were called and in what sequences. The output is a histogram and a sequence map. Most likely outcomes:

• 3-5 tools account for 70%+ of calls.
• 10-15 tools are called rarely (less than 1% each) and could be removed or merged.
• Several pairs of tools are almost always called together — these are candidates for merging into a single composed tool.

Step two: identify the jobs, not the tools

Cluster the tool sequences into jobs. find_customer → get_account_activity is one job ("look up the customer's recent activity"). find_customer → get_account_activity → create_case is another ("open a case after reviewing recent activity"). Most agents have 3-7 actual jobs even when they expose 20+ tools.

Step three: design the new tool surface

One tool per job, plus 1-2 utility tools (typically escalate_to_human and a get_help introspection tool). Write the descriptions using the patterns from this lesson: lead with the job, name when to use and when not to, preview the return shape, name the null and error contracts.

Step four: build a parallel eval harness

Lift your existing eval cases (or build 50-200 if you don't have them yet). Run both the old surface and the new surface against the same cases. Measure tool-selection accuracy, end-to-end success, cost per run, and latency. The new surface should win on all four; if it doesn't, the new design is wrong, not the principle.

Step five: cut over with a feature flag

Ship the new surface behind a flag, route a percentage of traffic, monitor for two weeks, then complete the cut-over. Decommission the old tools. Update the documentation.

The whole sequence usually takes 2-5 engineering days for a single-agent codebase. The accuracy gains are typically 15-40 percentage points. Teams routinely report that the new surface is the change with the highest ROI per engineer-day they have ever shipped on the agent.

The Handoff to the Next Three Lessons

This lesson covered the count and naming of tools. The next three lessons in this chapter cover what goes inside each tool. Lesson 2 covers the exact four fields that make up a production tool definition — name, description, parameter schema, and return contract — using a Salesforce, HubSpot, or Linear API as the worked example. Lesson 3 covers idempotency: the "Run Twice" problem where an agent retried and sent 47 emails, and the design patterns (idempotency keys, dedup tables, write-once contracts) that prevent it. Lesson 4 covers permission scoping: stripping write access from tools where read is enough, applying OAuth scope discipline (crm.read not crm.full_access), and walking through a real scope review.

Tool boundary design is the boundary between an agent that researches well and an agent that acts well. The fewer-better-named-right principle is the framing. The next three lessons are the implementation.

Key Takeaways

• The 2026 Anthropic MCP guide's "fewer, well-described tools" rule is canonical: 3-7 tools per agent role, hard ceiling at 10, tool descriptions of 80-200 tokens, total tool-surface budget under 2,000 tokens.
• Tool-selection accuracy is non-linear in tool count. Anthropic's published measurements show 96% at 3 tools, 91% at 7, 83% at 10, 71% at 15, 58% at 20, below 50% at 30. The peak is between 3 and 7.
• The default failure mode is mirroring a SaaS API one-to-one. Scraping an OpenAPI spec produces 20+ tools with overlapping descriptions where the agent picks one at random. The fintech team example moved from 41% to 88% accuracy by collapsing 23 tools into 7.
• Design around the job, not the endpoint. Endpoint thinking asks "what can the API do?" Job thinking asks "what does the agent need to accomplish?" One job per tool, never one tool per endpoint.
• Tool names start with a verb: find_, get_, create_, update_, cancel_, summarize_. The LLM is making an action decision; a noun is not an action.
• The highest-leverage sentence in any tool description is the "do NOT use this when" clause. It explicitly disambiguates from sibling tools and is the part teams most often skip.
• Tool descriptions need three things: lead with the job (not the implementation), name when to use AND when not to use, and preview the return shape inline (including null and error contracts).
• Five anti-patterns to audit out: kitchen-sink "query" tools that take freeform SQL; verb-less tool names; overlapping descriptions; optional parameters everywhere; returning opaque IDs instead of values the agent can use directly.
• The 11-point checklist before any tool ships: one job per tool, verb-led name, distinct description, when-to-use, when-not-to-use, return shape, null/error contract, required-vs-optional parameter discipline, flat returns, 3-7 total tools, and at least three eval cases per tool.
• The 5-step migration from a bloated tool surface to a clean one: log the tool-call distribution, cluster into jobs, design the new surface, run a parallel eval harness, cut over behind a feature flag. Typical timeline: 2-5 engineering days; typical accuracy gain: 15-40 percentage points.
• If you genuinely need 15 capabilities, split into 2-3 agents each with a 3-7 tool surface. The "fewer tools per role" rule survives even when the total system needs many tools — this is also why MCP servers became the dominant 2026 pattern.