GrepAI provides 10 read-only codebase tools with complete JSON schemas and reasonable descriptions. All tools have proper input schemas with types and descriptions, meeting baseline requirements. However, descriptions are generic (avg ~80 chars, below the 194-char production baseline) and lack LLM-optimized guidance on WHEN to use each tool vs. alternatives. No tool annotations (readOnlyHint, idempotentHint) despite all being read-only. Error handling is absent, no recovery guidance, no actionable error messages. Output schemas are not documented. Tool composition is sound (each does one thing), but parameter naming could be more explicit (e.g., 'pattern' vs 'search_pattern', 'path' vs 'file_path' to avoid ambiguity across tools).

• Add tool annotations: set readOnlyHint=true and idempotentHint=true on all 10 tools to signal safety properties to LLMs.
• Expand descriptions to 150-250 chars each. Include WHEN to use (e.g., 'Use find_definition to locate where a function is declared; use find_references to see where it is called'). Add dependency hints (e.g., 'Call list_files first to discover available files before reading').
• Document output schemas for each tool. E.g., search_codebase returns {matches: [{file: string, line_number: int, content: string, context_before: string[], context_after: string[]}], total_matches: int}.
• Add error handling with actionable recovery messages. E.g., 'File not found at path/to/file.py. Available files in path/to/: [list]. Did you mean path/to/file.js?'
• Standardize parameter naming: use 'file_path' instead of 'path' for file operations, 'search_pattern' instead of 'pattern', 'directory_path' for directory operations. Add descriptions clarifying whether paths are relative to workspace root.

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

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