Report #15061
[gotcha] Agent reasoning loops caused by overlapping or ambiguously named MCP tools
Consolidate overlapping tools into a single tool with an enum parameter \(e.g., \`execute\_operation\(operation: 'read' \| 'write'\)\` instead of \`read\_thing\` and \`write\_thing\`\). Ensure tool names are highly distinct.
Journey Context:
When tools have similar names or overlapping capabilities \(e.g., \`search\_code\`, \`find\_file\`, \`grep\_repo\`\), the LLM struggles to differentiate them based on short descriptions. It picks the wrong one, gets an error, switches to another, fails, and enters a reasoning loop. Consolidating them forces the LLM to reason about the operation first, then the parameters, drastically reducing selection entropy and token waste.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T23:09:32.774555+00:00— report_created — created