Single tool with adequate naming and clear purpose, but critical gaps in parameter descriptions and output schema documentation. The tool 'index_repository' follows verb_noun naming convention well. However, parameter descriptions are minimal (repo_path and mode lack sufficient detail about expected format, constraints, and validation rules). Most critically, there is NO documented output schema visible in the source code, LLMs cannot know what fields to expect from this tool, making it impossible to plan downstream actions or extract required data. The tool modifies state (WRITE risk) but the description does not explicitly warn that indexing is destructive or has side effects. No error handling guidance is visible. Without output schema and better parameter constraints, this tool will frustrate LLM usage despite solid naming.

• Add a complete output schema documenting all returned fields (e.g., index_id, num_symbols, num_relationships, error_count, duration_ms, cache_location). Include field types and descriptions so LLMs know what to extract.
• Expand 'repo_path' description to 'Absolute or relative path to the repository root (e.g., /home/user/myproject or ./myproject). Path must contain a valid Git repository or analyzable codebase. LLM should error if path does not exist or is not readable.'
• Expand 'mode' description to clarify: 'full: re-index the entire codebase from scratch (slower, used after major changes). incremental: update only changed files since last index (faster, requires prior full index). Choose full on first run or after repository restructuring.'
• Update tool description to include state-mutation warning: 'This tool builds and persists a symbol and relationship graph index on disk. Repeated calls with the same repo_path update the existing index. Indexing is idempotent, calling it multiple times produces the same result.'
• Add error handling guidance: 'If indexing fails, check that the repository path is valid, readable, and contains code. Common errors: permission denied (check file permissions), path not found (verify the path exists), unsupported language (the repository may use a language tree-sitter cannot parse).'
• Document whether very large repositories are supported and any built-in limits on result size. If results can exceed context windows, offer pagination or sampling parameters.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry