AgentLoom exposes 16 tools with basic schemas and descriptions, but critical gaps undermine production readiness. Most tools lack parameter descriptions (e.g., workspace, relative_path, timeout_seconds have no guidance on format or constraints). Descriptions are present but generic, many under 100 chars and lacking WHEN/WHY context. No output schemas documented. Error handling is absent; tools do not guide recovery. Tool names are reasonable (verb_noun pattern) but lack clarity on mutual exclusivity and dependencies. No evidence of idempotency, rate limiting, or permission gates. STDIO transport caps protocol score at 50.

• Add detailed parameter descriptions to every tool. For workspace: 'Absolute path to the controlled repository (e.g., /home/user/projects/myapp).' For relative_path: 'File path relative to workspace root; must be within workspace (e.g., src/main.py, tests/test_*.py). Prevents path traversal.' For timeout_seconds: 'Maximum seconds to wait (1 - 3600). Defaults to 30 if omitted.'
• Document output schemas for all tools. E.g., inspect_workspace returns {files: [{path, type, size}], config: {name, version}, tests: [{name, status}]}. Include field types and whether fields are always present or conditional.
• Add error handling guidance to each tool. E.g., read_workspace_file: 'Returns 404 if file not found, call inspect_workspace first to list available files. Returns 403 if path escapes workspace, use relative paths only.'
• Implement confirmation or dry-run for destructive tools. write_workspace_file should accept a dry_run=true parameter that returns 'Would write X bytes to path/file' without modifying state. run_workspace_tests should return a summary of tests to run before executing.
• Clarify tool selection criteria. Add to make_context_engine_* descriptions: 'Use json_payload for structured data validation, log_payload for log parsing, search_payload for grep-like results, text_payload for plaintext. Each embeds one hidden validation item for testing context engine robustness.'