تجنّب الأدوات المتداخلة

When you give Claude a set of tools, the model has to pick the right one for each step. It does this by reading the tool descriptions, not by guessing from clever names.

If two tools sound like they do the same job, Claude faces a coin flip. Sometimes it picks the right one, sometimes the wrong one. This is called misrouting, and it is one of the most common reasons a well-built agent behaves unpredictably in production.

In this lesson you will learn how overlapping, ambiguous tools cause misrouting, and how to design clean, non-overlapping tools that route reliably.

The key fact to internalize: tool descriptions are the primary selection mechanism. The model reads each description and chooses the tool whose stated purpose best matches the current task.

A good description includes:

• Purpose — what the tool does
• Return values — what it gives back
• Input formats — with concrete examples
• Edge cases and applicability boundaries — when NOT to use it

When two descriptions blur together, the boundaries disappear, and Claude can no longer tell them apart.

Here is a classic overlapping pair. Both tools claim to fetch order information, with vague descriptions that do not draw a clear line between them.

Ask yourself: if a user says "where is my package?", which tool should Claude call? The descriptions give no way to decide, so the model will sometimes pick the wrong one.

Misrouting is not a cosmetic problem. In an agentic loop, one wrong tool call cascades:

• The wrong tool returns the wrong shape of data, or an error.
• Claude tries to recover, burning extra turns and tokens.
• Preconditions get skipped — for example, calling process_refund down a path that never verified the customer's identity.

In the Customer Support scenario, tools like get_customer, lookup_order, process_refund, and escalate_to_human each have a distinct job. Blur any two and the whole flow becomes unreliable.

The cleanest fix for overlap is often to collapse duplicates into a single, well-described tool. If two tools really do the same thing, you do not need both.

Notice how the description now states purpose, return values, input format with an example, and an explicit boundary about what it does NOT do.

Sometimes you genuinely need two related tools. The trick is to make each description state when to use it AND when not to, pointing at its sibling.

Here a customer-lookup tool and an order-lookup tool sit side by side, but each names the boundary so Claude can route correctly every time.

Overlap often appears because an agent is handed every tool in the system. The discipline is to scope tools to the role: give each agent only the tools its job needs.

A refund agent does not need a code-search tool. A research subagent does not need process_refund. In a multi-agent system, each AgentDefinition carries its own allowed_tools following least privilege — fewer tools means fewer chances to confuse two of them.

Overlap and bloat are the same disease. The fact sheet is precise about counts:

• 4–5 tools per agent is optimal for reliable selection.
• 18+ tools degrades selection reliability sharply.

More tools means more surface area for two descriptions to brush against each other. If you find yourself past five tools, ask whether some belong to a different agent's role, or whether two of them are really one tool wearing two names.

A subtle source of overlap: people wrap read-only reference data as a Tool when it should be an MCP Resource.

In MCP, the primitives are distinct:

• Tools — actions (do something, possibly with side effects)
• Resources — read-only data and context, like schemas or catalogs
• Prompts — reusable templates

If a product catalog is exposed as a Resource instead of yet another get_* tool, your action tools stay few and distinct, and routing stays clean.

A tempting but weak fix is to just rename tools — lookup_order_v2, get_order_fast, order_helper. Remember: Claude selects on descriptions, not names. A prettier name with the same vague description routes no better.

The real differentiator is the applicability boundary: a sentence in each description that says exactly when this tool wins and the other loses. Boundaries are what eliminate the coin flip.

Before you ship a toolset, run this audit:

• For every pair of tools, can you state one input where it is unambiguous which to call? If not, merge or clarify.
• Does each description name purpose, returns, input example, and an explicit “do NOT use when…” boundary?
• Is each tool actually used by this agent's role, or did it leak in?
• Are you at 4–5 tools, not 18+?
• Is any read-only data better modeled as a Resource?

Passing this audit is the difference between an agent that routes reliably and one that quietly misroutes under load.

A support agent intermittently calls the wrong tool when users ask about orders. Apply what you learned.

Key takeaways:

• Descriptions, not names, drive selection. Ambiguous or overlapping descriptions cause misrouting.
• One tool, one job. Merge true duplicates; otherwise give each tool an explicit “when to use / do NOT use” boundary that points at its sibling.
• Scope to the role. Give each agent only the tools it needs (least privilege), and keep to 4–5 tools — 18+ degrades reliability.
• Model read-only data as a Resource, not as another tool, to keep action tools few and distinct.
• A great description names purpose, return values, input formats with examples, and applicability boundaries.

Design tools so the right choice is obvious, and your agent routes correctly every time.