Lessons Learned Designing MCP Tools for AI Agents
How the FlurryPORT developer discovered why AI agents ignored their MCP tools, and the practical design lessons that fixed it.
The developer behind FlurryPORT built what seemed like a straightforward Model Context Protocol (MCP) integration by reusing existing application APIs. But when testing with a rival coding AI, the agent ignored the provided tools entirely and tried inventing its own ways to send and receive webhooks. This surprising result led to a round of direct questioning and a pre-build design review with the AI, surfacing several concrete lessons.
Key findings included that AI agents respond better to structured, actionable data than raw numbers; verbose guidance prose gets ignored while simple tool affordances get used; and error states should be conveyed via machine-readable codes rather than free-form text. Partial successes create what the reviewing agent called "explanation debt," state transitions (like an anonymous-to-account conversion) need explicit mapping or agents waste minutes rediscovering context, and one-time notifications should become durable response fields rather than single events that can be missed.
The redesign produced measurable improvements: rejected requests during an 80-event bulk run dropped from about 50 to zero, the full anonymous-user funnel shrank from 20 minutes to 7, post-signup re-orientation fell from 4 minutes to 21 seconds, and local echo-receiver setup dropped from over a minute and a half to 3 seconds. The author emphasizes that having an AI agent review the design before building proved far more valuable than post-hoc debugging.
The case is a cautionary tale for engineers building MCP tools: technical correctness doesn't guarantee an agent will actually choose your tool. Descriptions, data shapes, and error codes function as a real routing layer that directly shapes agent behavior.