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

Beyond the read-only/idempotent annotations, it discloses that there is no DB or network access, that missing fields are cleanly omitted (never 'p. None'), that page numbers degrade gracefully when metadata is absent, and that the result is a Markdown string. This is substantial behavioral context beyond annotations, with no contradiction.

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 description is front-loaded with the purpose and example, then uses short labeled sections for the metadata caveat, usage condition, and return value. Every sentence adds useful behavioral or scoping information; nothing is redundant with the schema.

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-free formatter with rich annotations, it covers output type, missing-field behavior, metadata dependency, and when to use it. The main gap is the undocumented `document_id` parameter, which prevents full completeness; otherwise an agent has enough information to invoke the tool 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?

Schema description coverage is 0%, so the description carries parameter meaning. It explains how `spreker`, `quote`, `partij`, `pagina`, `alinea`, `bron`, and `datum` appear in the formatted result and how omitted fields are handled. However, `document_id` is never mentioned and date/page formats are not specified, so compensation is incomplete.

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 precise action ('Formatteert een bronvermelding') and gives a concrete output example with page number and paragraph, plus a separate full quote-attribution template. It also scopes the tool as the formatting layer versus separate corpus-level ontology, so it is clearly distinguished from content-generation siblings.

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?

It has an explicit 'Gebruik wanneer' condition: use it to present a quote or source with page/paragraph. It also warns that page metadata must exist in the source and that corpus-level sentence/paragraph precision is out of scope. It does not explicitly compare against sibling tools, but the stated usage context is clear.

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