pi-shazam provides 7 well-scoped analysis tools with clear semantic names (shazam_overview, shazam_lookup, shazam_impact, shazam_verify, shazam_changes, shazam_format, shazam_rename_symbol). All tools have descriptions ranging 62-137 chars, which meet baseline minimums but lack LLM-optimization depth. Input schemas are present and typed (all params have 'type' fields: string, number, boolean). However, parameter descriptions are minimal ('Optional: max output tokens to truncate result' appears verbatim across 5 tools), and output schemas are not documented in the source. Error handling via errorReporting=true is declared but recovery guidance is not visible in tool definitions. The tools follow a consistent verb_noun pattern and are read-only/write-safe with risk annotations. Tools compose well (each has one clear purpose), but descriptions lack the actionable context about dependencies, output shape, and when to choose one tool over a similar alternative (e.g., why shazam_lookup vs shazam_impact). No tool annotations (readOnlyHint/destructiveHint) are present in the visible schema.

• Expand parameter descriptions from boilerplate to actionable guidance. For maxTokens, state: 'Maximum tokens in the response (1-10000, default 5000). Increase for large codebases, decrease to fit in context windows.' For json, state: 'When true, return structured JSON with typed fields (symbol name, file path, line number); when false, return formatted text summary.'
• Add output schema documentation to each tool. For shazam_lookup JSON mode, document: 'Returns {"symbol": string, "definitions": [{"file": string, "line": number, "type": string}], "usage_sites": [...], "cross_references": [...]}'.
• Enhance tool descriptions with context and sequencing hints. E.g., shazam_impact: 'Analyze the impact scope of changes to a symbol or file on the rest of the codebase. Call shazam_overview() first to understand the structure; then shazam_lookup() to find a specific symbol; then this tool to see affected dependents. Returns counts and list of impacted files/symbols.'
• Add explicit tool annotations to MCP schema. For shazam_format and shazam_rename_symbol (both WRITE), add destructiveHint: true or idempotentHint (if safe to retry). For read-only tools, add readOnlyHint: true.
• Document error scenarios and recovery paths. E.g., shazam_rename_symbol: 'Returns success or error. On error, reasons include: symbol not found (try shazam_lookup first), new name conflicts with existing symbol (try shazam_overview to see available names), or rename failed due to syntax (check the file is valid code). Provides detailed error message with suggested alternatives.'