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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing ordering (newest first), the metadata-only nature ('Bara uppgifter om dokumenten, inget innehåll'), and confirms read-only behavior in prose, which helps an agent understand what it actually receives.

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 front-loaded: purpose and scope first, then usage, then returned fields, then the read-only assurance. The enumeration of return fields is slightly verbose but earns its place since no output schema exists; no sentence is pure filler. Slightly long overall, so not a 5.

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?

Given no output schema, the description compensates well by enumerating what is returned per document (id, name, filename, file type, size, category, companies, visibility, uploader) and by confirming metadata-only. Annotations cover safety, scope is stated, and the sibling routing is provided, leaving little an agent would need to call it correctly.

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?

The tool takes zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameter meaning, and it instead usefully describes the returned fields, which is extra value rather than a 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?

States a specific verb and resource ('Listar dokumenten i dokumentarkivet') with concrete scope (all companies you have access to, newest first) and example categories. It explicitly separates itself from related siblings by noting that policy content is read with list_policies and read_policy, so an agent can tell it apart from delete_document/edit_document without opening any 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?

Gives clear context ('Använd för att hitta ett dokument och dess id') and names the alternative tools used for a related-but-different need (list_policies/read_policy for policy content). It does not spell out explicit when-not-to-use conditions, but the routing guidance to the alternatives is present and unambiguous.

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