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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds meaningful context on top: it is a public endpoint (no auth implied), returns English natural-language text with sources, conditions and pagination preserved, and it warns that cases are examples rather than approval probabilities or processing-time forecasts. That expectation-setting caveat is exactly the kind of behavioral disclosure annotations cannot carry.

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-loaded with the core action and scope, then alternatives and exclusions, then return shape. Efficient overall, though the trailing sentence stacks several unrelated caveats (endpoint type, language, pagination) into one dense run-on that could be split for faster scanning.

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 9-parameter, no-output-schema tool, the description covers the required selector, the optional filter families, where to get valid values, what a call returns (compact page, public IDs, website links), and where to go for full records. Nothing an agent needs to invoke it 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?

With 56% schema coverage, the description contributes real meaning: it maps the tool to school, advisor, subject and 'inclusive' age filters, clarifying that minAge/maxAge bounds are inclusive — a detail the schema does not state. It does not elaborate on page/pageSize/locale, but those are documented in-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 verb ('Find') and resource ('published successful visa cases') with hard scope: exactly one subclass from 500/600/485/820, optional school/advisor/subject/age filters. It also clearly separates itself from the two nearest siblings by naming list_visa_case_filters for valid values and get_visa_case for detail lookups.

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?

Explicit about prerequisites ('Call list_visa_case_filters for valid values') and the follow-up step ('call get_visa_case for details'). It also enumerates what this tool does NOT do — no keyword search, no courseCode filter, no similarity ranking, no cross-subclass search — so an agent can rule out misuse before opening the schema.

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