Change proxy country / operator

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

Goes well beyond the annotations: it discloses what actually changes (physical location only, credentials untouched), the latency cost of check_after_change (1-10s), and a per-proxy cooldown constraint. That is exactly the kind of operational side-effect detail an agent needs for a destructive, non-idempotent mutation.

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 dense sentences that front-load the core mechanic, then the selection rule, then the optional verification flag and the cooldown caveat. No filler or restatement of the tool name.

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 mutation with no output schema, the description covers what changes, how to target the change, and what check_after_change returns conceptually. It omits error/permission behavior (what happens on an invalid or unavailable geo, or a cooldown hit), which would round out a destructive operation.

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 baseline is 3, but the description adds a genuine cross-parameter rule the schema cannot express: at least one of country/id_country/geoid/operator must be supplied, and geoid is 'most specific'. It does not resolve ambiguity between conflicting selectors, keeping it out of the top band.

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 precise verb+resource ('swaps the underlying modem of a proxy') and immediately distinguishes it from the nearest alternative action (buying a new proxy), noting that proxy_id and credentials are preserved. An agent can tell apart change_geo from buy_proxy or set_residential_geo from the description alone.

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 frames the tool as the no-new-purchase path and names the required selection inputs, plus when to enable check_after_change. It stops short of naming a specific sibling to use instead (e.g. rotate_ip for same-geo IP rotation, set_residential_geo for residential plans), so exclusions are only implied.

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