Skip to main content
CertGrove
Start learning
Tools & MCP

Designing tools agents can choose correctly: 5 principles and 3 common pitfalls

An agent choosing the wrong tool often points to unclear descriptions. This article explains what drives tool selection and how to identify the right answer in scenario questions.

The CertGrove team · Updated · 9 min read
Clear boundaries in descriptions help agents choose the right tool on the first call.

A recurring Tools & MCP scenario is an agent with several tools that keeps choosing the wrong one. Suggested fixes often include fine-tuning the model, increasing max_tokens, merging tools or rewriting descriptions. To choose the right fix, understand what information the model uses.

How does the model choose a tool?

On each call, Claude receives a list of tools with name, description and input_schema. The model cannot know what a tool does beyond what is written there. If two tools have similar descriptions, the model has to guess.

When an agent chooses the wrong tool, review the descriptions first, before considering more expensive solutions.

5 principles for writing descriptions

  1. 1Describe the tool in one specific sentence“Get one order by its exact ID” is clearer than “handle orders”.
  2. 2State when to use itDescribe the signals in a user request that make this tool the right choice.
  3. 3State when not to use itPoint to another tool for similar cases. This is often the missing part.
  4. 4Use a precise input schemaClear types, required fields and enums for fixed choices reduce invalid calls.
  5. 5Return recovery guidance with errorsExplain what is missing and the next step so the agent can recover instead of retrying blindly.

Example: before and after

Before — ambiguous
{ "name": "search_orders", "description": "Find orders." }
After — clear boundaries
{ "name": "get_order", "description": "Get ONE order by its exact ID. Use when the user provides an order ID. Do not search by date or product — use search_orders." }

The revised description says when to use the tool, when not to use it and which alternative to choose. This is the information the model needs to distinguish them.

3 common pitfalls

Pitfall 1 · Overlapping toolsEvery additional tool is another choice the model must distinguish. Fewer tools with clear, distinct purposes often work better.
Pitfall 2 · One universal toolA tool that accepts free-form instructions may look simple, but loses structured inputs, makes validation harder and moves ambiguity inside the tool.
Pitfall 3 · Errors without recovery guidanceA bare “Error” encourages blind retries. Explain what is missing and what to do next, such as choosing a different tool.

Try a scenario question

Example question

A support agent often calls search_orders when users give an exact order ID. What is the most appropriate first fix?

Summary

  • The model chooses tools using name, description and input_schema.
  • Descriptions should say when to use a tool and when not to use it.
  • Wrong tool selection → improve descriptions before considering expensive solutions.
  • Avoid overlapping tools and universal tools with free-form inputs.

Frequently asked questions

The CertGrove teamBilingual study notes for developers preparing for Claude Certified Architect — Foundations.