The 'scan' tool has a minimal schema with only one parameter ('target' as string) and a generic description. The input schema lacks proper type validation, constraints, or error guidance. No output schema is documented. The description (67 chars) is below the 194-char baseline and lacks context on when/why to use the tool, prerequisites, or what the response structure contains. No parameter descriptions beyond the bare name.

• Expand tool description to 150-250 chars: 'Scan a directory or file for code markers (TODO, FIXME, XXX) and return findings with severity levels. Use this to audit codebases for incomplete work or technical debt. Returns a list of findings with id, severity, and file path.'
• Add parameter description for 'target': 'Absolute or relative path to a directory or file. Must be readable and under 10GB. Supports wildcards (*.py, *.js). If not found, returns empty findings list.'
• Document output schema in tool description or as a separate schema field: 'Returns {tool: string, findings: [{id: string, sev: string, where: string}], score: number}. Findings are sorted by severity (high, medium, low).'
• Add input validation: constrain 'target' with a regex pattern (e.g., '^[a-zA-Z0-9/_.-]+$') and max length (e.g., 1024 chars) to prevent path traversal and injection attacks.
• Implement error handling: return structured errors like '{error: "Permission denied", path: "/root", suggestion: "Try a readable directory like ./src"}' instead of raw exceptions.