nex_ip_snap_pull

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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses the cost model (quota consumption), that no separate payment confirmation occurs, that results are persisted server-side, and warns that the operation is non-repeatable when the outcome is unclear. That is exactly the retry-safety and side-effect context an agent needs for a destructive, non-idempotent call.

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, front-loaded with the action and cost, then the safety warning. Every clause carries information, though the second sentence packs three separate instructions together and reads as a run-on.

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 the cost and non-idempotency risk well for a tool with no output schema, and indicates proxies are persisted server-side. It still omits what the call returns (the proxies themselves vs. only a confirmation), what happens if quota is insufficient mid-call, and what 'num' controls.

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 0%, so the description must carry all three parameters. It defines only nexIpId ('the local SNAP order ID'); 'num' (presumably count of proxies) and 'countryCode' (format is in the schema pattern but its meaning/source is not) are left unexplained.

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 concrete verb and resource: 'extract proxies for the user's task' and clarifies that it consumes short-term quota tied to a local SNAP order ID. That distinguishes it from nex_ip_snap_buy and nex_ip_snap_package_list, though it never names those siblings directly.

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 preconditions ('check remaining quota and nex_proxy_list first') and a clear prohibition ('never repeat an unclear extraction'), which is real when-to/when-not guidance. It stops short of naming the sibling tool to use instead when quota is exhausted or an order does not yet exist.

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