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

The description adds real value beyond the annotations: it names required authority (product credentials, signed mandates, single-use action grants), states that the adapter never supplies server credentials, and documents failure behavior (unavailable or non-JSON backends produce tool errors). But it also asserts "Sandbox/demo... does not create a stored invoice, send a bill, collect payment or record an operator decision" and "This adapter grants no authority," while the annotations declare destructiveHint=true, readOnlyHint=false, and the description elsewhere claims it "Creates invoice-style optional authority." The side-effect profile contradicts the annotations and contradicts itself.

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 most important sentence (what the tool does) is buried in second position behind a dead-end note about an unavailable historical backend, and the remainder is a stack of hedging disclaimers alternating with operational claims. It is not front-loaded and several sentences (proxy disclaimer, sandbox note, availability clause) work against rather than for selection.

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?

There is no output schema, so the description carries the burden of explaining returns; it only hints at a "queued label" that "does not represent a real queue entry" and some binding to rail run/receipt/return package state, without ever describing the actual response. Combined with an undocumented parameter and contradictory statements about whether anything is persisted, the definition is not complete enough for an agent to invoke this open-world, non-idempotent tool with confidence.

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% for the single "mode" property, and the description never explains what mode means, what values are accepted, or how arguments/signed authority should be packaged. "POST /api/agent-invoice-rail" adds only the transport, and the object-level schema text defers to an undocumented "product contract." With a low-coverage parameter, the description had to compensate and does not.

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 does contain a usable verb+resource statement ("Create an invoice-style reference for a rail run when instant checkout is not the right payment flow") and it implicitly distinguishes itself from the checkout sibling. However, it is preceded by "Unavailable historical backend" and "Sandbox/demo: prepares an example invoice-reference object for review," which frame the tool as non-functional and conflicting with the mutation framing that follows. An agent must reconcile three different accounts of what this tool is before it can decide anything.

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 a stated condition of use ("when instant checkout is not the right payment flow") and a mention that credentials, signed mandates and single-use grants are required where applicable, which is genuine routing context. But no alternative sibling is named, and no when-not-to-use case is given beyond the vague "catalog proxy entry, not a guarantee of backend availability" warning.

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