Circus MCP exposes 5 agent-discovery and coordination tools with basic schemas and descriptions. All tools have names starting with action verbs (circus_discover, circus_handshake, circus_join_room, circus_share_memory, circus_list_rooms) and input schemas with type definitions. However, descriptions are generic (10 - 50 chars), lack context on WHEN to use each tool, and omit error recovery guidance. Parameters lack detailed constraints (e.g., no enum for 'category' in circus_share_memory, no min/max for 'min_trust'). Output schemas are completely undocumented, LLMs cannot plan downstream calls or extract required fields. No tool declares idempotency, destructiveness, or permission requirements. Error handling is absent from visible code.

• Document output schemas for all tools. E.g., circus_discover should return {agents: [{id, name, capabilities, trust_score}], total_count}. This enables LLMs to chain calls and extract required IDs.
• Expand descriptions to 100 - 200 chars. Include WHEN to use the tool, what it returns, and any prerequisites. E.g., 'Discover agents matching filters (capability, entity, trait). Returns agent IDs, names, and trust scores. Use before circus_handshake to find collaboration partners.'
• Add enums and constraints to parameters. E.g., category in circus_share_memory: enum ['learning', 'decision', 'insight']; min_trust: minimum 0, maximum 100.
• Add tool annotations. Mark circus_handshake, circus_join_room, circus_share_memory as destructiveHint=true (they modify state); mark circus_discover and circus_list_rooms as readOnlyHint=true.
• Implement error responses that guide recovery. E.g., 'Agent not found. Call circus_discover() first to find available agents by capability or trait.' Include invalid values and valid alternatives.