A developer asks the agent to show a deployment plan. It calls the tool that starts the deployment. Both tools contain "deployment" and both descriptions promise to manage it, so the model made a consequential choice without an explanation of the difference.

Tool naming deserves the care of a user interface. An MCP community discussion about overlapping tools asks how to balance compact outputs with a growing tool catalog, which becomes urgent when overlapping tools differ in whether they change a real system.

Diagnose the choice before adding instructions#

Capture the tool definitions presented on the failing turn, the request, and the selected arguments. A source file with the intended description does not prove the running client received it, since caches, adapters, and environment-specific tool lists change what the model sees.

Compare the competing tools. Does each description name the object, action, result, and any external effect? "Manage releases" is too broad for a read and a write; "read the proposed changes for an existing release" and "start the approved release job" convey different jobs.

Check defaults too. A tool that starts an operation when preview is omitted relies on the model remembering one optional boolean. When consequences differ materially, separate the operations or require an explicit action choice.

The MCP tools specification defines tool names, descriptions, and schemas. Those fields are an interface to the model and do not replace authorization or approval.

Use paired requests as a diagnostic#

Build an example set around one release: "show the proposed release," "compare it with the current deployment," "prepare the release request," and "start the approved release." The nouns are nearly identical while the expected operations differ.

Add an incomplete request: "take care of the release." The acceptable response is a read, a clarification, or a reviewable proposal; starting the deployment needs the authority your application normally demands.

Run these requests with the same model and tool definitions, and record the selected tool and arguments before judging prose. Saying "I will preview this" does not rescue a call to the execution tool.

Ambiguity	Interface repair	Test to retain
Same noun, different side effect	Put the action first in the description	Preview versus execute
One tool has many unrelated modes	Split distinct business jobs	Correct mode on sparse prompts
Two aliases do the same thing	Keep one canonical route	Stable selection after cleanup
Required identifier is unclear	Describe identifier source and format	Name versus immutable ID
Missing arguments trigger defaults	Make consequential choices explicit	Omitted field cannot cause a write

Reduce the working set carefully#

An agent preparing a release does not need every billing, people operations, and document design tool. A relevant subset eases the choice and must still include the reads that establish prerequisites.

Do not remove an inspection tool while leaving the execution tool visible: the agent can then act without checking its target. A hidden tool is still callable, so the server must enforce the same policy on direct calls.

Keep discovery separate from permission: a planner finds a tool in the catalog whose current identity cannot invoke it. Recovery is an explanation of the missing authority or an allowed alternative, never a broader credential the agent picks itself.

Repair old conversations as well as new ones#

Renaming a tool affects stored plans that use its previous name. Decide whether to keep a temporary adapter, reject the old name with a migration message, or restart the plan. Silently mapping an old read tool to a new write operation is dangerous.

A migration adapter preserves meaning, validates arguments, enforces current action policy, and returns an explicit incompatibility when no equivalent operation exists. The action lifecycle separates a requested action from its eventual result.

Keep the agent your developers use. Improve the definitions at the integration point, keep the paired requests as regression cases, and inspect action evidence for calls routed through Deixic. For sensitive operations, the approval guidance makes the target and proposed change reviewable.