Lesson 05 — Tools: Design, Schemas, Errors

Pydantic models, structured errors, and tool ergonomics.

MCP Servers Module 2

Why move beyond @mcp.tool() decorators

The pkb.search tool we'll add

from pydantic import BaseModel

class SearchArgs(BaseModel):
    query: str
    limit: int = 10

@mcp.tool()
def search(args: SearchArgs) -> list[str]:
    """Search notes by full-text query."""
    ...

The LLM sees a schema with query (required) and limit (optional, default 10) — derived automatically from the Pydantic model.

What Pydantic gives you for free

• Type coercion — "42" → 42 when the field is typed int.
• Validation errors with field paths — the client sees exactly which field failed.
• Default values — declared inline on the model.
• Optional fields — typed as Optional[...] or with a default.
• Enums — constrain values via Literal["draft", "published"].

Designing tool names

• noun.verb style — e.g., pkb.search, not pkb_search.
• Lowercase — consistency, easier to type, no case-sensitivity surprises.
• No spaces — tool names are identifiers, not labels.

Why noun.verb? It matches the convention many official servers use, and the dot acts as a namespace — pkb.search and github.search are clearly different tools, even if the verb collides.

Designing tool descriptions

• The description is what the LLM reads to decide whether to call the tool.
• Be specific — "Search notes by full-text query" beats "Searches things".
• Mention what it returns — "Returns a list of matching note IDs".
• Mention failure modes — "Raises if limit exceeds 100".

If the LLM picks the wrong tool, the description is almost always to blame — rewrite it before you blame the model.

Raising errors

from mcp.shared.exceptions import McpError
from mcp.types import ErrorData, INVALID_PARAMS

@mcp.tool()
def search(args: SearchArgs) -> list[str]:
    if args.limit > 100:
        raise McpError(ErrorData(code=INVALID_PARAMS, message="limit must be <= 100"))
    ...

Structured errors travel back to the LLM as JSON-RPC errors with proper codes — the client can distinguish "bad input" from "tool failed" from "server crashed", and surface the right message to the user.

Idempotency

Returning structured content

Tools can return text, images, or resource references via TextContent, ImageContent, and EmbeddedResource. The return type doesn't have to be a string — FastMCP wraps the value in the right content block for you.

from mcp.types import TextContent

return [TextContent(type="text", text="hello")]

For most tools, returning a plain Python value (string, list, dict) is enough — FastMCP serialises it into a TextContent block automatically.

Naming the result fields

When returning structured objects (Python dicts), pick field names that are self-documenting — the LLM will use them in its reasoning. {"note_id": "hello", "matched_at": 12} reads better than {"id": "hello", "pos": 12}, and the LLM is more likely to thread the right value into its next step.

• Be explicit — note_id over id.
• Be consistent — if one tool returns note_id, others should too.
• Avoid abbreviations — position over pos.

pkb.search implementation

from pydantic import BaseModel, Field
from mcp.shared.exceptions import McpError
from mcp.types import ErrorData, INVALID_PARAMS

NOTES = {"hello": "Hello note body", "todo": "Pick up groceries"}

class SearchArgs(BaseModel):
    query: str = Field(..., description="case-insensitive substring match")
    limit: int = Field(10, ge=1, le=100)

def search(args: SearchArgs) -> list[str]:
    q = args.query.lower()
    hits = [k for k, v in NOTES.items() if q in v.lower() or q in k.lower()]
    return hits[: args.limit]

Testing tools in isolation

def test_search_finds_hello():
    result = search(SearchArgs(query="hello"))
    assert "hello" in result

With FastMCP-decorated tools, the underlying function is still callable as a plain Python function — you can unit-test it directly, no transport, no client, no JSON-RPC envelope. The decorator wraps the function for MCP but doesn't replace it.

Recap & what's next

• Pydantic models for inputs — multi-field, validated, with defaults and enums.
• Raise McpError for errors — structured JSON-RPC errors, not Python tracebacks.
• Pick stable noun.verb names — and descriptions the LLM can actually use.