mcp-security-scanner demonstrates strong definition quality across 18 security-focused tools. All tools have descriptions exceeding 20 characters with clear explanations of security concerns they detect. Input schemas are present and properly typed with Zod validation. However, several significant gaps prevent a higher score: (1) Output schemas are not documented, tools return formatted text/findings but the exact structure is not specified in schema definitions; (2) Error handling lacks recovery guidance, findings indicate security issues but don't guide what to do next; (3) Parameter descriptions are adequate but some lack constraint details (e.g., max_resources default is stated but no range documented); (4) Tool composition could be improved, several tools operate on the same resource types (e.g., cfg_* tools) making tool selection less obvious; (5) No tool annotations (readOnlyHint/destructiveHint) despite clear safety implications. The rt_fuzz_tools tool correctly marks itself as WRITE risk, but others lack explicit safety signals. Baseline: 18/18 tools have descriptions (100%, meets A+ baseline of 94%). 17/18 tools have visible input schemas with types. Average description length ~150 chars (within 34-392 baseline). However, per-tool parameter descriptions vary, some parameters like 'confirm_execute' are well-explained, others like 'categories' in rt_fuzz_tools lack detail on valid options.

• Add explicit 'returns' schemas to all tool definitions. Define the Finding structure: {id: string, title: string, severity: string, owasp_mcp: string, category: string, evidence: string, remediation: string, cwe: string}. This enables LLMs to parse and act on findings.
• Enhance error handling in rt_check_oauth, rt_check_tls, and rt_check_capabilities with typed error responses: {error: string, code: 'UNREACHABLE'|'INVALID_URL'|'TIMEOUT'|'AUTH_REQUIRED', suggestion: string}. Example: 'Could not reach server at http://localhost:3000/mcp (UNREACHABLE). Verify the URL is correct and the server is running.'
• Add tool annotations to ToolDef: all cfg_* and dep_* tools should have readOnlyHint: true. rt_fuzz_tools should have destructiveHint: true and destructiveHint description 'Optionally executes fuzzing payloads against live tools; may cause crashes.'
• Convert rt_fuzz_tools 'categories' parameter from string description to formal enum: {type: 'array', items: {type: 'string', enum: ['empty', 'long_string', 'path_traversal', 'command_injection', 'sql_injection', 'special_chars', 'type_confusion']}}.
• Add batch variants for common workflows. Example: rt_check_oauth_batch(server_urls: string[]) to test multiple servers in one call, reducing token overhead.
• Document output pagination for tools that can return many items (rt_check_resource_content, dep_audit_lockfile). Add max_results parameter with default of 50 and document the limit in descriptions.
• Add dependency hints to tool descriptions. Example: rt_fuzz_tools could state 'Call rt_check_capabilities first to see available tools before fuzzing.' cfg_scan_env_files could state 'Use cfg_auto_discover first to locate config files if path is unknown.'