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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so safety needs no restating. The description adds genuinely new behavior: at most 5 pages returned, ordered by best match first, and English-only indexing — useful for interpreting results. It still doesn't say whether results are snippets or full page text, which matters for deciding to call the sibling.

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?

Two sentences, no filler: the content scope and result limits come first and the ordering guarantee second. Every clause carries information an agent can act on.

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?

This is a simple one-parameter search tool with an output schema, so return-value documentation is correctly omitted, and the annotations cover the safety profile. The description supplies corpus scope and result-count/ordering behavior. The only gap is whether results are page references requiring qr_suisse_get_page, which would complete the retrieval workflow.

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?

With a single parameter at 100% schema coverage, the schema already documents the query string, its 1–200 length bounds, and gives two example queries. The description only repeats the English-language constraint, adding no new meaning about tokenization, phrase handling, or multi-keyword behavior. Baseline 3 applies.

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: 'Keyword search in the QR Suisse documentation', and enumerates the indexed content (overview, agent instructions, auth, pricing, one page per operation) so the agent knows the corpus scope. It does not explicitly contrast with the sibling qr_suisse_get_page, so differentiation is only implied by 'search' vs. 'get page'.

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?

Usage is implied by 'keyword search' and the English-only constraint, and the examples of query style help. But there is no explicit when-to-use rule versus qr_suisse_get_page (e.g., 'search first, then fetch the full page by id'), and no when-not guidance.

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