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

Annotations already declare the safety profile (readOnly=false, destructive=true, idempotent=true), and the description usefully adds side effects beyond them: VAT-breakdown edits recompute base and VAT totals, foreign currency is re-converted at the CNB rate to DUZP, and the change is logged to document history. It does not address the destructive angle named by the annotations — e.g. that 'note' overwrites the existing value, or that fields omitted from the call stay untouched versus being cleared — so the added context is real but partial.

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?

Four short sentences, each carrying a distinct fact (fields, VAT recalculation, FX conversion, audit trail), with the field list front-loaded. No filler or repetition, though it could be tightened into fewer, more structured clauses.

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 15-parameter mutation with no output schema, the description covers the main computational side effects but leaves important operational questions open: partial vs. full replacement semantics, whether locked/approved documents can be edited, permission requirements, and what a successful response contains.

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 60%, so the baseline is 3. The prose explains the semantic consequence of the VAT-rate fields (recalculation of base and VAT totals) and the currency conversion rule, which is genuine value beyond the schema, but it never mentions totalAmount, receiptDate, or the null-means-clear convention that the schema defines for taxDate and companyId.

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 opens with a specific verb and resource ('Opravi udaje dokladu') and enumerates the mutable fields (date, DUZP, VAT-rate amounts, type, company, note), so an agent knows exactly what class of operation this is. It does not explicitly differentiate itself from siblings such as correct_vat_filing or delete_document, which keeps it from a 5.

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?

There is no when-to-use guidance, no exclusion of alternatives, and no stated prerequisites (e.g. whether an approved/filed document may still be edited, or when to prefer correct_vat_filing over editing amounts). The agent must infer usage purely from the verb and field list.

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