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

Annotations declare readOnlyHint=true, and the description aligns with that by describing an export/read operation. The description adds meaningful behavioral context beyond the annotation: the dataset exceeds one response, pagination is cursor-based with a complete flag, chunks are byte-budgeted, and attribution is required. It does not contradict the annotation. A small gap is that it doesn't explicitly state the response shape, but the pagination behavior is well covered.

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 dense but front-loaded with the most important fact (whole dataset, not a page) and then flows through dataset options, pagination, attribution, and pricing. It is longer than ideal, but every sentence carries information an agent needs to call the tool correctly. The pricing detail is arguably extra, but it supports the licensing use case. Slight deduction for length and for burying the pagination protocol mid-description.

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 tool with no output schema, the description does a good job of explaining what comes back (chunks of data, complete flag, next_cursor) and how to handle it. It covers the three datasets, the pagination loop, attribution, and pricing. It doesn't describe the exact structure of each chunk or the movement summary format, but the description is sufficient for an agent to invoke the tool and handle the response correctly. The licensing/pricing context is a bonus that helps the agent decide whether this tool is appropriate.

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 75%, and the description adds meaning beyond the schema by explaining the dataset enum values in detail (what each dataset contains) and by describing the cursor pagination contract. The context parameter is explained in the schema, and the description reinforces the licensing/attribution context. The co_brand parameter is only lightly touched ('stamps the attribution'), but the schema already covers it. This is above the baseline 3 because the description enriches the dataset and cursor semantics.

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 states a specific verb ('export') and resource ('the WHOLE dataset'), and enumerates the three dataset options (ratings, providers, history) with what each contains. It also distinguishes itself from page-limited views by explicitly saying it is not a 100-row page, which differentiates it from sibling tools like get_rating_history or find_ratings.

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 explicitly names the intended audience ('media outlets and analysts licensing the data to publish rankings and trends'), explains the pagination protocol ('while complete is false, call again with cursor set to next_cursor and concatenate data'), and gives pricing/licensing context. It also warns that history is the one dataset that cannot be reconstructed after the fact, which is a strong when-to-use signal.

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