A ledger of AI tools and building sites for overseas traffic.

Home / Workflows & MCP / Writing an MCP Server: Four Constraints for Tool Design

Writing an MCP Server: Four Constraints for Tool Design

More tools make the model dumber. Four constraints to keep your server "few but precise" instead of "complete but unused".

Sep 23, 2026 4 min read naket.top Updated 2026-09-29
Writing an MCP Server: Four Constraints for Tool Design

The most common way an MCP server fails isn't a technical problem — it's "I gave it ten tools and the model doesn't want to use a single one." The cause is vague descriptions, oversized returns, or overlapping responsibilities between tools.

Constraint 1: Keep the tool count at 3–5

Every tool description takes up context. On a server with ten tools, the descriptions alone can eat several thousand tokens, and on top of that the model has to choose among them — the cost of choosing is higher than the cost of executing.

For a knowledge base server, three tools are enough: search, read, list directory.

Constraint 2: Write "when to use it", not "what it is"

Bad: search_notes: search notes Good: search_notes: search the titles and body text of local notes by keyword; use when the user asks "what did I write down before" or needs to cite their own old notes

The difference is that the latter tells the model the trigger condition.

Constraint 3: Returns must be small and carry location

Returning a whole article burns context. The usable shape is "top 3 hits + a snippet for each + the line number":

{
  "hits": [
    {"path": "70-servers/3x-ui.md", "line": 12, "snippet": "…salamander…"}
  ]
}

With line numbers, the model can do a second read of the exact range instead of swallowing the whole document.

Constraint 4: Error messages must guide the next step

Bad: {"error": "failed"} Good: {"error": "file not found", "hint": "use list_tree to confirm the path; note that the 98-clippings directory is excluded"}

The model won't guess; it just follows the hint. Writing error messages concretely is effectively pushing troubleshooting knowledge down into the tool layer.

A counterexample

My first version had seven tools (search, tags, date range, stats, export…), and the model ended up using almost only search. After cutting it down to three, usage actually went up.

Tools aren't better when there are more of them; they're better when they're more precise.

One more: don't build a "do-everything tool"

A tool like run_shell(command) looks powerful but is actually a disaster: the model crams complex logic into a single command, and when it fails you can't tell from the return value which step went wrong.

The right approach is to split it into tools with semantics: list_files, read_file, search_text. Each tool does one thing and returns a fixed structure — that's what the model can learn.

How to write parameters

Parameter names should be self-explanatory: q is worse than keyword, p is worse than path. Prefer enums over free-form strings — format: "json"|"text" cuts misuse in half compared with format: string.

Versioning and compatibility

Changing a tool description changes model behavior; it's the same as changing an interface. Adding tools is fine, but be careful about renaming parameters on existing tools — better to add a new tool, mark the old one deprecated, and delete it after it has run for a while.

In one sentence

An MCP server succeeds or fails not on the protocol implementation but on whether the tool descriptions read like a manual written for a newcomer.

A real case

I built "read the database" as a single query(sql) tool, and the model quickly started stitching together complex joins, getting nothing but "syntax error" when it failed. After splitting it into list_tables, describe_table, and sample_rows(table, limit), the model could work its way through step by step — because every step returns something definite.

The conclusion is blunt: tool granularity determines the model's success rate, not whether the model is smart enough.

One last practice: local first, remote later

A local stdio version has the lowest debugging cost — logs go straight to the terminal, and you restart immediately after changing a line. Once the tool semantics are stable, wrap it into a remote HTTP service and add auth and rate limiting. Do it in the opposite order and you'll burn most of your time chasing network problems.

MCPtool designprotocol

Further reading

MCP Specification ↗