cpu_buy_cell

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers thoroughly. It reveals the call's internal workflow: preparing the purchase, verifying the exact order, sending owed currency approval, waiting for the receipt, and sending the fulfilment transaction. It also discloses retry safety ('can never bind a second order'), proof requirements, and the exact failure modes, which is exceptional transparency for a financial 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?

The description is long, but the length is justified by the tool's financial risk and complexity. It is front-loaded with the core action, then covers prerequisites, failure modes, safety, and result semantics. There is some redundancy around 'exact order' and 'never substitutes a different listing', which appears multiple times, so it is not perfectly concise.

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 the tool's high stakes—spending currency, sending approvals, and fulfilling an NFT order—the description is remarkably complete. It covers prerequisites, failure conditions, retry behavior, proof of success, what the result reports, and even the worst-case retry cost. The input schema and output schema provide the remaining structured detail, so nothing critical 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?

Although the schema already covers all parameters at 100%, the description adds valuable behavioral meaning beyond the schema. It explains that expectedOrderHash must be copied from cpu_get_cell_market and binds the purchase to that exact listing, clarifies maxAmount is a hard ceiling in base units and must be a decimal integer string, and ties tokenId to the specific Cell the listing sells. This is more than the schema alone provides.

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 and resource: 'Buy ONE exact Cell listing on the NFT marketplace, in a single call.' It explicitly contrasts this with cpu_buy_lot, which buys resources for $CPU, so the agent cannot confuse the two. The scope ('ONE exact Cell listing', never substitutes another listing) is unusually precise.

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 an explicit prerequisite: read cpu_get_cell_market first and pass that listing's exact expectedOrderHash. It also names the key alternative, cpu_buy_lot, and states the exact condition that separates them (land/NFT market vs in-game resource purchases). It further clarifies what happens if the order is stale, cancelled, expired, or repriced, so the agent knows when the call will fail.

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