Set residential geo and session mode

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

Rich beyond the annotations: it discloses cost ('Free'), reversibility, that a change rewrites the provider login, that unknown geo codes are silently ignored with the prior location kept, and that the response carries updated http/socks5 connection strings. The only caveat is mild tension between 'reversible' and destructiveHint=true, though the description never claims a read-only operation, so this is added context rather than a contradiction.

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 read/write distinction, then progressively adds constraint detail. Dense but every sentence carries information (cost, side effect, code source, enum behavior) with no filler.

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?

No output schema exists, yet the description covers the return payload ('the response carries the updated http/socks5 connection strings') and the mutation side effects. Combined with the parameter guidance, an agent has everything needed to call it correctly.

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 86%, so the baseline is 3, and the description earns above it by explaining the semantics behind the enum: rotating = new IP per request, sticky = one IP held for session_time minutes (max 120). It also explains what happens to unrecognized geo codes, which the schema does not.

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+resource (reads or changes geo targeting and session mode of a residential proxy) and clarifies the dual read/write nature up front. An agent can immediately tell this both inspects and mutates a proxy's geo/session config, which is more specific than a generic 'settings' tool.

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?

The trigger for read vs write is stated explicitly: 'With only proxy_id it returns the current settings; any other parameter changes them.' It also routes the agent to get_residential_locations for valid geo codes, leaving little to inference.

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