# MCP Tooling Contracts (JSON-RPC over stdio)

## listTools
- **Method**: `listTools`
- **Params**: none
- **Result**:
  - `tools`: array of Tool objects  
    - `name`: string (unique)  
    - `description`: string  
    - `inputs`: array of InputParam  
      - `name`: string  
      - `type`: string (constrained to allowed primitives)  
      - `required`: boolean  
      - `description`: string  
    - `docsAnchor`: object  
      - `path`: string (under `docs/`)  
      - `anchor`: string (heading id)  
      - `summary`: string  

## invokeTool
- **Method**: `invokeTool`
- **Params**:
  - `name`: string (must match Tool.name)
  - `args`: object (key/value per Tool.inputs)
- **Result**:
  - `status`: enum (`ok`, `invalid_input`, `failed`, `unsupported`)
  - `output`: string (human-readable result or guidance)
  - `actions`: array of suggested follow-ups (optional)
  - `docsAnchor`: object (same shape as listTools.docsAnchor) for quick navigation

## syncDocs
- **Method**: `syncDocs`
- **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 JSON-RPC error object with code/message.
- **Validation errors**: return `invalid_input` with details in `output`.
- **Unknown methods**: return `unsupported` status with guidance to run `listTools`.