On this page
Agents ignore an MCP tool when the model cannot tell from its name and description when to use it, when another tool looks like a better match, or when the client never offers it to the model. Flowlines shows calls, users and sessions for each of your tools by AI client and use case, and the tool path inside every session, so you can see which tools are never called, which are picked by mistake and which are called over and over.
The model chooses tools from text. It reads the names, descriptions and input schemas your server returns from tools/list and decides which one fits the user's request. When that text is vague or two tools sound alike, the choice goes wrong in ways that look like low adoption. This guide covers four patterns: tools that are never called, tools picked by mistake, overlapping tools and tools called many times in a row.
Why does an agent ignore an MCP tool?
An agent ignores a tool for one of five reasons, and each leaves a different trace in your usage data; Flowlines shows calls, users and sessions per tool and per AI client, which is enough to tell them apart.
| Cause | What you see in usage data | Fix |
|---|---|---|
| The description does not say when to use it | Zero or very few calls, even in sessions where it fits | Rewrite the description around the user's job |
| Another tool sounds like a better match | The other tool is called for jobs this one was built for | Merge the tools or make their boundaries explicit |
| The client did not offer the tool | Calls in one client, none in another | Check the client's tool limits, permissions and settings |
| Nobody needs it | No sessions where the job comes up | Remove it or wait for demand before improving it |
| Telemetry is missing | Zero calls for every tool, or for one server | Fix the exporter before drawing conclusions |
Start with the last row. A gap in telemetry looks exactly like a tool nobody uses.
How do I find MCP tools that are never called?
Compare the tools your server declares with the tools that received calls in the same window, per AI client; Flowlines lists observed activity for every tool, so a declared tool with no calls stands out.
- Export the declared catalog. Call
tools/liston the production server, follow pagination to the end, and keep the list of names. - Count observed calls per tool. Use a window long enough for the job to come up at least once, often 28 days.
- Split by AI client. A tool used in Claude but never in ChatGPT is a discovery or presentation problem, not a demand problem.
- Exclude internal traffic. Your own tests can make an unused tool look alive.
- Classify each unused tool. Read its description as the model would, with no other context, and write down the user request that should trigger it.
| Tool (synthetic) | Calls, 28 days | Clients with calls | Likely reading |
|---|---|---|---|
search_customers | 1,240 | 4 | Core tool, healthy |
find_account | 310 | 3 | Overlaps with search_customers; check confusion |
export_report | 0 | 0 | Description never mentions CSV or export formats users ask for |
merge_duplicates | 12 | 1 | Used in one client only; check how that client presents tools |
A tool with zero calls is not automatically a bad tool. It may cover a monthly job, or it may be blocked by a permission the user never granted. Read a few sessions where the job should have come up before deciding.
Why does the agent pick the wrong tool?
The agent picks the wrong tool when two tools overlap in name or description, so the model guesses; Flowlines shows the tool path of each session, which makes the pattern of one tool followed straight away by a similar one easy to spot.
Look for pick-and-switch sequences: a session where tool A is called, returns little or nothing useful, and tool B is called for the same job. One occurrence means nothing. The same pair across many users means the boundary between A and B is unclear to the model.
| Pattern (synthetic) | Sessions | What it suggests |
|---|---|---|
find_account then search_customers | 140 | The model reaches for find_account first, but search_customers answers the question |
get_invoice then list_invoices | 65 | Users ask about invoices without an ID; get_invoice needs one |
search_docs then search_docs with a narrower query | 210 | Usually legitimate refinement, not confusion |
The last row matters. Not every switch is a mistake. A model that searches, reads the result and searches again with a better query is doing its job. Open sessions before you change anything.
Which overlapping tools should I merge?
Merge tools that answer the same user question with different arguments, and keep tools separate only when their jobs differ in a way the description can state in one sentence.
| Overlap | Example | Better design |
|---|---|---|
| Same object, different lookup key | get_customer_by_email, get_customer_by_id | One get_customer with either argument |
| Same action, different scope | search_open_tickets, search_all_tickets | One search_tickets with a status filter |
| Synonyms | find_account, search_customers | One tool, named after the user's word for the object |
| Read and write in one tool | manage_subscription with an action argument | Separate read and write tools with clear annotations |
Fewer tools also cost fewer tokens. Every declared tool's name, description and schema is text the client may place in the model's context, whether or not the tool is used.
Why is the same tool called many times in a row?
A tool is called repeatedly because of pagination, retries after errors, empty or unhelpful results, or a missing filter; Flowlines shows repeated calls inside each session, so you can see which of these is happening and for which users.
| What you see | Likely cause | Fix |
|---|---|---|
| Same arguments, an error before each repeat | Retry after a failure | Fix the error, and return a message the model can act on |
| Same arguments, no error | The result did not tell the agent what to do next | Return a clearer result, or say explicitly that nothing matched |
| Changing cursor argument | Pagination | Usually fine; consider a larger page or a summary tool |
| Small changes to a query, many times | No filter for what the user wants | Add the missing filter or a more specific tool |
Repeated calls inflate call volume and make a struggling tool look popular. They also raise calls per completed job, which is a better KPI than raw volume for this reason. When repeats follow errors, the MCP error codes guide explains how to return tool errors the model can recover from.
How should I write MCP tool names and descriptions?
Write each description for a model that knows nothing about your product: say what the tool does, when to use it, when not to, and what it returns. Then check the effect in usage data rather than by intuition.
- Name the object and the action in the user's words:
search_customers, notcrm_query_v2. - Keep names unique and stable. Some clients combine tools from several servers, and a generic name like
searchis easy to confuse. - Start the description with when to use it. "Use when the user asks about a customer by name or email."
- Say when not to use it, and name the better tool: "For invoices, use list_invoices."
- Describe every input in the schema, with formats and examples, and mark what is required.
- Describe the result, including what an empty result means.
- Set annotations honestly.
readOnlyHintanddestructiveHinthelp clients decide when to ask for confirmation; they are hints, not security controls. - Return errors as text the model can fix. "Date must be YYYY-MM-DD" lets the agent retry correctly; a stack trace does not.
How many tools should an MCP server expose?
The MCP specification sets no maximum number of tools, so expose the smallest set of clearly distinct tools that covers the jobs your users bring. Each extra tool is one more option the model must rule out, and clients may limit or defer the tools they present. Measure selection rather than guessing: if a tool is rarely chosen and often switched away from, it is a candidate to merge or remove.
How do I know a description change worked?
Compare equal windows before and after the change, on the same clients and use cases, using selection and outcomes rather than call counts. Flowlines shows calls, users and sessions per tool before and after a release, so the comparison is quick.
| Measure | Before (synthetic) | After (synthetic) | Reading |
|---|---|---|---|
| Sessions where find_account was followed by search_customers | 140 | 35 | Fewer wrong first picks |
| Calls per completed account lookup, median | 3 | 2 | The agent finds the right path faster |
| Users calling search_customers | 210 | 228 | Usage did not drop after the merge |
These numbers are illustrative. A before and after comparison is observational: client updates, new users and seasonal jobs can move the same measures. See did an MCP tool change help? for the comparison rules.
Key takeaway: an unused or misused MCP tool is usually a naming, description or overlap problem, and usage data tells you which. MCP tool analytics in Flowlines shows calls, users and sessions for every tool by AI client, so tools with no calls and tools called over and over stand out. Read the MCP analytics guide for the broader measurement model, or see MCP observability for the product walkthrough.
Frequently asked questions
Why is my MCP tool never called?
Usually because the model cannot tell from the tool's name and description when to use it, another tool looks like a better match, or the client never offered it. Rule out a telemetry gap first, then test the description in each client you support.
How do I find MCP tools that are never used?
Compare the tools your server declares in tools/list with the tools that received calls in the same window, per AI client. A tool with no calls in any client is unused; a tool with calls in one client only points to discovery or permissions.
Why does the agent pick the wrong MCP tool?
Overlapping names and descriptions. When two tools both sound like they search customers, the model guesses. Look for sessions where one tool is called and immediately followed by a similar one for the same job, then merge the tools or sharpen the descriptions.
Why is the same MCP tool called many times in a row?
Pagination, retries after errors, empty or unhelpful results, or a missing filter. Check whether the arguments change between calls and whether an error came before them. Repeats with identical arguments usually mean the result did not tell the agent what to do next.
How many tools should an MCP server expose?
The MCP specification sets no maximum. Fewer, clearly distinct tools are easier for a model to choose between. Merge tools that overlap, remove tools nobody calls after checking why, and measure selection before and after the change.
Can Flowlines show which MCP tools are unused?
Yes. Flowlines shows observed calls, users and sessions for every tool it has seen, by AI client, and the tool path inside each session, so tools with no activity and tools called repeatedly stand out. Confirm your declared tool list before removing anything.