mcp-guardian defines 5 security-focused tools with clear naming (verb_noun pattern: security_audit, tool_pin_check, tool_pin_save, pattern_test, tool_diff). Descriptions are present and domain-specific (avg ~120 chars), explaining what each tool does. However, schemas are incomplete: tool_pin_check and tool_diff have empty input objects ({}), violating the pattern that every parameter needs a description. security_audit has 3 params with types and descriptions; tool_pin_save has 2 params; pattern_test has 2 params. Output schemas are not documented anywhere in the source. Error handling is minimal, no recovery guidance, no categorization of retryable vs fatal errors. The tool definitions appear hardcoded in bin/mcp-guardian.ts rather than explicitly registered via SDK methods, making composition and introspection difficult.

• Add explicit output schemas for all 5 tools. Document what fields each returns (e.g., security_audit returns {findings: [{type, severity, description}], summary: string}). This enables LLMs to chain tools and extract results.
• For tool_pin_check and tool_diff, add at least one optional parameter (e.g., 'server_name' to filter by server, 'detailed' to control output verbosity). Empty schemas signal incomplete tool design.
• Add error handling guidance to descriptions. E.g., security_audit: 'Returns findings array. If async_scan=true and server unreachable, returns partial results with error field.' tool_pin_save: 'If force=false and manifest exists, returns {status: "exists", action: "call with force=true to overwrite"}.'
• Clarify parameter defaults and dependencies. E.g., security_audit: 'config_path defaults to ~/.claude_desktop_config.json. If not found, scans only this server's tools.' tool_pin_save: 'If server_name omitted, defaults to "mcp-guardian". If force=false and manifest exists, returns error with existing hash for comparison.'
• Add a discovery tool (e.g., 'list_pinned_servers') that returns available server manifests. This helps agents understand what can be checked/diffed without trial-and-error.