Peer-bus MCP has significant definition quality gaps. Tool descriptions are dense, technical, and assume deep domain knowledge of peer-bus internals (bus_version, pool.schema, heartbeat keys, reader keys). Most descriptions exceed 200 chars and use jargon ('herdr', 'tmux', 'grok', 'flock', 'pane') without explanation. Parameter descriptions are sparse or missing entirely: 'to' in send_message has a description, but 'body' does not; 'include_stale', 'include_read', 'limit', 'display_name' lack descriptions. Input schemas are present but minimal, no enums, no ranges, no validation hints. Error handling is generic ('ok': false, 'error': string) with no recovery guidance. Naming is acceptable (verb_noun pattern: list_agents, send_message, receive_messages) but 'flock' and 'list_agents' are duplicates with identical schemas and nearly identical descriptions, violating the single-responsibility principle. No output schemas are documented. Security: display_name parameter could be misused; no explicit permission gates or audit trail hints.

• Remove 'flock' and keep only 'list_agents' (or vice versa). Consolidate duplicate tools to reduce LLM confusion.
• Rewrite descriptions for non-expert LLMs. Replace 'Live flock as {bus_version, pool, agents}. pool.schema is an integer (2 = five_hour+seven_day+state)...' with 'List all active agents connected to the peer-bus network, including their status and availability window (5-hour or 7-day).' Avoid jargon; explain what the tool does in plain English.
• Add descriptions to all parameters. E.g., 'body' → 'The message text to send (plain text, max 10000 chars)'; 'include_stale' → 'If true, include agents that have not sent a heartbeat in the last 5 minutes'; 'limit' → 'Maximum number of messages to return (1-100, default 50)'.
• Document output schemas for each tool. E.g., list_agents returns {bus_version: string, pool: {five_hour: int, seven_day: int, state: 'live'|'stale'}, agents: [{name: string, ref: string, context: string, ...}]}.
• Enhance error messages with recovery guidance. E.g., 'Invalid recipient: "Ada [9e7e13]" not found in live roster. Call list_agents() to see available recipients.' instead of 'Invalid recipient'.