claude-bridge has 22 tools with complete schemas and descriptions, but quality is uneven. Naming is verb-first and mostly clear (list_*, peer_*, get_*, set_*), following conventions well. Descriptions are present for all tools (avg ~120 chars) and parameters, meeting baseline minimums. However, descriptions are often terse and lack context about WHEN to use tools or dependencies between them. Parameter descriptions exist but are minimal (avg ~50 chars). Output schemas are not documented, callers must infer structure from code. Error handling is basic (err() helper returns code+message but no recovery guidance). No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Peer-related tools (peer_ask, peer_reply, peer_spawn, peer_stop, peer_restart, peer_compact) modify state but descriptions don't explicitly warn of side effects. Control-plane tools (team_layout, peer_spawn, peer_stop, peer_restart, peer_compact) are high-risk but lack confirmation/dry-run patterns.

• Add output schema documentation to every tool. Document the ToolResult.content[].text JSON structure (e.g., 'Returns {ok: true, count: number, projects: Array<{projectDir: string, path: string}>'). This enables LLMs to plan downstream calls and extract data reliably.
• Add tool annotations via MCP SDK: mark read-only tools with readOnlyHint=true (list_*, peer_list, peer_inbox_read, peer_chat_read, peer_chat_search, peer_context_status, model_info, rate_limit_status, team_status, control_status); mark destructive tools with destructiveHint=true (peer_spawn, peer_stop, peer_restart, peer_compact, team_layout, peer_ask, peer_reply, peer_set_*); mark idempotent tools with idempotentHint=true where applicable.
• Expand descriptions for control-plane and peer-modification tools to 100-150 chars. Include: what the tool does, when to use it, side effects, and prerequisites. E.g., 'peer_spawn: Create a new peer session (daemon control-plane). Side effect: spawns a new process. Requires daemon running. Use when starting a new isolated Claude Code session.'
• Implement confirmation/dry-run pattern for destructive tools. Add optional 'dryRun' boolean parameter to peer_spawn, peer_stop, peer_restart, peer_compact, team_layout. When true, return what would happen without executing. This prevents accidental peer termination or data loss.
• Enhance error responses with recovery guidance. Instead of 'list_projects_failed', return 'list_projects_failed: Could not read project directories. Ensure CLAUDE_BRIDGE_ROOT is set and readable. Try control_status to check daemon health.' This guides LLM retry logic.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry