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" adds nothing. Useful additions are the source of truth ("as registered in Fortnox") and the API endpoint reference. It does not disclose how paging behaves beyond the single summarize note, nor what 'expand' does to the response.

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?

The core sentence is front-loaded and efficient, but "Read-only" duplicates the annotations and the summarize.all_pages sentence is dropped in without connection to the rest. The trailing API URL and endpoint add bulk rather than 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?

An output schema exists, so return values need not be spelled out, and the safety profile is covered by annotations. What is missing is the list-vs-single-record question raised by page/limit, and any differentiation from get_connected_company. For a tool with nested objects and 8 parameters, the description leaves real gaps.

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 description coverage is 63% across 8 parameters, and the description only touches summarize.all_pages ("gives totals over every page"), which largely restates the schema. Page, offset, limit, expand, fields and sortby go unexplained, including the ambiguous schema text "Open each record (rows)". The description does not compensate for the coverage gap.

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 ("Returns the connected company's details ... name, organisation number and address"), which is clearer than a tautology. However, it never distinguishes itself from the near-identical sibling get_connected_company, so an agent cannot tell the two apart from the text alone. It also wavers between singular ("the company's details") and a paginated list shape implied by 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?

"Use when the person asks about the company's own registered details" gives a usable trigger condition. There are no exclusions and no alternatives named, which matters here because get_connected_company appears to cover the same ground. Usage is implied rather than fully scoped.

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