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

Goes well beyond the annotations (which already cover readOnly/idempotent/non-destructive): it discloses that results carry a per-field status, that OCR-number fields read from a scanned image via text recognition are flagged for checking, and that results are computed server-side from live data across all pages. Missing only failure behaviour (e.g. what happens if the id is not found or is not PDF/image).

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 what is read and what is extracted, then when to use it, then the caveat about text-recognised fields. Dense but every sentence carries information; the API docs URL and the bilingual example add a little bulk without adding much decision value.

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 one-parameter read-only tool with full annotation coverage and an output schema, the description covers purpose, trigger, field list and accuracy caveats, so an agent can call it confidently. Only edge-case behaviour (invalid id, non-invoice file) is left unaddressed.

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 100% and the single parameter 'id' is already documented in the schema as the file id in the inbox or archive, so the schema does the heavy lifting. The description adds the scoping notion ('one invoice file') but no extra format, accepted-id-kind, or default detail beyond the schema.

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 ('Reads one invoice file in the Fortnox inbox or archive') and enumerates exactly what is extracted (amount, VAT, dates, OCR, organisation number, supplier, per-field status). That is far more specific than the Swedish title 'Tolka en faktura'. It stops short of naming a sibling such as extract_document_fields to explain why an agent would pick this file-scoped extractor over the generic one.

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?

Gives a concrete trigger: 'Use when the person asks what an invoice file says, for example its amount, due date or OCR number', reinforced with a worked Swedish example question. It offers no explicit when-not guidance or named alternative (e.g. for ledger values use get_invoice), so it is clear on context but silent on exclusions.

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