Design MCP tools

After building, successfully deploying, and monitoring your MCP server, the natural next step is to optimize it. You can unlock substantial performance gains by focusing on strategic tool curation, selecting, refining, and organizing tools to reduce overhead and maximize server efficiency.

This guide presents several tool curation principles for MCP server optimization and demonstrates how to use the curation features in Gram .

What is tool curation?

Tool curation involves choosing and organizing MCP tools to expose to LLM models. By carefully selecting, naming, and describing your tools for LLMs, you can manage context windows and prevent hallucinations. Tool curation combines technical optimization with prompt engineering and significantly impacts how well your MCP server performs in production.

Tool curation matters because:

• LLMs break down with too many tools: LLMs become unreliable when exposed to more than 30-40 tools. Beyond this threshold, they display tool hallucination (inventing non-existent tools) and perform irrelevant tool selections (using the wrong tools for tasks). These failed attempts and incorrect tool calls increase computational overhead and API costs.
• Tool descriptions have a greater impact than model choice: Optimizing your tool descriptions and names can have a bigger impact on the quality of your MCP server  than the underlying LLM models your users choose. A well-curated toolset with clear descriptions will outperform a comprehensive but poorly organized toolset, even when using smaller, cheaper models.
• Every tool name and description becomes part of the prompt that guides LLM decision-making: Tool curation works like prompt engineering for tools. Similar to crafting effective prompts, tool curation requires understanding how LLMs process information and make choices.

When do you need tool curation?

Just like premature optimization in software, curating tools too early can be a waste of effort if you don’t yet understand real user behavior. Instead, wait until clear warning signs emerge that indicate tool curation is needed, such as:

• Tool hallucination: The LLM invents non-existent tools.
• Irrelevant tool selection: The LLM uses tools that aren’t suited to the current goal.
• Increased end-user costs: MCP clients make many failed attempts and incorrect tool calls.
• Agent confusion: Tasks that should be simple require multiple attempts.
• Context window exhaustion: Tool definitions consume too much available context.

How to do tool curation effectively?

The best place to begin tool curation depends on how you built your MCP server.

If you generated your MCP server from an API (using a tool like FastMCP), start by editing your code directly. For example, you can add detailed docstrings or update function metadata.

If you generated your MCP server from an OpenAPI document (using a tool like Speakeasy ), rather start by editing the OpenAPI document itself. Use the following principles to edit OpenAPI documents for effective tool curation:

Group tools by workflow, not API structure

❌ Resource-based grouping: API documentation often organizes endpoints by resource type, because it makes sense for developers reading technical documentation.

However, organizing API endpoints by resource type forces agents to jump between tool categories to complete simple workflows. For example, an agent trying to create a support ticket for a customer must search through the User Management Tools, then switch to the Ticket Management Tools, potentially missing the connection between related operations.

✅ Workflow-based grouping: Because agents think in terms of tasks and workflows, rather organize the endpoints according to workflows. This lets agents complete entire tasks without switching contexts or hunting through unrelated tool categories. Each toolset represents a specific workflow.

Include dependency tools in each toolset

❌ Missing dependencies: Many tools require information from other tools to function properly. If you indicate the required information, most developers know how to find it.

However, when you exclude prerequisite tools from a toolset, agents can get stuck with incomplete information and fail to complete workflows. For example, if an agent trying to create a license doesn’t know how to find the required user_id or determine valid license_type values, the workflow breaks down immediately.

✅ Complete dependency chain: Rather create a toolset that supports the complete workflow, from discovery through validation, ensuring agents have all the information they need to succeed.

Use clear, consistent naming patterns

❌ Mixed conventions: Using varying punctuation and synonyms doesn’t impair most developers’ understanding of tools.

However, inconsistent tool names create cognitive overhead for agents. When agents learn patterns, they expect consistency. Mixed conventions force agents to memorize individual tool names rather than predicting them. For example, the above tools all retrieve customer information but the use of camelCase, snake_case, and different verbs makes it harder for LLMs to discover and remember them.

✅ Consistent patterns: Rather use predictable naming patterns for related tools. For example, the consistent search_* and get_* patterns help agents predict tool names and understand the distinction between searching (finding multiple results) and getting (retrieving specific items) information.

Write descriptions for agents, not humans

❌ Technical descriptions: The descriptions in API documentation usually target developers who understand technical implementation details.

However, agents need less technical information and instead require task-oriented descriptions that explain when and how to use tools within larger workflows. The example above describes the technical implementation but provides no guidance about when and how to use the tool.

✅ Task-oriented descriptions: Rewrite the description for agents by specifying the scenarios when they should use the tool and any preparatory tasks they first need to perform. For example, the following description tells agents exactly when to use the tool, what preparation is needed, and how it fits into customer service workflows.

Provide workflow context in descriptions

❌ Isolated descriptions: Developers know that tools rarely exist in isolation, and intuitively understand the larger workflows they form a part of based on their descriptions.

However, these descriptions treat each tool as independent, providing no guidance about workflow relationships or sequencing.

✅ Workflow-aware descriptions: Add workflow context to descriptions to help agents understand how tools connect and which actions come before or after each tool call. For example, the following descriptions help agents understand tool relationships and natural workflow sequences.

Avoid the “everything” toolset

❌ The giga-toolset: You may be tempted to save time by including every available tool in a single toolset.

However, this overwhelming collection forces agents to process irrelevant options for every task, slowing down decision-making and increasing error rates. One way you can prevent this decision paralysis is by organizing your toolsets according to user personas. For example, a customer service agent might only need the tools for listing tickets, listing customers, viewing customers, and adding internal notes.

✅ Focused toolsets: Instead of exposing the agent to all the tools in your MCP server, create a focused toolset to prevent it from spending more time analyzing options than completing actual work. In the following example, each toolset has a clear purpose and contains only the tools relevant for that purpose, enabling faster agent decision-making with fewer errors.

Tool curation in Gram

Gram  is a platform built by Speakeasy that helps you create, curate, and host MCP servers. You upload your OpenAPI document, then the platform generates tools based on your endpoints and allows you to curate them into a toolset.

Gram supports tool curation by enabling you to:

• Combine just the tools you need into streamlined toolsets – even from multiple sources
• Edit tool names and descriptions in the UI to provide improved context for LLMs

Taskmaster Demo

To demonstrate tool curation in Gram, we’ll use the Taskmaster Internal API .

When you upload the OpenAPI document, openapi.yaml from the Taskmaster Internal API project, the default toolset includes tools from different domains: Customer-Service, Marketing, and Licenses.

If you use the Taskmaster MCP server as is for a customer service agent (without curating the tools), you can deploy and install it in your MCP client without issue. However, you encounter problems when prompting your MCP client, for example, to create a user.

Claude notices the different possibilities and asks for confirmation. This may work well for interactive use, but automatic agents either stop the thought process or use the tool that seems most adequate, increasing the risk of making an error.

Instead, you can reorganize the Taskmaster MCP server by creating a specific workflow-optimized toolset. In this case, you should enable only the tools necessary for a customer service workflow that allows a customer service agent to:

• List tickets
• Create and validate licenses
• Retrieve user information

This focused toolset reduces tool confusion and improves agent decision-making.

After organizing the toolset, you can edit individual names and descriptions to provide more clarity on what each tool does. Hovering over a tool name or description reveals an Edit button to allow you to update the relevant information.

Click Edit to open the editing modal and enter more descriptive values based on the tool curation principles from the previous section.

Conclusion

In this guide, you explored how to optimize your MCP server through tool curation. By narrowing your toolsets to only the essential tools, you not only improve the experience for both users and agents but also lower costs — since even smaller models with shorter context windows can perform effectively with a focused set of tools.

MCP server optimization extends beyond tool curation. You can monitor your MCP server to identify other optimization opportunities through data analysis.