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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: the backend is a sandbox/demo that fabricates a sample run, output 'is not evidence of production execution,' existing credentials and signed mandates are still required, and unavailable/non-JSON backends surface as tool errors. That is meaningful disclosure of behavior and side effects an annotation cannot express.

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?

Four paragraphs restate the same idea twice ('Create a short, portable proof object' vs 'Creates a portable proof passport'). It is front-loaded with the confusing 'Unavailable historical backend' line rather than the primary purpose, and the boilerplate about credentials/authority dilutes the signal.

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, open-world tool with no output schema, the description does cover credentials, error surfacing, and the sandbox limitation. What it never resolves is the tension between promising a verifiable proof object and disclaiming that nothing is retrieved or verified, so the agent cannot fully predict the outcome of a call.

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% and the single 'mode' property is effectively an opaque free-form POST body with additionalProperties allowed. The description partially compensates by telling the agent to 'Supply its documented mode, arguments, and required signed authority or grant,' but the parameter remains unspecified with no example or format, so the agent is left guessing at valid values.

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 give a specific verb and resource ('Create a short, portable proof object for a completed rail run'), which sets it apart from the many sibling rail tools. However, it immediately undercuts itself by declaring an 'Unavailable historical backend' and saying it 'does not retrieve or verify completed work or supplied proof,' leaving the agent unsure whether it produces anything real. The core purpose lands but is muddied by the sandbox framing.

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?

It supplies a clear temporal cue ('Use it after a completed run') and names the artifacts it touches (receipt, return package, callback, transcript linkage). No alternative sibling is named, and no when-not-to-use condition is given, so routing between this and adjacent proof/return-package tools is left to inference.

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