MCP Tools: What They Are and How to Build Them Right (2026)

MCP tools are the reason AI agents can do more than generate text. They let models query databases, call APIs, read files, and trigger workflows through a standardized protocol that works across Claude, Cursor, ChatGPT, and dozens of other clients. But here's what the official spec doesn't tell you: most MCP tools in production today are poorly described, bloat your context window, and break across clients.

This guide covers what is mcp tools, how to build them so they work reliably, and how to manage them at scale without burning through your context budget.

What Are MCP Tools?

MCP tools are executable functions exposed by MCP servers that allow AI models to interact with external systems. Think of them as the "hands" of an AI agent. While the model handles reasoning and language, tools handle action: querying a database, creating a GitHub issue, sending a Slack message, or analyzing application metrics.

The Model Context Protocol defines three core primitives that servers can expose to clients: tools, resources, and prompts. Understanding the differences matters because choosing the wrong primitive leads to wasted tokens and unreliable behavior.

The key distinction: MCP tools are model-controlled. The LLM reads the tool's name, description, and input schema, then autonomously decides when to call it. Resources and prompts require explicit human or application triggers. Understanding the relationship between mcp tools resources prompts is essential because many developers misuse prompts as tools or expose read-only data as tool calls, wasting tokens and adding decision overhead. This means your tool description is the single most important factor in whether the model uses it correctly, because it's the only information the LLM has when making that decision.

MCP tools support a straightforward lifecycle. The client calls tools/list to discover available tools and their schemas. When the model decides a tool is needed, it calls tools/call with the appropriate parameters. The server executes the function and returns results as text or structured content. This how clients discover and invoke tools pattern is consistent across all MCP-compatible clients.

Why MCP Tool Descriptions Matter More Than You Think

One developer audited Anthropic's official MCP servers and published the results: the Filesystem server scored 81/100, with 72% of its parameters having zero descriptions. That's the official reference implementation. Community-built servers are often worse.

This isn't a cosmetic problem. When an MCP tool description is vague or missing, the LLM guesses. And guessing with tool calls means wrong parameters, failed executions, and wasted tokens on retries.

We analyzed over 40 discussions where developers share what breaks in their MCP tool setups. The pattern is consistent: poorly described tools create cascading failures that show up as mysterious agent behavior, not obvious errors.

MCP tool annotations provide metadata beyond the description that helps clients make smarter decisions about tool usage. Annotations can signal whether a tool is read-only or destructive, whether it's idempotent, and whether it requires human confirmation before execution. The MCP spec defines annotations like readOnlyHint, destructiveHint, and openWorldHint that clients use to build safety guardrails. Without these mcp tool annotations, clients treat every tool call the same, which means either too many confirmation prompts or too few safety checks.

The best MCP tool descriptions follow a predictable structure. They start with what the tool does in one sentence, specify the exact format and constraints of each parameter, and describe what the output looks like. For tool description best practices for production environments, specificity beats brevity every time.

How MCP Clients Discover and Invoke Tools

Every MCP interaction starts with discovery. When a client connects to an MCP server, it calls tools/list (also referred to as mcp list tools) to get the complete mcp tools list of available tools, their descriptions, and their JSON Schema definitions. This is where tool overload begins, because every tool in that list consumes context window space just by existing.

The invocation flow works in three steps:

1. Discovery: Client calls tools/list, server returns all available tools with schemas
2. Selection: The LLM reads tool descriptions and decides which tool fits the current task
3. Execution: Client calls tools/call with the tool name and arguments, server executes and returns results

Different clients handle this differently. Claude Code mcp tools load schemas at session start and keep them in context throughout. Cursor mcp tools use a similar approach but with different schema validation rules, which is why a tool that works in Claude Desktop can fail silently in Cursor. The mcp tool output schema also varies by client, with some clients expecting plain text and others parsing structured JSON.

The tools/list response includes a cursor field for pagination, which matters when your MCP tools server exposes dozens of tools. But most clients today fetch the full list at startup, stuffing every schema into the context window whether the model needs it or not.

The Tool Overload Problem: Why More Tools Means Worse Performance

One developer put it bluntly: they "got tired of the '100 MCP servers' approach." And they're not alone. Across the discussions we analyzed, tool sprawl emerged as the most common pain point for teams running MCP in production.

The problem is straightforward. Every MCP tool added to a session costs context tokens, and those costs compound. A developer building a truncation proxy for Claude Code reported that "token usage was getting silly" because single tool calls were dumping raw HTML, base64 images, and massive JSON into the context window. Another noted that their "context window fills up" after just a few tool interactions, forcing early session compaction.

Here's what actually happens when you load too many tools:

• Token overhead: Each tool's name, description, and schema consume 200-500 tokens. With 50 tools, that's 10,000-25,000 tokens before the model even starts reasoning
• Decision degradation: Models become worse at picking the right tool as the number of options increases. One developer found that "anything with more than 3-4 params" caused the model to guess instead of asking
• Output bloat: Tool responses get "dragged around in context" and multiply when the model spawns subagents

Teams are solving this in different ways. The MCP Wrapper Pattern exposes only three discovery tools instead of the full toolset, letting the model search for relevant tools on demand. You can also reduce tool overload with dynamic loading patterns that fetch tool schemas only when needed, or optimize tool output with compression to shrink responses before they enter the context. For parallel workloads, you can run tools in parallel for 10x speed without multiplying context costs.

The root issue is architectural. Loading every tool into every session treats MCP like a flat menu when it should be a searchable registry. Teams building production agent systems need a way to scope tools per task, compress outputs, and route requests through a gateway that manages the full tool lifecycle.

Building Production-Ready MCP Tools

Knowing what breaks in production tells you exactly what to build. The community data points to three areas where most MCP tools fail: descriptions, schemas, and error handling.

Write Clear Tool Descriptions

Your tool description is the prompt the LLM reads to decide whether to call your tool. A bad description means the model either ignores your tool entirely or calls it with wrong parameters.

Structure every description with three parts:

• What it does (one sentence, specific verb): "Retrieves the 10 most recent commits from a specified GitHub repository branch"
• Required context (what the model needs to know): "Requires a valid repository owner and name. Returns commit SHA, message, author, and timestamp."
• Output format (what comes back): "Returns JSON array sorted by date descending"

Compare that to the real description from a popular MCP server: "Gets commits." That's what 72% of production tools look like.

Design Minimal Schemas

Keep input parameters under 4. Every additional parameter increases the chance the model guesses instead of asking. Use enum constraints wherever possible, because they turn an open-ended guess into a selection from valid options.

Mark optional parameters as required: false explicitly. Many MCP clients handle implicit optionality differently, which is why tools "worked fine in Claude Desktop" but broke in other clients.

Handle Errors with Context

Return error messages that tell the model what to try next, not just what went wrong. "Repository not found" is useless. "Repository 'owner/repo' not found. Verify the owner and repository name are correct, or check if the repository is private" gives the model a recovery path.

You can validate your tool definitions before deploying them to users. Test your tool definitions with MCP Inspector to catch schema issues, missing descriptions, and parameter validation gaps before they reach production.

Popular MCP Tools and Servers in 2026

The MCP ecosystem has grown from a handful of reference implementations to hundreds of servers covering development, data, APIs, and monitoring. Here are the categories that matter most for teams building AI agents, along with the tools developers actually use in production.

MCP Gateways and Infrastructure

Apigene connects any API or MCP server to AI agents through a single gateway. Instead of configuring dozens of individual MCP servers, teams route all tool calls through one endpoint that handles dynamic tool loading, compressed tool output, and access controls. It also renders full UI components inside ChatGPT and Claude through the MCP Apps standard, so tool responses aren't limited to plain text. For teams running 19 real-world tool implementations, a gateway approach eliminates the configuration sprawl that developers consistently complain about.

Development Tools

Browser-tools MCP (1,000+ monthly searches) gives AI coding assistants access to browser DevTools data like console logs, network requests, and DOM snapshots. Filesystem MCP provides file read/write capabilities. Git MCP connects to repositories for commit history, diffs, and branch management. These are the top servers ranked by tool capabilities for coding workflows.

Data and Database Tools

Servers for PostgreSQL, SQLite, and MongoDB let LLMs query databases directly. Supabase MCP tools expose both database and auth functionality. These tools benefit the most from clear descriptions because SQL generation requires precise parameter documentation.

API Connectors and Monitoring

Zapier's MCP server connects to 6,000+ apps. New Relic's MCP tool reference provides observability tools for metrics analysis. Linear and Atlassian MCP tools connect project management workflows to AI agents.

You can browse 251+ servers by tool type to find tools for your specific stack, or check the 100+ verified official servers in the community directory.

Managing MCP Tools at Scale

The gap between "MCP tools work on my laptop" and "MCP tools work for my team" is where most production deployments stall. We analyzed discussions from engineering teams managing 10+ MCP servers, and three operational challenges dominate.

Secrets and Configuration Management

Teams can't commit .mcp.json files because they contain API tokens. Managing 10+ environment variables across team members requires full application restarts on every change. One engineering lead described the problem as an "implicit dependency graph" where required MCP servers and their auth requirements "live in peoples heads" instead of being declared anywhere.

The deeper issue is that MCP has no concept of a project-level manifest. There's no package.json equivalent that declares "this project needs these 5 MCP servers with these auth requirements." Every team member configures servers manually, and onboarding is a copy-paste ritual that breaks when config paths change.

Security and Access Controls

Developers report API keys "showing up in the context window" and worry about data leakage. Others warn about prompt injection risks from compromised MCP servers. One developer stopped installing community servers entirely after examining what was hidden in SKILL.md files: non-binary payloads designed to manipulate agent behavior.

Production deployments need gateways that manage tool access, rate limiting, and audit trails. A gateway approach lets you enforce allowlists, redact secrets before they reach the model, and log every tool call for compliance. You can also aggregate tools from multiple servers into a single managed endpoint instead of exposing raw server connections to the LLM.

Cross-Client Compatibility

A tool that works in Claude Desktop may break in Cursor, VS Code Copilot, or ChatGPT. The root cause is inconsistent JSON Schema validation across clients. Optional fields, $ref combinations, and enum handling all vary. Desktop updates can silently change config lookup paths, breaking custom MCP servers overnight. One developer recommended "pinning config to your project's .claude/settings.json" to survive these changes.

The fix is testing across clients before shipping and sticking to the simplest JSON Schema constructs: flat objects, explicit types, no $ref, no oneOf. If your tool works with the strictest validator, it'll work everywhere.

The Bottom Line

MCP tools give AI agents the ability to act, not just talk. But the gap between a working demo and a reliable production deployment is wider than most teams expect. Tool descriptions are the make-or-break factor for LLM accuracy. Context bloat from tool schemas and outputs is the primary cost driver. And managing secrets, config, and cross-client compatibility becomes operational overhead that scales with every new tool you add.

The pattern that works: write specific descriptions, keep schemas minimal, compress outputs, and route everything through a gateway that handles loading, security, and observability. Apigene provides that gateway layer, connecting any API or MCP server to AI agents through a single endpoint with dynamic tool loading, compressed outputs, and UI rendering inside the chat. If you're building agent products that need reliable tool integrations without the infrastructure tax, explore Apigene's MCP Gateway.