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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the mutation/safety profile is covered. The description adds real behavioural context beyond that: a document is created in the archive under the category Leverantörsfaktura, it becomes visible via list_documents/list_policies, and it is readable/downloadable. It does not clarify idempotency semantics on repeat calls, which the annotation asserts but the description leaves unexplained.

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?

It is a single dense sentence-complex with the primary action front-loaded, followed by destination, discoverability and scope notes in descending importance. Every clause carries information; the trailing "Argument: orgnr, invoice_id" is the only piece that does not earn its place.

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 side-effect tool with no output schema, the description does enough: it says what artifact is produced, where it is stored, how it can be found afterwards, and what scope is expected. The main missing piece is any statement about the return value or about what happens if the same invoice_id is generated twice despite idempotentHint=true.

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 well documented in the schema (format, example, how to find it via list_companies) while invoice_id has no description at all. The description only restates the parameter names ("Argument: orgnr, invoice_id") and therefore adds nothing, leaving the undocumented invoice_id uncompensated. Baseline 3 is appropriate at this coverage level.

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 names a specific verb and resource ("Generera en leverantörsfaktura som PDF") and states the destination ("spara den i dokumentarkivet"). It also indirectly separates itself from the listing siblings by naming list_documents/list_policies as the place the result appears. It does not explicitly contrast with create_supplier_invoice or get_supplier_invoice, so it stops short of full sibling differentiation.

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 an implicit trigger (when you need a PDF of an existing supplier invoice) and a directive about the resulting document's scope ("scope upload (inte view)"), which is useful operational guidance. However, there is no explicit when-to-use/when-not statement and no named alternative (e.g. versus create_supplier_invoice or get_supplier_invoice), 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.