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

Goes well past the annotations (which only give readOnly=false/destructive=false/idempotent=false): discloses the required 'payroll' scope, deterministic amount calculation, the optional bokföringstak with rejection behavior, exact-duplicate blocking with the allow_duplicate escape hatch, and the side effect that time_entry_ids are marked paid and released on reversal. This is exactly the auth, mutation, and reversibility context an agent needs.

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 core action and the PayrollRun/voucher outcome, then arguments, then edge cases (cap, dedup). Dense with parentheticals and long, but essentially every clause conveys non-obvious behavior, so little is wasted.

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 an 8-param, 5-required mutation tool with no output schema and near-zero schema documentation, the description covers the required scope, defaults, dedup/cap failure modes, and cross-tool dependencies. Nothing essential to invoking it correctly is missing.

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 13% (just orgnr documented), so the description carries the burden and largely does: it expands the entries object shape (employee_id, gross_cash_ore, benefit_ore?, extra_tax_ore?, components?, time_entry_ids?), enumerates components = lönearter, and explains net_pay_account's default 1930 and liability-account behavior. year/month/pay_date are only named, not clarified, keeping it from a 5.

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 ('Bokför en lönekörning'), names the side effect (skapar PayrollRun och bokför löneverifikatet serie L), and thereby implicitly distinguishes itself from calc_payroll, which only computes. An agent can tell what this tool does and what artifact it produces without opening the schema.

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 routes the agent to sibling tools by name ('se calc_payroll' for lönearter, 'från get_payroll_time_basis' for time entries), giving clear usage context. It stops short of an explicit when-to-use-this-vs-calc_payroll statement or when-not-to-book, so it is clear context rather than full decision guidance.

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