AgentPay (Russia)

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

With no annotations, the description carries full behavioral disclosure. It explains the need to open openUrl, host-specific popup limitations, the requirement to immediately poll with the same sessionId and wait_seconds=90, auth handling (Bearer vs apiKey), and never-end-turn-while-pending. This is exemplary transparency.

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 every sentence is action-oriented and non-redundant, front-loaded with the core condition (only start when no sessionId). It packs multiple critical rules without fluff, and the structure flows logically from trigger to execution to edge cases.

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 a single optional parameter with no output schema, the description fully compensates by covering the entire auth lifecycle: initial connect, host quirks, polling behavior, subsequent sessionId propagation, and explicit prohibitions. It is complete enough for an agent to execute this tool and the follow-up flow correctly in all mentioned contexts.

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?

Though the schema already enumerates all client values with 100% coverage, the description adds critical usage semantics per host—e.g., Cursor/Antigravity often cannot pop a window, so paste a markdown link; Grok/ChatGPT/Claude web lack Authorization and need sessionId on every tool. This adds meaning beyond the schema's simple enum 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?

The description explicitly states the tool initiates AgentPay browser connect, with a precise precondition (no sessionId) and a clear contrast to poll_agent_link. It identifies the action (start connect, open URL, poll) and the resource (AgentPay browser session), fully distinguishing it from siblings.

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?

Provides explicit when-to-use (only when no sessionId and tools fail without auth) and when-not-to-use (if sessionId exists, use poll_agent_link instead). Names the alternative tool and gives specific workflow steps, including never starting a new link in the same chat and never asking owner to reconnect.

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

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

With no annotations, the description fully discloses behavioral traits: it mentions test mode coin spending, awaiting_review status not debiting, recovery on failure, sessionId authentication, and that the server attaches the address. It covers side effects, error handling, and authorization nuances, providing everything an agent needs to anticipate behavior.

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 a single dense paragraph with no bullet points or logical grouping. It front-loads purpose but then quickly jumps into conditional flows, error handling, and numerous 'never' directives. It is overly long and could be better organized with sections or bullets, making it harder to parse quickly.

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 complexity (11 parameters, nested objects, no output schema, no annotations), the description is remarkably comprehensive. It covers authorization, test mode, delivery requirements, review flow, error recovery, and retry logic. The only minor gap is lack of description of return values or response structure, but since there is no output schema, the description still provides sufficient context for effective use.

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 only 45%, so the description compensates for many parameters. It explains delivery (method, pickupPointId, not to invent PVZ), sessionId (when to pass, not to invent), lucky (skip present_choices), clarification (mode, confirmed, answerSummary), and idempotency_key (retry semantics). However, some required parameters like store_id, amount, and items lack explicit semantic detail beyond schema, and the description does not clarify their format or constraints.

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 clearly states the tool's function: 'Propose or place an order in an allowlisted store using AgentPay coins.' It uses a specific verb (propose/place) and identifies the resource (order in an allowlisted store) and currency (AgentPay coins). It does not explicitly name sibling tools for differentiation, but the purpose 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 provides extensive when-to-use guidance: it specifies conditions for asking delivery method, handling NEED_FULFILLMENT, retrying with idempotency_key, waiting on review status, and using sessionId. It also gives explicit 'never' instructions to avoid misuse (never ask for bank card, never web-search, etc.). This goes beyond basic usage to include exclusions and alternatives like get_purchase_status.

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

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

With no annotations, the description carries full burden and does an excellent job: it discloses payment reuse ('Reuses today's pending payment'), idempotency concerns ('do not hammer retries'), prerequisites (sessionId for certain connectors), and several safety constraints. These are meaningful behavioral details beyond basic 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 dense but every sentence adds a unique operational rule. It is front-loaded with the core purpose and then lists conditions/constraints. Could be slightly more organized, but it is not redundant and remains appropriately concise for the complexity.

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 tool with no output schema and no annotations, the description covers the trigger condition, the action, integration with get_payment_status, sessionId authentication flow, and many edge-case prohibitions. It is contextually complete for an AI agent to know when and how to invoke it correctly.

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 baseline is 3. The description adds extra value for sessionId by explaining the AGENTPAY_API_KEY scenario and tying it to begin_agent_link, which is not fully covered in the schema. It also reinforces the 'never invent sessionId' rule. This goes beyond just restating the schema.

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 clearly states the tool creates a top-up request by asking the owner to add coins, opening YooKassa or cabinet. It distinguishes itself from siblings like create_purchase and get_payment_status by explicitly mentioning the INSUFFICIENT_FUNDS trigger and the payment 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?

It gives explicit when-to-use ('Call on INSUFFICIENT_FUNDS'), explicit when-not-to-use ('Never take a card in chat', 'Never enable auto-topup yourself'), and references alternatives like get_payment_status and begin_agent_link. It also advises against retrying when payment is pending and specifies sessionId handling.

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

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

No annotations exist, so the description carries the full burden. It discloses important behavioral traits: coins are closed-loop (not cash/withdrawable), the wallet may be frozen (do not spend), and test mode requires telling the user before shopping. It also warns against repeating actions like begin_agent_link. This is transparent about side effects and constraints.

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 a single dense paragraph containing both essential usage and multiple caveats (closed-loop, frozen wallet, sessionId handling). While structured, it is somewhat verbose and mixes operational notes with purpose, making it slightly less concise than ideal.

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 complexity (test mode, frozen wallet, authentication nuances), the description covers key aspects: return fields (testMode, testBalance, realBalance), the need to inform the user in test mode, closed-loop constraints, and sessionId usage. It lacks explicit error scenarios or when to prefer other tools, but overall it is sufficiently complete.

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?

The schema already covers sessionId with detailed description (optional, from begin_agent_link/poll_agent_link, for authentication). The description adds a conditional requirement ('If AGENTPAY_API_KEY required... pass sessionId and retry'), which enriches the parameter's semantics beyond the schema, earning above baseline.

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 clearly states the tool retrieves the agent's wallet balance, with a specific verb ('get') and resource ('Agent wallet'). It distinguishes itself from sibling tools by listing example user queries (e.g., 'how much money does the agent have', 'balance') and specifying it is used after verify_connection, making its purpose 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 provides explicit trigger conditions (example queries, after verify_connection) and gives a conditional instruction for when to pass sessionId (if AGENTPAY_API_KEY required). It does not explicitly contrast with alternative tools, but the triggers are clear enough to guide appropriate usage.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the call blocks for up to wait_seconds, that it may require sessionId for authentication, and warns against common pitfalls. It does not detail error handling or timeout behavior beyond returning status, but covers the essential operational behavior.

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 concise but dense, with the core purpose stated first. It includes several imperative warnings that add length but are valuable for correct usage. Overall, it is well-structured and front-loaded, though slightly cluttered with do-nots.

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 waiting/status tool with authentication nuances, the description covers key aspects: wait behavior, return values, session handling, and prohibitions. It does not provide examples or error cases, but given the tool's complexity and lack of output schema, it is sufficiently complete.

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 67% (choice_set_id lacks description), but the description compensates by explaining wait_seconds range and the purpose of sessionId, including when to pass it. It adds meaning beyond the schema, though it does not elaborate on choice_set_id (implied by the flow).

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 clearly specifies the tool's action: it waits for an owner choice after present_choices, holding the call until status becomes 'chosen' or timeout. It explicitly mentions the return values (status and chosenOptionId), making it distinct from siblings like poll_agent_link or present_choices.

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 provides explicit when-to-use context ('after present_choices'), clear parameter guidance (wait_seconds range), and explicit exclusions: 'Never begin_agent_link again', 'Never ask the owner to edit connector settings', 'Never web-search'. It also explains when to pass sessionId, giving strong usage direction.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: it may trigger a one-time prompt to the owner, it requires a sessionId in certain conditions, and it explicitly states what not to do. It doesn't describe the return value or side effects beyond the prompt, but the explicit prohibitions add significant transparency.

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 concise and front-loaded with the core purpose. It uses imperative 'Never' statements to convey constraints efficiently. It's slightly dense with multiple instructions, but each sentence earns its place. No fluff.

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 complexity (conditional behavior, integration with save_delivery_address, sessionId handling), the description covers the essential workflow and constraints. There's no output schema, but the description doesn't need to explain return values since the tool's primary action is to retrieve and possibly prompt. It could mention what happens if the address is already available, but the conditional logic is well covered.

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?

The schema description coverage is 100% for the single parameter sessionId, and the schema already explains its purpose and usage. The description adds context about when to pass sessionId ('if AGENTPAY_API_KEY required and you already have sessionId from this chat'), which is useful but not extensive. Baseline 3 is appropriate since the schema does the heavy lifting.

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 clearly states the tool's purpose: 'Get the owner's saved AgentPay home address.' It specifies the resource (owner's saved AgentPay home address) and the action (get). It distinguishes from siblings like save_delivery_address by focusing on retrieval, though it doesn't explicitly contrast with other get_* tools.

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 provides explicit when-to-use guidance: if readiness.missing is not empty, ask the owner ONCE with a specific prompt, then save_delivery_address. It also gives clear exclusions: 'Never ask field-by-field across turns,' 'Never begin_agent_link again,' 'Never ask the owner to edit connector settings or reconnect,' and 'Never web-search.' This is exemplary usage guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states what the tool returns ('sayToUserRu, side (agentpay vs merchant), and the contact'), and imposes ethical constraints ('Do not invent a reason', 'Do not hide whose side it is'). It also explains the sessionId retry logic, adding transparency about authentication behavior. No contradictions with absent 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 somewhat long but every sentence adds necessary guidance—trigger examples, return values, retry logic, and prohibitions. It is front-loaded with the core action and then lists conditions. It is not overly verbose, though it could be tightened by grouping related instructions. The structure is logical and scannable.

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 simplicity (a FAQ lookup) and the absence of an output schema, the description fully covers usage: when to call, what to pass, what to expect in return, and critical pitfalls. It also addresses edge cases like sessionId retries. The description leaves no glaring gaps for an agent to misuse the tool.

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 100%, so parameters are already documented. The description adds value beyond the schema by providing usage context for sessionId ('pass sessionId and retry' and 'Never invent a sessionId'), which explains how to handle authentication failures. It also clarifies the 'q' parameter's flexibility by giving language examples, though these are partially covered in the schema. Overall, it supplements rather than repeats schema info.

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 clearly states the tool's purpose: 'Look up AgentPay operational FAQ before guessing.' It specifies the resource (FAQ) and the action (look up), and provides concrete trigger scenarios. It distinguishes itself from sibling tools by positioning it as the go-to for operational questions, unlike other tools like get_product or search_products.

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 explicit when-to-use guidance with specific examples ('why a SKU looks wrong', 'why a photo is missing', etc.) and when-not-to-use instructions ('Never web-search', 'Never begin_agent_link again', 'Never ask the owner to edit connector settings'). It also provides a retry condition for sessionId, making usage highly actionable.

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

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

No annotations are provided, so the description carries full burden. It discloses that limits are hard and enforced by server, that the agent cannot raise them, and clearly states limitations (cannot edit settings, reconnect, or web-search). It also warns about not repeating begin_agent_link. This exceeds the typical transparency expected and provides critical behavioral context.

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 dense with essential information but slightly long, covering multiple operational scenarios (limits retrieval, error handling, security warnings, alternative tools). Each sentence adds value, but the list of 'Never' instructions could be integrated into usage guidelines. Still, it's efficient and front-loaded with the primary purpose.

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 complexity (auth flow, hard limits, interdependencies) and lack of annotations/output schema, the description is exceptionally complete. It explains not only what the tool does but also its role in the overall purchase flow, error recovery, and security constraints. The agent is fully equipped to invoke it correctly.

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 covers sessionId at 100% with a detailed description, the tool description adds significant context about when to pass sessionId (when connector lacks Authorization Bearer) and how to obtain it (from begin_agent_link/poll_agent_link). This exceeds the schema's explanation, integrating usage into the overall flow. Baseline is 3 but the added operational nuance justifies a 4.

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 explicitly states the tool retrieves hard spending limits per purchase, daily, weekly, and confirmation threshold. It clearly differentiates from siblings by specifying it's for limits, and names the action 'get' with a resource. The purpose is unambiguous and distinct from related tools like get_balance or get_spending_policy.

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?

Explicitly instructs when to use: 'Call before create_purchase when the user says...' and lists trigger phrases. It also directs to get_recovery_guide for owner changes, preventing misuse. Provides clear conditions and exclusions, making it superior to alternatives like get_spending_policy or get_balance.

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

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

No annotations provided, so description carries full burden. It discloses rate limit (max 3 auto-topups per day), required key (AGENTPAY_API_KEY), and authentication behavior (pass sessionId, retry). Slightly lacking edge-case behavior (e.g., what happens on network failure) but strong for core transparency.

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?

Compact and front-loaded with the main action. Multiple exclusions make it slightly dense but every sentence carries actionable info. The listing of user phrases is helpful.

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 no output schema, it supplements return values (paid, payment.status, latest topups, autoTopup fields) that an agent would otherwise not know. Covers usage, auth, restrictions; is complete for its purpose.

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 already describes sessionId with high coverage (100%). Description adds context: recommends passing it for all tools when no bearer token and highlights 'Never invent a sessionId'. This adds value but doesn't fully compensate for all edge cases.

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 verb+resource+scope ('Check whether the last top-up/payment succeeded') and explicitly distinguishes how it relates to siblings (call after create_topup_intent, after a failed purchase). Clearly distinguishes from get_purchase_status and get_balance.

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?

Explicit when-to-use, when-not-to-use (do not create another payment if pending/succeeded), authentication guidance, and exact prohibitions (never begin_agent_link again, never web-search). Provides conditional logic (if AGENTPAY_API_KEY required and sessionId exists).

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

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

With no annotations available, the description carries the full burden of behavioral disclosure and does substantial work: it lists the always-returned fields, signals the allowlist restriction, explains q semantics, and gives sessionId retry guidance. It does not cover error behavior or missing-product cases, but the operational constraints and retry rule are valuable.

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 purpose is front-loaded and every clause adds operational value, but the description is dense with instructions such as retry behavior and multiple 'Never' restrictions packed into one block. It is efficient, but slightly less scannable than a shorter, more segmented description.

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 read-oriented tool with no output schema and no annotations, the description covers the key return fields, when to call it, required ID semantics, and auth retry behavior. It does not mention failure modes or how to verify an allowlisted store, but the essential operational context is present.

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 only 50%, so the description compensates by tying product_id and store_id to the lookup and by giving q practical meaning: 'Pass q as the owner's search phrase so pick explains this sku against that query.' It also reinforces sessionId usage beyond the schema text with the retry instruction.

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 starts with a concrete action: 'Get one ProductCard by product_id + store_id from an allowlisted store.' This clearly identifies the resource, the lookup keys, and the store restriction, and distinguishes it from broader sibling tools like search_products by emphasizing single-card retrieval by composite IDs.

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 explicitly says 'Call to confirm price, photos, and why this product before create_purchase,' which gives a direct when-to-use instruction. It also provides exclusionary guidance with 'Never web-search,' 'Never begin_agent_link again,' and 'Never ask the owner to edit connector settings or reconnect,' making the intended invocation context very clear.

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

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

With no annotations, the description carries full burden. It discloses that the tool holds the server until paid, submitted, rejected, or timeout, describes the return value (paid, payment.status, purchase.status), and notes retry conditions: if AGENTPAY_API_KEY required and sessionId is already available, pass sessionId and retry. It also warns against repeating actions like begin_agent_link and web-search, which is critical for agent behavior.

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 compact and information-dense, covering all essential points in a few sentences. It front-loads the core purpose and then provides critical constraints. No redundant or filler content. Every sentence adds value, such as return values and prohibitions.

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 complexity (polling with state transitions), the description is remarkably complete: it explains the states, the wait mechanism, return values, retry logic, and key prohibitions. Despite no output schema, the description explicitly lists the returned fields. It also mentions authentication scenarios, which is important for an agent to act safely.

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 67%, but the description adds meaning beyond the schema: it specifies wait_seconds range (5–120) and explains the server behavior during the wait. For sessionId, the description clarifies when to pass it (if AGENTPAY_API_KEY required and sessionId already exists) and warns never to invent it. The schema descriptions are also rich, especially for sessionId, but the description still adds critical usage context.

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 clearly states the tool's function: to wait for a purchase to transition out of awaiting_review/awaiting_confirmation states, returning payment and purchase statuses. It also distinguishes it from siblings by specifying it is used immediately after create_purchase, differentiating it from get_payment_status and get_choice_status which serve similar polling needs.

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?

Provides explicit usage guidance: call immediately after create_purchase when status is awaiting_review, and instructs to pass wait_seconds (5–120). It also gives strong negative guidance: do NOT tell owner to return, never begin_agent_link again, never ask owner to edit connector settings, and never web-search. However, it doesn't mention alternatives to this tool, though the sibling context makes it clear that other status tools exist.

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

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

With no annotations, the description fully discloses behavioral traits: it instructs on reading recovery fields, opening URLs, and explicitly forbids certain actions even when ordered. It also specifies authentication handling ('If AGENTPAY_API_KEY required and you already have sessionId from this chat: pass sessionId and retry'). This goes beyond basic operation and clarifies constraints.

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 a single dense paragraph but front-loads the core purpose and then layers triggers, constraints, and exceptions. Every sentence carries actionable information, though it is lengthy. Structure could be improved with bullet points, but the content is efficient and well-ordered.

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 no output schema and the tool's role in error recovery, the description fully covers what the tool returns (catalog of failures), how to react, and guardrails. It also addresses common scenarios (4xx, sessionId) and integrates with sibling tools like set_test_mode, making it complete for the agent's decision-making.

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?

The single parameter sessionId is well-documented in the schema, and the description adds integration context (pass sessionId and retry when API key required). This adds value beyond the schema, which already covers its purpose and restrictions. Since schema coverage is 100%, baseline 3, but the description's additional guidance justifies a 4.

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 clearly states the tool's purpose as a 'Full catalog of AgentPay failures with RU copy, cabinet deep links, and recovery.openUrl.' It names the specific resource and distinguishes it from siblings like get_faq or get_limits by focusing on failure cases and recovery actions.

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?

Explicit triggers are provided ('Call when something failed, the user asks «что не так», «почему не купил», or before explaining a 4xx'), along with exceptions (test mode via set_test_mode) and negative instructions (never change limits, freeze, auto-topup, allowlist, never ask to edit connector settings, never web-search). This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses response content, states that raw delivery addresses are not included, explains sessionId retry behavior, and warns against re-initiating setup flows. It does not explicitly call itself read-only or mention rate limits, but it is substantially transparent.

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 front-loaded with the tool's core purpose and field list, but the latter half packs several tangential or generic warnings ('Never web-search', 'Never ask the owner to edit connector settings') that could be trimmed or moved to annotations. It is dense and useful, but not tightly 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 no output schema and no annotations, the description is unusually complete: it lists return fields, trigger conditions, a create_purchase delivery caveat, sessionId authentication handling, and prohibitions. An agent has enough context to select, invoke, and interpret this tool successfully.

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?

The only parameter, sessionId, is already fully described in the schema, so the baseline is 3. The description adds operational meaning by instructing the agent to 'pass sessionId and retry' when AGENTPAY_API_KEY is required, which goes beyond the schema's description.

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 'Get hard + soft spending policies' and enumerates the exact fields returned: allowlist, forbidden categories, confirmation mode, preference weights, allowLuckyPurchases, luckyPurchaseMaxCoins, and delivery.complete/missing. This clearly identifies the resource and differentiates it from siblings like get_limits and get_user_preferences.

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 explicitly says when to call the tool: 'Call before a surprise buy or when the user says...' and lists trigger phrases. It also gives exclusions and behavioral constraints: 'Do not send delivery on create_purchase', 'Never begin_agent_link again', 'Never ask the owner to edit connector settings', and 'Never web-search'.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses side effects (e.g., never begin_agent_link again, never web-search), authenticates via sessionId, and specifies pharmacy course reminder behavior. It misses some details like rate limits or error cases, but covers key behavioral traits, so a 4 is justified.

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 thorough but quite long, with dense, run-on sentences that mix categories, triggers, and instructions. It front-loads the purpose but could be better structured with bullets for readability. Despite the length, every section adds value, so it's a 3 rather than lower.

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 complexity (multiple categories, use-cases, sessionId handling), the description is remarkably complete. It covers prerequisites (call before search_products), category-specific behaviors, course reminders, and auth guidance—all without an output schema. No significant gaps are apparent.

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 100%, so the baseline is 3; the schema already explains sessionId in depth. The description adds usage context for the category parameter (e.g., ALWAYS call with category=pharmacy first) but not new semantics beyond what the schema provides, so a 3 is appropriate.

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 clearly states the tool fetches user category preferences, schema, learned signals, and onboarding purposes, going beyond the generic name. It distinguishes itself from siblings like get_spending_policy and update_preference by specifying the exact data returned and its role in purchasing flows.

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 provides explicit when-to-use (before search_products for purchase intent, for pharmacy/sport categories, when filling preferences) and when-not-to-use (idle advice like 'какие витамины попить'). It names alternatives like search_products and create_purchase, and even lists trigger phrases, making usage decisions unambiguous.

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

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

With no annotations, the description carries the full burden. It discloses mandatory shopping constraints, testMode behavior, authentication requirements, and warns against re-initiating agent link. It doesn't describe error handling or response status, but covers the critical behavioral side effects thoroughly.

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 every sentence serves a purpose: core purpose first, then constraints, triggers, alternatives, and auth specifics. It is front-loaded and logically ordered, though slightly verbose for a simple list tool.

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 no output schema, the description compensates by describing the returned store structure (checkoutProfile, pickupPoints). It also covers invocation context, auth, test mode, and safety rules. Missing details like pagination or empty list behavior are minor gaps but not critical.

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% and baseline is 3. The description adds significant value: for 'need' it clarifies it's an optional topic and recommends peek_stores for quiet offers; for 'sessionId' it explains authentication flow and when to pass it (Grok/ChatGPT/Claude). This goes well beyond the schema.

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 clearly states the tool lists stores on the agent's allowlist and explicitly distinguishes it from peek_stores and search_products for different query intents. The verb 'list' and resource 'allowed stores' are specific and 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?

Provides explicit trigger phrases ('магазин', 'где можно потратить') and explicit exclusions ('For «найди» / «сравни» / «подбери» call peek_stores first'). It also gives conditional instructions for testMode and sessionId, making when-to-use extremely clear.

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

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

No annotations are provided, so the description carries full responsibility. It discloses key behaviors: returns last plus purchases[], mentions testMode coin usage, explains usePastPurchases=false yielding empty history, and warns against inventing past baskets or re-running begin_agent_link. This goes beyond what structured fields reveal.

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 a single block of text but front-loaded with purpose and usage, then caveats. While long (~150 words), every sentence adds value—workflow, exclusions, and environment-specific handling—justifying the length. Slightly dense but well-organized.

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?

Despite no output schema, the description states it returns 'last plus purchases[]' and tells how to use them. With 100% schema coverage, 4 optional params, and complex context (test mode, sessionId, usePastPurchases flag, connector variations), the description covers all major aspects: triggers, workflow, edge cases, and exclusions, making it complete.

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?

With 100% schema parameter coverage, the schema already explains parameters. The description adds contextual guidance (e.g., sessionId retry logic, test mode behavior) that goes beyond but doesn't fundamentally alter parameter semantics. Baseline 3 is appropriate since the schema carries the primary load and the description adds marginal semantic enrichment.

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 clearly states that it lists the owner's recent AgentPay purchases with line items, specifying scope (bought statuses only) and provides trigger phrases. It explicitly distinguishes from sibling tools like search_products and create_purchase, making the purpose 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 provides explicit when-to-use triggers with example phrases, and gives sequential workflow guidance (use last.items, then search_products, then create_purchase). It also states exclusions: 'Do not invent a past basket', 'Do not search the idiom as a product name', and clarifies conditions like usePasturchases false and sessionId requirements, fully guiding tool selection.

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

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

With no annotations, the description bears full responsibility and covers behavior thoroughly: it reveals output format ("speak that one sentence"), restrictions ("Do NOT list SKUs"), retry logic ("pass sessionId and retry"), and auth handling ("Never begin_agent_link again"). It also clarifies non-actions ("Never ask owner to edit connector settings"), providing complete transparency.

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 lengthy (~200 words) but every sentence contributes essential operational constraints. It opens with a concise catchphrase ("Quiet first hop") and front-loads the most critical rules. While dense, it avoids redundancy and each clause adds value, though it could be trimmed slightly for brevity.

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 no output schema, the description covers return values (matched stores + sayToUserRu), error handling (unmatched scenario), authentication (sessionId handling), and sibling interactions (avoiding search_products until consent). It also addresses rate-limits implicitly ("Call ONCE"). For a tool with multiple constraints, this is exceptionally complete.

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 baseline is 3. The description adds valuable meaning beyond the schema: it provides concrete examples for need ("виタミны, техника, протеин") and expands on sessionId (when to pass it, never invent it, auth semantics). This goes beyond mere schema repetition, earning a 4.

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 explicitly states the tool's function: "Returns matched stores + sayToUserRu." It also identifies the precise scenario for invocation ("Call ONCE when shopping-adjacent") and gives concrete triggers (найди, подбери, сравні, пошук). It differentiates from the sibling tool search_products by explicitly instructing not to call that until owner agreement. This is a specific verb+resource with clear scoping.

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?

Offers exhaustive when/when-not guidance: "Do NOT call search_products until the owner agrees to look," "Never call for advice or rumination," and "If unmatched, say so once and stop pushing." It also distinguishes from chat-only interactions and web-search, providing unambiguous context for an agent.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the server holds the call while the owner is in the browser, how to treat the pending openUrl, and what to do when status=approved. It does not cover denial/timeout/error details, but the core behavior is transparent.

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 substantially longer than needed and repeats key directives: 'NEVER begin_agent_link again in the same chat' appears twice, and the Grok Authorization warning also appears twice. While front-loaded, the later auth guidance is redundant and distracts from the main polling behavior.

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 role in a multi-step auth/shopping workflow and the lack of annotations/output schema, the description covers most necessary context: session reuse, wait behavior, pending state, approved-state follow-up, and missing-Authorization handling. Small gaps remain around explicit status values and failure/timeout behavior.

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 already 100%, so the baseline is 3. The description adds value by prescribing wait_seconds=90 right after begin_agent_link and explaining why ('so the server holds this call while the owner is in the browser'), which goes beyond the schema's bare parameter descriptions.

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 action: 'Wait until the owner clicks Разрешить.' It also names the required sessionId source ('Pass sessionId from begin_agent_link'), which clearly distinguishes this polling step from the begin_agent_link sibling tool.

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?

Usage is highly explicit: use it right after begin_agent_link, always pass wait_seconds=90, keep the call alive, re-poll the same sessionId, and never call begin_agent_link again. It also gives post-approved follow-up actions and auth fallback rules.

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

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

No annotations are provided, so the description carries the full burden. It discloses expected follow-up actions (call get_choice_status, wait), what to avoid (asking for typed input, creating purchase early), how to handle sessionId if required, and explicit 'never' instructions. Minor gap: it doesn't explicitly state what the endpoint destroys or changes, but for a creation tool this is adequate. No contradictions.

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 concise and front-loaded with the core purpose and key kinds, followed by critical instructions. It packs many essential directives without wordiness; each sentence carries weight. Just slightly dense but appropriately so for the complexity.

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 complexity (three modes, required follow-up, authentication nuance, restrictions), the description covers all essential aspects: selection criteria, after-call behavior, error handling (sessionId), and prohibitions. No output schema, so the description clearly states the return value (choiceSetId + pageUrl) and what to do with it. Completeness is high for an integration-heavy tool.

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 80%, and the description adds meaningful detail: it explains the semantic difference between kind values (alternatives vs look vs bundles) with concrete examples, and clarifies the sessionId necessity for certain connectors. The agentIntroRu and wants params are somewhat understood from their schema descriptions, but the description doesn't elaborate on them beyond the schema.

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 clearly states it creates a choice page for the owner and explains the three kinds (alternatives, look, bundles) with specific use cases. It distinguishes itself from sibling tools like search_products, create_purchase, and get_choice_status by defining its role in the 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?

The description explicitly says when to use each kind, mandates calling get_choice_status immediately after, prohibits asking the owner to type numbers, and reminds not to call create_purchase until status=chosen. It also says not to repeat begin_agent_link or ask for connector settings, providing clear contextual guidance and exclusions.

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

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

No annotations exist, so the description carries full behavioral disclosure. It reveals that confirmation occurs outside the chat, that chat 'ok' is not valid approval, and that sessionId must be passed in certain cases. It also warns against unintended actions. While it could clarify the tool's response or blocking behavior, it effectively conveys the key constraints and external dependencies.

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 dense with actionable directives but avoids padding. It front-loads the core action and then details triggers, constraints, and session handling. The structure is logical, though slightly rambling with multiple clauses. It does not waste words, making it efficient despite its length.

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 complexity (external confirmation, session management) and the lack of an output schema, the description provides essential context: when to use it, how to handle sessionId, and what not to do. It misses a description of the response after confirmation, but for an agent's decision-making, the coverage is strong enough to avoid common mistakes.

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 only 25% (only sessionId is described). The tool description adds useful context for sessionId ('pass sessionId and retry') but provides no clarification for amount, message, or purchase_id. Since the schema lacks descriptions for three parameters, the description should compensate, but it only partially does so for sessionId, leaving the others underspecified.

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 clearly states the tool's action ('Ask the human to confirm') and the resource ('in AgentPay web or Telegram'). It lists specific triggers ('спроси меня', 'подтверди', HITL) and distinguishes it from sibling tools like begin_agent_link by emphasizing it's for confirmation, not link initiation.

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?

Explicitly states when to call ('when the user must approve a spend, freeze, or missing delivery data') and provides clear exclusions ('Do not treat chat ok as payment approval', 'Never begin_agent_link again', 'Never ask the owner to edit connector settings'). It also gives conditional guidance on sessionId usage, offering comprehensive usage direction.

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

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

With no annotations, the description carries the full burden, and it does well: it discloses the mutation nature (saving), the requirement to ask once, optional intercom, and retry behavior with sessionId. It also states what not to do, but lacks details on failure responses or idempotency. Given the absence of annotations, a 4 is appropriate.

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 dense but structured: it leads with purpose, then procedural instructions, then constraints and retry logic. Every sentence adds value, though it repeats 'never' multiple times which could be tightened. It's not minimal, but it's efficient for a complex tool.

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 14 parameters, no output schema, and no annotations, the description covers the essential context: what to ask, how to provide the phrase, optional fields, retry logic, and prohibitions. It doesn't describe return values or error specifics, but for a mutation tool it's sufficiently complete for an agent to operate correctly.

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 only 21% (3 of 14 params), and the description compensates substantially by explaining the address phrase components (город, улица, дом, квартира, etc.) and how they map to `text`. It also clarifies sessionId usage and that intercom is optional. It doesn't describe every parameter, but it adds meaning beyond the sparse schema, so a 4 is fair.

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 clearly states the tool saves the owner's home address into the AgentPay cabinet, specifying the exact action and destination. It also distinguishes itself from sibling tools by focusing on address saving and including specific fields like intercom and phone, making it 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 provides explicit when-to-use and how-to-use instructions: ask for the full phrase in one turn, pass it as `text`, never invent missing parts, and retry with sessionId if the API key requires it. It also gives exclusions: never begin_agent_link again, never ask to edit connector settings, and never web-search. This is exemplary usage guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does so elaborately. It reveals the return structure (ProductCard fields, clarifyHint, quietHint), tells the agent to read clarifyHint before create_purchase, and warns about side constraints such as never paying outside AgentPay and never dumping the result list. This is far beyond a minimum and lets the agent anticipate tool behavior without needing an annotation layer.

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 fairly long and is written as one dense run-on paragraph, which hurts scannability. However, every clause carries a necessary behavioral instruction, and it is front-loaded with the core purpose. A bulleted list would improve structure, but no sentence is wasted or merely repetitive.

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?

The tool has no output schema, so the description must explain the return value, and it does. It covers clarifyHint (skip/present_choices/ask_one), quietHint, and how to react to them. It also covers the sportpit workflow requirement (get_user_preferences(sport) before searching), sessionId handling for agent-link, and clear negative instructions (no bank card, no web search). Given the rich behavioral contract, this description leaves almost no context out.

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?

The schema already covers 100% of the parameters, including aliases, so the baseline is 3. The description adds some semantic nuance by consolidating the alias concept: 'All mean the PRODUCT query, never an address' and by emphasizing q's min-length and example. However, some of this duplicates the schema, and it introduces a conflict by calling q 'REQUIRED' while the schema declares zero required parameters. This inconsistency prevents a higher score.

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 starts with a precise verb-resource pair: 'Search products in allowlisted AgentPay stores.' This clearly distinguishes it from sibling tools like get_product (single product fetch), peek_stores (store preview), and list_purchases (purchase history). It unambiguously states the scope and function.

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 explicit when-to-use rules: call only after specific purchase intent words ('купи', 'закажи', 'оформи', etc.) or after peek_stores when confirmed. It also gives explicit when-not-to-use guidance: 'Never call for thinking/advice' and names alternatives for specific situations, e.g., 'If the owner says «как обычно», «то же самое», «повтори заказ» — call list_purchases first'. It also correctly reroutes address-related input to get_delivery_address / save_delivery_address. This is exemplary.

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

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. It details the impact of enabled/disabled states (test coins vs real coins, hide test stores), mentions the authentication nuance with sessionId and retry logic, and clarifies prohibitions regarding owner involvement and connector settings. This goes far beyond a basic toggle description.

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 substantial but well-organized: it opens with the core action, lists triggers, then covers behavioral rules and authentication edge cases. Each sentence adds value; the use of 'While' and 'Never' statements provides structure. It's slightly long but appropriate given the tool's complexity.

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 tool with two parameters, no output schema, and a behavioral toggle affecting spending modes, the description covers all necessary context: what happens in each mode, when to call, how to handle authentication with sessionId, and critical prohibitions. It also provides guidance on when to suggest toggling (after real top-up), making it self-sufficient for an AI agent.

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?

The input schema already documents both parameters with 100% coverage. The description adds extra meaning by explaining the practical effect of 'enabled' (true = test stores + coins, false = live stores + hide test shops) and clarifies when sessionId should be used (when connector has no Authorization Bearer), along with explicit warnings not to invent or ask the owner to configure it.

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 clearly states the tool's purpose: 'Turn AgentPay test mode on or off.' It specifies the exact action on a targeted resource and distinguishes itself from siblings by noting it's the only policy setting the agent may change, and explicitly references save_delivery_address as the alternative for address storage.

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?

Explicit when-to-use triggers are given: 'Call when the owner says...' or after a top-up when agreeing to leave sandbox. It also provides clear exclusionary guidance ('Never begin_agent_link again', 'Never ask the owner to edit connector settings', 'Never web-search') and points to an alternative tool (save_delivery_address) for address saving.

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

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. It reveals important traits: 'Persist structured data only,' 'Never invent fields the owner did not confirm,' consent requirements for sport, non-medical-advice caveat, sessionId retry behavior, and prohibitions on re-initiating agent link or asking the owner to edit connector settings. This is rich, non-obvious behavioral context.

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 dense with necessary instructions. It front-loads the core purpose and trigger ('Update stored preferences... Call IMMEDIATELY'), then layers category-specific rules, constraints, and auth guidance. Every sentence contributes operational value, though the run-on style and number of directives make it slightly less scannable than ideal.

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 complexity, lack of annotations, nested open-ended data object, and no output schema, the description is remarkably complete. It covers triggers, categories, consent, auth retry behavior, exclusions, and data-invention guardrails. Minor gaps remain around exact success/error response shapes and a fully structured schema for every category, but the description provides enough context for an agent to invoke the tool correctly in most scenarios.

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 only 33%, so the description must compensate. It does by explaining category semantics and providing concrete data examples (height, topSizeEu/topSizeRu, dietFlags=['vegetarian'], vitaminsTaken, courseEndsOn). It also warns against inventing fields, which is essential for the open-ended 'data' object. It doesn't fully enumerate all possible data structures, but it adds substantial meaning beyond the bare schema.

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 clearly states the tool's purpose: 'Update stored preferences for a category.' It goes beyond a generic verb+resource by specifying exactly what kinds of lasting facts trigger an update (body/fit, grocery rules, pharmacy, sport) and explicitly distinguishes it from one-off orders, which separates it from sibling purchase tools.

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 provides explicit when-to-use guidance: 'Call IMMEDIATELY when the owner states lasting body/fit facts in chat' and 'Also after lasting rules.' It also gives category-specific conditions (e.g., sport requires consent, pharmacy after a vitamin buy) and a clear exclusion: 'Do not use for one-off orders.' This is exemplary usage guidance.

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

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

With no annotations provided, the description carries the full behavioral burden and honors it thoroughly: it discloses auth requirements (pass sessionId when no Authorization Bearer; never pass apiKey), the NEED_BROWSER_GRANT fallback (open recovery.openUrl), a retry rule (if AGENTPAY_API_KEY required and sessionId exists, pass sessionId and retry), and success-side messaging constraints including testMode wording and forbidden phrases.

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 prose is one dense, run-on block of roughly ten rules — a trigger, an auth-check, a retry path, and safety-message constraints are all jammed together in a single paragraph. Each point does earn its keep, but the wall-of-text structure and the mix of English/Russian make it harder to scan at a glance; structured separation would make it notably better.

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 complex tool with zero required params, no annotations, and no output schema, the description is exceptionally complete: it covers the trigger flow, auth/ retry paths, the browser-grant error case, and required post-success messaging. The remaining gaps are the output shape (success/error payload) and the ambiguous reference to 'recovery.openUrl' (the sibling list contains get_recovery_guide, not an openUrl method).

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, and the schema's own descriptions are already detailed (sessionId origin, the als_<sessionId> prefix, 'never invent a sessionId'). The narrative adds real value beyond the schema: explicitly saying pairing code is optional, that apiKey must never be passed, and the precise condition for passing sessionId/retrying (absence of Authorization Bearer or AGENTPAY_API_KEY requirement).

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 identifies a specific action and resource: 'Finish AgentPay connect' after the browser grant, and gives concrete trigger conditions ('after poll_agent_link status=approved, or when the user says «проверь MCP»'). It distinguishes from the connection flow siblings (begin_agent_link, poll_agent_link) through context, though the exact 'verify' behavior is implied rather than crisply stated in a standalone sentence.

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?

Provides explicit when-to-use guidance: after approved status, or on user request; explicit alternatives ('if you have no sessionId and no auth, call begin_agent_link once'); and exclusions ('Never begin_agent_link again', 'Never ask the owner to edit connector settings or reconnect', 'Never web-search'). This fully specializes when to call versus the alternatives.

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