3 MCP Tool Design Patterns for Production

The first test of an MCP server can feel incredible. You expose a few tools, connect an AI assistant, and it works. Then real users connect their assistants, you add more capabilities, and the behavior gets less predictable.

An assistant picks the wrong tool, sends invalid inputs, or gets stuck in a retry loop. From the user’s perspective, it looks like their assistant doesn’t know how to use your product.

Before blaming the model, I’d look at the tools. Three design patterns can make it easier for an assistant to choose the right operation, recover from an error, and understand what a call will change.

1. Give each tool one clear purpose

Imagine a tool called subscription_manager. Depending on an action setting, it can look up a subscription, change the plan, or cancel it. Its inputs include an optional new plan, an optional cancellation date, and other settings.

To a developer, one flexible tool can feel clean and reusable. But the assistant has to work out which inputs belong to each action. When that relationship is unclear, it guesses.

I’d split that example into three focused tools:

• get_subscription retrieves the subscription details.
• change_subscription_plan asks for the new plan.
• cancel_subscription asks when to cancel.

Each tool has a clear purpose and the inputs relevant to that purpose. Changing a plan might still involve several internal API calls. A focused tool can handle a substantial workflow as long as it serves one clear job in the product.

The same thinking applies to responses. When the assistant asks for subscription details, return what it needs to decide the next step. Sending the customer’s entire database record adds information it has to sort through.

2. Write errors that help the assistant recover

A response that says “Bad request” tells the assistant that something failed. It gives very little help with what to do next.

Treat the error message like a quick coaching tip. Explain what went wrong and how to fix it. If the tool expects YYYY-MM-DD and receives a date in MM-DD-YYYY format, a useful response is: “Invalid date format. Use YYYY-MM-DD and try again.”

Now the assistant has a specific correction to make. It can change the input instead of repeating the same failed call or trying unrelated variations.

Other errors need the user’s help. If the user lacks permission to perform an action, say that clearly. Retrying the same request won’t change their access. The response should help the assistant recognize that it needs to stop and involve the user.

3. Explain consequences and check approval on the server

Your product may be one of many services connected to an assistant. The assistant application controls which tools it loads. You control how clearly your server describes those tools and what happens when they’re called.

For example, cancel_subscription needs to explain whether it ends access immediately or stops the next renewal. That distinction belongs in the tool description so the assistant can match the operation to the user’s intent.

For a sensitive action that needs approval, show the user what will change. A project-deletion tool could first return a preview naming the project and explaining what will be removed. Your product records the user’s approval, and the server checks that approval and the user’s permissions before deleting anything.

Duplicate prevention needs its own check. A user can approve an operation, the server can complete it, and the response can still get lost. If the assistant retries, the server should recognize the repeated request and avoid doing the work again. Approval alone doesn’t handle that case.

Once the tools are designed, test them through the assistants your users connect. Include invalid inputs, missing permissions, and a repeated request after a lost response. Watch whether the assistant corrects its input, asks for help, or keeps trying. Those failure paths tell you where the tool still needs work.