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

Annotations already flag destructive=true and idempotent=true, but the description adds real value beyond them: the exact eligibility rules, the refusal case (a year with vouchers is never removed), and the return value ('räkenskapsåren efter borttagningen'). It doesn't explicitly confirm that an ineligible year yields an error rather than a silent no-op despite idempotentHint, which keeps it below 5.

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 the action and the core constraint, then layers the exceptions. It's dense with semicolon-separated clauses in one long statement, but every clause (gap rule, current year, vouchers, return value) carries information an agent needs.

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?

No output schema exists, yet the description states what is returned (the fiscal years after deletion). Combined with full eligibility rules and both parameters accounted for, an agent has everything needed to call it correctly or to choose the alternative.

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 50%: orgnr is documented in the schema (10 digits, from list_companies) but 'year' is a bare integer. The description compensates by clarifying that year means the end year ('slutåret'), which is non-obvious for a fiscal-year range tool.

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 verb+resource ('Ta bort ett tomt räkenskapsår') and immediately narrows scope to a mistakenly-added, voucher-free year. This clearly separates it from add_fiscal_year, lock/unlock_fiscal_year, and other year-end siblings.

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?

Explicit preconditions: only a year without verifikat, only the first or last year, never a gap, never the current year, same rules as the app's Remove action. It also names the alternative path when the precondition fails ('rätta i stället med motverifikat').

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