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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds two genuinely new facts beyond them: the 'reconcile' permission requirement and the state precondition that only pending drafts can be edited before approval. It still omits whether omitted arguments leave existing values intact or clear them – the key behavioral question for an idempotent edit.

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-loads purpose, then permission, then argument list – a sensible order with no filler. Dense but every clause carries information; the argument enumeration is compact rather than padded.

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 7-parameter mutation tool with no output schema and sparse annotations, the definition supplies the essentials: purpose, permission gate, editable state, and parameter shapes. It falls short on partial-vs-full update semantics and any note about the result of the edit, but the core is present.

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 only 14% (just orgnr), so the description carries most of the burden. It names all arguments, gives a date format (YYYY-MM-DD) and, importantly, expands the otherwise-empty 'lines' array into [{account, debit_ore, credit_ore, text?}] – a real add over the schema. series, text and note are still named without explaining their effect.

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?

Names a specific verb and resource (Ändra ett verifikatförslag / edit voucher draft) plus a scope constraint (väntande, innan det godkänns – pending, before approval) that cleanly separates it from approve_voucher_draft, reject_voucher_draft and book_voucher. It does not name a sibling explicitly, but the 'pending, pre-approval' scope makes the distinction inferable.

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?

States a precondition (requires the 'reconcile' permission) and an implicit usage window (only pending drafts, before approval). It gives no explicit guidance on when to pick this over siblings such as create_voucher or list_voucher_drafts, and no exclusions, so usage is only implied.

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