Single tool 'tokenrotate_scan' has a basic description (73 chars) but critical gaps in schema documentation and parameter guidance. Input schema visible with 'target' parameter (string type, description present), but output schema is completely undocumented, LLMs cannot plan downstream actions or extract structured data. No error handling guidance, no validation rules, no examples of expected output format. Tool name lacks action verb clarity ('tokenrotate_scan' is vague about what 'scan' returns or when to use it vs other tools). Parameter 'target' description is minimal ('Target path to scan for secret rotation markers') and does not explain expected format, constraints, or what constitutes valid input. No guidance on handling errors (invalid paths, permission denied, timeout). Baseline: 194 chars avg description, 72 chars avg param annotation, this tool falls well short.

• Document the complete output schema: 'Returns {tool: string, findings: [{id: string, sev: string, where: string}], score: number}'. Include field descriptions and example output.
• Expand parameter description: 'target: Filesystem path (file or directory) to scan. Supports absolute and relative paths. Recursively searches subdirectories. Returns error if path does not exist or is not readable.'
• Add validation rules to description: 'target must be a valid filesystem path (1-4096 chars). Supports Unix and Windows paths. Relative paths are resolved from current working directory.'
• Rename tool to 'scan_for_rotation_markers' or 'detect_secret_rotation_tasks' to clarify intent and distinguish from generic file scanners.
• Add error handling guidance: 'If path not found, returns error with available parent directories. If permission denied, returns error with required permissions. Timeout after 30s with partial results.'
• Document the three detection rules (GEN-001/TODO, GEN-002/FIXME, GEN-003/XXX) in the tool description so LLMs understand what constitutes a finding.