CodeOracle has 4 tools with basic verb-noun naming (audit_*, check_*, get_*), but critical gaps undermine quality. All tools have descriptions (10-50 chars), but they are too brief and lack context on WHEN to use each tool or what distinguishes them. Input schemas are present but minimal: each tool accepts only a single 'directory_path' string parameter with a description. No output schemas are documented, responses are JSON strings with ad-hoc structures (e.g., {"Stack": [...], "Files": [...]}) that LLMs must parse without guidance. Error handling is minimal: tools return plain strings like 'Error: Path not found.' with no recovery guidance. No parameter validation beyond existence checks, no pagination, no rate limiting. Tools lack idempotency guarantees and do not document side effects or permissions. Security: tools perform filesystem traversal on user-supplied paths without sanitization, risking directory traversal attacks.

• Add output schema documentation for each tool. Example for audit_project: 'Returns {"Stack": [string], "Files": [string], "total_files": number}'. This enables LLMs to extract and chain results.
• Expand descriptions to 80-150 chars with WHEN and WHAT. Example: 'Scans a project directory to identify tech stack (Python, Node.js, etc.) and list key source files. Use this first to understand project structure before deeper analysis.'
• Implement path validation: reject paths containing '..' or starting with '/', enforce a configurable base directory, and return clear errors like 'Path must be relative and within /projects. Got: ../../../etc'.
• Add limit and offset parameters to audit_project and audit_ml_assets. Default limit=50, max=500. Document in descriptions: 'Returns up to 50 files; use offset for pagination.'
• Improve error messages with recovery hints. Instead of 'Error: Path not found.', return 'Path not found: /invalid/path. Verify the directory exists. Available base paths: /projects, /home/user/code.'