pix_list_metrics

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

It explains key behavioral semantics beyond the readOnly/idempotent annotations: these are continuous sampled series rather than event lists, and keys_available counts keys per lane, which is distinct from row presence. It does not describe output schema details, but an output schema exists to cover that.

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?

Three sentences, with the core purpose first and no filler. The explanatory aside about keys_available is useful but slightly dense; overall it earns its place.

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?

For a read-only listing tool with an output schema, the description adequately explains the conceptual model and next step (pix_get_metric_values). It leaves optional timeout_seconds undocumented and could be more explicit about capture_id, but the core calling context is present.

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%, so the description carries the burden, but it only refers obliquely to 'this capture' and never explains capture_id or timeout_seconds. The timeout parameter is entirely undocumented in both schema and description.

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 states the tool returns 'the metric series this capture can plot' and explains these are sampled graph lanes, which identifies the resource and scope. It also distinguishes them from 'a list of events', though it does not explicitly contrast with sibling metrics/counters tools like pix_list_counters or pix_get_metric_values.

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 gives context that this lists available metric lanes and closes with 'Feed a lane name to pix_get_metric_values', which implies a follow-up workflow. It does not explicitly state when to choose this over related tools, nor does it offer exclusions or alternative conditions.

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