Three tools with explicit schemas and descriptions, but significant gaps in parameter documentation and output schema clarity. handoff_to_user has a complex nested 'spec' parameter (object type) with no sub-field descriptions, forcing LLMs to infer structure. handoff_verify and handoff_runbooks lack output schema documentation. Descriptions are present (60-90 chars) but generic, they state WHAT but not WHEN or WHY. No error handling guidance visible in tool definitions. Tool names follow verb_noun pattern (good), but parameter naming lacks type suffixes (spec vs spec_object, goal vs goal_string).

• Expand handoff_to_user description to ~150 chars: 'Send a handoff spec to the user and block until they respond. Use this when the agent needs human input or approval before proceeding. Returns the user's decision and any metadata.'
• Document the 'spec' object schema inline or via a $ref. At minimum, describe sub-fields: 'spec.steps (array of step objects), spec.context (string), spec.metadata (object with optional fields)'.
• Add output schema documentation for all three tools. E.g., handoff_runbooks returns '{runbooks: [{id, title, goal, steps}], draftSpec: {...}}'.
• Add format/constraint hints to 'goal' parameter: 'A short phrase describing the desired outcome (e.g., "create user account", "send email"). Searches runbook titles and descriptions.'
• Document error scenarios and recovery paths in tool descriptions. E.g., 'If the app is disconnected, returns APP_DISCONNECTED error. Retry after reconnection or ask the user to reconnect.'

Inferred effective spec: 2025-06-18+.

• Relies on Roots (deprecated) - pass files/dirs via tool parameters, resource URIs, or configuration