list_pods

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full transparency burden and does a good job: it discloses that the tool surfaces phase, restart counts, and container status reasons, and explains the label-matching behavior for the app parameter. It does not mention authorization or pagination, but these are less critical for a read-only list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is one dense, front-loaded sentence with no filler. It leads with the action, then lists scoping options in a compact parenthetical, then states the useful output. Every clause adds information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the key invocation details and the important output semantics, and an output schema exists to fill in return type details. A minor gap is the default scope when no namespace is provided (all namespaces vs. current namespace), but this is not enough to reduce completeness further.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description manually explains all three parameters: namespace, a raw label selector, and an ArgoCD app name matched via the 'app.kubernetes.io/instance' label. This adds meaning the bare schema does not, so an agent knows exactly what values to supply and how filtering works.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with the specific verb-resource pair 'List pods' and then details the optional scoping dimensions (namespace, label selector, ArgoCD app name), making the purpose unmistakable. It differentiates itself from siblings like get_pod_logs or describe_resource by focusing on the pod inventory/health overview. The mention of App tracking label also clarifies exactly what 'app' means.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use the tool: to view pods and quickly detect unhealthy containers, with filters that can narrow scope. It stops short of explicitly contrasting with alternatives or stating when not to use it, but the scoping options and health-surfacing goal provide a clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.