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

Beyond the annotations, it discloses the real side effect: settlement from the connected balance at the shown price, refusal if the actual price exceeds max_price_usdc, one-hour token expiry, and the approval_required status with retry semantics. This is exactly the behavioral context an agent needs for a paid action, and it does not contradict the annotations.

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 longer than average but every sentence earns its place: action, settlement effect, required parameter values, user-consent guardrail, token expiry, and approval retry. It is front-loaded with the core purpose and proceeds in a clear operational order.

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 nine parameters, nested optional inputs, an output schema, and a transactional side effect, the description covers all critical agent decisions: when to call, which values to pass, what happens on price mismatch, token expiry, and approval-required handling. Nothing necessary for safe invocation 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?

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter guidance: offer_token, prompt, and max_price_usdc must come from the exact discovery row and displayed price, and the token pins endpoint and price together so the agent should not restate them.

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 states a concrete action: run the user-chosen offer, settle it from the connected balance, and return the result. It distinguishes itself from discovery/compare/approval siblings by tying offer_token to apiosk_discover and by explicitly saying not to use this tool for exploration.

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?

It gives explicit preconditions: show the exact price, get user choice, never choose for them. It also covers when to rerun apiosk_discover for an expired token and when to poll apiosk_approval_status before retrying, so the agent is told both the primary and exceptional paths.

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