PyVisualizer exposes three tools through fastmcp with clear purposes (search_code, context_pack, impact). All three have explicit descriptions and input schemas visible in mcp_server.py. However, there are significant gaps: (1) descriptions lack actionable guidance on WHEN to use each tool vs alternatives, (2) parameters lack descriptions for some fields and no enum constraints are present, (3) output schemas are not documented in the tool definitions themselves, (4) no error handling guidance or recovery instructions are provided. The tool names follow verb_noun pattern and are reasonably distinct. This is a moderately competent implementation that would benefit from richer parameter documentation and output schema clarity.

• Add explicit output schema documentation to each tool. For search_code, document that results are returned as an array of objects with fields {qualified_name, file, line_number, score}. For context_pack, specify the structure of the context pack (call edges, source snippets, metadata). For impact, describe the structure of the blast radius (direct_callers, transitive_callers, callees, affected_modules).
• Enhance 'context_pack' strategy parameter with an enum constraint and decision guidance: strategy (enum: 'graph'|'text'|'hybrid'; default 'hybrid'). Add description: 'Choose graph for call-graph visualization, text for source-heavy context, hybrid for both. Use graph when you need to understand module dependencies; use text when you need full source code snippets.'
• Add relationship documentation for context_pack's 'task' and 'focus' parameters. E.g., 'If task is provided, focus is optional and narrows results to the specified symbols. If focus is provided without task, returns context for those symbols only. task defaults to empty string (no task guidance).'
• Document error cases and recovery for each tool. For search_code: 'If no results are found, try a shorter query or broaden the search scope. Returns empty array if query matches no functions.' For impact: 'If symbol not found, verify the qualified name format (module.class.method). Returns error with similar symbol suggestions if available.' For context_pack: 'If budget_tokens is below 200, returns error with minimum budget guidance.'
• Add guidance on tool sequencing. Clarify that search_code is a discovery step to identify candidates, context_pack builds focused context around those candidates, and impact shows consequences before refactoring. This guides multi-step agent planning.