Single tool 'ast-grep' with explicit registration via mcp.NewTool(). Tool has a description (138 chars, within 10-1024 range), proper type annotations, and three parameters with descriptions. However, descriptions are relatively terse and lack WHEN-to-use context and dependency hints expected in production tools. Output format is documented as JSON but no structured schema is provided for the output object. Error handling is basic (returns CommandError string) without recovery guidance. The tool's name 'ast-grep' starts with the command name rather than an action verb (search_codebase, find_patterns), which reduces discoverability. Parameters are well-typed (string) but lack constraints like patterns/enums and expected format details. No pagination support despite potentially returning large result sets.

• Rename tool from 'ast-grep' to 'search_code_patterns' or 'find_ast_matches' to follow verb_noun convention and improve LLM discoverability
• Expand tool description to 150-250 chars: include WHEN to use (structural code search), supported languages list, pattern syntax requirement, and link to ast-grep docs
• Add explicit output schema documenting the JSON structure: e.g., { matches: [{file: string, line: number, column: number, text: string}], total: number, limit: number }
• Document 'lang' parameter with enum or list of supported languages (javascript, python, go, rust, typescript, etc.) and auto-detection behavior
• Add format constraint to 'pattern' parameter: describe valid AST pattern syntax with 1-2 minimal examples (e.g., 'function $_($$) { $$$ }')
• Implement result limit (cap at 50 matches) and pagination via offset/limit parameters; document in description and return total count
• Enhance error handling: categorize errors (InvalidPattern/LanguageNotSupported/PathNotFound) and return actionable guidance, e.g., 'Invalid pattern: missing operator. Valid: $$$ for any node, $FUNC for function name'
• Add tool annotation for 'readOnlyHint' (already present via WithReadOnlyHintAnnotation) and document it in the description
• Clarify 'dir' parameter: document whether it accepts absolute or relative paths, and if relative paths are resolved from process cwd or WORKDIR=/src