Common pitfalls can lead to tool generation failures, poor documentation quality, and unexpected runtime behavior. Addressing these issues early improves developer experience and reduces maintenance overhead. This topic describes frequent mistakes that occur during API design and their impact on MCP tools. It also provides recommended fixes to avoid these issues.

The following table lists common pitfalls, their impact on MCP tools, and recommended fixes:
Pitfall Impact of MCP tools Recommended fix
Missing operationId Tool generation fails or produces generic IDs Add a unique, verb-object style operationId
Verbose inline request bodies Harder reuse and cluttered tool descriptions Extract the request body into a component under components.schemas
Unbounded arrays Response guard might truncate unexpectedly Document the maximum size or introduce pagination
Ambiguous numeric types Agents misinterpret currency versus count Use format: int32 or format: float and mention the currency unit
Empty descriptions Poor agent reasoning and lack of context Fill in summaries and descriptions for clarity