Why Coding Agents Ignore Your MCP Server: 8 Discoverability Fixes for 2026

Key takeaways

• A working MCP server is not the same as a discovered one. In a May 2026 demo, an agent passed 7 of 9 tasks without calling a single MCP tool, because it solved the problems itself.
• With tool search on, your tool names and descriptions act as the search index. Vague names like process and format lose.
• Schema size is a trade-off. Richer descriptions cost tokens (about 300 rose to about 1,600 in the demo) but fixed the skipped calls.
• You can't watch every agent your users bring, so write evals that assert on tool calls, not just final answers.
• An agent that skips your server also skips your guardrails. Discoverability is partly a safety problem.

The problem: the agent just does it themselves

Here is the failure mode. You build an MCP server, connect it to Claude Code or another coding agent, and ask for something your tools handle. The agent writes a shell one-liner or reasons through the task in text. Your server sits there, idle.

This was the core demo in a talk at MCP Dev Summit North America 2026 by Red Hat engineers Wesley Chun and Calum Murray, written up by the Agentic AI Foundation. Their test server had four text tools named process, transform, convert and format, with no type hints and no useful descriptions. Seven of nine tasks passed. But the assertions that checked for tool calls showed the agent never touched the server. After the tools were renamed and properly described, all nine tasks passed with the tools actually in use.

That's the uncomfortable part. Your tests can be green while your server is dead weight.

Below are eight fixes, roughly in the order I'd apply them. A caveat on scope: the research here is strongest for Claude Code. I haven't verified deferred loading or tool search behavior in Cursor, Codex, Gemini CLI or Copilot, so test those yourself.

Fix 1: Name tools like a person would search for them

Agents pick tools partly by name. process could mean anything. convert_markdown_to_html means one thing.

A few habits that help:

• Put the verb and the object in the name (create_calendar_event, not create).
• Use the vocabulary your users use in prompts, not your internal service names.
• Avoid generic verbs shared across many servers. If three servers expose search, the agent has no reason to choose yours.
• Prefix with the domain when it's not obvious (k8s_scale_deployment).

This is the cheapest fix on the list. It costs almost no tokens and it was half of what turned the Red Hat demo around.

Fix 2: Write descriptions as if they were a search index

Claude Code now withholds tool definitions from context by default and lets the agent search the catalog to load what it needs. That changes what a description is for. It isn't documentation a human skims. It's the text a retrieval step matches against the user's request.

A Cyrus guide from January 2026 puts it plainly: the more specific and keyword-rich a tool description is, the better Claude finds the tool. So write descriptions that include:

• What the tool does, in one plain sentence.
• The nouns a user would mention ("pull request", "deployment", "invoice", "CSV").
• When to use it, and when not to, especially if a shell command could do something similar.
• What it returns.

A weak description: "Processes data." A better one: "Converts a CSV file to JSON. Use when the user asks to transform tabular data into JSON objects. Returns an array of row objects."

One addition that's my own suggestion rather than something from the research: also mention your server in the project's agent instructions file (CLAUDE.md, AGENTS.md or similar) for the two or three tasks it should always handle. Instructions in context are a more direct nudge than hoping search finds you.

Fix 3: Budget your schema tokens honestly

In the Red Hat demo, schema tokens rose from about 300 to about 1,600 after the tools were described properly. That's more than five times the cost, and it was worth it, because the tools went from ignored to used.

But the budget is real on the other side too. Claude Code's docs say 50 tools can consume 10 to 20K tokens, and that selection accuracy degrades beyond roughly 30 to 50 loaded tools. A GitHub issue asking for lazy loading cited a baseline cost of about 67k tokens, cut to about 10k.

So the answer isn't "make everything longer." It's:

• Fewer, sharper tools. Merge near-duplicates.
• Long descriptions where they decide whether the tool gets picked, short ones where the name is already obvious.
• Don't ship 80 endpoints as 80 tools just because your API has 80 endpoints.

Fix 4: Check how tool search is configured

If you maintain a server and your users run Claude Code, know what their client does with your definitions. From the docs:

• Tool search is on by default.
• It falls back to loading everything upfront on models earlier than Opus 4 and Sonnet 4, and on Microsoft Foundry deployments hosted on Azure.
• The ENABLE_TOOL_SEARCH environment variable accepts true and auto. With auto, definitions stay upfront until deferrable definitions reach 10% of the context window. auto:5 lowers that threshold to 5%.
• Setting CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS keeps tool search off.

# Always defer tool definitions and search for them
export ENABLE_TOOL_SEARCH=true

# Load upfront until deferred definitions hit 5% of context
export ENABLE_TOOL_SEARCH=auto:5

Why this matters for discoverability: when your tools load upfront, the name matters but the agent sees everything. When they're deferred, a poor description means the agent may never search for the right keywords. You need to test both modes, because your users will be in both.

Fix 5: Don't assume code mode replaces your tools

There's a popular idea that agents scale better by writing code against MCP servers instead of calling tools one at a time. The MCP discussion thread on code execution argues that this bypasses the context window and turns servers into little more than APIs.

Red Hat's numbers on their Kubernetes MCP server are a cold shower:

• On Opus 4.6, switching to code mode dropped the task pass rate from 87.5% to 41.6%.
• Adding an API-search tool brought it back to 91.6%, at 4x the token cost.
• When both code mode and standard tools were available, agents used code mode only 6% of the time.

Two lessons. First, if you offer a code-mode interface, don't remove the plain tools. Second, agents have strong habits. They reach for what they know, and that's usually a shell or a normal tool call. If you want them on a new path, you have to make that path obviously better and easy to find.

Fix 6: Absorb failures inside the server

Discoverability doesn't end at the first call. The Red Hat team found some odd behavior after calls went wrong:

• Longer tool descriptions improved call success, but agents gave up faster when a call failed.
• Leaner schemas led to more retries. The team says it doesn't know why, and that it held across models.
• When an update was rejected, some agents deleted and recreated the resource. The end state looked right, so only assertions on tool calls caught it.

Their fix for the last one was to handle update conflicts inside the server, so the agent never sees a rejection it might improvise around. I'd generalize that. Return error messages that tell the agent what to do next ("resource version changed, re-fetch and retry"), and put retry or merge logic on your side wherever you can.

There's a plain-performance cousin of this too. Microsoft's Q&A guidance on agent-to-agent MCP calls notes that they can add latency and that a default 60-second timeout often gets hit. Slow tools get abandoned.

Fix 7: Write evals that assert on tool calls

This is the fix that makes the other seven provable. You can't instrument every agent your users bring, so you need a repeatable way to check what any agent does with your server.

The Red Hat team built MCP Checker for this. It's an open-source eval framework that proxies and logs every MCP interaction. Scenarios are written in YAML and can run in CI, and it works with any agent. Their demo drove Claude Code through the Agent-Client Protocol.

Whatever tool you use, the pattern is:

1. Write 10 to 20 realistic user tasks your server should handle.
2. Run them through at least two different agents and two model sizes.
3. Assert that the right tool was called, with the right arguments. Don't only assert on the final answer.
4. Re-run after every rename or description change, and track the pass rate.

A task where the agent solves it by itself is a failure for your server, even if the answer is correct.

Fix 8: Make discovery deliberate, and guard the bypass

There's a security angle here that a pure growth mindset misses. One thread in r/ClaudeCode makes the point bluntly: an agent autonomously discovering and invoking tools it wasn't explicitly granted access to is a security problem, not a feature. Endor Labs makes a related argument, noting that an MCP server can execute in the agent's environment and, like a malicious dependency, do harm or steal data.

So discoverability needs a counterweight:

• Be discoverable to agents your users have approved, not to everything. Use allowlists or an MCP gateway where your environment supports it.
• Remember the flip side from the Red Hat talk: an agent that bypasses your server also bypasses your safety logic. If your Kubernetes server has guardrails but the agent runs kubectl directly, those guardrails never fire. Where the stakes are high, enforce limits with sandboxes or hooks, not just with a well-named tool.
• Keep tool permissions narrow. A tool that's easy to find and can do anything is worse than one that's hard to find.

A quick checklist

Beyond the protocol: being recommended by coding agents

MCP discovery is one half of a bigger question for developer-tool and API companies: when someone asks a coding agent which SDK or service to use, does yours come up? That's a separate visibility problem from tool search. Platforms like Promptwatch track how Codex, Claude Code and OpenCode recommend tools, SDKs and docs, which gives you a read on whether your docs and positioning are reaching agents at all.

If you want to compare other options, the GEO software directory at bestgeosoftware.com lists tools in the category.

Where to start

Do Fixes 1 and 2 this week. Rename your three most important tools, rewrite their descriptions with real user vocabulary, and run a handful of tasks through an eval that checks tool calls. If the pass rate with calls asserted goes up, you've found your problem. The Red Hat demo went from 7 of 9 hollow passes to 9 of 9 real ones with exactly that change, and the cost was about 1,300 extra schema tokens.