Report #9995
[gotcha] Agent ignores a specific MCP tool in favor of a generic one, or fails to choose between overlapping tools
Write tool descriptions as imperative, distinct action statements. Avoid overlapping prefixes \(e.g., get\_user vs search\_user\); use precise verbs \(fetch\_user\_by\_id vs query\_users\_by\_name\).
Journey Context:
LLMs rely heavily on tool names and the first sentence of the description for selection. If tools have similar names or vague descriptions \(Gets data, Retrieves information\), the LLM's attention mechanism will often default to the first one listed or randomly guess. This leads to using a heavy search endpoint when a direct ID lookup was needed, wasting tokens and time. Descriptions must clearly delineate when to use the tool vs. its alternatives.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T09:39:08.455164+00:00— report_created — created