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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the result (names, codes, capitals) and by clarifying that this is the shallow variant versus a full-facts sibling. It leaves the 1-20 limit behavior to the schema, which is a minor gap.

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?

Two sentences, zero waste. Capability and filter modes come first, then the result shape and the handoff to the sibling tool, which is exactly the order an agent needs them.

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?

An output schema exists, so the description need not enumerate return fields, and it still summarizes them at a useful level. With five optional parameters and full schema coverage, the definition supplies everything required to call it correctly; only edge-case behavior (empty result, limit ceiling) is left implicit.

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 100%, so every parameter already carries its own documentation, and the baseline is 3. The description clarifies the union semantics of the query (part of a country OR capital name) and that filters can be combined, but it adds little beyond the enum values and field descriptions already present.

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 and resource ("List countries") plus the three filter modes it supports (name/capital substring, continent, landlocked). It also names the sibling it is not ("call get_country for the full facts"), so an agent can distinguish search from detail lookup without opening either schema.

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 detail-seeking calls to get_country, which gives clear context for when this tool is the wrong choice. It does not spell out a negative case for the search itself (e.g., what happens when no filters are supplied), but the usage context is unambiguous.

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