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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the account balance is charged immediately, geo settings and the connection string are preserved, and estimate_only suppresses the charge. It does not mention failure modes such as insufficient balance or a bad price_id.

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 compact sentences, each carrying distinct information (what it does, billing behavior, where to verify the result), with the core action front-loaded and 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?

For a mutating tool with no output schema, the description covers the key concerns: immediate billing, settings preservation, the estimate-only escape hatch, and how to observe the resulting quota. It stops short of stating prerequisites (valid price_id, sufficient balance) or error behavior, which an agent might need before committing money.

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 all four parameters are already documented, including estimate_only and the num multiplier semantics. The description only reinforces estimate_only and points to where the resulting quota is visible (residential_traffic_left_mb in list_proxies), which is useful but not parameter-level detail beyond the schema. Baseline 3 applies.

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 ('tops up') and resource ('traffic quota of an existing residential proxy'), and the word 'existing' implicitly distinguishes it from buy_residential/buy_proxy which create new proxies. An agent can tell what this does without opening the 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?

The description gives a clear decision rule for the main fork: charge immediately by default, or set estimate_only=true to price without charging. It does not explicitly name the alternative tool for acquiring a new proxy (buy_residential), so the 'when not to use' case is left to inference.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true, openWorldHint=true) by stating exactly what is destroyed (the profile's current proxy settings are replaced), the local-runtime and API-key prerequisites, and the operational caveat that an open profile must be restarted to apply.

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 dense sentences, front-loaded with the core action before the replacement warning and prerequisites. Every clause carries operational information; the parenthetical about mobile-proxy change-IP links is the only mildly tangential detail.

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 destructive mutation with no output schema and only three simple parameters, the definition covers prerequisites, side effects, and the post-call restart requirement. It omits what the tool returns and does not clarify the http/socks5 protocol choice, leaving a small gap.

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 67%: proxy_id and profile_id already carry descriptions ('from list_proxies', 'AdsPower profile id (user_id)'), and the description mostly repeats those while adding that host/port/login/password/change-IP link are sourced from the stored proxy record. The 'protocol' enum is never explained in prose, so the description adds only marginal value over the schema.

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+target: writes a mobileproxy.space proxy into an AdsPower browser profile via the AdsPower Local API. That is clearly distinguishable from siblings like update_proxy_settings or change_proxy_credentials, which operate on the proxy rather than pushing it into a browser profile.

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 clear when-to-use context and prerequisites (AdsPower running locally, Local API enabled, ADSPOWER_API_KEY if security verification is on) and warns to confirm with the user because existing settings are replaced. It stops short of naming explicit alternatives for the non-AdsPower path, so it is strong but not fully prescriptive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds material context the annotations cannot: the account balance is charged immediately, and estimate_only=true avoids both charging and allocation. It stops short of saying whether a purchase can be reversed or refunded.

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?

Four dense sentences, each carrying distinct information: the charge action, the estimate escape hatch, the geo-selection hierarchy, and the return payload. Nothing is repeated from the schema and the charging behavior is front-loaded.

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 money-spending mutation with 9 parameters and no output schema, the description covers the critical risk (immediate charge), the dry-run path, location selection, and the return shape. It omits behavior of auto_renewal and operator, which are the remaining gaps an agent would want.

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 78%, so the schema carries most parameter meaning, but the description adds cross-parameter relationships the schema lacks: country accepts either an ISO code or id_country, and geoid sourced from get_geo_list is the most precise locator. This meaningfully disambiguates three overlapping location parameters.

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 (buys) and resource (mobile, server or backconnect proxies), and enumerating the proxy types distinguishes it from the sibling buy_residential. An agent can identify the tool's scope without opening the 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?

It gives a useful conditional for estimate_only (quote without charging or allocating) and explains how country/geoid select a location, but it never names an alternative or says when to prefer this over renew_proxies or buy_residential. Usage is implied through parameter branches rather than stated as when-to-use guidance.

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

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

Annotations already flag destructiveHint=true, non-idempotent and open-world, but the description adds real value beyond them: the account balance is charged immediately, and estimate_only=true is a no-charge preview path. The free later geo change is useful operational context. It does not describe whether a repeat call buys a second bundle or what is returned, so not a 5.

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 what is being purchased, then the charging behavior, then the optional-parameter escape hatch - no filler sentences. Slightly dense, packing the geo workaround into the same breath as the country parameter, but 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?

For a non-idempotent purchase tool with no output schema, the description covers the critical facts an agent needs: immediate charge, the estimate-only escape hatch, and country optionality with a free post-hoc alternative. It omits what a successful purchase returns (package id, traffic amount) and whether buying twice stacks, which keeps it from a 5.

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 the baseline is 3. The description echoes the schema's semantics for estimate_only and country (optional, global pool default) but adds nothing about the num multiplier or price_id linkage beyond what the schema already spells out.

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 (buys a residential proxy) and immediately disambiguates it from the time-rental sibling tools by calling out that it is 'a traffic bundle rather than a time rental.' An agent can separate this from buy_proxy/renew_proxies/add_residential_traffic without opening any 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?

Gives clear context: use estimate_only=true to price without charging, and country can be omitted for a global pool because set_residential_geo can change geo later for free - effectively naming an alternative for post-purchase adjustment. It never states explicitly when to pick this over buy_proxy or add_residential_traffic, so it falls short of full when/when-not guidance.

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

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.

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

Goes well beyond the annotations (which already flag destructive, non-idempotent, open-world) by disclosing key behavior: missing credentials generate random ones, the same pair is applied to every proxy, and old clients stop connecting. This adds valuable context about side effects and defaults, though it omits auth/rate-limit details.

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?

Four tightly written sentences, front-loaded with the primary action and followed by important behavioral details. Every sentence earns its place without redundancy.

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?

Given a mutation tool with three parameters, no output schema, and rich annotations, the description covers purpose, default behavior, side effects, and return value. It is nearly complete, missing only explicit guidance on alternatives and edge cases like permission requirements.

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?

With only 33% schema description coverage, the description compensates by explaining that login/password are optional and what happens when they are omitted, plus that the same pair applies to all proxies. It adds meaningful semantics beyond the schema's pattern constraints.

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: 'Sets a new login and password on one or more proxies.' This clearly distinguishes it from sibling tools that manage IPs, geo, or traffic, though it does not explicitly name alternatives. The core purpose is unambiguous.

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?

Provides a concrete scenario ('for example after credentials leaked'), which implies when to use it. However, it does not specify when not to use it or how it differs from related tools like update_proxy_settings or rotate_ip. Usage is implied rather than fully guided.

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

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

Annotations already mark it read-only and open-world, but the description adds critical operational traits: it makes real outbound requests, can take up to ~45 seconds, caches results for 60 seconds per proxy, and is limited to one mobile or server proxy. These are exactly the details an agent needs to avoid timeouts or redundant calls.

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?

Purpose is front-loaded in the first sentence, followed by three short, high-value sentences on latency, caching, and scope. No filler; every clause carries information an agent would otherwise have to discover by trial.

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?

There is no output schema, and while the description lists the observed fingerprint components (TTL, window, MSS, etc.) it does not describe the comparison result structure or failure behavior. Given the annotations and the operational warnings, it is largely complete but leaves the return shape 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 coverage is 100% and the sole parameter is documented as a mobile or server proxy_id from list_proxies. The description's 'mobile or server only' and 'one proxy per call' reinforce the schema constraint but add no new naming, format, or range semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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 action (sends a real request through the proxy) and resource (fingerprinting endpoints), and its active-probe nature distinguishes it from set_tcp_fingerprint, which it names. It does not explicitly differentiate from the close sibling get_tcp_fingerprint, leaving some ambiguity about which verification tool to pick.

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 a concrete when-to-use ('to confirm set_tcp_fingerprint took effect') and practical constraints (slow, cached, one proxy per call, mobile/server only). It doesn't name alternatives such as get_tcp_fingerprint or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavioral detail: prefix matching on word starts, Cyrillic/Latin input acceptance, and the quirk that captions are mostly English with some Russian while operator names are API ids like 'megafone' and 'beeline'. It does not discuss pagination or what happens when more locations exist than the limit.

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 question it answers and what it replaces, then supporting detail on input formats and downstream use. It is dense but every sentence carries either routing, matching, or data-shape information. The embedded quoted question is slightly verbose but earns its place by framing the use case.

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 return-value burden and does so: locations with free modems, operators with free modems, prices per rental period, plus the reusable geoid and operator ids. What it omits is result-size behavior relative to the limit parameter and how to interpret an empty result, which an agent would need for a complete picture.

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 83%, so most parameters are already documented. The description still adds value beyond the schema by explaining the matching rule for city and operator (start of a word in the caption / operator name) and that operator values are API ids rather than display names. The currency, limit and min_free parameters get no extra narrative, but their schema descriptions are sufficient.

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 description states a precise verb+resource ('answers where can I get a mobile proxy in <country/city> on <operator>, and what does it cost in one call') and explicitly distinguishes itself from sibling tools by naming the chain it replaces: get_geo_list, operator lookups and get_price. An agent can route to it without opening any 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?

It gives a concrete when-to-use condition (you need locations, free modems per operator, and prices together) and names the alternatives it supersedes. It also closes the loop on downstream usage by stating the returned geoid and operator feed the purchase and change_geo tools, so the agent knows this is a lookup step, not a purchase step.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real context beyond them: newest-first ordering, the fields returned (amount, PID-naming description, receipt link), and that timestamps are Moscow time — a non-obvious detail an agent would otherwise get wrong.

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 with zero filler. The resource and its contents are front-loaded, and the timezone and pagination notes follow in 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?

With no output schema, the description carries the return-value burden and does so well by naming the fields returned. Annotations cover the read-only profile. Only minor gaps remain (no explicit note on empty history or whether offset past the end returns an empty page).

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% for both parameters, so the schema already documents limit and offset. The description only adds the ordering nuance that offset skips the newest operations, which is marginal but not nothing; baseline 3 is correct.

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 ('Lists balance operations') and enumerates the operation types (top-ups, purchases, renewals, refunds), which separates it from the closest sibling get_balance. It never names an alternative tool explicitly, so sibling differentiation is implied rather than stated.

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?

'Page with offset' tells the agent how to iterate results, which is genuine usage guidance. However, there is no statement of when to reach for this tool versus get_balance, nor any exclusions, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, yet the description still adds real value: currency RUB, the conditional can_payout field for partner accounts, and the failure mode affecting purchases/renewals. This is solid context beyond the structured fields.

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 tightly written sentences, front-loaded with what is returned before pivoting to the failure condition. No filler or redundant restatement of the 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?

With no output schema, the description carries the return-value burden and does so by naming balance (RUB) and can_payout. Nothing critical is missing, though it could note response shape or partner-status conditions slightly more.

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?

There are zero parameters, so there is nothing for the description to compensate for; the baseline for a parameterless tool applies. No additional argument semantics are needed.

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 (Returns) plus resource (account balance) and even pins the unit (RUB) and the extra can_payout field. It is clearly distinguishable from the proxy/traffic siblings, none of which touch account funds.

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 description gives useful context (purchases/renewals fail on insufficient balance) but never explicitly says when to call this tool versus alternatives like get_account_history or get_price. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: exactly what the returned strings look like, that mobile proxies include a change-IP URL, and that residential output reflects live geo settings mutated by set_residential_geo. It does not mention auth requirements or rate limits, but the output-shape disclosure is substantial.

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, front-loaded with the core purpose followed by the enumeration of output formats and the geo caveat. Dense but each clause carries information; no filler or repetition.

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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly (four concrete output forms plus the mobile change-IP case). Combined with annotations covering the read-only profile, the definition is complete enough to call correctly, though a note on when to prefer it over sibling credential tools is missing.

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?

Only one parameter (proxy_id) with 100% schema coverage, including a description pointing to list_proxies. The description never mentions the parameter, so it adds no meaning beyond the schema. Baseline 3 applies when the schema does all the work.

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 (returns) and resource (a proxy's credentials as ready-to-paste strings) and enumerates the exact output forms (http/socks5 URLs, host:port:login:password line, curl command, change-IP link). An agent can distinguish this from credential-mutating siblings like change_proxy_credentials or update_proxy_settings.

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?

Usage is implied rather than stated: the strings are for proxy managers and browser-profile tools, and for residential proxies they reflect geo settings that set_residential_geo changes. There is no explicit 'use this when/when-not' or named alternative, so the agent must infer that this is the copy-paste export path.

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

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

Discloses caching behavior (60s server-side, 5 min client-side). Annotations (readOnlyHint, openWorldHint) align with description. No contradictions.

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 conveying all essential info: return data, use cases, caching. No fluff.

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?

Covers return data, usage contexts, required geoid for buy_proxy, caching, and filtering. Complete given optional single parameter and no output schema.

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?

The single parameter 'country' is described in both schema and description with similar detail. Description adds usage context (filter by ISO code) but does not significantly expand beyond schema.

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?

Explicitly states it returns all geo-locations with specific fields (geoid, caption, ISO, free-modem count) for proxy availability. Clearly distinguishes from siblings like list_proxies by focusing on locations.

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?

Provides explicit use cases: recommend location, validate before buy_proxy/change_geo, filter by country. Mentions geoid needed for buy_proxy, linking to sibling tools.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses useful behavior: results are filtered to only what needs attention and ordered critical → warning → info, and it explains the cost tradeoff of check_spam (one lookup per proxy, slower). It doesn't detail pagination or exact thresholds, but adds real context over the annotations.

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, front-loaded with the core purpose, then the return ordering, then the optional-cost caveat. Every sentence carries distinct information with no redundancy.

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 explaining returns and does so at a high level ('only what needs attention, ordered critical → warning → info'). It covers the optional spam path, though the exact shape of each item 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?

With 100% schema coverage the baseline is 3, and the description adds meaning on top: it explains check_spam adds one lookup per mobile/server proxy bounded by max_spam_checks and flags the resulting slowdown. It leaves expiring_within_days and low_traffic_percent to the schema, so it isn't fully additive.

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 ('one-call answer to is everything OK with my proxies') and enumerates what it aggregates: balance, expiring proxies, running-out traffic, and optional blacklist checks. This clearly distinguishes it as an aggregate health tool apart from siblings like get_balance, list_proxies, and get_proxy_status.

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 framing 'one-call answer to is everything OK' gives clear context for when to reach for it, and it warns that check_spam=true is slower, which guides the optional-path decision. It doesn't explicitly name alternatives for narrower questions (e.g., get_balance), so no exclusions are stated.

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

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

Annotations already supply readOnlyHint=true and openWorldHint=true, and the description adds the useful fact that a single call returns the full set of rental periods (1–365 days). It does not state the currency of returned values or whether prices are live/quoted vs. cached, which for an open-world pricing call would be valuable.

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 tight sentences, zero filler. The return scope is front-loaded before the input-format detail.

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 value, and it does so adequately (prices keyed by all rental periods). The only noticeable gap is how currency selection affects the response, and whether the caller must supply it or gets RUB by default.

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%: country is documented in the schema, and the description reinforces it with accepted formats ('RU', numeric id_country) and examples — helpful redundancy. The currency parameter is undocumented in the description, though its enum with default 'RUB' is largely self-explanatory.

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 ('Returns') and resource ('mobile proxy prices for a country') plus the exact scope (all rental periods, enumerated). An agent can distinguish this pricing lookup from buy_proxy or list_residential_plans, though no sibling is named to sharpen the boundary.

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?

No when-to-use guidance, no alternates, no prerequisites. The agent is not told how this differs from list_residential_plans or find_available_geo, both of which plausibly touch pricing/location data.

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

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

Annotations only cover readOnly/openWorld, so the description carries real weight and delivers: the ~3s extra latency of check_spam, that it is the only way to assess IP quality, and the important residential-proxy caveat that the check returns a different pool IP and says nothing about the sticky-session IP. This is exactly the beyond-annotations context an agent needs.

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?

Purpose is front-loaded, then usage, cost, and the caveat. Four sentences, each doing work, though the residential caveat sentence is dense and slightly overpacked relative to the rest.

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 steps in to say what is returned (current external IP, blacklist listing) and when results are or aren't trustworthy. Sufficient for correct invocation, though the exact return shape is not fully enumerated.

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 genuine meaning: check_spam is the only quality-assessment path and is slower, and the residential caveat constrains interpretation of the result. That exceeds what the schema's terse 'Run spam-blacklist check' conveys.

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 (returns) and resource (the CURRENT external IP of a proxy), plus an explicit optional secondary operation (spam/abuse blacklist check). An agent can distinguish this from rotation siblings like rotate_ip and rotate_until_clean immediately.

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-use ('verify a fresh rotation succeeded', 'decide if you need to rotate again because the IP is dirty') and a sharp when-not/don't-rely caveat for residential proxies where the check bypasses the sticky session. The condition for choosing check_spam=true is also spelled out.

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

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

Annotations cover readOnly/openWorld, but the description adds real behavioral value beyond them: the backend silently ignores unknown codes and keeps the previous location, and returned entries may carry title_ru that is absent for small towns. These are non-obvious data-shape and failure traits not present in the annotations or schema.

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?

Dense and front-loaded: the purpose and integration constraint lead, with cascade and data-quirk notes following. Every sentence carries information, though the paragraph is on the longer side.

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 compensates by describing returned fields (`code`, title_ru) and their caveats, plus the cascade constraints for correct invocation. It covers what an agent needs to call and interpret results, with only minor gaps around pagination or full result shape.

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 already 100%, so the schema documents the parameters. The description nonetheless adds ordering/dependency semantics and the rationale (cities need a region because large countries have thousands) that go beyond the raw field descriptions, though it stops short of enriching every field.

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 (lists) and resource (geo targets for residential proxies), enumerating the four target kinds (countries, regions, cities, ASNs). This clearly distinguishes it from siblings like get_geo_list, find_available_geo, and set_residential_geo, which it explicitly references.

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 ties itself to set_residential_geo (only `code` values returned here are accepted) and warns that unknown codes are ignored. It also spells out the cascade required for calls (countries → regions+country → cities+country+region), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful context beyond that: the metric it does not return (remaining quota), where that value lives, and how the two combine for a burn-rate estimate. It stops short of describing the return shape or cost/latency traits.

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 tight sentences, front-loaded with the purpose, then the use case, then the critical gap and its fix. No repetition of the title or schema, and every sentence carries routing or constraint 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 should ideally sketch the return (units, per-day granularity, empty-case behavior); it gives granularity only via the title. It does, however, close the biggest completeness risk for this tool by pointing to where the complementary remaining-quota value lives and how to combine them.

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% – 'days' and 'proxy_id' are both documented in-schema with bounds and defaults. The description implies a daily time series but adds no format, timezone, or unit detail beyond the schema, so baseline 3 applies.

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 (daily traffic consumption for a residential proxy) and explicitly delimits scope against list_proxies by noting the remaining quota is NOT returned here. An agent can distinguish it from the sibling usage/quota tools 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?

Gives the concrete question it answers ("how much have I used / how long will the bundle last"), names the alternative source for the missing data (list_proxies → residential_traffic_left_mb), and states the intended workflow of combining both before add_residential_traffic. Explicit when and which sibling to pair with.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the null profile_id means the device's own unmasked fingerprint, and unsupported proxy types surface under 'errors' rather than failing silently. Auth or rate-limit behavior is not covered, so this is not a 5.

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 compact sentences with the output interpretation and the scope/error constraint front-loaded. No filler and no repetition of the title.

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?

There is no output schema, so the description must interpret return values, and it does explain both the null case and the errors bucket. It is close to complete for a simple read tool, though a hint about response shape (per-proxy mapping) would fully close the gap.

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?

With one parameter and 100% schema description coverage, the schema already documents proxy_ids (including the mobile/server restriction). The description adds no syntax or format meaning beyond what is already structured, so the baseline of 3 applies.

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 (shows the TCP fingerprint profile each proxy imitates) plus a scope constraint. It is distinguishable from set_tcp_fingerprint by the read-only framing, but it does not explicitly differentiate itself from close siblings like diagnose_tcp_fingerprint or list_tcp_profiles.

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 description constrains the applicable input domain ('mobile and server proxies only') and states what happens otherwise ('listed in errors'), which is implicit usage guidance. However, it never says when to prefer this over diagnose_tcp_fingerprint or list_tcp_profiles, so alternative selection is left to inference.

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

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

The description adds substantial behavioral context beyond the readOnlyHint and openWorldHint annotations: it discloses that sensitive connection details including login and password are returned, explains how filtering affects backconnect/residential proxies, and clarifies that the server already drops expired proxies while active_only rechecks client-side.

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?

The description is compact and front-loaded: it first states what is returned, then filters, then the key caveats. Every sentence contributes either output detail, filtering behavior, or an important semantic constraint, 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, so the description appropriately summarizes the return fields and the proxy_id usefulness. Combined with annotations that already declare it a safe read operation, the definition is complete enough for an agent to select and invoke the tool 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 description coverage is already 100%, so the baseline is 3. The description adds useful meaning by enumerating the type values, explaining country as ISO code or numeric id_country, and noting that backconnect/residential proxies lack a country id and will be excluded by country filtering.

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 description uses a specific verb and resource: it returns all proxies owned by the authenticated user, and it states the returned fields (host, port, login, password, geo, operator, expiration) plus the proxy_id values other tools consume. This clearly distinguishes it from sibling tools such as get_proxy_status or get_geo_list.

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 description gives clear context for using the tool, including supported filters and the important caveat that backconnect and residential proxies have no country id and are therefore excluded by a country filter. It does not explicitly name alternative siblings for specific sub-cases, but the intended usage is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful domain context beyond annotations: residential is billed per GB in bundles, larger bundles are cheaper per GB, and price_id links to purchase or top-up. It does not describe pagination or the exact return shape, but the billing behavior is well disclosed.

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 short sentences, front-loaded with what the tool returns followed by the billing rationale and the price_id role. Every sentence carries distinct information 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?

With no output schema, the description does meaningful work by noting the return includes plans with price per GB and a price_id, plus the tiered pricing behavior. It stops short of describing the full response shape or whether results are ordered, but it covers enough for an agent to use the tool 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description mentions price_id, but that is a return-value field rather than an input parameter, so there is no parameter semantics to add.

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 ('Returns the residential proxy plans') plus the key attribute (price per GB). It distinguishes itself from the sibling get_price by explicitly stating that these prices replace get_price for residential, so an agent can route correctly without opening a 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?

Gives a clear routing rule — use these plans for residential pricing rather than get_price — and explains why (billed by traffic volume, not rental period). It does not state explicit exclusions or point to purchase/top-up siblings by name, but the alternative is named with a clear condition.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real conceptual context about what a TCP/IP fingerprint preset is and why you would want one. It doesn't cover return volume or how include_details changes the payload, but the added domain meaning is substantive with no 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?

Two sentences, front-loaded with the verb and resource, with the alternative mentioned last. No filler; the conceptual explanation earns its place by disambiguating a jargon-heavy term.

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 read-only list tool with fully documented parameters and no output schema, the description supplies enough to call it correctly and understand the payload's significance. Return-shape and pagination details are the only gaps, and they are minor here.

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 both parameters (category, include_details) are already documented, giving a baseline of 3. The description's parenthetical OS list loosely maps to the category enum but adds no syntax or filtering detail beyond the schema.

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 (Lists) and resource (TCP/IP fingerprint presets), defines what those presets are (OS signatures for proxied traffic), and names the sibling set_tcp_fingerprint as the apply-action counterpart. An agent can distinguish it from get_tcp_fingerprint and set_tcp_fingerprint without opening any 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?

The use case is clear (pick a preset consistent with the client device) and it explicitly points to set_tcp_fingerprint as the tool that applies one. It stops short of stating when-not to use it or naming all nearby siblings, so it sits just below the explicit when/alternatives bar.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds concrete consequences beyond them: active connections drop, recovery takes about a minute, and it is rate-limited to once per 30 minutes per proxy. That rate limit is operationally critical and appears nowhere in structured fields.

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, and the highest-value facts (what it does, when to use it, blast radius and duration) are front-loaded in that order.

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 one-parameter destructive operation with no output schema, the description covers purpose, side effects, downtime, and rate limit — everything an agent needs to decide and warn before calling.

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?

Only one parameter, and the schema already carries a 100% description ("Mobile proxy_id from list_proxies"). The description adds no parameter-level detail, but with a single fully-documented identifier the baseline of 4 applies.

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 ("Power-cycles the 4G modem behind a mobile proxy") and immediately frames it against the sibling it is not — rotate_ip. An agent can distinguish this from rotate_ip or restart-style siblings without opening the 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 defines the trigger condition ("hangs where the proxy stops passing traffic") and the exclusion ("rotate_ip does not help"), naming the alternative by name. When-to-use and when-this-is-the-right-escalation are both stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the account balance is charged immediately, at a per-proxy rate, and auto-renewal settings are left untouched. It does not cover failure modes (e.g. insufficient balance) or reversibility.

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?

Four tight sentences, front-loaded with the action and its cost consequence, then the estimate escape hatch, then preservation of auto-renewal, then sibling routing. Every sentence carries distinct information with no padding.

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, and the description does explain what estimate_only returns (a total) while noting the charge behavior of the normal path. It is nearly complete for a 3-parameter mutation tool; only edge-case outcomes such as charge failures or partial-success handling across multiple proxy_ids are unaddressed.

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 all three parameters are already documented in the schema, including the valid period_days values and the estimate_only meaning. The description reinforces estimate_only and adds the per-proxy pricing nuance but supplies no syntax or format detail beyond the schema, so the baseline 3 is correct.

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 ('Extends ... proxies by a period') and immediately scopes the eligible proxy types (mobile, server, backconnect). It also names which resource type it does NOT cover and routes to the correct sibling, so an agent can distinguish it without opening any 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?

Gives explicit when-to-use context: use estimate_only=true to price without charging, and use add_residential_traffic instead for residential proxies. This names both a mode-selection condition and the alternative tool for an out-of-scope case, leaving nothing to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotent, and the description adds substantial context beyond them: active connections drop, it takes ~3-10s, it is free of charge, there is a short cooldown between rotations, and verify adds ~1-2s. This is exactly the operational detail an agent needs before invoking a disruptive action.

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?

Purpose is front-loaded, and every subsequent sentence carries distinct information (per-type behavior, side effects, latency, cost, cooldown, verify cost). No filler or repetition.

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 destructive mutation tool with no output schema, the description covers side effects, timing, cost, cooldown, and the optional verify flag, which is everything an agent needs to call it safely and 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 description coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by quantifying the cost of verify=true (adds ~1-2s), which the schema only describes functionally. That is modest but real added value.

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 description opens with a specific verb+resource: 'Gets a proxy a new exit IP.' It then differentiates behavior by proxy_type (mobile reconnect vs residential sticky/rotating), giving an agent a precise mental model of what the tool does.

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 provides conditional context (sticky mode needs a rotation; rotating mode already changes per request), which implicitly guides usage. However, it never explicitly states when to choose this over the sibling rotate_until_clean, nor does it name alternatives, so guidance remains implied rather than explicit.

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

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

Adds substantial behavior beyond the annotations: active connections drop on every rotation (concretizing destructiveHint), a cooldown refusal path returning status="cooldown" with wait_seconds, the mobile-only restriction, and that the operation is free of charge. These are operational facts the annotations cannot convey.

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 purpose and every clause carries information (loop semantics, alternative, cooldown return, side effect, scope, cost). It is dense and reads as one long run-on sentence, but nothing is wasted.

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 still discloses the meaningful return shape (status="cooldown" plus wait_seconds) along with prerequisites, side effects, scope limits, and cost. Nothing an agent needs to invoke it safely is missing.

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 all three parameters are already documented in the schema, including keep_if_clean's exact semantics. The description's 'up to max_attempts' and keep_if_clean restatement largely duplicate the schema rather than adding new meaning, so baseline 3 is appropriate.

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 (get a mobile proxy onto an IP absent from spam/abuse blacklists) and describes the rotate-check-repeat loop. It explicitly distinguishes itself from the sibling tools rotate_ip and get_proxy_status by framing itself as a one-call replacement for chaining them.

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 names the alternative workflow ('in one call instead of chaining rotate_ip and get_proxy_status'), states the keep_if_clean=true conditional behavior, and gives a hard scope restriction ('Mobile proxies only (proxy_type=0)'). An agent knows exactly when to pick this over rotate_ip.

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

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.

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

Adds substantial context beyond the annotations: cost ('Free'), reversibility, queued asynchronous delivery with an up-to-a-minute lag, and per-proxy partial-failure behavior in errors. These directly clarify the destructiveHint=true flag by framing the change as reversible while still state-modifying — complementary rather than contradictory — and disclose failure/timing traits an agent could not infer from schema or annotations.

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 effect, then scoped to a bounded clause per remaining concern (restore, cost, delivery lag, rejections). Dense but every sentence carries operative information; 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?

For a two-parameter, non-idempotent-looking mutation tool with no output schema, the description covers effect, cost, reversibility, async delivery timing, verification route, and error semantics. Nothing an agent needs to invoke it correctly is missing.

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%, and the schema already documents proxy_ids (from list_proxies) and profile_id (from list_tcp_profiles, 0 = native). The description largely restates these, adding only the framing of profile_id=0 as 'restores the device's own fingerprint', so baseline 3 is appropriate.

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 ('Makes mobile or server proxies present a TCP fingerprint profile') and names the sibling that supplies the value (list_tcp_profiles). Scope is bounded to mobile/server proxies, so an agent can distinguish it from neighboring profile/fingerprint tools without opening a 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?

Gives explicit when-to-use (match network-level OS to the client device), a when-not (residential and backconnect proxies are rejected per proxy), and the restore path via profile_id=0. It also routes the agent to diagnose_tcp_fingerprint for verification, covering the alternatives section more fully than most definitions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=true, and openWorldHint=true. The description usefully adds the patch semantics ('only the settings you pass are changed'), which supports the idempotency hint, but it never explains what is destructive — e.g. that auto_rotate_minutes=0 stops rotation or that an empty comment clears a label — nor whether permissions are needed.

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 tight sentences: the mutation scope is front-loaded, the affected fields are enumerated, and the partial-update guarantee closes it out. Nothing is wasted.

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 bulk mutation (up to 100 proxies) with destructiveHint=true and no output schema, the description leaves open what happens on partial failure, whether the operation is atomic, and what the agent gets back. Annotations cover the safety profile, but these bulk-mutation gaps remain.

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 the schema already documents all four parameters with ranges, defaults, and clearing semantics. The description only restates the same three optional fields, adding the minor detail that the rotation timer is relevant to mobile proxies.

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 description gives a specific verb ('Changes settings'), a precise resource (proxies, in bulk), and enumerates the three mutable fields: auto-renewal, comment, and the IP rotation timer. It is clearly a settings-patch tool rather than an action tool like rotate_ip, but it never names or contrasts a sibling, so the differentiation is implicit rather than stated.

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 only guidance is 'Only the settings you pass are changed,' which is a partial-update rule rather than routing advice. It does not tell the agent when to prefer this tool over renew_proxies for renewal behavior or over rotate_ip for immediate rotation, both of which are adjacent siblings.

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