Разбор платёжного QR

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds what happens beyond the annotation state: the tool queries the bank for the provider, is safe to run first as a preview, and may optionally need a user-provided comment if the QR lacks the payment purpose. No contradiction with annotations.

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 longer than a simple sentence, but every phrase 'adds' something: the non-destructive note, the provider routing, the comment issue. It is front-loaded with the core purpose and read-only warning. It is somewhat cluttered in the paragraph, but not bloated.

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?

The output schema handles formal return fields, while the description explains the practical flow: what recipient info is shown, which downstream sibling to pick, when to ask about comment. This is sufficient for an agent to call and use the tool correctly; additional nuance such as error handling for invalid QR codes would be a small bonus.

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?

With 0% schema coverage, the description carries the full burden for `qr`. It identifies needed input as the payment QR from a receipt/invoice, formatted per GOST with the ST0001... payload. It implies this directly maps to the only parameter, though it never explicitly writes 'pass the QR payload in the qr parameter', which would make it clearer.

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 unique verb+resource: "Прочитать платёжный QR со счёта/квитанции" with the specific standard and format (ГОСТ Р 56042-2014, ST0001). It also differentiates itself from siblings like ticket_qr by scope (payment) and from pay_bill/transfer_requisites by role (parse/read vs. execute payment).

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 says when to use: before transfer_requisites, to show the user recipient/amount/commission. It also contains a routing rule: legal-entity requisites → transfer_requisites, any other provider → pay_bill, plus a condition for when comment must be asked from the user. This makes alternatives and selection conditions clear.

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