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

Annotations only declare a destructive write; the description adds substantial context on top: partial semantics (lines not linked to a catalog item and batch-tracked items needing a lot number are skipped and listed), idempotency ('what is already received is not received twice'), and post-condition visibility via erp_stock_levels. It also fully discloses the proposed-write protocol — status='confirmation_required' with action_id and plan_token, write only after confirm_action — which is exactly the behavioral detail an agent needs before calling a destructive tool.

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?

Front-loaded with the action and its scope, then the addressing rules, the exclusion caveats, idempotency, and the confirmation protocol in that order. It is dense but nearly every clause carries operational meaning; the parentheticals and the bilingual gloss add a little weight without much loss.

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, no-output-schema mutation, the definition covers what is written, what is deliberately skipped, repeat-call safety, and the two-step confirmation handshake needed to actually execute. Nothing material for a correct invocation is missing apart from the required-key ambiguity noted above.

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 only 33% (only draft_id is described in the schema), so the description must compensate, and it largely does: it explains the draft_id vs invoice_id alternate keys and the conditional meaning of 'warehouse' as a name, not an id. It does not resolve the ambiguity that the schema marks zero required parameters, leaving unclear whether draft_id and invoice_id are mutually exclusive or one is mandatory.

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 gives a specific verb and resource (receive goods of a recorded supplier invoice into stock) plus the domain synonym «оприбуткувати», and scopes it precisely to catalog-item lines. It is clearly distinguishable from purchase_invoice_list, purchase_invoice_get and erp_stock_levels, which are mentioned only as sources of the id or as verification.

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 says how to address the invoice (draft_id from purchase_invoice_list, or the ERP invoice_id) and when to pass 'warehouse' (only when the company has several, else the main one). What's missing is a negative routing statement, e.g. that an unrecorded invoice must first be created via purchase_invoice_create_from_file rather than received here.

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