SHINE tools lack critical definition quality. Tool descriptions are present but generic (avg ~80 chars, well below 194-char baseline). Input schemas are visible in code but lack formal JSON Schema structure, parameters are documented in comments, not in a machine-readable schema object. No output schemas documented. Parameters lack type constraints (enums, ranges). Error handling is minimal (fail() calls with generic messages). No tool annotations (readOnlyHint, destructiveHint). Tools like 'commit' and 'commit-to-subrepo' perform destructive operations but lack confirmation patterns. Parameter descriptions are sparse (e.g., 'phase' is just 'Phase number (default: 1)', no format guidance). No pagination support despite tools returning lists (roadmap, verify). Composition is weak: 'init' and 'state' should be separate from 'commit' operations, but state mutation is conflated with read operations.

• Define formal JSON Schema for all tool inputs. Include type, description, enum (for constrained params), and default for each parameter. Example: 'phase' should be {type: 'string', description: 'Phase number (1-99, default: 1)', pattern: '^[0-9]{1,2}$', default: '1'}.
• Add output schema documentation for all tools. Specify returned fields, types, and structure. Example for 'roadmap': {type: 'object', properties: {phases: {type: 'array', items: {type: 'object', properties: {number: {type: 'number'}, title: {type: 'string'}, ...}}}}}.
• Implement confirmation pattern for destructive operations. Add a 'confirm' parameter (boolean, default false) or a separate 'preview_commit' tool that returns a diff before actual commit.
• Expand parameter descriptions to 50 - 150 chars. Include format, constraints, and examples. Example: 'phase: Phase number (1-99, default: 1). Determines which phase directory to initialize.'
• Add error recovery guidance. Replace 'git add failed: <stderr>' with 'Git staging failed. Ensure you are in a git repository and have write permissions. Retry or check git status.'.