Создать оплату от покупателя

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true) it discloses that the created document is left unposted, that posting yields Дт 51 Кт 62 with the settlement account derived from contract settings, that currency/u.e. contracts require a rate in 1C or the payment posts without entries, and that the org bank account defaults to the main one. These are exactly the mutation consequences an agent cannot infer from structured fields.

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 core purpose and posting behavior are front-loaded, and each subsequent sentence carries distinct information (unposted state, currency caveat, account defaulting). The clipped trailing 'dry-run/confirm.' is terse and slightly ambiguous, and the dense accounting jargon makes it heavier than ideal.

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 10-parameter mutation with an output schema, the description covers what matters: what document is created, its unposted state, the posting produced, currency-rate pitfalls, and default resolution for organization/bank account/default database. The dry-run/confirm protocol is fully spelled out, leaving no operational gap for correct invocation.

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 already 100%, so the baseline is 3. The description adds modest value on defaults (bank account taken by name or the first/main one, amounts auto-filled for rouble contracts) but does not extend most individual parameters beyond what the schema text already says.

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 concrete verb and an exact 1C document type («Поступление на расчётный счёт», оплата от покупателя) produced from amount, counterparty and contract. That resource is distinguishable from the sibling write.money.create_bank_writeoff (outgoing) and write.money.create_cash_receipt (cash desk) without opening any schema.

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 gives clear operating conditions: always run dry-run first, get user consent, then resend with operationId and identical arguments, and retry confirmation with the same id after a timeout. It also warns when to set operationKind ('обычно НЕ задавайте… не угадывайте') and when a rate must be supplied for currency contracts. It stops short of explicitly naming which sibling tool to pick instead for cash or outgoing payments.

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