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

Annotations provide readOnlyHint=true, and the description does not contradict it. Beyond the annotation, the description adds significant behavioral context: a detailed pricing model ($0.005 per request + $0.0002 per record, capped at $0.50, pay-as-you-go, included in certain plans), billing category 'UNDERSTANDING', and a pointer to estimate costs first and to apis://prices. This goes beyond what the annotation supplies.

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 moderately sized but every component earns its place: the purpose is front-loaded, the illustrative sentence aids comprehension, and the pricing and estimation details are essential for safe invocation. It is not as tight as a two-sentence ideal but contains no pure filler.

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?

The description explains the core return concept (facet-level scores with cohort average and delta) and pricing behavior, but it omits how to identify a cohort (the slug parameter origin) and does not mention pagination behavior or defaults for 'page' and 'limit', despite the schema having explicit bounds. Given no output schema, it could have linked to find_cohorts or clarified the cohort reference.

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 only 20% (only 'context' has a description). The tool description does not explain what 'slug' refers to or how 'kind' interacts with it, nor does it clarify defaults or behavior of 'page' and 'limit.' Since the schema is under-documented and the description does not compensate, an agent would have to infer that slug is a cohort identifier and know to use find_cohorts to obtain it.

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 opens with 'UNDERSTANDING — facet-level scores for every member of a cohort, each with the cohort average and the delta against it.' This names the specific resource (cohort scores), the action (fetch facet-level scores), and the output shape (scores with cohort average and delta). The analogy ('A 60 in governance means nothing until you know the market sits at 45') further differentiates it from siblings like cohort_rankings or cohort_stats.

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?

The description establishes clear context: this endpoint is for understanding how a cohort's facet-level scores compare to the average, and is explicitly framed as 'the endpoint that says so.' However, it does not name sibling alternatives (e.g., cohort_rankings for rankings, cohort_stats for aggregate stats) or state when not to use it, so it stops short of full exclusion guidance.

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