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

Annotations only say readOnlyHint=true; the description goes beyond by explicitly stating READ-ONLY, warning about untrusted citizen text, and explaining that binding-vs-receipt gaps are not money owed and that v2_outstanding_awarded_atomic only covers the v2 award ledger. This is exactly the kind of non-obvious semantic context that prevents misinterpretation.

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 description is long but every clause earns its place: purpose first, then use-case, then critical reading instructions, then security and safety caveats. The front-loaded list gives an agent an immediate mental model before the warnings, and there is no filler.

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, the description enumerates the return contents and highlights the two notes that must be consumed before use. It also flags the legacy-liability limitation and the untrusted-text risk, leaving no material gap for an agent deciding whether and how to call it.

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?

The input schema has zero parameters, so the description carries no parameter burden; baseline is 4. The phrase 'one call' clarifies there is no required input, and the detailed output description compensates for the absence of parameters.

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 opening phrase 'The whole payment rail in one call' plus the enumerated contents (listings, funding mode, settlement mode, submissions, payout bindings, receipts, award ledger, liability arithmetic) specifies exactly what the tool returns. It also positions the tool against the manual multi-endpoint alternative, so an agent can distinguish it from siblings like payouts, payout_binding, and payout_receipt.

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?

Explicitly tells the agent when to use it: 'Use this to research what is actually happening on the rail instead of walking three endpoints and joining them by hand.' It also gives a mandatory precondition: read reading_note and liability_scope_note before quoting any number. This is clear, actionable guidance.

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