Nucleus Brain is a bash-based STDIO server with 31 tools. Critical issues: (1) Tool definitions are inferred from shell script comments and help text, not explicit MCP tool registration, no visible JSON Schema definitions in source. (2) Most tools lack structured input schemas; parameters are documented in comments but not in machine-readable form. (3) Descriptions are present but often generic (e.g., 'Start Nucleus infrastructure') and under 50 chars. (4) No output schemas documented. (5) No error handling guidance, tools fail silently or with raw shell errors. (6) No parameter validation or type constraints visible. (7) Tools like 'nucleus init' and 'nucleus sync' combine multiple concerns (detect stack, initialize, wire connection). (8) No idempotency guarantees or confirmation patterns for destructive ops (e.g., 'bd-lock clear'). Per-tool analysis: nucleus init (naming 70, description 40, schema 0, overall 37); nucleus start/stop/restart (naming 80, description 30, schema 0, overall 37); bd-lock clear (naming 70, description 30, schema 0, overall 33, destructive with no confirmation); brain query (naming 60, description 50, schema 0, overall 37). Average across 31 tools: ~28.

• Migrate from bash script definitions to explicit MCP tool registration with full JSON Schema. Each tool must have: name, description (50-200 chars), inputSchema with type and description for every parameter, and documented output schema.
• Add parameter type constraints: enums for status/mode fields (e.g., status: [in_progress, closed, open]), min/max for numeric params, regex patterns for IDs. Replace free-form strings with constrained inputs.
• Expand tool descriptions to 50-200 chars. Answer: What does it do? When should the LLM call it instead of similar tools? What does it return? Example: 'nucleus start' → 'Start Nucleus Docker containers (orchestrator, brain, dashboard). Call this after nucleus init to bring the platform online. Returns health status and port number.'
• Document output schemas for all tools. Specify what fields are returned, their types, and which IDs/references downstream tools need. Example: 'brain search returns {results: [{id, title, snippet, relevance_score}], total_count, next_cursor}'.
• Add confirmation patterns for destructive operations (bd-lock clear, nucleus stop, bd-guard bd_close). Implement a dry-run mode or require explicit confirmation parameter. Return clear error messages if preconditions fail (e.g., 'Cannot close bead: not in in_progress status. Call bd-guard bd_update with status=in_progress first.').