Heddle MCP server has well-structured schemas and clear naming conventions for delegation tools, but suffers from critical gaps in parameter descriptions, missing output schema documentation, and weak error handling guidance. 11 of 13 tools lack parameter descriptions entirely. The governance/approval tools (heddle_record_gate, heddle_update_manifest, etc.) have complex schemas but minimal guidance on when/why to use them. Mock tools (echo, upper) are trivial. No tool descriptions explain recovery paths or error conditions. Baseline: 194 chars avg description, 72 chars avg param annotation, this server averages ~80 chars for tool descriptions but ~0 chars for param descriptions.

• Add descriptions to every parameter. For 'agent' in heddle_delegate, write: 'Name of the child agent to delegate to. Must match a configured child agent name.' For 'briefing', write: 'Task description for the child agent (1+ chars). Agents use this to understand what work to perform.'
• Document output schemas for all delegation tools. E.g., heddle_delegate should document: 'Returns {taskId: string, status: "pending"|"running"|"completed"|"failed", report?: object}' so agents know what fields to expect.
• Add error handling guidance to tool descriptions. E.g., heddle_delegate: 'If the agent times out, the tool returns status=failed with a timeout error. Retry with a longer timeoutSeconds or break the task into smaller subtasks.'
• Clarify governance workflow. Add a preamble to heddle_record_gate, heddle_update_manifest, etc. explaining: 'These tools record governance decisions during a Heddle run. Call heddle_record_gate to log a gate result, then heddle_update_manifest to update the run manifest. Use heddle_require_approval to request explicit approval before proceeding.'
• Remove or conditionally disable mock tools (echo, upper). They clutter the tool namespace and serve no production purpose. If needed for testing, gate them behind a HEDDLE_MOCK environment variable check.