paperless-mcp: Skill for Claude Code

Tool Registration

Tool Registration Checklist

Every MCP tool you register must carry the full set of metadata below — not just the behaviour. A tool that works but lacks a title, hints, or docs is incomplete. When adding or changing a tool, verify each item:

• Title — a human-readable annotations.title (e.g. "Search Vault"). Title-aware clients (notably VS Code, which honours only title and the read-only hint among annotations) render this as the tool's label; without it they fall back to the raw machine name. Set it inline in the tool's annotations={...} dict.
• Behavioural hints — read_only_hint, and where they apply destructive_hint / idempotent_hint, in the same annotations dict (MCP SDK v2 snake_case; serialized camelCase on the wire). These describe side effects accurately (a destructive tool must set destructive_hint=True).
• Icon — an entry wired via register_tool_icons(...) or @mcp.tool(icons=[...]) (see Tool icons).
• Docstring — a Google-style docstring; FastMCP surfaces its summary and Args: entries as the tool description and per-parameter descriptions the model reads. Write it with the writing-model-facing-text skill: what the tool does, when to call it, what each parameter means; developer notes go in # comments, not the docstring. It states the contract only; how the tool fails is never docstring content.
• Outcomes — every way the tool can end (a result, a request the model must change, a stale version, a server fault) maps to a return value, a ToolError and a log level. Decide them with the designing-tool-outcomes skill, which also says how to write each ToolError message so it stands on its own: what was wrong and the next call to make. Put @tool_boundary (from fastmcp_pvl_core) under @mcp.tool so no exception reaches FastMCP unhandled; the template-owned tests/test_tool_outcomes.py fails any registered tool without it.
• Docs entry — a row in your published tools reference (e.g. docs/tools/index.md) so the tool is documented for users (per the Documentation Discipline section in AGENTS.md).
• Enforcement test — keep a test that enumerates the registered tools and asserts each carries the metadata above (at minimum a non-empty annotations.title). Enumerate the full registry, not just the client-facing listing, so app-only / hidden tools cannot slip past. Such a test turns this checklist into a CI gate: a future tool added without a title fails loudly rather than silently shipping its machine name.