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

Beyond the readOnly/openWorld annotations, it discloses the data source (public shanghairanking.com table), that no API key is required, the hard truncation to the top 30, and the exact cost model ($0.002 USDC per successful call via x402 on Base, Solana, or Arc, with failed calls not charged). Cost and failure-charging behavior are not derivable from any structured field, so this adds real value.

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?

Front-loads what the tool returns, then alternatives, then pricing in a clear progression, with no filler sentences. The indicator-name enumeration (Alumni, Award, HiCi, N&S, PUB, PCP) is slightly bulky but earns its place by telling the agent whether the result set answers the question.

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 single optional-parameter read tool with full schema coverage and an output schema, this covers everything an agent needs: what is returned, the truncation limit, alternatives, and the payment mechanics that could otherwise cause an unexpected charge.

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 coverage is 100%, so the limit parameter's range and default are already documented; the description still adds the causal reason for the 1–30 bound (the public page only publishes 30 rows). That explains why the parameter is capped rather than merely restating it, though it does not add syntax beyond the schema.

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 resource (ShanghaiRanking ARWU 2026 world university ranking) and enumerates exactly what each row contains: world position, institution, national rank, total score, and the six named indicator scores. It also distinguishes itself from two named siblings (GRAS for subject rankings, mega_pack for side-by-side comparisons), so an agent can pick the right tool without opening 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?

Explicitly routes the agent: use search_shanghai_gras_rankings for academic-subject rankings and search_university_rankings_mega_pack for side-by-side comparisons, with the condition that selects each. It also states the practical ceiling (top 30 only), which determines whether this tool can serve a request at all.

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