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

Goes well beyond the annotations: the price can rise mid-drop, a purchase within max_price_cents completes at the new price while a higher price returns price_moved with nothing charged, metadata is stripped, and the response flags test: true during the test run. It also notes the per-UTC-day spend cap and that the idempotency key makes retries safe, giving the agent the failure and no-charge semantics the annotations do not carry.

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 core action, then layers the price, idempotency, cap and test-mode caveats in a logical order. The sentences are long and dense but nearly every clause conveys a distinct operational rule.

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?

With no output schema, the description carries the return contract itself (license, download link, test flag, price_moved code) plus the spend cap and no-charge guarantees. An agent has everything needed to call this correctly and interpret failure modes.

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 75%, yet the description still adds real meaning: max_price_cents is framed as the operator's agreed ceiling and its behavior on price movement is spelled out, and idempotency_key's retry semantics are reinforced. The 'use' enum values (social/web/ad/ai_training) are left to the schema, which is a minor gap.

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 precise verb+resource+effect: buys one use of one photo from the account's prepaid wallet and returns a license plus a download link with metadata removed. This clearly distinguishes it from siblings like num_quote_photo and num_photo_wallet, which do not transact.

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 clear operating context (set max_price_cents to the operator's agreed ceiling; prices rise in a live drop) and explains the refusal path. It never explicitly names the alternative to consult first (num_quote_photo), so the when-not guidance is implied rather than routed.

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