infrabroker demonstrates strong tool design with clear naming conventions, detailed descriptions, and comprehensive parameter schemas. All 13 tools follow verb_noun patterns (ssh_execute, k8s_apply, etc.). Descriptions are generally 150-250 characters and explain what the tool does, when to use it, and prerequisites. All parameters have type definitions and helpful descriptions. However, there are gaps in output schema documentation, return types are not explicitly defined in the visible schema structures, and error handling guidance is minimal. The tool composition is excellent: ssh_* and k8s_* form coherent families with appropriate risk annotations (WRITE, READ_ONLY, DESTRUCTIVE). Parameter relationships are well-documented (e.g., dry_run behavior, sudo constraints, TTL handling). Security practices are sound, no credentials exposed as parameters, risk levels clearly marked. The main weakness is incomplete output schema documentation and missing recovery guidance for error cases.

• Document output schemas explicitly for each tool. Define the JSON structure returned by ssh_execute (stdout, stderr, exit_code, etc.), k8s_get (the full Kubernetes object structure), and k8s_list (items array with count/next_cursor). This enables LLMs to extract the right fields for downstream calls.
• Add structured error responses with recovery guidance. When a call fails, return {error: '...', action: 'retry|ask_user|give_up', suggestion: '...'}. E.g., 'User not found in RBAC groups. Verify the user's group membership or request elevated access.'
• Add limit and offset/cursor parameters to ssh_list_servers and k8s_list_clusters. Default limit=50, support limit=1-1000. Return total_count so LLMs can decide whether to paginate. Update descriptions to note the limit.
• Add pagination to k8s_logs. Support limit for line count (default 50-100) and next_cursor for continuing past a certain log offset. Return {lines: [...], next_cursor: '...', has_more: bool}.
• Make enum constraints explicit in schemas. For ssh_session_open mode, define enum: ['exec', 'shell', 'pty']. For k8s_* resource, hint that values are lowercase plurals (pods, deployments, configmaps).
• Expand error handling in tool descriptions. Add a note like: 'If the policy denies access (allow_sudo=false or allow_pty=false), this tool returns a policy_denied error. DO NOT retry, inform the user that this host does not support the requested capability.'
• Document what happens when session_id is invalid in ssh_session_exec and ssh_session_close. Return a specific error (session_not_found) with guidance to open a new session.