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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' in the description is redundant. The description adds the upstream API mapping (GET /3/archive) but says nothing about pagination behavior, result ordering, or limits despite exposing page/limit/offset/sort parameters.

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?

Three short sentences, front-loaded with the core action and scope, with usage and endpoint notes following. The only wasted phrase is the 'Read-only' sentence, which duplicates the annotation.

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?

With a rich annotation set and an output schema present, return-value detail is unnecessary, and the description covers what the tool returns and when to call it. The gaps are pagination/sorting semantics and the presence of a fileid parameter on a folder listing, which an agent might misread.

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 57%, and the description contributes one real clarification: omitting path means the archive root, which the schema's 'name of folder' does not convey. The remaining parameters (page, limit, offset, sortby, sortorder, and the unexplained fileid) get no meaning from the description, leaving the coverage gap only partly filled.

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 gives a specific verb and resource ('Lists the files and subfolders of a folder in the Fortnox archive') and clarifies scope as the root or a path-given folder. It implicitly separates itself from the single-file sibling get_archive_file, but never names or contrasts an alternative explicitly.

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?

'Use when the person asks which files are stored in the archive or in a given archive folder' gives a clear triggering condition tied to user intent. There are no when-not conditions or named alternatives (e.g., for a single file's metadata), so it stops short of full routing guidance.

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