Designing MCP tools an agent won't misuse

The first article in this series introduced two key points about AI-native products. First, they are not chat widgets but MCP servers that let agents perform actions. Second, every tool an agent can invoke needs to have idempotency and typed, recoverable errors, as agents retry and fan out by default. Both of these assumptions relied on the use of typed schemas.

While validating inputs is essential (using Zod for input validation is a must), the article shifts focus to the misuse that can still occur even after successful input validation. Agents rarely send malformed JSON; they send well-formed, wrong data. The payload may pass all schema checks but still perform the incorrect action because language models reason from tool descriptions rather than reading developer documentation.

Typing inputs prevents garbage but does not stop a valid call that should not have been made. There are four ways that well-typed calls can still go wrong: selecting the wrong tool, providing valid-but-wrong arguments, issuing a call with wrong order or missing precondition, and encountering a failure with a stringified 500 error.

The good news is that these issues are not input-validation bugs but interface design bugs. The solution lies in designing the MCP surface to prevent these failures. The first lever is to constrain the input space rather than just typing it. Instead of using open types like strings, use closed types like enums. For example, instead of using a free string for fiscal zone, use an enum that specifies the exact options like peninsula, canarias, ceuta_melilla, eu, or world.

This eliminates spelling variations and ensures the model chooses from a predefined set of options. The second lever is to make the description and annotations part of the contract. The tool's description should be disjoint and imperative, clearly stating what each tool does and what it does not do. MCP provides machine-readable tool annotations that serve as advisory hints for the host.

These annotations can signal whether a tool is read-only, destructive, idempotent, or open-world. By leveraging these annotations, the host can take appropriate actions, such as auto-approving read tools, requiring human confirmation for destructive tools, and displaying idempotency hints for write tools. By applying these principles and utilizing the MCP surface effectively, developers can design their tools to prevent misuse and ensure a safer, more reliable user experience.