Update owned release metadata

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

Annotations only mark this as destructive/non-idempotent, while the description adds critical behavioral detail: description/category are shared APP fields affecting all releases; other attributes are preserved; exact user confirmation and unchanged state are required; and uncertain outcomes are never automatically retried. This gives an agent the safety-relevant context beyond the structured annotations.

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 composed of short, purposeful sentences, each adding a distinct constraint: core action, shared-field side effect, preserved attributes, preconditions, RPM scope, and retry policy. The primary action is front-loaded, and there is no redundant filler.

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?

With an output schema present, return values do not need to be described. The description covers field semantics, cross-release side effects, preserved data, preconditions, non-idempotency, and the binary/RPM limitation, making the tool safe and callable by an agent. The only slight ambiguity is the exact mechanics of 'user form confirmation', but the requirement itself is clearly disclosed.

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 0%, so the description must compensate. It explicitly names description, category_id, and release_notes as the editable fields, identifies version_id as the target version, and implies app_id through the 'shared APP fields affecting all releases' statement. It does not formally enumerate every parameter, but an agent can map the schema properties from the textual clues.

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 first sentence states a specific verb ('Change'), the exact editable fields ('plain-text description, category_id and/or release_notes'), and the target scope ('owned version_id'). It clearly differentiates this from sibling tools by limiting it to metadata changes and explicitly excluding RPM replacement.

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 description gives clear usage context: it applies only to owned versions, requires exact user form confirmation, and requires an unchanged state. It also states what the tool does not do ('Does not replace RPMs'), but it does not explicitly name an alternative sibling tool for RPM replacement, so the routing guidance is strong but not fully explicit.

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