Four tools with basic descriptions and partial schemas. All tools have descriptions (10-200 chars range), but parameter documentation is sparse. onion_scan and onion_audit lack output schema documentation. onion_fix has a numeric layer parameter with min/max constraints, which is good. Error handling and recovery guidance are absent. No tool annotations (readOnlyHint/destructiveHint). Naming is clear (verb_noun pattern), but descriptions lack WHEN/WHY context that LLMs need for tool selection.

• Add explicit output schemas to all tools. Document the structure of scan results (e.g., {layers: [{name, score, issues}], overallScore}), audit findings, goal content, and generated files.
• Expand tool descriptions to 100-150 chars. Include: WHAT it does, WHEN to use it (vs similar tools), and WHAT to do with results. E.g., 'Scan a project to detect which of the 8 onion layers are present. Call this first to assess architecture maturity before running onion_audit for detailed quality issues.'
• Add error recovery guidance. E.g., 'If scan finds no layers, ensure the directory contains .env, CLAUDE.md, skills/, or .mcp.json files. See onion_goal to generate a GOAL.md fitness function.'
• Implement a dry-run or confirmation step for onion_fix. Return generated file contents for user review before writing to disk. Add a separate 'apply_onion_fix' tool that writes confirmed changes.
• Add tool annotations: mark onion_scan, onion_audit, onion_goal as readOnlyHint=true; mark onion_fix as destructiveHint=true and idempotentHint=false to signal that retries may duplicate files.