Bawbel Scanner provides 12 tools with explicit schemas and descriptions. Most tools have clear verb-noun naming (scan, scan_cmd, init_cmd, pin_cmd, accept_cmd, creds_cmd, chain_cmd) and documented input parameters with types and enums. However, descriptions are inconsistent in depth, some are terse (version_cmd: empty input, minimal context), and several lack guidance on when to use them vs. similar tools. Output schemas are not documented in the source provided, forcing LLMs to infer result structure. Error handling and recovery guidance are absent. Parameter descriptions are present but often lack format constraints, ranges, or examples of valid values. The tool set is well-composed (each does one thing), but lacks idempotency hints and confirmation patterns for destructive operations (init_cmd, pin_cmd, accept_cmd all modify files).

• Document output schemas for all tools. For scan/scan_cmd, specify ScanResult structure: {findings: [{id, severity, file, line, message}], total_count, summary}. For scan_conformance_cmd, document ConformanceReport: {grade, score, checks: [{name, status, details}]}.
• Add confirmation patterns to destructive tools. init_cmd and accept_cmd should support a --dry-run flag or return a confirmation prompt before modifying files. Example: 'Would overwrite .bawbelignore. Proceed? (yes/no)'.
• Clarify accept_cmd parameter relationships. Document that do_list, expiring_soon, and search_path are discovery modes (mutually exclusive with id_str + file_path). Add examples: 'To list all suppressions: accept_cmd --do_list --search_path /project' vs 'To suppress a finding: accept_cmd --id_str AVE-2026-00047 --file_path src/main.py --line 42 --reason "False positive in test code"'.
• Expand version_cmd description to: 'Display scanner version and availability of optional detection engines (YARA, Semgrep, LLM, Sandbox). Use this to verify dependencies before running scans that require specific engines.' Add output schema: {version, engines: {yara: bool, semgrep: bool, llm: bool, sandbox: bool}}.
• Add error recovery guidance to scan tools. Document common failures: 'Path not found → verify path exists and is readable', 'No findings → check that rules are loaded (run version_cmd)', 'Timeout → reduce scope or increase timeout parameter'. Return structured errors: {error_code, message, recovery_hint, retry_safe: bool}.