grepai exposes 14 code-analysis tools with generally solid descriptions and well-formed input schemas. All tools are read-only, which reduces security risk. However, there are several patterns from the 54 Agentic Tool Patterns that are not fully addressed: (1) Output schemas are not explicitly documented in the source code, LLMs cannot see what fields to expect from responses; (2) Error handling guidance is absent, no indication of what to do if a search fails, index is unavailable, or a symbol is not found; (3) Some parameter descriptions lack actionable formatting constraints (e.g., 'limit' has no min/max bounds stated); (4) A few parameters use generic naming ('format') without clear enum values in descriptions; (5) No idempotency hints for tools that might be retried. The tool names are clear and verb-based (search_, trace_, list_, rpg_, refs_, stats_), and descriptions are reasonably detailed (averaging 150 - 250 chars), but they stop short of guiding an LLM on when to use one tool vs. another or what to expect from output.

• Add explicit output schema documentation for each tool. For grepai_search, document: 'Returns an array of SearchResult objects with fields: file_path (string), start_line (int), end_line (int), score (float), content (string), feature_path (optional string), symbol_name (optional string).' Do this for all 14 tools so LLMs know exactly what to expect.
• Enhance tool descriptions with error recovery hints. Example for grepai_search: 'If no results found, try a broader query (fewer keywords) or call grepai_list_workspaces to verify the workspace exists. If the index is not built, call grepai_index_status to check status and trigger indexing if needed.'
• Add min/max bounds to numeric parameters. Change 'limit' descriptions to: 'Maximum number of results to return (default: 10, range: 1 - 100)' and 'depth' to: 'Maximum depth for graph traversal (default: 2, range: 1 - 5)' to prevent out-of-bounds calls.
• Declare 'format' parameter as an enum in the schema. Instead of relying on description examples, add a formal constraint: 'enum: ["json", "toon"]' at the schema level. This prevents hallucinated formats.
• Add tool-to-tool hints in descriptions. For grepai_list_workspaces, add: 'Call this first if you do not know the workspace name, then pass the result to grepai_search or grepai_rpg_search.' For grepai_search, add: 'Use grepai_trace_callers or grepai_trace_callees after finding a symbol to understand its call site.' This guides multi-step planning.
• Add idempotency declarations. Prefix all tool descriptions with '[Idempotent. Safe to retry.]' to signal to LLMs that these tools are read-only and do not modify state, enabling confident retry logic.