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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: result ordering (not-ready and failed pods sort first), the refusal semantics for an unscoped list (error_code scope_required), and the response envelope (total, returned, truncated, scope). It does not mention permissions or pagination defaults for limit, which keeps this short of a 5.

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?

Front-loaded with the highest-value information (what a row looks like, then sorting, then filtering rules, then the sibling pointer). The long field enumeration is justified because no output schema exists, and semicolons keep it to a tight block with no filler sentences.

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?

With no output schema, the description carries return-shape duty and does so completely (per-pod fields, ordering, truncation flags). Safety is covered by annotations, parameter constraints are restated, and the alternative for logs is named, leaving nothing an agent needs in order to call this correctly.

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 coverage is 100%, so the baseline is 3 and the schema already documents name, limit, namespace, cluster_id, all_namespaces and label_selector. The description adds the constraint interplay ('a list needs namespace or all_namespaces=true', 'a named read needs neither') and the truncation envelope, which helps the agent combine parameters correctly rather than restating them.

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?

States a specific verb+resource (fetch pod information, one summary row per pod) and enumerates the exact columns returned, including how 'reason' is computed. It explicitly names the sibling it is not (get_pod_logs), so an agent can distinguish it from other read tools without opening schemas.

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?

Gives explicit scenarios ('check pod health, find crashing pods, or verify deployments') plus the scoping precondition for a list (namespace or all_namespaces=true) and the negative routing rule ('For logs, use get_pod_logs instead'). Both when-to-use and when-to-use-something-else are stated.

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