nex_ip_snap_buy

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds material context beyond them: the balance is charged at the current server price, the call returns a local order id that must be retained for nex_ip_snap_pull, and ambiguous outcomes require reconciliation before retry. It stops short of stating what happens on partial failure or whether the charge is refundable on error, which keeps it at 4 rather than 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-loads the action, then the downstream dependency, then the cost, then the retry safety rules. Every clause carries real information, though the price-inquiry parenthetical and attempt cap make the block denser than strictly necessary for a one-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent one-parameter purchase with no output schema, the description covers cost, the returned value's purpose, the prerequisite enumeration tool, and retry hygiene. Missing only failure-mode specifics (whether a failed attempt consumes balance), which is the main residual risk for a billing action.

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 0% (a bare positive integer), so the description must do the work, and it does clarify that num is an exact ipNum drawn from nex_ip_snap_package_list rather than an arbitrary count. It still leaves mild ambiguity about whether the value identifies a package or a quantity of IPs, so 4 rather than 5.

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 (buy) and resource (short-term proxy quota package), scoped to an exact ipNum sourced from nex_ip_snap_package_list, and explicitly separates itself from nex_ip_snap_pull (consumes the order id) and, by implication, nex_ip_buy. An agent can distinguish it from every sibling offering 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 positive guidance (use remaining quota first; call directly when the task needs it), an explicit exclusion (a price inquiry is not a purchase request), and a recovery procedure (reconcile records and billing before any retry, max 3 attempts). This is unusually complete routing guidance for a purchase tool.

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