gitops-mcp has 11 tools with basic descriptions and input schemas, but significant gaps limit production readiness. Most tools lack parameter descriptions (e.g., cluster_query accepts 'command' with no format/constraint guidance). Descriptions are present but generic, many under 100 chars and lacking WHEN/WHY context. No output schemas documented. Error handling is absent; tools provide no recovery guidance. Tool naming is reasonable (verb_noun pattern) but composition issues exist: org_query is a mandatory audit wrapper rather than a standalone tool, forcing artificial sequencing. Security concerns: auth_login and cluster_connect are WRITE operations but lack confirmation/dry-run patterns. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels.

• Add output schemas to all tools. Document returned fields (tenant_id, environment_id, status, etc.) so agents can chain calls without guessing. Example: tenant_list returns [{name, region, version, status}].
• Enhance cluster_query description with allowed command patterns and constraints: 'Read-only kubectl commands only (get, describe, logs). Prefix with kubectl or omit. Examples: get pods, describe deployment nginx, logs pod-name.'
• Add destructiveHint and idempotentHint annotations to tools. Mark auth_login and cluster_connect as destructive; mark auth_status and all read-only tools as idempotent.
• Implement confirmation/dry-run for auth_login and cluster_connect. Add optional 'dry_run' parameter or require explicit confirmation before executing.
• Refactor org_query from mandatory wrapper to optional audit tool. Remove 'ALWAYS call this first' language; let agents decide when to log. Alternatively, move audit logging to middleware without exposing it as a tool.

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

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