elba_upd_from_bill

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

With no annotations, the description carries the full burden and does real work: it discloses that most fields are inherited rather than supplied, that document status is derived from whether the bill carries VAT, and that duplicate UPDs per bill are blocked by default and must be explicitly permitted. It stops short of stating permission requirements, whether the document is created as a draft or published, or what the call returns.

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?

Three tightly packed sentences with no filler: the derivation is front-loaded, the status logic follows, and the two parameter rules close it out. Dense but every sentence carries information; only the mixing of behavioral rules with parameter rules slightly weakens the structure.

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 five-parameter mutating tool with no annotations and no output schema, the description covers the surprising behavior well but leaves gaps an agent would want: what the generated document's identity is in the response, whether number/upd_date are overrides, and whether the created UPD is editable afterwards.

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%, so the description must compensate. It does so well for two of five parameters — product_type with its default and scope ('for all line items') and allow_duplicate with the exact condition that requires it — but number, upd_date and even bill_id are never explained (e.g. whether number overrides the auto-generated document number, or which date upd_date sets).

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 specific operation (generate a UPD from an issued bill) and immediately explains the data source: line items, client, bank account and VAT are inherited from the bill, with the basis field set to «Счёт № от». It does not, however, distinguish itself from siblings elba_create_upd or elba_act_from_bill, so an agent must infer which generator to pick.

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?

Usage is implied through the conditional rules given — a VAT bill yields status 1, a non-VAT bill status 2, and a second UPD for the same bill requires allow_duplicate=true. Missing is any explicit statement of when to prefer this over elba_create_upd (creating a UPD from scratch) or elba_act_from_bill, leaving the sibling selection to inference.

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