Coddy Agent exposes 30 tools with minimal schema documentation and sparse descriptions. Most tools lack detailed parameter descriptions, input validation constraints, and output schema documentation. Tool names are inconsistent (verb_noun vs bare nouns). Critical security issues: run_command and ssh_run_command expose shell execution without dry-run or confirmation patterns. No evidence of error handling guidance, recovery paths, or actionable error messages. Descriptions average ~30 chars, well below the 194-char baseline for production tools. Only 5 tools have descriptions exceeding 20 chars. Parameter schemas are inferred from file references rather than explicitly visible in source code, preventing verification of type definitions and constraints.

• Add dry-run parameters to all irreversible tools (run_command, rm, ssh_run_command). Return a preview of what would execute before confirming. Implement confirmation-request pattern.
• Expand parameter descriptions to 50-150 chars. Include format specs, enums, and constraints. E.g., 'command: Shell command to execute (bash syntax; no sudo; max 1000 chars). Example: ls -la /tmp'.
• Document output schemas for all tools. Specify field names, types, and limits. E.g., 'Returns {matches: [{path: string, line_number: int, content: string}], total: int, limit: 50}'.
• Add error handling guidance. Document which errors are retryable, which require user input, and what recovery steps apply. E.g., 'If command times out after 30s, retry with a shorter timeout or simpler command.'
• Standardize tool naming to verb_noun pattern. Rename 'question' → 'ask_question', 'session_describe' → 'describe_session', 'coddy_scheduler_job_create' → 'create_scheduled_job'.