ddflow_promote_status

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

With no annotations provided, the description carries the full disclosure burden; 'Reads only' is the one behavioral claim it makes and it usefully rules out mutation. Beyond that it says nothing about permissions, scoping, or what an open promotion means operationally. It is the minimum safe disclosure for a read tool, not rich context.

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 dense sentence with zero filler, and the read-only constraint is saved for the end as a clean qualifier. The colon-list construction is slightly awkward but front-loads the subject (each environment branch) before the detail.

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?

There is no output schema, so the description's field list doubles as the return-value summary, which is genuinely useful. However, it does not explain what an 'open promotion' or 'auto_promote' implies for the caller, and with one optional param and no annotations the definition is adequate but thin for a promotion-status tool.

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% and the single optional as_agent parameter is fully described in the schema, including a pointer to ddflow_identify. The description adds no parameter meaning of its own, so the baseline 3 for well-covered schemas applies.

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 enumerates exactly what is reported per environment branch: head, commits behind upstream, open promotion, and auto_promote flag. Combined with the name ddflow_promote_status, an agent can tell this is a read-only promotion-state inspector distinct from ddflow_promote_add or ddflow_pr_status. It stops short of a crisp 'reports the promotion status of environment branches' opener, but the content is unambiguous.

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?

There is no statement of when to call this versus siblings such as ddflow_pr_status, ddflow_status, or ddflow_promote_add, and no prerequisites or conditions are given. The only implied guidance is 'Reads only', which says nothing about the situation that warrants calling it.

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