The Shellockolm server has 8 tools with mixed definition quality. Naming is generally clear and verb-based (find_, quick_scan, scan_, analyze_, patch_, verify_, generate_), but there are critical issues: (1) duplicate tool names ('scan_directory' appears twice with different descriptions), creating severe ambiguity; (2) descriptions vary wildly in quality, some are detailed (find_packages at 127 chars with use-case guidance), others are generic (analyze_project at 75 chars); (3) input schemas are visible and properly typed with JSON Schema, which is good, but descriptions within schemas sometimes lack specificity about constraints (e.g., max_depth defaults to 3 but no rationale); (4) no output schemas are documented, tools like quick_scan and scan_directory return results but the response structure is not declared, forcing LLMs to guess what fields exist; (5) tool annotations are completely absent (no readOnlyHint, destructiveHint, idempotentHint despite clear risk classification); (6) error handling guidance is not visible in any tool description; (7) patch_project has a dry_run parameter (good pattern), but the description doesn't explain what to do if dry_run=true fails or succeeds; (8) generate_report accepts output_path as optional but no guidance on what format is produced or where it goes if omitted. The server shows structural competence (proper schemas, mostly sensible parameters) but lacks the polish and detail needed for robust agent use.

• Rename one 'scan_directory' to 'scan_directory_deep' or 'scan_project_cves' to eliminate the duplicate. Make the distinction unambiguous in the name itself.
• Document output schemas for all tools. Example: quick_scan returns {vulnerabilities: [{cve_id: string, severity: string, package: string, version: string}], scan_time_seconds: number, total_issues: number}. Use JSON Schema in tool registration.
• Add tool annotations via destructiveHint: true for patch_project and generate_report; readOnlyHint: true for find_packages, quick_scan, scan_directory, analyze_project, verify_fix.
• Add explicit constraints to all 'path' parameters: '(string) Absolute or relative file system path. Supports ~ expansion. Must be readable. If path is a file, applies to its parent directory.'
• Add max_depth rationale and boundary behavior: 'max_depth: Maximum directory nesting level to search (default: 3). Prevents scanning into deep node_modules. If path depth exceeds max_depth, scan stops at max_depth level.'
• Document patch_project flag interactions: 'If dry_run=true, returns a summary of proposed changes without modifying files. If backup=true, creates backup before any modifications. If dry_run=true and backup=true, backup is created but not used (previewing only).'
• Add timeout and progress guidance to long-running tools: 'quick_scan typically completes in 2-3 minutes; if > 10 min, consider interrupting and checking system resources. No progress callback available; monitor logs separately.'
• Clarify when to use analyze_project vs quick_scan vs scan_directory: 'Use quick_scan for fast CVE check (2-3 min); use scan_directory for thorough audit (10+ min); use analyze_project AFTER scan to get details on a specific vulnerability or project.'