# MCP Tooling Contracts (MCP over stdio via `nixos-mcp`)

## tools/list
- **Method**: `tools/list`
- **Params**: none
- **Result**:
  - `tools`: array of Tool objects  
    - `name`: string (unique)  
    - `description`: string  
    - `inputSchema`: object (JSON schema derived from tool signature)  

## tools/call
- **Method**: `tools/call`
- **Params**:
  - `name`: string (must match Tool.name)
  - `arguments`: object (key/value per Tool inputs)
- **Result**:
  - `status`: enum (`ok`, `invalid_input`, `failed`, `unsupported`)
  - `output`: string or object (human-readable result or structured payload)
  - `actions`: array of suggested follow-ups (optional)
  - `docsAnchor`: object for quick navigation  
    - `path`: string (under `docs/` or `specs/`)  
    - `anchor`: string (heading id)  
    - `summary`: string  

## sync-docs (tool)
- **Purpose**: Validate that documented tools match the live catalog.
- **Params**: none
- **Result**:
  - `status`: enum (`ok`, `drift_detected`)
  - `missingInDocs`: array of tool names
  - `missingInCatalog`: array of doc anchors without tools
  - `mismatches`: array of objects  
    - `name`: string  
    - `expected`: string (description/input summary)  
    - `actual`: string  

## Error Handling
- **Transport errors**: standard MCP error object with code/message.
- **Validation errors**: return `invalid_input` with details in `output`.
- **Unknown tools**: return `unsupported` status with guidance to run `tools/list`.