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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description adds extensive behavioral context beyond that: refusal behavior without auth ('refuse and start connect — do not pretend the order went through'), debit semantics (awaiting_review does NOT debit), failure recovery shape (userMessageRu/sayToUserRu plus recovery.openUrl and openUrlRu), server-side enforcement even when review is off (allowlist, catalog prices, limits, HITL, freeze, clarify gate), and response hints (paid + payment.status). No statement contradicts 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?

Every sentence carries behavioral weight — there is no fluff — but the text is a single unbroken paragraph mixing hard constraints, UI elicitation details (button label, do-not-ask-yes/no), branch conditions, and negative rules with no structural hierarchy. The core purpose statement sits at sentence 3 instead of the lead, and the sessionId guidance partially duplicates the schema's own description. Dense but poorly organized; it would parse far better with grouped sections.

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 10-parameter, nested-object tool with no output schema, this is remarkably complete: auth flow, elicitation UI behavior, test mode, lucky branch, clarify gate, review flow, failure recovery, server-side enforcement, and response field hints (paid + payment.status) are all covered. Given annotations already flag destructiveness, an agent has everything needed to invoke correctly and predict consequences.

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 40% (lucky, sessionId, choice_set_id, clarification have schema text). The description compensates meaningfully for the low coverage: lucky is tied to allowLuckyPurchases and luckyPurchaseMaxCoins, choice_set_id/clarification are tied to the NEED_CLARIFICATION consequence, and sessionId reuse is explained. However, the remaining 60% of parameters (items subfields, explanation, idempotency_key, category) receive no description-level semantics beyond the schema's bare names.

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 the core function explicitly: 'Propose or place an order in an allowlisted store using AgentPay coins.' This is a specific verb+resource pair that separates it from siblings like create_topup_intent (adding coins), present_choices (showing options), and request_user_confirmation (asking a question). The two-mode behavior (propose via elicitation vs. place directly) is disclosed, removing ambiguity about what invocation accomplishes. Minor flaw: the purpose sentence appears third, after auth and refusal rules, so it is not front-loaded, but it is unambiguous.

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 explicitly conditions invocation on many states: testMode (spend only gray test coins), get_spending_policy.allowLuckyPurchases (pass lucky:true), clearifyHint required (pass choiceSetId or clarifiation or the server returns NEED_CLARIFICATION), review enabled (status awaiting_review, show photos, owner confirms in cabinet), and existing sessionId (pass it and retru, never begin_agent_link again). It also gives hard when-not rules: 'Never send userID', 'Never ask for a bank card', 'Never change limits, freeze, autotopup, allowlist'. This goes far beyond clear context and includes explicit exclusions.

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