docs: auto-generate tool documentation from MCP server metadata (#394)

Add a script that introspects the server's registered tools at runtime
and generates per-category markdown pages under docs/tools/, ensuring
documentation exactly matches the JSON schema advertised by the server.

- Add scripts/generate_tool_docs.py to generate docs from tool metadata
- Generate one page per category (system-info, services, logs, etc.)
- Include parameter details with types, defaults, and constraints
- Include structured return types with nested field expansion
- Filter out internal tools (hidden_from_model) and the host parameter
- Replace hand-written docs/tools.md placeholder with generated pages
- Add docs/tools/ to .gitignore (generated at build time, not committed)
- Document the generation step in contributing.md

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: owtaylor

.gitignore

@@ -39,6 +39,7 @@ htmlcov/
 
 # Documentation build
 site/
+docs/tools/
 
 # IDEs
 .vscode/

AGENTS.md

@@ -51,4 +51,6 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
 
 ## Docs
 
-Full details: `docs/contributing.md` | Architecture: `docs/architecture.md` | API: `docs/api/`
+Full details: `docs/contributing.md` | Architecture: `docs/architecture.md`
+
+Tool docs under `docs/tools/` are auto-generated — run `uv run python scripts/generate_tool_docs.py` after adding or modifying tools.

docs/contributing.md

@@ -238,6 +238,26 @@ Coverage reports are generated in `coverage/htmlcov/index.html`.
 
 ---
 
+## Building Documentation
+
+The [Tools](tools/system-information.md) pages are auto-generated from the server's runtime tool
+metadata. You must run the generation script before building the docs:
+
+```bash
+# Generate tool documentation, then build the site
+uv run python scripts/generate_tool_docs.py
+uv run mkdocs build --strict
+
+# Or for local preview
+uv run python scripts/generate_tool_docs.py
+uv run mkdocs serve
+```
+
+The generated files live in `docs/tools/` (gitignored). If you add or
+modify a tool, re-run the generation script to update the docs.
+
+---
+
 ## Security Guidelines
 
 ### Read-Only Operations Only

docs/tools.md

@@ -66,7 +66,14 @@ nav:
       - Security Best Practices: security.md
       - Architecture: architecture.md
       - Debug Logging: debugging.md
-  - Tools: tools.md
+  - Tools:
+      - System Information: tools/system-information.md
+      - Services: tools/services.md
+      - Processes: tools/processes.md
+      - Logs: tools/logs.md
+      - Network: tools/network.md
+      - Storage: tools/storage.md
+      - Script Execution: tools/script-execution.md
   - Contributing: contributing.md
 
 extra: