Get Proxy Targeting

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds rich behavior beyond that: values are dynamically sourced from the upstream provider, ordered by pool size with a 'prefer front' heuristic, residential/mobile pool separation, the country-wide default for cities when a region is omitted, and the subtle warning that mismatched region/city pairs are accepted but leave no exit node. No annotation is contradicted.

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?

Five sentences, each carrying distinct operational information: purpose, when-to-call, acceptance guarantee, ordering preference, and the two traps. The purpose is front-loaded, and the structure flows logically from what → when → how → gotchas. Nothing is repeated from the schema verbatim, and the length is justified given the real complexity of the tool.

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?

Behavioral guidance is exhaustive: sourcing, ordering, pool semantics, validation behavior, and downstream consumer tools are all covered. The only gap is the exact output shape: there is no output schema, and while the schema's reference to 'this tool's own regions array' anchors one field name, the precise structure for cities and ISPs (field names, nesting) is left implicit. For a tool with three flat parameters and strong annotations, this is a minor omission.

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% and each parameter already has a strong description (ISO format, case-insensitivity, enum with defaults, pool separation, regions-array sourcing), so the baseline is 3. The description adds genuine meaning beyond the schema: the ordering heuristic ('prefer values near the front'), the acceptance guarantee ('Anything listed here is accepted'), the two-call workflow ('if you target a region, call again with that region and take the city from that narrower list'), and the 422 consequence — all of which shape how the agent chooses values.

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 opening sentence 'List the proxy regions, cities, and ISPs accepted for a country' states a specific verb, resource, and scope. The description further distinguishes this from the many sibling read tools (list_geos, list_emulators, get_scan) by naming the four consumer tools (create_scan, create_bulk_scans, create_campaign, update_campaign) that this lookup feeds, making its role unmistakable.

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?

Gives explicit when-to-call guidance: 'Call this before setting proxy targeting on create_scan, create_bulk_scans, create_campaign, or update_campaign'. It explains why this is mandatory (values come from the upstream network provider and cannot be listed in those tools' schemas) and the failure mode of the alternative ('a guess is a 422'), effectively stating the when-not-to: never guess or hardcode values.

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