nex_ip_snap_package_list

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

readOnlyHint already covers the read-safe profile, and the description adds genuinely useful operational context: prices are package totals (not per-unit) in USDT, and only an exact returned ipNum is a valid purchase target. That last point prevents a concrete class of downstream error and is exactly the type of context annotations cannot express.

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 short sentences, zero filler, and the critical constraint (exact ipNum, USDT totals) is front-loaded right after the purpose statement.

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 parameterless read-only listing, an agent needs to know what it returns and how to use it; the description covers the key return fields and the purchase precondition. Missing only minor details such as whether results are always non-empty or how many packages are typically returned.

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?

Zero parameters, so the baseline is 4. The description goes slightly beyond by describing the shape of returned fields (ipNum, price in USDT), which is relevant given there is no output 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 and resource ('List current short-term proxy quota packages') and anchors it to the NEX_SNAP_IP_COMBO source, which separates it from nex_ip_product_list and the other *_list siblings. The 'short-term / quota package' framing is clear enough that an agent can pick this over nex_ip_product_list 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?

Implies the workflow ('Buy only an exact returned ipNum') without naming nex_ip_snap_buy explicitly, so the routing to the purchase step is inferable rather than stated. No explicit when-not-to-use or comparison against nex_ip_product_list is given.

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