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

Annotations already establish this is a non-read-only, non-destructive, non-idempotent write. The description adds that the operation is a 'proposal' and requires a public URL, but never explains what proposing entails — e.g. whether it enqueues a pending action needing approval via manage_action, despite that being core behavior for an agent. It also does not warn about non-idempotency, which the annotations flag.

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?

Very short and front-loaded, with the '[Order changes]' category tag first and the core action immediately after. Nothing is padded, though the brevity comes at the cost of the missing behavioral 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?

An output schema exists, so return-format explanation is not required, and the target/data-scope note is present. However, for a mutation that is explicitly non-idempotent and framed as a 'proposal', the description omits the resulting workflow state and permission/auth expectations an agent needs.

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 50%: url and account are documented in the schema, but name and order_id are not. The description only echoes the 'public URL' detail already in the schema and says nothing to disambiguate the bare 'name' parameter or clarify accepted order_id formats, so it fails to compensate for the coverage gap.

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 (propose attaching) and resource (an invoice PDF) against a named target (an order), and reinforces the URL input mechanism. It is clearly distinguishable from neighbor tools like invoices_issue or invoices_issue_for_order, though it doesn't explicitly say how it differs from them.

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 guidance on when to choose this over the closely related siblings (invoices_issue_for_order, invoices_issue). The only scoping statement — 'Works on: Demo shop (sample data)' — is a data-availability note, not a when-to-use rule.

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