ddflow_pr_status

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

No annotations are provided, so the description carries the full burden, and it does disclose the key traits: it is a log-only read that does not touch the forge, and its data is a snapshot ('as last recorded', 'when it was last looked at'). It does not cover output shape or whether results are paginated, so it falls short of complete disclosure for a tool with zero annotation coverage.

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 tightly-packed sentence plus a scoping clause, with the core purpose front-loaded and zero filler. Every phrase (field enumeration, staleness cue, sibling contrast) 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 low-complexity read tool with no output schema and one optional parameter, the description covers purpose, scope, staleness and the alternative tool. It substitutes the field list for an output schema, leaving only minor gaps around result shape/pagination.

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?

The single parameter (as_agent) is fully documented in the schema at 100% coverage and the description adds nothing about it. Baseline 3 applies when the schema already does the heavy lifting.

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 (reads the log) and resource (every item's pull request status as last recorded), and even enumerates the fields returned — review, checks, target, rounds, last-looked-at. It explicitly contrasts itself with the sibling ddflow_pr_sync, so an agent can pick it out 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?

Names the alternative tool explicitly ('ddflow_pr_sync asks the forge') and states the selecting condition (this reads the cached log only). The when-to-use-this vs when-to-sync decision is fully spelled out.

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