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

Annotations already declare the non-read-only, non-destructive, open-world profile, so the description's job is to add context — and it does: a newly published action enters Review with per-use human approval until an admin promotes it to Automatic, which materially changes how an agent should sequence this call. It omits what happens to the previously published revision and what a version mismatch returns, keeping it short of a 5.

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 short sentences, front-loaded with the action and its versioning contract, with no filler. The middle sentence ('The agent can propose it from the next investigation') is the weakest — its wording is slightly oblique — but it is not padding.

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 6-parameter mutation with 5 required fields and no output schema, the definition covers the approval gate and version expectation but leaves open what happens on a stale version, whether the prior revision is retained, and how idempotency_key interacts with the non-idempotent annotation. Enough to call it, not enough to call it confidently in failure cases.

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 50%: reason, idempotency_key, and expected_version carry their own descriptions, while company, environment, and key are documented only by format/enum/pattern. The description mentions the expected-version concept but explains no parameter, so it neither compensates for the gap nor is it fully redundant — a baseline 3.

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 names a specific verb ('Publish') and resource ('the current draft as the next revision') plus the concurrency contract ('with the expected version'), so the operation is unambiguous. It does not, however, distinguish itself from near-siblings such as summer_actions_company_save, summer_actions_stage_update, or summer_actions_company_retire, leaving the agent to infer the boundary.

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 agent can propose it from the next investigation' implies a usage context but is vague about preconditions and does not say when to prefer save/stage_update over publish, or when not to publish at all. The approval-workflow sentence hints at consequences rather than routing guidance, so usage is implied rather than stated.

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