AgentPay

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

Annotations declare readOnlyHint: false, which the description honors by describing a state-changing flow starter. The description adds value beyond the annotations by disclosing that no API key is required and by giving hard constraints: 'Never invent keys', 'Never ask the owner to paste ap_ from the cabinet'. It does not contradict any annotation. Minor gap: it doesn't state what the response payload contains beyond openUrl.

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, exclusions, parameter guidance, and critical prohibitions are all relevant. It is front-loaded with the purpose before the constraints. Slightly verbose with the repeated 'Never' constraints, but each carries distinct behavioral weight.

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 flow-starter with a single fully-documented parameter and no output schema, the description covers the essential behavioral contract: the preconditions, the follow-up step (poll_agent_link), the openUrl action, and the prohibitions. It relies on the schema for the client enum. It could more explicitly describe the return shape, but the openUrl reference covers the key output an agent needs to act on.

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 the schema already documents the client parameter thoroughly, including allowed values and the warning against inventing a different brand. The description restates the client enum but adds no new meaning beyond the schema, so the baseline 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 names a specific verb (start) and resource (AgentPay browser connect), and explicitly scopes it: 'only when a personal tool needs the owner's data' while clarifying that MCP setup itself needs no authorization. This clearly differentiates it from sibling auth tools like start_dixy_call_auth and from setup 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 gives explicit when-to-use guidance ('only when a personal tool needs the owner's data'), a clear when-not-to ('Never start an authorization flow during setup'), and the full invocation sequence (open openUrl so the owner clicks Разрешить, then poll_agent_link). It names the follow-up sibling tool and the required client value format.

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: stock checking and basket-id resolution order, 'bskState del/limit describes UI buttons, not availability', demoScope restrictions, session reuse without SMS upgrades, and the explicit statement 'This does not create an order or pay.' This is rich, non-redundant context that helps the agent avoid harmful or confusing actions.

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 purpose, but it is a long single paragraph with many imperative constraints. Several rules such as 'Never web-search', 'Never ask the owner to edit connector settings or reconnect', and 'Never brute-force ids' are useful but could be more tightly grouped or trimmed. It earns its place for complexity, but the lack of structure hurts readability.

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 no output schema, the description covers a lot: what the tool does, session recovery, demoScope constraints, payment disclaimer, and troubleshooting guidance. It mentions 'Preserve resolvedItems and quantities' and 'share openUrl only if returned', giving hints about the return payload. It is not fully exhaustive about failure modes or exact return format, but it provides enough for an agent 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 description coverage is 88%, so the schema already documents most parameters. The description adds meaningful semantic guidance on top: 'Pass item queries plus optional preferred external catalog ids' maps directly to the items array, and the sessionId handling ('pass sessionId and retry', 'Never invent a sessionId') clarifies the schema's brief description. It also clarifies that id is not for brute-forcing, which is valuable.

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: 'Dixy-only live basket resolver' that 'searches the selected shop's official JSON catalog, checks stock and resolves internal basket ids before adding.' This clearly differentiates it from sibling purchase, payment, and Ozerki tools, and from generic cart tools like prepare_dixy_checkout.

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 strong usage context: it is Dixy-only, should not be used to create orders or pay, and provides explicit actions for session recovery ('Recover dixySessionId through start_dixy_call_auth'). It also gives clear when-not-to instructions ('Never brute-force ids with cart mutations', 'Never begin_agent_link again'). It does not explicitly name alternative sibling tools for comparison, but the boundaries are 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?

Annotations already declare destructiveHint=true, and the description goes well beyond that by disclosing session requirements, refusal behavior ('refuse and start browser connect'), non-debit review mode, failure recovery JSON, and response fields (paid + payment.status). It also lists explicit never-do actions and authentication handling, providing deep behavioral context 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 single dense paragraph with many clauses, conditionals, and prohibitions, which makes it hard to scan. While most sentences carry important information, the lack of formatting, bullets, or separate sections hurts readability and quick comprehension. It is more exhaustive than 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?

For a complex mutation tool with 10 parameters and no output schema, the description covers extensive ground: session flow, test mode, lucky purchases, clarify gate, review mode, failure recovery, and response fields. Yet it omits detailed semantics for core parameters like store_id, items, idempotency_key, and explanation, and does not specify the full success response shape, leaving it just short of fully 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 description coverage is only 40%, so the description must compensate. It adds meaning to lucky, sessionId, choice_set_id, and clarification, and explains SKU selection in lucky mode. However, it does not elaborate on store_id, amount, idempotency_key, items, or explanation, leaving some parameters to the sparse schema. Partial compensation for low coverage earns a 3.

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 'Propose or place an order in an allowlisted store using AgentPay coins', providing a specific verb, resource, and payment mechanism. This distinguishes it from sibling tools like create_topup_intent or prepare_dixy_checkout. The added detail about session requirements and review mode reinforces the tool's core purpose without ambiguity.

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: prerequisites (begin_agent_link/poll_agent_link), conditional flows for testMode, lucky purchases, clarifyHint, and review mode, plus clear prohibitions (never begin_agent_link again, never ask the owner to edit settings). It even references sibling tools like present_choices when explaining the clarify gate, leaving little room for incorrect invocation.

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 already mark the tool readOnly and non-destructive, and the description adds substantial behavioral context: it enumerates return fields, prohibits substituting nearby pharmacies for exactPharmacy queries, requires explicit stock-risk warnings, explains two-stage deliveryPreview reporting, and specifies that all listed brands are valid partner pickup points. It also discloses the NEED_PICKUP_LANDMARK behavior and the canPromiseFinalDelivery guardrail, going far beyond what annotations 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 front-loaded with purpose and trigger conditions, and nearly every sentence carries a useful rule. However, it is a dense wall of Always/Never directives without sectioning or formatting, so it is less crisp than ideal. The length is largely justified by the tool's complexity, but the structure could be improved.

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 must carry return-value and conditional-behavior information; it does, listing fields like distanceBasis, nearbyIncompleteOptions, missingItems, inStock, lowStockItems, distanceAssessment, and deliveryPreview. It also covers failure cases (matched=false, NEED_PICKUP_LANDMARK), authentication fallback via sessionId, stock warning thresholds, and the required handoff step, making the tool callable without 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?

With schema description coverage at 63%, the description carries meaningful parameter burden. It explains why items should include product names ('so missingItems are human-readable'), what near must contain ('at least city + metro/street/district' with an example), when exactPharmacy should be true, and how lat/lon or sessionId can be used. This adds real semantic value beyond the raw schema 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 opens with a specific role: 'Ozerki pickup-point resolver for multi-brand Ozerki-network pharmacies.' It immediately states the exact trigger ('MUST be called before handoff when the owner asks for pickup near a place or has no exact delivery address') and distinguishes the tool from the handoff step by saying the chosen storeId is passed to prepare_ozerki_handoff. An agent can tell exactly 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 very explicit when-to-use conditions and important exclusions: a city name alone selects only a region and must not be treated as a location; if neither landmark nor coordinates are known, ask one short question; exact-pharmacy questions require exactPharmacy=true and must not substitute another branch. It does not, however, explicitly name sibling tools as alternatives (e.g., search_products) when deciding between catalog search and pickup resolution, so it falls just short of perfect 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 declare readOnlyHint, but the description adds substantial behavioral context: it requires a partner customer link with orders:read, lists what data is and isn't returned (e.g., no address/phone/email), and describes the sessionId retry flow. It also aligns with openWorldHint=false by prohibiting web searches.

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, trigger conditions, authorization requirements, return scope, follow-up workflow, and error handling. It is front-loaded with the core purpose and usage.

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 tells the agent what to expect in the response (normalized order IDs, dates, item names/SKUs/categories/brands, frequency signals), what is excluded, prerequisites, and how to recover when sessionId is needed. Nothing essential is missing for correct invocation.

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 doesn't materially expand parameter meaning beyond the schema; it only hints at sessionId retry behavior already covered in the sessionId parameter 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 uses a specific verb and resource: 'Get the owner's on-demand purchase history from a linked enterprise partner account.' It clearly identifies the data scope (purchase history, normalized items, frequency signals) and distinguishes this read tool from sibling purchase/search 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?

It explicitly states when to call: 'when the owner asks to use past orders/history/loyalty from a specific partner, or before a repeat/personalized order in an enterprise store.' It also gives workflow guidance: use the context for product choice, then verify price/stock with search_products or get_product before create_purchase.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds valuable behavioral context: it returns merchant-synced price, inStock, imageUrls, sku, description, catalogSyncedAt, priceSource (feed|live), always includes attributed url, trackedUrl, and pick. It also discloses the auth behavior (sessionId required for live data, never invent sessionId) and the rule about using trackedUrl instead of url. This goes beyond the annotations 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 dense but every sentence earns its place. It front-loads the core purpose, then covers auth, return fields, link usage, and triggers. It is longer than average, but the length is justified by the auth complexity and the critical trackedUrl rule. A slight trim could improve scannability, but the structure is logical: purpose → auth → returns → usage rules → triggers.

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 product lookup with no output schema, the description covers everything an agent needs: what it returns, when to call it, how to handle auth, what to do with the returned trackedUrl, and trigger phrases. The absence of an output schema is compensated by the explicit return field list. The description is complete for the tool's 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 50%: product_id and store_id have no descriptions in the schema, while q and sessionId do. The description compensates by explaining product_id + store_id as the composite key for a ProductCard, and explains q as 'the owner's search phrase so pick explains this sku against that query.' It also explains sessionId's role in the agent-link auth flow. The description adds meaning beyond the schema for the undocumented parameters, though it doesn't give format details for product_id/store_id.

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: 'Get one ProductCard by product_id + store_id from an allowlisted store.' It clearly distinguishes this from sibling search_products (which searches) and list_allowed_stores (which lists stores). The scope is precise: one product, identified by two keys, from an allowlisted store.

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 to confirm price and stock before create_purchase, never quote price from memory. It also gives when-not-to-use guidance: never web-search, never begin_agent_link again if sessionId already exists, never ask the owner to edit connector settings. It names the alternative flow (begin_agent_link → poll_agent_link) for live data. 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?

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 mark the tool as read-only, and the description reinforces this with 'Never change limits, freeze, auto-topup, or allowlist.' It also discloses observable behavior: 'On every error read recovery: say userMessageRu, open openUrl in the browser,' plus authentication retry rules and the test-mode exception. This adds substantial context beyond 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 dense and front-loaded with purpose and triggers, and nearly every sentence carries operational value. However, it is a long run-on block of directives without paragraph breaks or list formatting, which slightly reduces scannability.

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 one optional parameter and no output schema, the description is complete: it explains when to call, what the catalog contains, how to handle errors, authentication conditions, and explicit safety boundaries. No critical information an agent needs 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 input schema already documents sessionId thoroughly at 100% coverage. The description adds conditional value by saying 'If AGENTPAY_API_KEY required and you already have sessionId from this chat: pass sessionId and retry' and 'Never invent a sessionId,' which clarifies when and how to use the parameter in practice.

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 resource: 'Full catalog of AgentPay failures with RU copy, cabinet deep links, and recovery.openUrl.' It clearly identifies what the tool returns and gives concrete trigger phrases, making it distinguishable from sibling tools like get_faq or get_payment_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 explicitly states when to call ('Call when something failed', 'before explaining a 4xx') and provides trigger keywords. It includes strong when-not guidance ('Never change limits... Never begin_agent_link again. Never web-search.'), though it does not name alternative sibling tools for fallback cases.

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 mark readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: authentication requirements (sessionId handling, never invent, retry logic), prohibitions (never begin_agent_link again, never ask to edit connector settings), and domain-specific logic (clothingGender interpretation, BMR/TDEE calculation). 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 long and dense, but every section adds necessary guidance for a complex tool with many edge cases. It is front-loaded with purpose and primary usage, then details. While it could be trimmed slightly, the structure is logical and justified by 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?

Given the tool's complexity, absence of an output schema, and minimal annotations, the description covers all necessary aspects: triggers, exclusions, authentication, category-specific logic, and actions like asking once then updating preferences. No critical information 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?

The schema covers both parameters fully (100% coverage), but the description enriches semantics: it explains how 'category' values are used (dairy, apparel, sport, etc.) and when to pass 'sessionId' (when connector lacks Authorization Bearer), plus retry conditions. This goes well beyond 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 clearly states the tool fetches user category preferences, schema, learned signals, and onboarding purposes, with a specific verb ('get') and resource. It distinguishes itself from siblings by specifying when to call it before search_products and contrasts with update_preference and list_purchases.

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 conditions (e.g., 'before search_products only when the owner already asked to buy or to look in AgentPay'), when-not-to (idle advice), and alternatives (list_purchases for 'как обычно', 'то же самое', 'прошлый раз'). Also includes detailed rules for sportpit and apparel scenarios.

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 set readOnlyHint=true, and the description adds substantial non-obvious behavior: enforced shopping boundaries, conditional return of preferredStores + preferredStoreRoutingRu, testMode-dependent store visibility, and retry logic for AGENTPAY_API_KEY with sessionId. There is no contradiction with the readOnly annotation.

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 sentence carries a real constraint or trigger, so there is no filler. However, it is dense and mixes policy rules, invocation triggers, and auth retry guidance into one block, making it more of a rulebook than a tightly scoped tool 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 tool with no output schema, the description covers the return shape conditionally, the exact user phrases that trigger it, demo/test-mode handling, and session auth nuances. Nothing critical appears missing for an agent to invoke it correctly in 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?

Schema coverage is 100%, so the baseline is 3. The description adds operational meaning beyond the schema: demoOnly is tied to discussing only returned demo stores and avoiding Dixy/Ozerki, and sessionId is tied to retrying without re-running begin_agent_link. This is useful but not a full redefinition of the parameters.

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?

Opens with a specific verb-resource pairing ('List stores on this agent's allowlist') and immediately distinguishes itself from peek_stores and search_products. The allowlist concept plus the explicit 'agent MUST shop only here' makes the tool's role 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?

Gives explicit call triggers («магазин», «где можно потратить», «спецмагазин», «тестовый магазин»), conditional demoOnly behavior, and a hard routing rule: for «найди» / «сравни» / «подбери» call peek_stores first, not this tool. It also clarifies testMode interactions and when to pass 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?

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?

Annotations are minimal (no readOnlyHint, destructiveHint false). The description compensates by disclosing that repeating the poll is safe and does not trigger another phone call, and by setting explicit prohibitions (never ask for phone number, never request separate platform authorization, never begin_agent_link again). It also explains the sessionId authentication behavior. No contradiction with annotations; the safety guarantee aligns with destructiveHint false.

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 but every sentence carries crucial operational guidance: aliases, safety, retry conditions, and prohibitions. It is front-loaded with the core action and then expands into necessary context. While not terse, the density of actionable instructions justifies the length; a slightly tighter structure could remove redundancy (e.g., 'Never' list repeated), but it remains effective.

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 4 parameters, no output schema, and the need to coordinate with other tools, the description covers all necessary operational context: which parameter to prefer, how to handle aliases, what to do on success (pass partner_session_id), when to retry, and what to avoid. An agent can invoke this correctly without additional information.

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 all parameters have descriptions. The tool description adds significant value by clarifying that attemptId and sessionId are aliases for linkSessionId, by explaining the preference for linkSessionId, and by detailing when sessionId should be passed (when no Authorization Bearer). This goes well beyond the schema's static 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?

States a specific verb ('Poll') and a specific resource ('secure Dixy sign-in link') with clear context ('after the owner completes it in the browser'). It distinguishes itself from the sibling poll_agent_link by the Dixy-specific scope and references to start_dixy_call_auth. 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?

Explicitly states the preferred parameter (linkSessionId from start_dixy_call_auth) and acknowledges aliases. Provides clear conditions: when to retry (if AGENTPAY_API_KEY required and sessionId exists), when not to act (never begin_agent_link again, never ask for phone number or separate authorization), and post-conditions (pass partner_session_id as dixySessionId). This is far beyond typical 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?

Annotations only state readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description goes far beyond these: it discloses side effects ('This does not create a Dixy order and does not pay'), mutation of the cart, the 1000 RUB minimum-order behavior, the DIXY_CART_NOT_EMPTY clearing flow, reauth steps, anti-bot handling, and communication constraints (never ask for phone number, don't mention cookies). This is rich behavioral disclosure well beyond what annotations 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 long and dense, but it front-loads the core purpose and prerequisite before moving to conditional scenarios. Each sentence carries operational meaning, from minimum-order handling to error recovery to security constraints. It could be more scannable with lists or subheadings, but for a tool with this many edge cases the length is mostly earned.

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, yet the description explicitly names the return fields (totals, delivery fee, kg/pcs quantities, minimum-order signals, canSubmitOrder). It also covers all the major runtime scenarios an agent could hit: minimum order, cart not empty, reauth, anti-bot, missing API key, and session handling. For a complex checkout tool with no output schema, this is complete enough to call 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 parameter descriptions cover about 57% of parameters, so the description adds value by explaining operational semantics: 'kg/pcs quantities' maps to item quantity types, 'clearExistingCart:true only after explicit approval' clarifies a boolean parameter's triggering condition, and 'sessionId from this chat' clarifies session reuse. It doesn't systematically redocument every parameter, but the overlap is partially compensated by the schema's own descriptions plus these contextual additions.

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 'Dixy-only checkout preparation', naming a specific verb ('prepare'), a specific resource ('Dixy checkout'), and a scope that distinguishes it from Ozerki and other checkout flows. It then states concrete responsibilities: setting delivery store/address, adding/updating cart lines, and returning a basket preview with totals, delivery fee, quantities, minimum-order signals, and canSubmitOrder. This clearly differentiates it from siblings like check_dixy_live_cart and prepare_ozerki_handoff.

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 explicitly gated: 'Call only after check_dixy_live_cart and after the owner has provided/approved delivery address details.' It also routes error handling to specific siblings ('call start_dixy_call_auth(forceNew:true) only if the recovery link is absent') and warns against incorrect flows ('Never begin_agent_link again', 'Never ask the owner to edit connector settings or reconnect'). This is clear when-to-use and when-not-to-use guidance with named 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?

Annotations are minimal (readOnlyHint=false, openWorldHint=false, destructiveHint=false), so the description carries the full burden. It discloses side effects (extCart merges with existing basket), limitations (links don't persist store selection, Ozerki may ask to confirm address again), and what is not done (no final order, no payment). It also handles authentication edge cases (sessionId retry) and error paths (canHandoff=false). 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 long (~300 words) but each sentence carries critical information. It is front-loaded with the core purpose and then details conditions, fallbacks, and prohibitions. While it could be tightened slightly, the density and organization justify the length for such 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?

This tool has no output schema, so the description must cover return values and error handling. It mentions handoffUrl, fallbackUrl, canHandoff, recoveryOptions, and agentNextRu, plus behavior on failure. It also addresses authentication, pickup/delivery branching, and explicit don'ts. For a tool with nested address objects and conditional requirements, 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 only 50% per signal, but the description explicitly explains the critical parameters: storeId is mandatory for pickup and must come from owner's choice; flat is required for delivery with '-' fallback; items require real Ozerki goodsId; regionId default is 14; sessionId usage and authentication context. This goes far beyond schema descriptions, adding essential context 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 opens with a specific verb and resource: 'Ozerki-only availability preflight and tracked basket handoff.' It then explains exactly what the tool does (selects pharmacy, checks items, returns links) and what it does NOT do (create order, pay). It clearly distinguishes from siblings like get_ozerki_pickup_options (prerequisite) and list_allowed_stores (explicitly says not to use it).

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 states when to call ('only after fulfillment is agreed'), gives explicit preconditions for pickup (call get_ozerki_pickup_options first, obtain choice, pass storeId) and for delivery (flat mandatory). It names alternatives and conditions (e.g., use recoveryOptions and agentNextRu on failure, never call list_allowed_stores, never make the owner rebuild basket). This is comprehensive and 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?

Annotations are sparse (readOnlyHint=false, openWorldHint=false, destructiveHint=false), so the description carries the burden. It discloses important behaviors beyond the schema: server-side filters by category-matched stores, return of choiceSetId/pageUrl/catalogSearchScopeRu, always sharing pageUrl in chat, and not hand-picking SKUs from other stores. This gives the agent a realistic model of what happens when invoking the tool.

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 not padded: each sentence encodes a different operational rule or exclusion. The core purpose and mandatory trigger are front-loaded, and the later sentences cover safety and fallback behaviors. It could be better structured as bullets, but the content earns its place.

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 has no output schema and significant interaction complexity, the description is remarkably complete. It covers the return values, trigger conditions, parameter usage, downstream gating to create_purchase, sessionId retry handling, and forbidden alternatives. An agent has enough context to call the tool correctly and avoid common failure paths.

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. The description adds meaningful parameter semantics beyond the schema: for baskets/recipes pass kind=bundles and wants[{q}] for every ingredient, for apparel pass gendered wants, and pass canRenderImages=false for ChatGPT/Grok. It does not add much beyond the schema for agentIntroRu or sessionId, but the operational specifics it provides are valuable.

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 specific verb and resource: 'Create a comparison page (choice board, 2–4 options with pros/cons)'. It clearly differentiates the tool from siblings by specifying the trigger condition ('MANDATORY when search_products returns 2+ similar hits') and by describing the exact output artifacts. An agent can identify when this tool, rather than search_products or create_purchase, is needed.

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 exhaustively specified: call immediately on clarifyHint.action=present_choices, do not wait for «сравни», pass kind=bundles with wants for every ingredient, and do not create_purchase until get_choice_status shows chosen. It also gives explicit exclusions such as 'NEVER substitute a markdown table' and 'Never begin_agent_link again'. This is the strongest possible guidance 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?

The description adds behavioral context beyond the readOnlyHint and destructiveHint annotations: it confirms no coins are debited and no order is placed. It also discloses the need for sessionId in some cases and the Dixy-specific limitation, all consistent with the annotations. No 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 verbose and includes tangential instructions like 'Never ask the owner to edit connector settings or reconnect' and 'Never web-search,' which are not tool-specific and add noise. While the purpose is front-loaded, the extra directives hurt 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?

It mentions the return fields (amount, storeName, itemSummary, needsConfirmation, reviewOnly) and the workflow sequence, which helps. However, it lacks explanations for key parameters like items and store_id, and does not address error handling or edge cases. Given no output schema, this is a moderate 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 only 29% (2 of 7 parameters have descriptions). The description only adds context for sessionId (pass it and retry if needed) but does not explain items, store_id, lucky, category, or choice_set_id. Given the low coverage, the description should compensate but does not.

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 previews an AgentPay purchase before create_purchase, naming the specific resource and action. It distinguishes itself from create_purchase by stating it does not debit coins or place an order, which prevents confusion with that 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?

Explicitly states when to call it: 'after search_products/get_product and present_choices/clarification, before asking the owner to approve checkout.' It also provides exclusions such as 'Never begin_agent_link again' and 'Never web-search,' giving clear 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?

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 and destructiveHint, but the description adds far more behavioral context: public-demo fallback without auth, preliminary feed availability semantics, progressive Ozerki geography resolution, clarifyHint/quietHint behavior, trackedUrl substitution, and rules about not presenting wrong gender SKUs or reconstructing links. Nothing in the description contradicts the annotations, and the added context substantially reduces surprise for the agent.

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 an extremely long, uninterrupted wall of dense policy without bullets, sections, or paragraph breaks, mixing core tool behavior with global payment and connector prohibitions like 'Never ask for a bank card' and 'Never ask the owner to edit connector settings'. While most content is informative, the lack of structure and inclusion of non-tool-specific global policies make it significantly harder to scan 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?

For a complex search tool with no output schema and many routing nuances, the description is thoroughly complete: it enumerates returned ProductCard fields, explains clarifyHint and quietHint, covers auth and demo fallback, describes basket/recipe handling, and anticipates common owner expressions. An agent has enough context to select, invoke, and interpret this tool correctly in most real 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 already 100%, but the description adds genuinely non-obvious semantics: catalogOverview suppresses the two-name quiet limit, demoOnly excludes live stores such as Dixy/Ozerki, location/regionId follow a progressive Ozerki geography rule, and sessionId must come from begin_agent_link. These meanings are not inferable from parameter names or the schema alone, making the prose description a high-value complement.

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 opening sentence defines a specific verb and resource: 'Search products in allowlisted AgentPay stores'. The description clearly separates this tool from the broader ecosystem by emphasizing catalog search, AgentPay tracking, and merchant feeds, and it names distinct sibling tools it routes to (get_product, get_ozerki_pickup_options, present_choices, list_purchases). This goes far beyond the tool name and makes the resource and scope 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 provides explicit invocation triggers ('актуальная цена', 'есть в наличии', after 'купи', after peek_stores), explicit non-uses ('Never call for thinking/advice', use web search only after MCP/API failure), and alternative tool routing ('как обычно' → list_purchases first, metro/street → get_ozerki_pickup_options). It also gives context-specific policies for Ozerki profile, catalog overview, demo stores, and basket/recipe flows, making usage conditions exceptionally 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?

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?

Annotations are all false (readOnly, openWorld, destructive), so they carry no safety or mutation signal. The description compensates fully: it explains that the tool creates or recovers a session, returns an openUrl that must be shared immediately, requires polling with linkSessionId, and handles AGENTPAY_API_KEY retry logic. It also discloses that the tool takes no phone number and that the phone number never enters chat, which is critical behavioral context. No contradictions 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?

Although long, every sentence earns its place. The description is front-loaded with the purpose and triggers, then flows logically: reuse condition, forceNew condition, openUrl handling, phone avoidance, polling, auth retry, and explicit 'never' instructions. There is no fluff; the density is justified by the auth-flow complexity. It is structured as a procedural guide, which is appropriate for a tool that orchestrates a multi-step interaction.

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 is a session-initialization step in a larger flow, yet the description covers the full lifecycle: when to call, what it returns (openUrl), how to proceed (poll_dixy_call_auth), how to handle auth errors (AGENTPAY_API_KEY with sessionId), and what not to do. With no output schema, the description must explain return usage, and it does. The presence of sibling tools like poll_dixy_call_auth and begin_agent_link is addressed, so an agent can navigate the whole sequence without missing steps.

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%, but the description adds substantial meaning beyond the schema: forceNew is explicitly conditioned on prior server errors (DIXY_REAUTH_REQUIRED or DIXY_WEB_SESSION_REQUIRED), and sessionId is tied to the agent-link flow and the absence of a Bearer token. These are not in the schema and are essential for correct parameter usage. The description elevates the parameters from simple types to actionable rules.

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 ('Create or recover the secure Dixy sign-in') and immediately ties it to concrete triggers: when current prices, budget, availability, cart or checkout are needed. It distinguishes itself from siblings by naming poll_dixy_call_auth as the follow-up and by stating when to use forceNew. The purpose is unambiguous and differentiates this from the many other tools in the sibling list.

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 triggers (prices, budget, availability, cart/checkout) and when-not-to-use guidance: if already linked, reuse it; forceNew only after DIXY_REAUTH_REQUIRED or DIXY_WEB_SESSION_REQUIRED. It also gives negative instructions (never ask for phone in chat, never begin_agent_link again, never edit connector settings). This fully routes the agent through the correct flow and away from pitfalls.

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 say the operation is not read-only and not destructive, but the description adds critical behavioral detail: partial data is merged, unisex must not be set unless explicitly asked, sport prefs need prior consent, structured data must be persisted, and fields must not be invented. It also explains sessionId retry behavior, going well beyond 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 purpose and merge semantics up front, and most sentences carry operational value. Some trailing instructions like 'Never web-search' and 'Never ask the owner to edit connector settings' feel like broader platform rules rather than tool-specific guidance, adding slight bloat.

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 sparse schema and absent output schema, the description does a strong job covering merge semantics, allowed gender values, consent requirements, auth handling, and exclusions. The main missing piece is a complete list of valid category values and any expected response behavior, but the tool is still callable correctly with the provided guidance.

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 documentation only covers sessionId; category and data are minimally typed. The description compensates with concrete semantics like data.clothingGender = male|female|unisex|any, merge behavior, and category-specific consent for sport. However, it does not enumerate all valid category values or fully define the free-form data object, so a small gap remains.

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 clear action and resource: 'Update stored preferences for a category' after a specific trigger. It distinguishes itself from read-only and one-off purchase tools by saying 'Do not use for one-off gift orders.' No tautology; the purpose is explicit and actionable.

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 triggers: lasting user rules, the onboarding phrase, and sticky clarify answers. It also gives when-not-to-use guidance: one-off gift orders. Additional conditions like sport consent and specific rules for unisex make the usage context 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?

Annotations only indicate non-read-only and non-destructive, so the description adds useful behavioral context: browser-grant handling, optional retry with sessionId, testMode messaging, and a 'do not spend until granted' guard. It does not sharply state what persistent state verify_connection changes, but it is not contradictory and adds meaningful 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 most important trigger is front-loaded, but the rest is a dense run-on list of directives with mixed-language scraps like 'Разрешить', 'ap_', and 'recovery.openUrl', plus several prohibitions in one paragraph. It is information-rich but not well structured or 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 the lack of an output schema, the description covers the main branches: when to call, what to do without credentials, browser-grant handling, retry with sessionId, and testMode follow-up. It is slightly incomplete because NEED_BROWSER_GRANT and recovery.openUrl are not defined, but an agent with context from sibling tools can act.

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 the schema already explains code and sessionId, so the baseline is 3. The description earns an extra point by adding operational parameter conditions: pairing code is optional, and sessionId should be passed when AGENTPAY_API_KEY is required and a sessionId already exists in 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 action ('Finish AgentPay connect') and names precise triggers: after poll_agent_link returned apiKey, or when the user says «проверь MCP». It also distinguishes the tool from siblings by explicitly directing the agent to call begin_agent_link first when no ap_ exists and never 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?

It gives explicit when-to-use conditions, names the alternative tool for the no-credentials case, and lists clear never-actions such as do not invent a code, do not ask the owner to edit connector settings, and do not reconnect. This removes ambiguity about routing among the agent-link tools.

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