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

Beyond the readOnlyHint/idempotentHint annotations, the description adds real behavior: results are paginated, ordered newest-first, clamped to the plan's retention window, and filtered by the caller's role-based visibility. That retention and permissions context is exactly what an agent needs to interpret missing records. It stops short of describing page-size defaults or empty-result behavior.

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?

A single front-loaded sentence with no filler; the scope, ordering, retention constraint, and access model are all packed in without redundancy. The colon-separated dashboard reference grounds it in a known surface.

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 no output schema, the scope and visibility model are adequately covered. The gap is parameter-level detail across five optional filters at 20% schema coverage, which leaves the agent guessing about filtering and paging behavior.

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 only 20% (only 'channel' is documented), so the description must compensate and largely does not. It implies pagination via 'Paginated' but never explains page, per_page, dialect, or exit_code semantics or how filters combine.

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 ('Paginated history of the workspace's CI dry-run checks') and enumerates the sources (CLI, CI jobs, API, agents), which makes the scope concrete. It does not explicitly contrast itself with the sibling show_report, so an agent must infer that singular report retrieval lives elsewhere.

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 phrase 'history ... newest first' implies this is the enumeration tool versus the singular show_report, and the retention-window note hints at why older runs may be absent. However, there is no explicit 'use this when / use show_report instead when' statement or filtering guidance for the channel/dialect/exit_code parameters.

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