branch fixes

specs/002-mcp-server/contracts/mcp-tools.md

@@ -0,0 +1,41 @@
+# 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`.