Authoring an MCP tool

Authority: docs/10-product/srs.md and docs/30-api/mcp-tools.md.

The shape

@mcp.tool()
@guarded_tool
async def tg_do_thing(target: str, limit: int = 10) -> str:
    """One line saying what this does for the user.

    When to use it rather than a neighbouring tool, and any consequence the
    agent must know about before calling.

    Args:
        target: What forms are accepted.
        limit: What range; note that it is clamped, not rejected.

    Returns:
        What the text contains, and what a failure looks like.
    """

Decorator order matters: @mcp.tool() outermost, @guarded_tool directly on the function.

Hard requirements

The docstring is the agent's only manual

FastMCP publishes it verbatim as the tool description. Write it for an agent deciding which tool to call:

• Say when to use this one rather than a similar one. tg_get_recent_messages sees the last minute; tg_search_local_history sees years but only to the last sync.
• State consequences up front. "Blocks sends to strangers" belongs in the first paragraph, not in the return description.
• Describe what failure text looks like, so the agent can react rather than retry blindly.

After adding or changing a tool

Required by the documentation map:

1. A SPEC- clause in the SRS, naming its test.
2. A schema entry in docs/30-api/mcp-tools.md.
3. A row in the README tool table.
4. A glossary entry if a new concept appeared.
5. just check, then the DOCS SYNC block.

Verifying registration

.venv/bin/python -c "
import asyncio, server
print([t.name for t in asyncio.run(server.mcp.list_tools())])"