List Depot CI runs

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context beyond safety. It adds newest-first ordering, the limited return payload ('identity, status and timing only'), and the explicit absence of logs or failure detail. Pagination behavior is not described in prose, but the schema's pageToken parameter covers that gap.

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 description is front-loaded with the core action and ordering, then moves to use cases, a recommended call pattern, and finally the boundary of what the tool returns. Every sentence earns its place and no sentence merely repeats the schema or annotations.

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 list tool with a rich input schema and an output schema, the description covers ordering, filtering, return scope, exclusions, and next steps with the returned runId. An agent can both select this tool over siblings and invoke it correctly without needing further inference.

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 100%, so the baseline is 3. The description adds value by grouping the optional filters into a readable list and by providing a concrete recommended argument combination: status=['failed'] with limit=1. It does not redefine each parameter, but the invocation pattern gives the agent useful guidance beyond the raw schema.

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 opens with a specific verb+resource: 'List recent Depot CI runs' including ordering ('newest first'). It clearly names the filter dimensions and explicitly contrasts itself with depot_diagnose_ci_failure and depot_get_ci_run by stating what it returns and what it does not. This cleanly separates it from sibling list/detail/diagnosis tools.

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?

It gives concrete use cases ('find the run someone is talking about', 'did main go green', 'what ran for PR 412') and a recommended fast path: status=['failed'] with limit=1, then depot_diagnose_ci_failure. It also explicitly says the tool does not return logs or failure detail and directs the agent to depot_diagnose_ci_failure for that, so when-to-use and when-not-to-use are both clear.

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