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

With no annotations, the description carries the full burden and does: it discloses that returned transactions are UNSIGNED and must be signed by the caller, that funds sit in escrow, and that release occurs only on buyer approval, after 72 hours of silence, or by refund if nothing is delivered. Those are exactly the non-obvious consequences (money custody, timeout, reversibility) an agent needs before committing.

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?

One dense paragraph, but front-loaded with purpose and return shape before the escrow mechanics and the next-step pointer. Nearly every clause carries information; only the worked example "price 100, fee 5, total 105" is arguably redundant with the sentence it illustrates.

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 2-parameter mutation tool with no annotations and no output schema, the description covers return values, signing requirements, escrow timing and the follow-up call. The remaining hole is parameter meaning — neither `token` nor `listing` is defined, so an agent knows the flow but not how to populate the arguments.

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 define both parameters, and it does not. The parenthetical "wallet token" is ambiguous about whether it describes the service being bought or the `token` argument, and `listing` — a bare number with no stated source — is never explained (presumably an id from shop_list).

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?

"Buy a service (wallet token)" states a specific verb and resource, and the description immediately says what comes back (price, fee, total, two unsigned transactions). An agent can distinguish this from shop_list/shop_set/shop_rate without opening any schema, and the closing pointer to shop_confirm anchors it in the purchase flow.

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 sequencing: sign approve, then post, and "After the post is mined call shop_confirm." That is real invocation guidance rather than implied usage. It stops short of naming alternatives (e.g. browse with shop_list first) or stating when NOT to call this, so it is clear context without exclusions.

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