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

Annotations already establish readOnly and closed-world behavior, so the bar is lower; the description still adds that results are summary rows sorted cheapest-first, which is real behavioral context. It stops short of stating result limits, pagination, or how many countries are covered, so it is not fully transparent.

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?

Three sentences, zero filler, with the core scope and ordering front-loaded and the routing to get_country_profile placed at the end where a caller will look. Every clause carries information.

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 no output schema, the description carries the burden of describing the return and does so at a summary level ("Returns summary rows"), and it clarifies the central filter's units. It is nearly complete but omits the semantics of the countries parameter and any result-size expectations.

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 50%, and the description compensates by explaining what max_minimum_usd means per visa type (monthly USD income for digital_nomad/retirement, USD investment for investor), which the schema text does not convey. The countries array and region options are left entirely to the schema, so it is not complete.

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?

"Search digital nomad, retirement (pensionado) and investor visas across countries" is a specific verb plus resource, and it states the ordering ("cheapest entry first") that no sibling claims. It also distinguishes itself from get_country_profile by scope, so an agent can separate it from siblings 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?

It names the alternative explicitly ("use get_country_profile for full requirements") and gives the condition that selects it — needing full requirements rather than summary rows. The visa_type values are also tied to which filter metric applies, so the agent knows when each filter is meaningful.

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