mcp-server-craft

name	mcp-server-craft
description	Design and build an MCP server whose tools are narrow, typed, idempotent, and documented. Use when exposing any system to AI agents via the Model Context Protocol.
version	1.0.0
author	Zorost Intelligence
license	MIT
metadata	{"zorost":{"tags":["mcp","tools","agents","api-design","build"],"related_skills":["agent-loop-safety","spec-first-ai-feature"],"program_weeks":[16]}}

MCP Server Craft

1 · Purpose

Make the tools an agent calls as well-designed as any public API, because to the agent, the tool description is the documentation, and the schema is the contract.

2 · When to use

• Building an MCP server (or any tool layer) for agents.
• When an agent misuses a tool repeatedly, usually a tool-design bug, not a model bug.

3 · Inputs

• The system being exposed and its real operations.
• The agent task list: what the agent must accomplish, in verbs.
• An MCP client to test with (inspector, Claude Desktop, your Week-16 harness).

4 · Procedure

1. One tool, one verb. Name tools verb_noun: track_shipment, search_policy, request_refund. If a tool name needs "and", it is two tools.
2. Type every argument. Schemas with types, enums, ranges, and examples. The model fills what the schema describes; a vague schema invites a creative argument.
3. Write the description as a picker hint. First line: what it does. Then: when to use it, when not to use it, and what it returns. The agent chooses tools by this text alone.
4. Make reads idempotent and writes explicit. Reads never mutate. Writes take dry-run or confirmation parameters where the underlying operation is irreversible.
5. Return structured results, not prose. JSON the next step can consume: IDs, statuses, counts, plus a one-line human summary field.
6. Fail informatively. Errors return a code, a cause, and a next action ("lane not found, call list_lanes to enumerate valid lanes"). An agent that can read its errors can recover from them.
7. Paginate and bound. Any list operation takes limit and returns truncated: true when capped. An unbounded list_all is a context-window bomb.
8. Test from a real client, not just unit tests: connect an agent, give it the ten task list, and watch which tools it picks. Mispicks mean the descriptions failed, fix the text, not the model.
9. Version the server. Tool signatures are a contract; changing one is a version bump with a changelog entry.

5 · Anti-rationalization

Excuse	Answer
"The model is smart enough to figure the tool out."	The model reads the description you wrote, not the code you meant.
"One flexible query tool covers everything."	A do-everything tool is chosen for everything and validated for nothing.
"Errors can be plain strings."	The agent's next action is decided by the error text. Give it a next action.
"We'll document the tools later."	The description field IS the documentation the agent reads. Later never comes.

6 · Red flags

• Tools named handle_, process_, do_, verbs without meaning.
• Arguments typed as free strings where an enum or integer exists.
• A list tool with no limit parameter.
• Agents in testing call the wrong tool for a documented task.

7 · Verify

• Every tool has: typed schema, picker-hint description with a when-NOT line, structured output, informative errors.
• An end-to-end agent run against the ten-task list shows correct tool selection.
• The server version and changelog exist.

8 · ZoroLogistics example

Week 16's server ships four tools: track_shipment(id), list_lanes(origin?, destination?, limit=50), search_policy(query, limit=5), request_refund(shipment_id, reason, confirm=false). The refund tool with confirm=false returns the computed refund and requires_confirmation: true, the agent must re-call with confirm=true, which the harness routes to a human gate (agent-loop-safety). During testing the agent kept calling track_shipment with lane names; the fix was one line in list_lanes' description: "Use this to resolve lane names to IDs before tracking." Tool design is prompt design with types.

---

© 2026 Zorost Intelligence LLC · zorost.com