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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description still adds substantial operational context: the flag-vs-kind precedence rule when the SSOT disagrees, pagination via _meta.next_cursor with refusal when filters change, query-relative ordering (exact, prefix, substring, then description-only matches), and the module-filter interpretation that absence means 'no declared link', never 'does not work on the module'. No contradiction with annotations.

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 long but every sentence carries operational weight: purpose and return values are front-loaded, followed by the dataset boundary, pagination loop, and ordering rules. There is no filler, no restatement of schema content, and the density is justified by the number of non-obvious behaviors an agent must know to call the tool correctly.

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 an output schema present, the description is not required to restate return shape, yet it still names the returned fields. It fully covers the dataset boundary, the pagination loop, ordering semantics, and per-filter interpretation guardrails. Nothing an agent needs to invoke the tool correctly is missing.

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 100%, yet the description deepens every non-trivial parameter beyond the schema's own text: the client_enterprise kind value is unreliable as a filter (the flag wins), cursor rejects changed filters, query changes the ordering regime, and module selects only declared specialists rather than actual expertise. These are meanings the schema alone does not convey.

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 an unambiguous verb+resource+scope: searches the published Analytics Legends directory of SAP analytics service providers with four filter dimensions (country, kind, module, free text) and enumerates exactly what is returned (name, HQ, website, careers URL, editorial claim). The disambiguation paragraph explicitly carves out end-customer firms as excluded, separating this tool from the client-lookup sibling without needing to inspect other schemas.

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?

Delivers explicit when-not guidance: end-customer companies are a separate paid dataset excluded here, and the is_client flag — not the client_enterprise kind label — decides what the tool serves, so an agent will neither misuse this tool for client lookup nor misread result rows. It also routes to two siblings for live vocabularies (list_firm_kinds for the kind enum, count_firms_by for module codes), giving concrete alternatives for adjacent needs.

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