Build a server: tools

Schemas from type hints

Writing JSON Schema by hand for every tool is tedious and drifts out of date. So SDKs read the labels on your function instead, the same inspect trick FastAPI uses:

import inspect, json

JSON_TYPES = {str: "string", int: "integer", float: "number", bool: "boolean", list: "array", dict: "object"}

def schema_for(fn):
    props, required = {}, []
    for name, p in inspect.signature(fn).parameters.items():
        props[name] = {"type": JSON_TYPES[p.annotation]}
        if p.default is inspect.Parameter.empty:
            required.append(name)
    return {"type": "object", "properties": props, "required": required, "additionalProperties": False}

def search_products(query: str, max_price: float = 500.0, in_stock: bool = True):
    """Search the catalog by keywords. Use for any question about what the shop sells."""

print(inspect.getdoc(search_products))
print(json.dumps(schema_for(search_products), indent=1))

The docstring becomes the description, parameters without defaults become required, and the type hints become JSON types. With the official Python SDK, a whole server looks like this:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("shop")

@mcp.tool()
def search_products(query: str, max_price: float = 500.0) -> list[dict]:
    """Search the catalog by keywords. Use for any question about what the shop sells."""
    return catalog.search(query, max_price)

mcp.run()                     # stdio; other transports are an argument away

SDK names and options change between versions, so check its docs. The ideas don't change.

Results: content and structured content

tools/call sends {"name": ..., "arguments": {...}}. The result holds a list of content blocks, the material the model will read:

A result can also carry structuredContent: plain JSON data for programs, matching the outputSchema. Think of a store receipt, with printed lines for you and a barcode for the scanner. Good servers send both. Code reads structuredContent reliably, and a text block with the same data as JSON serves clients and models that only read text.

result = {"content": [{"type": "text", "text": "12 sold"}], "structuredContent": {"sold": 12}, "isError": False}
print(result["structuredContent"]["sold"] + 1)

Two kinds of error

A letter can come back for two reasons. "No such address" means it never got to anyone. "We don't stock that, try the blue one" means someone read it and is helping you. MCP has the same split:

1. Protocol errors are JSON-RPC errors: an unknown tool or a malformed request. Unknown tools use -32602 (Invalid params). These mean the call itself was broken.
2. Tool execution errors are normal results with "isError": true and a message in the content: a failed API call, an invalid date, "no campaign with that id". The host passes these back to the model, which can correct itself and retry.

So write execution errors for the model: say what was wrong and what would work. "No campaign cmp_999; ids look like cmp_101 to cmp_106" gets fixed on the next try. "Error 500" doesn't.

In plain words: if the model could fix it, tell the model. That means a normal result with isError: true and a helpful message.

import json

class ToolError(Exception):
    """Raise with a message written for the model."""

def to_result(fn, arguments):
    try:
        value = fn(**arguments)
    except ToolError as err:
        return {"resultType": "complete", "content": [{"type": "text", "text": str(err)}], "isError": True}
    if isinstance(value, str):
        return {"resultType": "complete", "content": [{"type": "text", "text": value}], "isError": False}
    return {"resultType": "complete", "content": [{"type": "text", "text": json.dumps(value)}],
            "structuredContent": value, "isError": False}

def stock(sku: str):
    levels = {"TENT-2": 12, "MUG-1": 0}
    if sku not in levels:
        raise ToolError(f"Unknown sku {sku!r}. Known skus: {', '.join(levels)}.")
    return {"sku": sku, "in_stock": levels[sku]}

print(to_result(stock, {"sku": "TENT-2"}))
print(to_result(stock, {"sku": "tent"}))

Writing tools a model can use well

The description isn't documentation for developers. It's the only thing the model reads when choosing what to do, so it deserves more care than any other string in your server. Treat it as a job description for someone starting today.

Compare these two:

• "Gets order." The model doesn't know when to use it, or what it needs.
• "Look up one order by its id, like ord_123. Returns status, items and total. To find orders by customer email, use find_orders instead."

The second says when to use it, what it takes, what comes back, and when to use something else. In practice, improving descriptions often helps more than changing the model.

What errors should say

Don't return stack traces. The model can't act on one, and it may reveal your file paths and library versions.

Decide who can fix each problem. If the model can fix it, such as a mistyped date, use a normal result with isError: true and a message explaining what to change. If the call itself was malformed, that's a protocol error. Reporting a fixable problem as a protocol error means the model never sees the message, so it can't try again.

Annotations are claims, not guarantees

readOnlyHint: true is your server telling hosts that a tool changes nothing. A host may then skip asking for approval. A careful host only trusts these from servers it already trusts, because nothing stops a malicious server from labeling a delete tool as read-only.

So on your own server, make them true. On the host side, treat them as hints from a stranger.

Tool order

Keep tools in a fixed order, which helps caching. It's the same reason a menu is printed the same way each day.