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

Annotations already declare destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description adds context the annotations do not: a confirmed=true gate before execution, that the channel header is resolved internally, and that the call both performs the processing attempt and returns refreshed order data or an error. No conflicting claim is made.

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?

Purpose and usage are front-loaded, which is good. The entry is padded with boilerplate ('explicit tool with a fixed endpoint; it is not a generic endpoint caller') and a low-value 'Search terms: sales processorderline' line, and the output behaviour is described even though an output schema exists.

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 destructive write endpoint, the description covers the confirmation gate, auth header handling, the main payload field and the success/error outcome. With an output schema present, returning to return-value detail is redundant but not harmful. Sibling differentiation is the one material gap.

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%, so the baseline would be 3. The description earns more by surfacing the request type (LoadAddressesFromOrderLineRequest) and the key payload field OrderLineIds: int[], neither of which appears in the schema, and by explaining the confirmed and channelOAuthId requirements in operational terms.

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 and resource: 'Starts automatic supplier purchase processing for exact existing order lines using the current saved auto-ordering settings.' That is far more than a restatement of the tool name. It does not, however, distinguish this from close siblings such as hgr_force_process_order_lines, hgr_process_order_lines or hgr_post_sales_forceprocessorderline, which an agent would need in order to choose correctly.

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?

An explicit 'Use when' clause is present: process or retry an existing order after correcting a payment card or another auto-ordering setting. That gives a concrete trigger. It stops short of naming alternatives or exclusions, so an agent comparing it with the force-process and manual-dispatch siblings is still left to infer the boundary.

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