AgentPay (Russia)

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

The annotations are sparse, so the description carries the behavioral burden and does it well: no API key required, give the owner specific URLs, account for VPN, never rewrite agentpay.su to agentpay.shop, and never ask for ap_ tokens. It also warns against inventing keys and switching MCPs. No contradiction with 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 purpose and main condition are front-loaded, and the imperative rules are specific and actionable. However, the description repeats the URL constraint in multiple ways ('MUST NOT rewrite' and 'Do NOT collapse to a single shop URL') and includes several overlapping prohibitions, making it more verbose than necessary.

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 single parameter and no output schema, the description covers the key decisions: when to call, what client to pass, what URL to share, and what prohibited actions to avoid. The main gap is that it references undefined concepts like 'openUrl', 'sayToUserRu', and the post-start flow (e.g. polling) without defining them.

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 fully documents the single client parameter, including valid host names and the warning not to invent a different brand. The description repeats a slightly shorter list of valid values, adding little beyond the schema. It also says 'Pass client' while the schema marks no parameter as required, creating minor ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action, 'Start AgentPay browser connect', and clearly scopes it to connectors with no OAuth/Bearer yet. It explicitly contrasts with the case where the host already supports OAuth, giving the agent a precise purpose and boundary.

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 gating: call ONLY when Auth is None, do NOT call when OAuth already exists, and the host must complete OAuth once instead. Later rules also forbid falling back to other shop MCPs when AgentPay is unauthorized, which is clear alternative-handling 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?

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.

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

Annotations are minimal (only readOnlyHint=false, openWorldHint=false, destructiveHint=false), so the description carries the disclosure burden. It discloses external side effects (opens YooKassa/cabinet), payment reuse behavior ("Reuses today's pending payment for the same amount"), authentication requirements for sessionId, and strong prohibitions like "Never take a card in chat" and "Never enable auto-topup yourself." No contradiction with 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 front-loaded with the core purpose and trigger, and nearly every sentence carries an actionable rule. However, it is a dense run-on sequence of 'Never' prohibitions that would be easier to scan as grouped constraints or bullets. It is still compact relative to the complexity of the payment/auth flow.

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 payment tool with no output schema and sparse annotations, the description covers trigger conditions, retry behavior, pending payment reuse, auth handling, and security boundaries. The main gaps are the ambiguous amountRub-vs-needCoins choice and the lack of explicit post-success flow, though get_payment_status is referenced as the monitoring path. Overall, it is quite complete for its complexity.

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 description adds some useful context, such as passing sessionId only when AGENTPAY_API_KEY is required and retrying with it instead of calling begin_agent_link. However, it does not clarify the relationship between amountRub and needCoins when both are optional and required=0, leaving ambiguity about which parameter to supply or how the server reconciles both.

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 concrete verb and resource: "Ask the owner to top up coins" and the mechanism "opens YooKassa or cabinet." It also pins the trigger to "INSUFFICIENT_FUNDS when auto-topup did not cover the purchase," which clearly separates this tool from purchase, payment-status, and agent-link siblings. An agent can immediately tell what this tool is for.

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 an explicit call condition (INSUFFICIENT_FUNDS after auto-topup failure), explicit alternatives (wait when get_payment_status shows pending), and explicit exclusions (never begin_agent_link again, never ask owner to edit connectors, never web-search). It also warns against hammering retries, which is exactly the kind of usage guardrail an agent needs.

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?

Beyond the readOnlyHint annotation, the description discloses behavioral details that materially affect how the agent should act: it returns skillUrl links, requires the agent to fetch and follow a SKILL.md, and instructs fetching a personal skill-bundle via a specific endpoint after browser authorization. It also surfaces the retry-on-401-style behavior around AGENTPAY_API_KEY and sessionId.

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 each sentence carries operational weight: triggers, return handling, auth flow, and prohibitions. It is front-loaded with the core function in the first sentence. A few directives overlap thematically ('Never ask the owner to edit connector settings' vs 'Never ask owner to open Authorization settings'), which slightly reduces conciseness.

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 there is no output schema, the description reasonably explains what is returned (skillUrl links) and what to do next, including fetching the public SKILL.md and the personal skill-bundle. It also covers auth recovery and important never-do's. It doesn't specify the exact response shape or failure/empty cases, but for an agent invoking this tool the critical path 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?

Schema coverage is already 100%, and both params are documented in the schema. The description adds value by explaining when sessionId should be passed in an auth-challenged context ('If AGENTPAY_API_KEY required and you already have sessionId from this chat: pass sessionId and retry') and implicitly links platform to the listed skills (Cursor/Claude/ChatGPT). This exceeds the baseline but doesn't deeply explain platform-specific behavior.

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 first sentence is specific and actionable: 'Fetch AgentPay skills index (skills.json) and install hints for Cursor, Claude Code, ChatGPT.' It names the exact resource, verb, and target platforms, clearly distinguishing this from siblings like get_faq or get_recovery_guide. The rest of the description reinforces the purpose with concrete triggers.

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 conditions: 'Call at session start when the user shops in Russia, after verify_connection, or when they ask «как подключить skill»...' It also provides clear negative guidance, including 'Never begin_agent_link again' and 'Never web-search,' which helps an agent avoid incorrect alternative tools or actions.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds much more: testMode handling ('mention sayToUserRu once', 'do NOT say «тестовые коины» in every product answer'), closed-loop coin semantics ('not cash, not withdrawable'), sessionId retry behavior, and prohibitions on reconnect and web-search. This is rich behavioral context beyond structured fields.

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?

Although lengthy, every sentence earns its place: purpose and triggers are front-loaded, followed by return fields, testMode nuance, pricing format, closed-loop explanation, auth retry, and negative constraints. There is minimal 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?

For a read-only tool with zero required parameters and no output schema, it covers return values, auth recovery, testMode behavior, pricing, and domain constraints. Nothing an agent needs to call it correctly 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 baseline is 3. The description adds the retry condition 'If AGENTPAY_API_KEY required and you already have sessionId from this chat: pass sessionId and retry', clarifying concretely when to supply the optional parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Get the agent's AgentPay wallet.' It also lists explicit Russian trigger phrases and the returned fields, making it clearly distinct from siblings like get_limits 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?

Provides explicit when-to-call triggers ('Call when the user asks ... or after verify_connection') and explicit when-not-to-do-actions ('Never begin_agent_link again', 'Never ask the owner to edit connector settings or reconnect'). This gives an agent concrete routing and exclusion 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds operational behavior: it is a polling/retry tool, requires sessionId under certain auth conditions, and should not trigger new agent-link setup. This adds useful context beyond the annotations, though it does not go into error or timeout 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 front-loaded with purpose and return values, then gives sequencing, auth handling, and guardrails. The 'Never web-search' directive is a bit abrupt, and the conditional sessionId sentence is dense, but overall each sentence contributes necessary guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description names the return fields ('status draft|chosen and chosenOptionId'), which is sufficient for a simple read-only poll. It also covers the key sequencing and auth conditions. It does not describe exact error responses or JSON shape, but those are not essential given the tool's simplicity.

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% because choice_set_id has no schema description. The description compensates by explaining the choice set originates from present_choices and that its identifier is used as choiceSetId before create_purchase. The sessionId parameter is already richly described in the schema, and the description reinforces the retry behavior. This is meaningful added semantics, though it could be more explicit about how choice_set_id is obtained.

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 says exactly what the tool does: 'Poll a choice set from present_choices' and states the meaningful return values, 'status draft|chosen and chosenOptionId.' This clearly distinguishes it from the many other get_* siblings by tying it to present_choices and the post-choice status.

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 timing: 'Call after present_choices when waiting for the owner, or before create_purchase to attach choiceSetId.' It also tells the agent what not to do in the auth-failure case: 'Never begin_agent_link again' and 'Never ask the owner to edit connector settings or reconnect.' This is actionable and specific.

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?

Annotations already mark readOnlyHint=true, so no contradiction exists. The description goes beyond annotations by revealing that the address is the owner's saved data, how to handle missing fields by asking and then calling save_delivery_address, and the sessionId retry rule when AGENTPAY_API_KEY is required. These are meaningful behavioral details not present in 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 front-loaded with the core function and then uses compact imperative sentences for usage rules. Every sentence carries distinct guidance: when to call, what to do on missing fields, what to never do, and how to handle auth. No filler or redundancy.

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 and full schema coverage, the description provides almost everything an agent needs: the returned field set, call context, missing-data handling, and auth caveats. A minor gap is that it does not explicitly describe the response container or error/empty-address shape, but the field enumeration and 'if fields are missing' instruction largely cover this.

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 documented in the input schema with 100% coverage, including the exact condition for passing it. The description does not add new parameter-level meaning beyond what the schema already provides, so a baseline score 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 uses a specific verb and resource: 'Get the owner's saved AgentPay home address split into courier fields', followed by an enumerated field list. It clearly differentiates itself from the sibling save_delivery_address by stating when to call it and what to do after. 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?

Explicit usage conditions are provided: 'Call before create_purchase or when the user asks «какой адрес», «куда везти», «домофон».' It also gives explicit when-not guidance: never invent fields, never begin_agent_link again, never ask the owner to edit connector settings or reconnect. This fully routes the agent between this and related tools.

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?

Annotations already mark this as readOnly, non-destructive, and closed-world. The description goes beyond that by disclosing what the tool returns, how it handles sessionId-based authentication when AGENTPAY_API_KEY is required, and important behavioral guardrails such as 'Do not invent a reason' and 'Do not hide whose side it is.' This is exactly the kind of context that helps an agent use the tool safely.

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 front-loaded with the core purpose, and every sentence carries guidance. The negative directives (never begin_agent_link, never web-search, etc.) add behavioral value although they could have been consolidated. Still, this is appropriately sized for the complex operational context it covers.

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?

There is no output schema, so the description correctly discloses the return contract: sayToUserRu, side, and contact. It also covers auth fallback for AGENTPAY_API_KEY, which is critical for Grok/ChatGPT/Claude connectors. For a read-only FAQ lookup tool, nothing essential 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 description coverage is 100%, so the baseline is 3: the schema already thoroughly documents q, storeId, and sessionId. The description adds operational context around sessionId ('pass sessionId and retry'), but it doesn't materially add per-parameter meaning beyond what the schema provides. A 3 is appropriate because 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 opens with a specific verb + resource: 'Look up AgentPay operational FAQ before guessing.' It then lists concrete trigger questions and states the exact return fields (sayToUserRu, side, contact), making the tool's purpose unmistakable. This clearly distinguishes it from the sibling tools, none of which are described as a catch-all FAQ lookup.

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: 'Call when the owner asks why a SKU looks wrong...' and similar scenarios. It also provides strong exclusions: 'Never begin_agent_link again,' 'Never ask the owner to edit connector settings or reconnect,' and 'Never web-search.' This leaves no ambiguity about when this tool should be invoked versus alternatives.

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?

Beyond the read-only annotations, it discloses that the server enforces limits even if ignored, that the agent cannot raise them, and how to handle an existing sessionId when AGENTPAY_API_KEY is required. This is rich behavioral context that annotations alone do not provide.

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 main purpose is front-loaded and the sentences are dense with actionable content. The repeated 'Never...' clauses add necessary guardrails but make the description slightly longer than strictly needed.

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 simple one-optional-parameter read tool with no output schema, the description covers what limits are included, when to call, how to authenticate with an existing sessionId, what not to do, and where to direct the user for changing limits. Nothing essential 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?

The schema already fully documents the optional sessionId, so the baseline is 3. The description adds extra operational meaning by specifying when to pass it: if AGENTPAY_API_KEY is required and a sessionId from this chat exists, pass it and retry.

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 names a specific verb and resource: getting hard spending limits the agent cannot bypass, and enumerates the limit types (per purchase, daily, weekly, confirmation threshold). This clearly separates it from siblings like get_spending_policy 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?

Explicitly states when to call it: before create_purchase when the user says «лимит», «потолок», «сколько можно потратить». It also points to get_recovery_guide for raising limits and gives explicit exclusions such as never begin_agent_link again 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?

Annotations mark this as read-only (readOnlyHint=true) and the description confirms a read operation. It additionally discloses return fields, the daily auto-topup cap (max 3), and procedural constraints around sessionId and connector settings, enriching behavior awareness beyond 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 front-loads purpose, follows with triggers, then return values, then conditional instructions and prohibitions. Every sentence is purposeful and non-redundant; despite length, it is efficiently structured for an agent.

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-only status-check tool with one optional parameter and no output schema, the description is complete: it specifies return fields, behavior on pending/succeeded, usage triggers, sessionId handling, and multiple never-do actions. An agent has everything required 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?

The single optional sessionId parameter is fully described in both schema and description. The description adds crucial context: when to pass it (no Authorization Bearer), what it authenticates after approved, and explicit prohibitions (never invent, never ask owner to edit settings), making the parameter semantics richer than the schema alone.

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 verb and resource: 'Check whether the last top-up/payment succeeded.' It then lists exact trigger conditions (after create_topup_intent, after a failed purchase, or when the user asks specific phrases), distinguishing it from siblings like get_purchase_status and create_topup_intent by context rather than explicit sibling naming.

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 states when to call ('Call after create_topup_intent, after a failed purchase, or when the user asks...') and what action to avoid ('If status is pending or succeeded, do not create another payment.'). It also gives conditional retry guidance for sessionId and strong prohibitions ('Never begin_agent_link again,' etc.), providing clear when-to/when-not-to 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?

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context: allowlisted store requirement, demo/test-only behavior without auth, merchant-synced data fields, priceSource distinctions, and the warning 'Never quote price from memory.' This goes well beyond what annotations alone convey and does not contradict them.

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 and front-loaded with the core purpose, followed by auth, return fields, and guardrails. It is longer than minimal, but nearly every sentence adds operational value for an agent; the long tail of 'Never' instructions is justified by high-stakes pricing 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?

With no output schema, the description fully enumerates the returned fields, including edge cases like priceSource (feed|live) and the always-present url/trackedUrl/pick. It also covers the auth lifecycle, required identifiers, and an example trigger list. An agent has enough to call it correctly and interpret the result.

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%, but the description compensates for all four parameters. It clarifies product_id and store_id as the lookup key, explains that q is the owner's search phrase for pick.whyRu, and elaborates on sessionId for authenticated retries. The meaning added is precise and actionable for correct invocation.

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 names a specific verb and resource: 'Get one ProductCard by product_id + store_id from an allowlisted store.' It scopes the tool precisely and helps distinguish it from siblings like search_products or peek_stores. The first sentence alone tells an agent exactly what this tool does and on what identifiers.

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 context with trigger phrases, explains the auth prerequisite for live data via begin_agent_link/OAuth, and tells the agent to call this before create_purchase. It also gives hard exclusions like 'Never web-search' and 'Never begin_agent_link again' when a sessionId already exists, which is actionable routing 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?

Annotations already mark the call read-only and non-destructive, and the description adds substantial behavioral guidance: pending means wait, failed should not be retried, chat acknowledgement is not proof of payment, and agent-link sessionId should be reused without re-running begin_agent_link. No annotation contradiction.

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 earns its place: purpose and return format first, then usage triggers, then edge-case and authentication rules. There is no filler or tautology.

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?

Completes the picture despite a modest schema: return fields, trigger conditions, missing-id fallback, pending/failed handling, and auth/sessionId behavior are all present. An agent has everything needed to call this tool 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 covers sessionId in detail but leaves purchase_id undocumented, so the description compensates by tying purchase_id to list_purchases and to the post-create_purchase context. It also explains when to pass sessionId and warns against inventing one. Slightly generic on purchase_id format but adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action—get purchase status by ID—and names the returned fields (paid boolean and payment.status). This is clearly distinct from sibling tools like get_payment_status because it is anchored to purchases and includes a concrete return shape.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit triggers: call after create_purchase or when the user asks about order/payment/purchase status. It also prescribes the fallback of calling list_purchases first when purchase_id is missing, and tells the agent what to do for pending and failed outcomes.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail beyond that: exact recovery actions (sayUserMessageRu/sayToUserRu, open both openUrl and openUrlRu), the sessionId retry rule, and prohibitions against following owner orders to mutate system state. No contradiction with annotations exists.

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 and front-loaded with the catalog definition and call timing before the guardrails. Every rule serves a purpose, though some statements such as 'Never web-search' and the repeated sessionId guidance are slightly tangential and partially redundant with the schema.

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 no-output-schema reference tool, the description compensates well by naming the fields to read (userMessageRu, sayToUserRu, openUrl, openUrlRu) and covering failure triggers, auth edge cases, test-mode routing, and forbidden actions. An agent has enough context to select and invoke the tool 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?

The schema description covers 100% of the only parameter, sessionId, including when to pass it and what it authenticates. The description repeats the sessionId retry instruction but does not add new parameter-level semantics beyond the schema, so the baseline of 3 applies.

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 identifies the resource: a full catalog of AgentPay failures containing RU copy, cabinet deep links, and dual recovery URLs. It also gives specific call conditions ('something failed', user asks 'что не так', 'почему не купил', before explaining a 4xx) that distinguish it from the sibling transaction and status 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 explicitly states when to call this tool and includes concrete trigger phrases. It also gives strong when-not/alternative guidance: never change limits/freeze/auto-topup/allowlist, never begin_agent_link again, never reconnect, and names set_test_mode as the exception for test-mode requests.

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?

Beyond the readOnlyHint annotation, the description discloses important behavioral details: returned delivery data excludes raw addresses, the server attaches the home address on create_purchase, preferredStoreRoutingRu should change product search behavior, and sessionId-based auth needs a retry rather than re-initiating agent link. These are non-obvious behaviors an agent needs to know.

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 clause serves a purpose: return-content inventory, trigger phrases, routing precedence, create_purchase caveat, auth retry, and prohibitions. It is front-loaded with the most important information and contains no filler or tautology.

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 zero-required-parameter retrieval tool with no output schema, the description fully compensates by listing the returned fields, when to invoke it, how to use its output, and relevant auth behavior. An agent has enough context to call the tool correctly and interpret the result.

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, already has 100% schema description coverage. The description restates when to pass it ('If AGENTPAY_API_KEY required and you already have sessionId from this chat: pass sessionId and retry'), but it does not materially add semantics beyond the schema. Baseline 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 opens with a specific verb and resource: 'Get hard + soft spending policies' and enumerates the exact fields returned (allowlist, forbidden categories, confirmation mode, preference weights, etc.). It also implicitly distinguishes itself from siblings by referencing search_products and create_purchase in the workflow, so an agent can tell what this tool is for.

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 trigger conditions: 'Call before a surprise buy or when the user says «правила трат», «политика», «что можно покупать», «на удачу».' It also provides routing guidance ('follow it before search_products'), caveats for create_purchase, sessionId retry behavior, and explicit prohibitions. This leaves little ambiguity about when and how to use the tool.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context: never to begin_agent_link again, never to ask owner to edit connector settings, never to web-search, and how to handle sessionId retry. These go beyond the annotations and guide the agent's behavior in observed situations.

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 and dense, but every sentence carries actionable information: purpose, exclusions, special cases, triggers, and authentication notes. It is front-loaded with the core purpose and then expands into usage nuances. While not brief, it avoids fluff and structures information logically, though readability could benefit from bullet points.

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 that returns a rich set of preference data and has many sibling tools, the description covers everything an agent needs: return contents, when to call vs alternatives, category-specific instructions, sessionId handling, and explicit don'ts. There is no output schema, but the description lists what is returned. It is complete enough to invoke correctly in all contexts described.

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% (both parameters have descriptions), but the tool description enriches semantics further: it lists all valid category keys, emphasizes that category=sport is mandatory for sport-related buying flows, and explains that sessionId must be reused from begin_agent_link/poll_agent_link and never invented. This value is not in 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 states a specific verb ('Get') with a precise resource ('user's category preferences') and enumerates the returned fields (fat %, brands, sizes, pets, sport macros, schema, learned signals, onboardingPurposes). It also lists the categories and explicitly differentiates from siblings like list_purchases and search_products by stating when each is appropriate.

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?

Extremely detailed usage guidance: it specifies exactly when to call (before search_products only when owner asked to buy/look in AgentPay), when not to call (idle advice), special handling for sport categories, triggers like 'мой бренд' and 'заполни предпочтения', and when to substitute list_purchases for phrases like 'как обычно'. It even covers retry logic with sessionId.

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?

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context beyond that: the hard allowlist constraint, testMode affecting which stores appear, the special return fields for merchant invite links, and retry rules using sessionId. This is rich, actionable behavioral detail.

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 primary purpose, followed by trigger conditions, testMode behavior, and auth retry rules. It is longer than minimal but every sentence carries operational instructions; a few repetitive 'Never' directives could be consolidated but overall it is efficiently structured.

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 having no output schema, the description explains what the tool returns (preferredStores + preferredStoreRoutingRu for merchant invite links), how testMode changes results, and how to handle sessionId. Combined with the annotations, this is sufficient for an agent to invoke the tool correctly in all described 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 coverage is 100%, so the parameters are already documented. The description adds meaningful context by explaining when to pass sessionId ('If AGENTPAY_API_KEY required and you already have sessionId from this chat: pass sessionId and retry') and by noting that need is optional and that peek_stores may be preferable for a quiet offer.

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 identifies the tool as 'List stores on this agent's allowlist', using a specific verb and resource. It differentiates itself from siblings by explicitly stating it is not a search tool and directing to peek_stores for 'найди'/'сравни'/'подбери'.

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 explicitly says when NOT to use it, instead calling peek_stores first. It also includes precise instructions about sessionId handling and testMode behavior, leaving no ambiguity about invocation context.

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?

Beyond the read-only annotations, the description discloses output shape ('Returns last plus purchases[]'), test-mode behavior with gray test coins, the usePastPurchases edge case, authentication retry logic with sessionId, and explicit prohibitions around begin_agent_link and connector settings. This substantially exceeds what annotations alone provide.

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 and front-loaded with purpose and trigger phrases before diving into workflow and constraints. Most sentences earn their place, though the negative instructions overlap somewhat ('Never begin_agent_link again', 'Never ask the owner to edit connector settings or reconnect', 'Never web-search') and could be trimmed without losing meaning.

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, the description gives a minimal return outline ('last plus purchases[]') and enough workflow context to proceed. It also covers test mode, empty-history edge case, and authentication retry. A more detailed return schema would make it fully complete, but the description handles the major gaps.

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 input schema already documents limit, storeId, category, and sessionId fully. The description adds little parameter-specific meaning beyond what the schema says; the mention of sessionId mostly repeats the schema. It also references usePastPurchases, which is not a parameter in the input schema, creating slight ambiguity.

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 verb-resource pair: 'List the owner's recent AgentPay purchases (bought statuses only) with line items.' It clearly distinguishes the tool from status-lookup and product-search siblings by emphasizing 'bought statuses only' and 'line items'. The trigger phrases further reinforce its scope.

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 trigger phrases and the 'wants to reorder' condition, plus a concrete workflow: use last.items, then search_products/get_product, then create_purchase. It also provides when-not-to-do guidance such as 'Do not invent a past basket' and 'If usePastPurchases is false, history is empty.' It does not explicitly name a sibling for one-off purchase-status checks, so it stops short of a 5.

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?

Annotations already mark it read-only and non-destructive, and the description adds useful behavior beyond that: it is a one-call quiet peek, its output is a single sayToUserRu sentence, it must not enumerate SKUs/prices/catalog, and it has specific auth/retry behavior around AGENTPAY_API_KEY and sessionId. This goes well beyond the annotations and clarifies the tool's operational side effects.

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 purposefully so; it front-loads the core rule ('Quiet first hop. Call ONCE...') before guardrails. Some clauses are imperative instruction rather than pure description, and the list of prohibitions is long, but each item earns its place by constraining an otherwise under-specified agent call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still tells the agent what to do with the result (speak the one sayToUserRu sentence, avoid listing SKUs/prices/catalog) and how to handle failure or missing auth. Given the tool's simple role and the rich schema for its parameters, nothing essential 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%, with need and sessionId already documented including examples in the schema. The tool description only repeats the need parameter ('Pass need') with examples already present in the schema, so it adds little beyond the structured definition; baseline 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 names a concrete action ('Quiet first hop', 'Call ONCE when shopping-adjacent'), states exactly what it returns ('matched stores + sayToUserRu'), and distinguishes itself from search_products by forbidding that call until the owner agrees. It is specific about the kind of resource (stores) and the shopper-intent triggers.

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: explicit shopping triggers, explicit never-use cases (advice, rumination, hypotheticals), and the routing rule to stay chat-only without AgentPay tools. It also gives failure and retry behavior (unmatched, missing API key with existing sessionId) and states not to call search_products until consent.

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?

The description discloses the polling behavior, the stable token nature, and the follow-up action of setting Authorization and calling verify_connection. It also states that no API key is required, which is critical for the agent. Annotations are minimal (readOnlyHint) and the description adds substantial behavioral context without contradicting them.

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 paragraph that is information-dense but still efficient. Every sentence contributes actionable guidance, from the polling condition to the post-approval steps and warnings. It could be slightly more concise, but the structure is logical and front-loads the core 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?

For a simple tool with one parameter and no output schema, the description covers the full lifecycle: how to initiate, what to expect, how to proceed on approval, and common pitfalls. It is complete enough for an agent to execute the polling flow correctly without additional context.

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 a description, so the baseline is 3. The description reinforces its origin and emphasizes the stability for re-polling, adding semantic value about how to use the parameter. It does not fully compensate for any missing details, but the coverage is high and the added context is meaningful.

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: polling AgentPay browser connect until the owner clicks 'Разрешить'. It specifies the resource and the condition for completion, and references the sibling begin_agent_link to set context. This differentiates it from related tools like verify_connection, which is called afterward.

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 instructions: pass sessionId from begin_agent_link, re-poll the same sessionId if needed, and call verify_connection on approval. It also provides exclusions ('never invent keys', 'never ask owner to paste ap_'), which are clear negative guidance. This fully informs when and how to use the tool.

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 all annotations false/neutral, the description carries the full burden and delivers: it reveals return fields (choiceSetId + pageUrl + catalogSearchScopeRu), explains the .su vs .shop URL distinction and VPN context, requires verbatim sayToUserRu, and details auth handling ('pass sessionId and retry', 'Never begin_agent_link again'). These are behavioral traits not visible in schema or 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 front-loaded with the core purpose and mandatory trigger, and every sentence carries operational weight with no fluff. However, it is a single dense paragraph with many clauses and prohibitions; bullet points or clearer breaks would improve scannability. Slightly overlong but not wasteful.

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?

There is no output schema, so the description needed to cover return values and did so. It also covers trigger conditions, bundle-mode construction, store-scoping constraints, URL sharing, auth fallback, and cross-tool sequencing with create_purchase and get_choice_status. For a tool with this complexity, the description is remarkably 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 80%, so the baseline is 3, but the description substantially enriches parameter meaning. It explains how to use wants for bundles ('wants[{q}] for EVERY ingredient in one call'), when canRenderImages should be false (ChatGPT/Grok), and when to pass sessionId ('if AGENTPAY_API_KEY required and you already have sessionId'). This goes far beyond the schema's minimal 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 verb+resource: 'Create a comparison page (choice board, 2–4 options with pros/cons).' It clearly distinguishes this tool from siblings by tying it to search_products and clarifyHint triggers, and by describing the output as a page instead of a purchase or search result.

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 guidance is explicit and comprehensive: 'MANDATORY when search_products returns 2+ similar hits or clarifyHint.action is present_choices — call immediately' and 'For a basket/recipe: pass kind=bundles...' It also gives exclusions, e.g., 'Do NOT create_purchase until get_choice_status shows chosen' and 'NEVER substitute a markdown table for this page.'

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?

Annotations provide no useful safety profile here, so the description carries the burden. It discloses important behavioral traits: external confirmation is required, the cabinet/Telegram is the source of truth, and a sessionId should be passed and retried if AGENTPAY_API_KEY is required. It does not describe the full side effect lifecycle or what happens after confirmation, but the behavioral context is substantial.

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 operational value: what to do, when to do it, how to treat chat responses, how to handle sessionId, and what to never do. The most important action is front-loaded, and the guardrails are concise rather than padded.

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 and no informative annotations, so the description must explain the full call context. It covers triggers, sessionId handling, and source-of-truth behavior. However, it does not describe what the response will be, how to interpret the confirmation outcome, or what to do when no sessionId is available and no API key is in place. Important edge-case context 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 description coverage is only 25%, so the description must compensate. It does clarify sessionId usage and the retry logic, but the meaning and expected format of the required 'message' parameter and the optional 'amount' parameter are left implicit. The description mentions approval contexts like spend and freeze, but does not explain how to populate the message or form the amount. This is insufficient for a low-coverage 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 action: ask the human to confirm in AgentPay web or Telegram. It further specifies when it is appropriate: when the user must approve a spend, freeze, or missing delivery data, and even gives trigger phrases. This distinguishes it from the sibling tools, such as begin_agent_link, by explicitly warning not to call begin_agent_link again.

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 conditions: approval of spend, freeze, or missing delivery data. It also provides when-not-to-use guidance: do not treat chat 'ok' as payment approval, never begin_agent_link again, never ask the owner to edit connector settings, and never web-search. This is strong routing and exclusion 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?

The description reveals many non-obvious behaviors: the server parses the messy text, optional fields override parsing, missing parts must not be invented, waiting orders resume automatically, and the success response should be relayed via sayToUserRu. It also gives authentication retry behavior around sessionId. No contradiction with 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 dense but every sentence earns its place: trigger, input strategy, parsing behavior, success action, auth handling, and explicit guardrails. It is front-loaded with the core purpose and call conditions.

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 14 params and no output schema, the description covers when to call, what to pass, what happens server-side, what to do after success, and how to recover from auth errors. Nothing essential for correct 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?

With only 21% schema coverage, the description carries substantial parameter meaning: it explains that text is the full raw phrase, that the server splits it into fields, and that structured fields override the parse. It does not individually detail all 14 params, but the field names are mostly self-explanatory and the main text-passing semantic is clear.

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 verb and resource: 'Save the owner's home address into the AgentPay cabinet, parsed into courier fields.' This clearly identifies what the tool does and distinguishes it from read-oriented siblings like get_delivery_address.

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 trigger conditions are given: specific Russian phrases, dictated address components, and the post-NEED_USER_DATA case. It also provides strong exclusions: 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds rich behavioral context: demo-catalog behavior without owner auth, server clamping limit to 8, preferredStoreRoutingRu/catalogSearchScopeRu store routing, clarifyHint/quietHint semantics, basket/recipe behavior, and authentication via sessionId. It also discloses the data is 'not stale training data' and warns against memory quotes.

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 and front-loaded with the core purpose, but it is very long and covers many edge-case behaviors (clamping, routing, basket/recipe, sportpit preconditions, negative instructions). Every sentence earns its place, yet the sheer volume makes it harder to parse. It is structured as a block of rules rather than clearly separated sections, so a 3 is appropriate.

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 search tool with 8 parameters, no output schema, and 25 siblings, the description covers nearly everything an agent needs: when to call it, when not to, what the response includes, how to route based on preferredStoreRoutingRu, how to handle clarifyHint, sessionId passage, and prohibitions. The lack of an output schema is offset because the description enumerates the returned fields and their meaning.

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, but the description adds substantial value beyond the schema: it clarifies q/text aliases are product-only strings (not addresses), explains limit clamping without owner auth (do not retry), and details sessionId usage with begin_agent_link/connector scenarios. The description also tells the agent to prefer q over aliases and how to interpret the returned fields.

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 specific verb and resource: 'Search products in allowlisted AgentPay stores,' and differentiates itself from siblings by naming when NOT to use it (e.g., don't search for idioms like 'как обычно' — use list_purchases). It clearly identifies its scope (demo catalog vs owner's list) and return payload (ProductCard fields).

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 lists trigger phrases («актуальная цена», «есть в наличии», «сколько стоит», after «купи», «закажи», etc.), says when to call alternatives (get_product, list_purchases, peek_stores), and provides precondition logic (call begin_agent_link before a real buy, get_user_preferences for sportpit). It also gives exclusions: never web-search, never quote price from memory, never dump results.

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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It discloses side effects for both enabled and disabled states, the sessionId retry behavior, and several hard prohibitions around connector settings and web searches, going well beyond what annotations could convey.

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 front-loaded: the core toggle action and trigger conditions come first, followed by behavioral rules. Every sentence carries an operational instruction; nothing is filler, and the length is justified by the tool's auth and policy 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 state-changing policy tool with no output schema, the description is remarkably complete: it covers exact invocation triggers, behavioral effects, auth handling, alternatives, and explicit non-actions. An agent has enough context to call it correctly and avoid dangerous sibling operations.

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 a small but meaningful extra: if AGENTPAY_API_KEY is required and a sessionId exists, pass it and retry, which is contextual behavior not present in the schema. It also reinforces what enabled=true/false means, though much of that repeats the schema 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 verb and resource: 'Turn AgentPay test mode on or off.' It clearly scopes the tool as 'the only policy setting the agent may change' and differentiates it from siblings like save_delivery_address, making its purpose unmistakable.

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 lists trigger phrases, the post-top-up scenario, and exclusions such as 'Never begin_agent_link again' and 'Never web-search.' It also names save_delivery_address as the correct tool for home address, giving the agent concrete 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 only default false annotations, the description carries the behavioral burden and does it well: it discloses persistence ('Persist structured data only'), confirmation constraints ('Never invent fields the owner did not confirm'), domain limits ('Sport prefs are for product picking, not medical advice'), and auth/retry behavior ('pass sessionId and retry. Never begin_agent_link again').

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 definition is long but front-loaded with purpose and triggers, and most imperatives carry real guardrail value. A few items ('Never web-search') feel tangential, and the auth/retry advice could be tighter, but overall the length is justified by the tool's pitfalls.

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 complexity (free-form data, consent prerequisite, auth retry), the description covers most operational needs: when to call, consent, structured-data-only, and session retry. The main gap is that data object shape and category enumerations are left to inference from examples; no output schema is needed for a persistence action.

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 33%, so the description must compensate. It does partly: examples like 'вес 80 кг' and 'Never invent fields' give semantic hints for data, and category=sport is called out. But it never defines the expected keys/values inside data or the full set of category values, leaving essential structure 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?

Description starts with a specific verb+resource: 'Update stored preferences for a category' and immediately gives concrete trigger phrases ('всегда 2.5%', 'не покупай Whiskas'). It also draws a boundary from sibling write tools by saying 'Do not use for one-off orders', so the agent can distinguish it from purchase creation.

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?

States explicit when-to-use conditions: after a lasting rule or the onboarding phrase 'Заполни предпочтения AgentPay', and 'After a clarify answer that should stick'. It gives a when-not-to-use instruction ('Do not use for one-off orders') and a prerequisite for category=sport (owner must have accepted sport prefs consent).

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?

The annotations are minimal, so the description carries the behavioral burden. It discloses authentication requirements (browser grant, VPN/non-VPN URLs), retrying with sessionId, the testMode messaging rule, and critical constraints like not inventing a code and not spending until granted. This goes well beyond the structured 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 a dense, unstructured wall of imperative instructions with mixed languages and abbreviated internal terms ('ap_', 'sayToUserRu'). It is front-loaded with the main purpose, but the many prohibitions and conditional branches become hard to parse, and some instructions appear contradictory on first read ('call begin_agent_link first' vs 'Never begin_agent_link again').

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 highly conditional tool with no output schema, the description covers many branches and restrictions well. However, it never states what the tool returns on success or failure or how the agent recognizes success beyond the phrase 'After success'. Given the complexity and missing output schema, that is a significant gap.

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 useful parameter-selection context beyond the schema: the pairing code is optional, and sessionId should be passed when AGENTPAY_API_KEY is required and a sessionId already exists from the chat.

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 verb+resource ('Finish AgentPay connect') and immediately gives the trigger conditions: after browser approval, when the user says «проверь MCP», or after poll_agent_link returned apiKey. This clearly distinguishes it from the sibling tools begin_agent_link and poll_agent_link.

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 states when to call the tool, when to call begin_agent_link instead, and what to do in branch conditions like NEED_BROWSER_GRANT and AGENTPAY_API_KEY required. It also gives exclusions and prohibitions, such as never asking the owner to edit connector settings and never beginning AgentPay link again after the key is installed.

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