mcp-tool-authoring

mcp-tool-authoring

Purpose: Make every new cos_* MCP tool match the contract every other tool follows. Drift here breaks the agent (deferred-tool schema lookups), the envelope (Rule 13), or the migration (Rule 9). One canonical authoring path keeps the ~80 tools coherent.

Read when: editing files matching:

• src/core/thinking_os/tools/*.py — MCP tools registered with the FastMCP server.
• src/core/graph_os/tools/*.py — graph-side tools (cos_graph_*).
• src/core/board_os/mcp_tools.py — Scrumban / task tools.
• src/core/web/routes/*.py — HTTP routes that wrap an MCP tool for the Hub UI.
• src/core/thinking_os/server.py — when registering a new tool module.

Skip when: editing tests, helpers, or non-tool internals.

The Five Hard Contracts

Every cos_* tool MUST satisfy ALL of:

1. Name prefix cos_ (Rule 2)

@mcp.tool
@safe_tool
async def cos_doc_search(query: str, limit: int = 5) -> dict:
    ...

Names without the cos_ prefix are silently rejected from the tool inventory. The inventory is the SSOT for docs/governance/mcp-tool-inventory.md (regenerated, not hand-edited).

2. Envelope shape via @safe_tool (Rule 13)

Every tool returns ok(data) or fail(category, message). The decorator does this for you:

from core.thinking_os.tools._shared import safe_tool, ok, fail

@mcp.tool
@safe_tool  # converts raw exceptions to fail() envelopes
async def cos_doc_search(query: str, limit: int = 5) -> dict:
    if not query:
        return fail("invalid_input", "query is required")

    rows = await _db.search(query, limit=limit)
    return ok({"results": rows, "count": len(rows), "meta": {"layer": "docs"}})

fail categories are documented in docs/engineering/mcp-error-envelope.md: invalid_input, not_found, unavailable, permission_denied, internal_error, rate_limited. Don't invent new categories without updating the contract doc.

3. ONE-line docstring (Rule 12)