Fixes all reviewer-blocking and minor issues from the initial review of
the feat/404-tool-docs-artifact implementation.
BLOCKING fixes:
- Replace the naïve Annotated[...] regex with a bracket-aware character
scan (_unwrap_annotated) so types like Dict[str, Any] | None and
List[str] | None are extracted correctly instead of being truncated or
emitting internal validator details (BeforeValidator, AliasChoices, etc.)
- Escape unescaped | characters in table cells (_escape_table_cell) so
union types like list[str] | str | None render correctly in GitHub
Flavoured Markdown tables instead of creating spurious extra columns
Minor fixes:
- Fix _extract_examples_section to detect the next top-level section
(Raises:, Returns:, etc.) and stop there; previously the Raises: block
was fenced inside the Python code example
- Add Description column data: _format_args_section now returns a parsed
dict of arg descriptions (_parse_args_block) which populates the table
Description column; fix indent-detection so the first arg line is not
stripped of its leading spaces by .strip()
- Add deduplication: drop the docstring first line when normalised it is
identical to the decorator description
- Demote ### sub-headers in docstring bodies to #### so they don't
pollute GitHub's outline sidebar at the same level as tool headings
- Fix TOC anchor collision: the `search` tool anchor would resolve to the
same #search as the ## Search group header; _tool_anchor detects
collisions and appends -tool; an HTML <a id> anchor is injected in
render_tool_section so the link resolves correctly
- Add comment explaining why ui_sdk.py is excluded from TOOL_FILES
- Format script with ruff (was failing CI ruff format --check gate)
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>
Adds scripts/generate_tool_docs.py which introspects all MCP tool
definitions via AST (no import side-effects), extracts names,
decorator descriptions, docstrings, parameters, and examples, then
emits a deterministic sorted markdown reference to docs/mcp-tools.md.
Also commits the initial generated artifact (23 tools, 1345 lines).
The file header explains it is auto-generated and shows the regenerate
command. Running the script twice produces a zero diff.
Closes#404
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>
Drew Cain