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

Annotations declare the write/non-idempotent/non-destructive profile, but the description adds material context the annotations cannot convey: the operation may consume the shop's credits when the fix is not free, and the result is asynchronous ('replaces the post's media when it is ready'). It stops short of covering failure behavior or reversibility (undo_change exists), so not a full 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 sentences, each earning its place: what it does, the required pre-call sequence, and the observable outcome. Front-loaded with the core action and free of repetition.

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 no output schema and only safety annotations, the description supplies the key missing pieces an agent needs: the credit-cost implication and the deferred media replacement. It omits what happens on failure or whether the fix can be undone, a minor gap for a one-parameter confirmation 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 description coverage is 100% and the single audit_id parameter is already documented as coming from request_post_fix, so the schema carries the load. The description reinforces the provenance but adds no syntax or format detail beyond it, making the baseline 3 correct.

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 (runs/confirms) and resource (a post fix started by request_post_fix) and ties it explicitly to the sibling that created it. An agent can distinguish this from request_post_fix (starts the fix) and post_fix_status (checks it) without opening any schema.

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?

Gives an explicit prerequisite sequence: 'Call post_fix_status first and tell the merchant whether it is free or what it costs.' It names the sibling tool to consult before invoking and the merchant-facing step in between, leaving nothing to inference.

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