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

With no annotations, the description carries the full behavioral burden. It discloses that no API key is required, that it returns an openUrl, and that the openUrl must be opened immediately so the owner can approve. It does not mention failure modes or behavior when ap_ already exists, but the prerequisite is stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: the first sentence names the action, the second covers the trigger and prerequisite, the third explains the parameter, and the final sentences give the required follow-up and a prohibition. No filler or redundant restatement.

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 is a one-parameter initiation tool with no output schema and no annotations, yet the description covers the trigger, prerequisite, parameter meaning, expected return value, immediate required action, next step, and user-handling rule. Nothing essential is missing for the agent to execute correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the client parameter with its allowed values, so the baseline is 3. The description adds value by explaining why the parameter matters—'so the browser page knows which host opened the link'—and recaps the exact allowed values, giving the agent purpose beyond the schema text.

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 action—'Start AgentPay browser connect'—and identifies it as the first call in the connection flow, triggered by a concrete user phrase. It is clearly differentiated from sibling tools like poll_agent_link by framing this as the initiating step and explicitly naming the next step.

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 first when the user says «Подключи AgentPay» and you do not yet have ap_.' It also provides follow-up instructions ('Then poll with poll_agent_link') and a clear negative directive ('Never ask the owner to copy ap_ from the cabinet').

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: test-coin spending in testMode, lucky purchase rules, clarification handling, server-attached delivery, idempotency_key requirements, and error recovery ('On error read recovery'). It even states that the server attaches the home address, preventing a wrong assumption.

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 delivers essential rules. It is one long paragraph with many conditional clauses, which could be easier to scan with bullet points, but given the tool's complexity, it stays efficient without 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?

The description covers the full invocation context: required parameters, conditional branches (lucky, clarification, testMode), prohibitions, error handling, and alternatives (skip present_choices). It even points to policy via get_spending_policy and recovery via get_recovery_guide, making it complete for an agent with access to siblings.

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 11%, but the description compensates extensively. It explains the required parameters (idempotency_key, items[], store_id, amount), the meaning of lucky:true, choice_set_id, clarification object, and the instruction to skip present_choices. It adds critical semantics for the trickiest 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?

The description opens with a specific verb and resource: 'Place an order in an allowlisted store using AgentPay coins.' It also gives concrete invocation triggers ('Call when the user clearly wants to buy («купи», «оформи», «потрать»)'') and distinguishes its scope from sibling tools like get_balance or list_allowed_stores by focusing on the purchase action.

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 the tool (user clearly wants to buy) and provides detailed conditionals for testMode, lucky purchases, and clarification needs. It also tells the agent what not to do ('Never change limits/freeze/allowlist', 'Never ask for a bank card') and references sibling tools like get_spending_policy and present_choices to guide the decision flow.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool asks the owner (a request, not a direct action), reuses pending payments, and advises waiting on get_payment_status. This is transparent about its side effects and interactions, though it could mention whether it mutates state or requires specific permissions.

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 three sentences, front-loading the primary purpose and trigger condition. Every sentence adds value: the action, the exclusion (card), and the pending-payment handling. No fluff.

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

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

The description covers the trigger, the payment flow, and interactions with get_payment_status, but it lacks parameter semantics and does not describe the tool's return value (no output schema). For a tool that asks the owner, the agent needs to know what happens next, but this is partially inferred from the sibling tools. It is adequate but not 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 0%, so the description must compensate. However, it does not explain the meaning of amountRub or needCoins, nor their relationship (e.g., exchange rate or required fields). An agent cannot infer how to set these parameters correctly from the description 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 clearly states the action (ask the owner to top up coins), the resource (coins), and the method (via YooKassa or the cabinet). It also specifies the trigger condition (INSUFFICIENT_FUNDS), making it distinct from sibling tools like get_payment_status or create_purchase.

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 ('Call on INSUFFICIENT_FUNDS'), what not to do ('Never take a card in chat'), and provides behavioral rules ('Reuses today's pending payment... do not hammer retries. If get_payment_status is pending, wait.'). This gives clear context and exclusions, guiding the agent on proper 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?

With no annotations, the description carries the full burden and does well: it reveals testMode behavior, the closed-loop nature of coins (not cash/withdrawable), and instructs not to spend if the wallet is frozen. It omits potential error conditions, but the key behavioral constraints are disclosed.

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 triggers, but it becomes crowded with product-answer policies like 'Quote prices as N коинов' and 'do NOT say «тестовые коины» in every product answer,' which are tangential to invoking get_balance. Each sentence has some value, but the structure is less crisp than the best examples.

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-parameter, no-output-schema read tool, the description covers the return fields, when to call it, and important edge cases such as testMode and a frozen wallet. It does not describe errors or what happens if the wallet is unconnected, but the mention of verify_connection supplies the main prerequisite.

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 tool has zero parameters, and the schema fully documents this with an empty properties object and additionalProperties false. The description needs to add no parameter semantics, and the baseline for zero-parameter tools is 4.

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

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

The description clearly states the tool retrieves the agent's AgentPay wallet and lists the returned fields (testMode, testBalance, realBalance), so the verb and resource are specific. It does not explicitly contrast with sibling tools like get_limits or get_spending_policy, but the balance focus is evident from the trigger phrases and return values.

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 provided: it should be called when the user asks about balance/budget in Russian or after verify_connection. However, it does not state when not to use this tool or name alternatives, so it falls slightly short of the highest bar.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states the operation is a poll, implies read-only status checking, and discloses the return payload (status and chosenOptionId). It does not explicitly rule out side effects or describe error cases, but for a simple status-polling tool the disclosed behavior is adequate.

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?

Three short sentences front-load the action and return values, then add workflow guidance. There is no filler; every sentence carries distinct and useful information.

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 single-parameter, no-output-schema tool, the description covers purpose, return values, and call timing. It could add details about what chosenOptionId contains when status is draft, but the current level is sufficient for an agent to invoke the tool correctly in the intended flow.

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 0%, so the description compensates by connecting choice_set_id to present_choices and create_purchase: 'Poll a choice set from present_choices' and 'attach choice_set_id.' This tells the agent the ID refers to a previously presented choice set, which is meaningful beyond the bare parameter name.

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: 'Poll a choice set from present_choices.' It also names the returned fields (status draft|chosen and chosenOptionId), making the tool's function immediately identifiable and distinct from siblings like present_choices and create_purchase.

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 timing is given: 'Call after present_choices when waiting for the owner, or before create_purchase to attach choice_set_id.' This clearly tells an agent when in the workflow to invoke this tool, though it does not spell out exclusions or alternative tools beyond the stated workflow anchors.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the address is split into courier fields, that missing fields should trigger a user inquiry, and adds a strict 'Never invent a street, entrance, or intercom' constraint. It does not specify what happens when no saved address exists (e.g., null vs error), but the mention of missing fields partially covers this.

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?

Three tight sentences: purpose and field list, usage triggers, and follow-up/constraint. Every sentence earns its place and the most important information is front-loaded.

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 parameterless getter with no output schema, the description covers what fields are returned, when to invoke it, what to do if data is incomplete, and a critical safety constraint. The only gap is the absence of explicit behavior when no saved address exists at all, but this is minor given the clear follow-up instruction.

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?

There are zero parameters, so schema coverage is trivially 100% and the baseline is 4. The description's field list relates to the return value rather than parameters, so no additional parameter semantics are needed.

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 ('Get') and a specific resource ('the owner's saved AgentPay home address'), then enumerates the exact output fields. It clearly distinguishes itself from siblings by mentioning create_purchase and save_delivery_address, so an agent can tell it apart without reading schemas.

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: 'before create_purchase' or when the user asks specific Russian phrases. It also provides a clear follow-up path: if fields are missing, ask the owner and use save_delivery_address. This is direct, actionable guidance with no ambiguity.

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

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

With no annotations provided, the description carries the full burden. It discloses the return contents (sayToUserRu, side, contact), instructs the agent not to invent reasons, and warns against hiding which side is involved. It does not explicitly state that the operation is read-only, but 'Look up' and 'returns' strongly imply it.

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 efficient and front-loaded: purpose first, then trigger scenarios, then output and guardrails. The example list is long but earns its place by making routing obvious. No redundant or filler content.

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 description adequately covers what the tool returns and when to use it, and the schema covers the parameters. It does not explicitly address edge cases like 'no FAQ found' or explain the optional storeId in the description, but the overall guidance is sufficient for a straightforward lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds useful examples of what can go into q and clarifies the output, but it does not add significant extra meaning to the parameters beyond the schema, matching the baseline.

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

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

States a clear verb and resource ('Look up AgentPay operational FAQ') and differentiates itself from sibling tools by spelling out concrete trigger scenarios (SKU, photo, search, coins, returns, delivery, MCP connect). The trigger examples make it unmistakable when this tool applies.

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 call conditions: 'Call when the owner asks why...' and lists multiple concrete examples plus Russian phrases. It does not name alternatives or exclusion cases, but the situational guidance is sufficiently clear for an agent to know when to invoke it.

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

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

No annotations are present, so the description carries the behavioral disclosure burden. It clearly states the server enforces limits even if ignored, that they cannot be bypassed, and that raising limits is not possible through this tool. It does not mention return format or pagination, but the key operational constraints are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, information-dense sentences with no filler. The core action and scope are front-loaded, followed by usage triggers, enforcement behavior, and a pointer to the relevant sibling 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?

For a zero-parameter read-only limits getter with no output schema, the description gives the agent enough context to call it correctly: when to call, what it returns conceptually, and what it cannot do. It doesn't detail the response structure, but that is not required 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?

There are zero parameters, so no parameter-level explanation is needed. The schema coverage is 100% by default. The description doesn't need to add anything about inputs; it already focuses on the tool's behavior and use case.

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 ('Get'), a specific resource ('hard spending limits'), and clarifies the scope with concrete limit types (per purchase, daily, weekly, confirmation threshold). It also distinguishes itself from the sibling get_recovery_guide by stating that limits cannot be raised here.

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

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

Provides explicit when-to-use guidance: call before create_purchase when the user mentions 'лимит', 'потолок', or 'сколько можно потратить'. It also tells the agent what not to expect (cannot raise limits) and points to get_recovery_guide as the alternative for changing limits.

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

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

With no annotations provided, the description carries the full burden. It discloses the tool's read-only nature ('Check whether'), the returned fields (paid, payment.status, autoTopup remaining today), and the state-dependent constraint (max 3 auto-topups; do not create another payment). It doesn't explicitly discuss authentication or rate limits, but for this status-check tool the disclosed behavior is sufficient.

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?

Three concise sentences, with the primary purpose front-loaded and no filler. Each sentence adds distinct value: what it checks, when to call it, what it returns, and what action to avoid.

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-parameter, no-output-schema status check, the description is complete. It covers the trigger condition, the returned signals, a business rule (max 3 auto-topups), and a high-level guardrail (do not create another payment). An agent has enough information to invoke and interpret 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?

There are zero parameters, and schema description coverage is 100%, so the schema already fully describes the input surface. The description adds meaningful context by explaining that the tool operates on the 'last' top-up/payment without requiring user input. Baseline of 4 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 ('Check') with a clear resource ('whether the last top-up/payment succeeded') and also names the related trigger create_topup_intent. It clearly distinguishes itself from sibling tools like create_purchase or get_purchase_status by focusing on top-up/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?

The description explicitly states when to call this tool: after create_topup_intent or when the user asks phrases like «оплата прошла», «списали карту». It also provides an exclusionary guideline: if payment is pending or succeeded, do not create another payment. This gives the agent actionable selection criteria.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the data source ('merchant-synced'), the returned fields, and the pick subfields. It also warns about staleness with 'Never quote price from memory,' which is a meaningful behavioral trait.

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 tight and front-loaded with the core action. Every sentence contributes useful information: scope, return fields, q's purpose, and the usage instruction. There is no filler or repetition.

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 low-complexity tool with no output schema, it covers the return values and optional parameter well. It could strengthen completeness by stating error behavior or explicitly pointing to search_products or list_allowed_stores as discovery sources, but those are not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must supply meaning. It explains q as the owner's search phrase and qualifies store_id with 'allowlisted store.' product_id is largely self-explanatory, and the required identifier pair is explicitly named.

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 one ProductCard by product_id + store_id.' It clearly scopes the tool to a single-product lookup and distinguishes it from broader search-oriented siblings by emphasizing exact identifiers and the downstream action create_purchase.

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 provides explicit when-to-use guidance: call it to confirm price and stock before create_purchase, and never quote price from memory. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to select it appropriately.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It does reveal that this is a read-only operation (no side effects), which is helpful. However, it doesn't disclose whether this is a pollable endpoint, what happens if purchase_id is invalid, or if there are any rate limits. The 'wait' instruction implies polling behavior but without specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the core function, and each sentence adds critical value. It covers purpose, usage conditions, prerequisite actions, and handling of result states without redundancy. No wasted words.

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 single-parameter tool with no output schema, the description is nearly complete. It explains what to do with the return values (pending/failed), but lacks detail on the return format structure (e.g., is it just a string or an object?). Given the output schema is absent, a minimal description of the return shape would enhance it further, but overall it's strong.

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 only has purchase_id with no description, and schema coverage is 0%. The description adds critical meaning by stating that purchase_id is required and, more importantly, how to obtain it if missing (call list_purchases first). This goes beyond the schema by telling the agent how to source the parameter, which is essential for successful 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 clearly states the tool's function: to get purchase status by ID and what it returns (paid and payment.status with possible values). It differentiates from siblings by specifying it's for purchase status, not payment status or choice status, and it provides context for when to use it (after create_purchase or when user asks about order 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?

The description gives explicit when to call it (after create_purchase or user queries), what to do if purchase_id is missing (call list_purchases first), and how to handle results (if pending wait, if failed do not retry). This is clear routing and conditional logic that differentiates from 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?

With no annotations, the description carries the behavioral burden. It discloses the intended follow-up behavior on every error (read recovery, say userMessageRu, open openUrl in the browser) and states guardrails: never change limits, freeze, auto-topup, or allowlist even on owner orders. This is strong, though it does not explicitly state whether the tool call itself is side-effect-free.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: resource definition, call conditions, required actions, guardrails, exception, and trigger keywords. The most important scope information is front-loaded.

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?

Even without an output schema, the description names the expected return content: RU copy, cabinet deep links, and recovery.openUrl with userMessageRu and openUrl fields. It also gives behavioral guidance, triggers, and guardrails, so an agent can use the result correctly without further detail.

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 has zero parameters and the schema description coverage is 100%, so the baseline is 4. The description adds no parameter details because there are none to document.

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: the full catalog of AgentPay failures, including RU copy, cabinet deep links, and recovery.openUrl. It also ties the tool to concrete user phrases and 4xx errors, which separates it from siblings 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 gives explicit when-to-use conditions: after a failure, when the user asks «что не так» or «почему не купил», before explaining a 4xx, and it lists trigger words. It also provides an exception path to set_test_mode, clearly routing to an alternative.

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

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

No annotations exist, so the description carries the full disclosure burden. It does reveal that the call returns a composed view with delivery readiness and explicitly forbids raw address, which is useful. However, it does not explicitly state that the operation is read-only, requires no special auth, or has no side effects; the 'Get' verb implies safety but does not confirm it.

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?

Two dense sentences, with the return contents in the first and usage triggers in the second. No filler or repetition; every word 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?

For a zero-parameter read tool with no output schema, the description covers what the agent receives (policy fields and delivery readiness state) and when to call. It leaves minor ambiguity around the exact shape of 'hard + soft policies' and 'missing[]', but for a simple getter this is sufficient.

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 tool takes zero parameters, and schema coverage is 100% with an empty object. The description cannot add parameter-specific meaning beyond that, and no parameter guidance is needed. Baseline 4 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 action ('Get'), a specific resource ('spending policies'), and enumerates exact fields returned (hard/soft policies, allowLuckyPurchases, luckyPurchaseMaxCoins, delivery readiness). It also explicitly excludes raw address, which distinguishes it from sibling get_delivery_address. This makes the tool's purpose immediately unambiguous.

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

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

The description gives concrete invocation triggers: before a surprise buy and when the user says specific Russian phrases like 'правила трат' or 'политика'. It does not explicitly state when not to use it or name alternative tools, but the guidance is clear enough to route an agent. Hence 4 rather than 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?

No annotations are provided, so the description carries the behavioral burden. It clearly indicates this is a read operation via "Get" and states when it should or should not be invoked, which implies no mutation. It also discloses what data is returned, though it does not explicitly discuss side effects, permissions, or failure 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 longer than average but every part contributes: purpose, usage conditions, alternatives, category keys, and triggers. It front-loads the core purpose, then moves to when/how to use it. It is slightly dense but not wasteful.

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

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

The tool has only one optional parameter and no output schema, so the description meaningfully fills the gap by listing returned data elements and call triggers. It does not describe response format or error cases, but for a straightforward preference getter with this rich usage guidance, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the single parameter as "Preference category key" with 100% coverage, so the baseline is 3. The description adds value by listing the actual category keys (dairy, grocery, apparel, pets, beauty, household, pharmacy, gifts, kids, digital), which enriches semantics beyond the schema.

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

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

The description opens with a specific verb and resource: "Get the user's category preferences". It enumerates concrete content (fat %, brands, sizes, pets, schema, learned signals, onboardingPurposes) and differentiates from siblings by naming list_purchases and search_products explicitly.

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 strongly contextualized: "Call before search_products only when the owner already asked to buy or to look in AgentPay", "Do not fetch prefs for idle advice", and it gives explicit alternatives for related phrases: "For «как обычно», «то же самое», «прошлый раз» call list_purchases first."

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

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

No annotations are present, so the description carries the full burden. It clearly discloses hard behavioral constraints (must shop only on the allowlist, never invent a shop, never open random websites) and testMode effects on store visibility and gray-coin spending. It could go further on return format or failure behavior, but core behavioral disclosure is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence carries operational weight: purpose, safety rule, trigger phrases, alternative routing, and testMode behavior. It is slightly dense, but the structure is front-loaded and none of the sentences are filler.

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 no-required-parameter list tool, the description is nearly complete: it covers when to use it, what to avoid, and mode-dependent behavior. The main gap is the lack of any mention of the return shape or contents, especially since no output schema is provided.

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 'need' parameter is already described in the schema with 'Optional topic. Prefer peek_stores for a quiet offer.' The description does not add further semantic detail about this parameter, which is acceptable because the schema already covers it.

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

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

The description states a specific verb and resource: 'List stores on this agent's allowlist.' It also clarifies the tool's role as the authorized shopping source, which distinguishes it from search-oriented siblings like peek_stores and search_products.

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

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

Explicit trigger phrases are given ('магазин', 'где можно потратить', etc.), and an explicit alternative is named: for 'найди'/'сравни'/'подбери' call peek_stores first. The testMode distinction also tells the agent when this list represents test stores only.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns 'last plus purchases[]', mentions testMode behavior ('gray test coins'), and warns against misinterpreting the idiom as a product name. It doesn't detail pagination or error behavior, but the key behavioral traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, then gives trigger phrases and follow-up actions. Every sentence adds value, though the parameter semantics gap means it's not perfectly complete. Still, it's well-structured and not verbose.

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 (3 optional params, no output schema), the description covers the main use case, trigger phrases, and follow-up action. It doesn't explain return structure beyond 'last plus purchases[]' or parameter meanings, but for a list tool with clear purpose, it's mostly complete. The missing parameter semantics and lack of output schema details prevent a 5.

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 0%, so the description must compensate. It doesn't explain the three parameters (limit, storeId, category) at all. However, the tool's core purpose is clear enough that an agent could infer limit is for count, but storeId and category remain unexplained. This is a gap, but the description's focus on usage context partially compensates.

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

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

The description clearly states the tool lists the owner's recent AgentPay purchases with line items, and it distinguishes itself from siblings like create_purchase and search_products. The verb 'list' plus the resource 'purchases' is specific and unambiguous.

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

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

The description explicitly lists trigger phrases ('как обычно', 'то же самое', etc.) and instructs to call it when the user refers to a previous order. It also provides a clear alternative: 'Check catalog price then create_purchase', and warns not to search the idiom as a product name. This is excellent 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal several traits: the call is 'quiet', should happen once, should not list SKUs, and should use sayToUserRu. However, it never explains what output the tool produces, whether it makes an external request, or what 'owner agrees' means, leaving key behavior implicit.

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 short and every fragment is an instruction, which avoids bloat. But phrases like 'Quiet first hop' and 'Speak sayToUserRu' are unexplained jargon, and the compressed style sacrifices clarity for brevity. It is not too long, but it is cryptic enough that an agent may struggle to interpret the intended behavior.

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

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

For a single-parameter tool with no output schema, the description gives enough invocation constraints to avoid obvious misuses, such as calling search_products too early or answering advice requests. Yet it never explains what peek_stores actually accomplishes or what the agent should do with its result, so the chain from this tool to later steps is vague. The low parameter count keeps this gap moderate rather than severe.

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 need is already fully documented in the schema with an example ('Topic, e.g. техника, витамины'), so the baseline is 3. The description only repeats 'Pass need' and adds no new semantics about value format, constraints, or phrasing. The schema covers the parameter, but the description does not enrich it further.

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 reads as usage policy more than a definition: it lists trigger phrases and tells when to call, but never states what peek_stores actually does or returns. 'Quiet first hop' and 'Do NOT list SKUs' hint that it is a preliminary store-level lookup, but the core verb+result is left implicit. This makes the tool's function hard to state precisely from the description alone.

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?

This is the strongest dimension. It gives explicit trigger phrases, a once-per-conversation rule, a clear exclusion ('Never call for advice'), and a named alternative with a condition ('Do NOT call search_products until the owner agrees'). It also instructs to pass the need parameter and to respond via sayToUserRu.

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

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

With no annotations, the description carries the behavioral burden and does so well: it states that no API key is required, that als_ is stable and reusable, that authorization should be set to the returned token, and that the owner should never be asked to paste ap_. It does not describe polling timeout, max attempts, or failure statuses beyond 'approved', which are the main remaining gaps.

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?

Roughly five dense sentences with no filler; the core polling action is front-loaded, followed by the success path, the retry behavior, and safety guardrails. Every sentence contributes information an agent needs.

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 one-parameter pollig step with no output schema, the description covers the source of the input, the approval condition, the auth token setup, the next tool to invoke, and the re-poll fallback. It stops short of specifying other response statuses or an eventual timeout, but the essential call path is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents sessionId at 100% coverage, but the description adds provenance ('Pass sessionId from begin_agent_link') and, more importantly, guidance to re-poll the same sessionId if tools still ask for a key. This makes the parameter's lifecycle explicit rather than just its type.

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 ('Poll AgentPay browser connect') and a clear terminal condition ('until the owner clicks Разрешить'), which immediately distinguishes it from begin_agent_link and verify_connection. It also names the sessionId source and the follow-up tool, so the tool's role in the flow 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?

It gives explicit workflow guidance: pass sessionId from begin_agent_link, poll until approved, then call verify_connection. It also states when to re-poll the same sessionId instead of generating new credentials and warns against inventing keys or asking the owner for ap_, covering both when to use and what not to do.

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

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

With no annotations, the description carries the full behavioral burdenasi and it succeeds. It discloses the return payload (choiceSetId + pageUrl), instructs to share pageUrl, and warns against a common misbehavior (substituting a markdown table, passing canRenderImages=false for ChatGPT/Grok). It also explains the dependency on get_choice_status before create_purchase, so an agent knows the tool's side effects and its place in the larger workflow.

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, and the core purpose is front-loaded. It is a long paragraph that could benefit from bullet points or visual grouping, but it contains no filler, redundant phrases, or vague safety warnings.

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?

Even with no output schema and no annotations, the description covers return values (choiceSetId + pageUrl), the next action (share pageUrl), guards around creating purchases, and a special instruction for ChatGPT/Grok (pass canRenderImages=false). This is a complete and self-sufficient definition for an agent to invoke the tool correctly within a multi-step workflow.

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 0%, so the description must compensate. It clearly explains wants[{q}] for products to compare and canRenderImages=false, and implies agentIntroRu via the chat-sharing instruction. However, it never explains the 'kind' enum (alternatives vs bundles) or the optional 'id' field within wants, leaving real ambiguity for a 4-parameter tool.

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: 'Create a comparison page (choice board, 2–4 options with pros/cons).' It immediately differentiates this tool from siblings like get_choice_status and create_purchase by defining its exact trigger ('MANDATORY when search_products returns 2+ similar hits or clarifyHint.action is present_choices'). The output is also made explicit (choiceSetId + pageUrl), making the tool's 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 provides explicit 'when to use' conditions by naming the precise triggers and even says 'call immediately, do not wait for «сравни».' It also gives explicit 'when not to' instructions, such as 'NEVER substitute a markdown table for this page' and 'Do NOT create_purchase until get_choice_status shows chosen.' This is exceptionally clear routing 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that confirmation must happen in AgentPay web or Telegram aid that chat 'ok' must not be treated as approval, setting a clear source-of-truth rule. However, it does not disclose whether the call is asynchronous, what it returns, or whether a pre-existing agent link is required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: it leads with the core action, follows with call conditions and concrete triggers, and ends with an essential warning. Every sentence earns its place, and there is no filler or repetition.

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 0% schema coverage, no annotations, and no output schema, this description is incomplete. It omits parameter semantics, return behavior, and prerequisites (e.g., active AgentPay link via begin_agent_link). While purpose and usage are clear, an agent cannot fully determine how to construct a correct call from this definition alone.

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 0%, and the description does not explain the meaning or use of `amount`, `message`, or `purchase_id`. The tool's purpose implies that `message` is the confirmation prompt, but the parameter roles and required content are left to inference.

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 and resource: 'Ask the human to confirm in AgentPay web or Telegram.' It then narrows the purpose by listing concrete approval contexts (spend, freeze, missing delivery data), which clearly distinguishes it from sibling tools like present_choices or get_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?

The description explicitly states when to call the tool ('Call when the user must approve a spend, freeze, or missing delivery data'), provides concrete trigger phrases ('спроси меня', 'подтверди', HITL), and includes a critical when-not rule: chat 'ok' is not payment approval. This is actionable and unambiguous, even without naming an alternative tool.

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

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

With no annotations provided, the description carries the full behavioral burden and does so effectively. It discloses that the server performs the parsing, that optional structured fields override parse results, that missing parts must never be invented, and that after success the agent should relay sayToUserRu while waiting orders resume automatically. This goes well beyond what the tool name alone implies.

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, then flows through triggers, usage, parsing behavior, constraints, and post-action behavior. Every sentence earns its place, and the detail about automatic resume and sayToUserRu would be genuinely costly for an agent to infer on its own.

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 13-parameter tool with no output schema and no annotations, the description is unusually complete. It supplies trigger conditions, input format guidance, override semantics, no-hallucination instruction, success-response behavior, and side-effect context. An agent has enough information to invoke the tool correctly and handle the outcome.

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 15%, so the description must compensate. It does this by explaining that `text` is the messy full phrase and that the server splits it into street, house, apartment, floor, entrance, intercom, and phone, while structured fields override the parse. A few self-explanatory fields like city, comment, postalCode, and recipientName are not individually discussed, but the key behavioral parameter `text` is thoroughly covered.

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, 'Save the owner's home address into the AgentPay cabinet', and adds the key detail that it is 'parsed into courier fields'. This clearly differentiates it from the sibling read tool get_delivery_address and from broader preference-update tools.

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

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

The description gives concrete trigger scenarios: specific Russian phrases like «сохрани адрес», dictation of apartment/entrance/intercom/phone, and the post-NEED_USER_DATA case. It also explains that the full chat phrase should be passed as `text`. It stops short of naming when not to use the tool or pointing to an alternative, so it earns a 4 rather than 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?

With no annotations, the description carries the full burden. It adds important behavioral context: it uses live merchant feed data ('not stale training data'), it returns a pick object with whyRu/rankScore/steps, and it mandates reading clarifyHint before create_purchase. It also includes behavioral prohibitions like 'Never quote price from memory' and 'Never dump the result list.' However, it does not explicitly state that the tool is read-only or describe error/edge-case behavior, so it is not a 5.

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 well-structured: purpose first, return value second, usage triggers and rules third. Every sentence carries useful information, and the critical cross-tool dependency (read clarifyHint before create_purchase) is highlighted. A slight deduction because the long list of 'Never' rules could be consolidated, but overall it is appropriately sized for a tool with no annotations and no output schema.

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

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

The description is complete for a search tool with this complexity. It explains the return format, special fields (pick, clarifyHint, quietHint), the relationship to create_purchase, and precise triggers. It even names the sibling alternative for repeat orders. With no output schema and no annotations, the description covers everything an agent needs to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The tool description reinforces that storeId refers to allowlisted stores and that results are capped, but these are already implied in the schema. It does not add new parameter-level meaning beyond the schema, so a 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'Search products in allowlisted AgentPay stores.' It specifies the scope (allowlisted stores), the return type (ProductCard from merchant feed), and lists key fields (price, inStock, imageUrls, sku). This clearly distinguishes it from siblings like get_product (single product) and list_purchases (purchase history).

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 after purchase-intent verbs. It also identifies an alternative: 'If «как обычно», «повтори заказ» — call list_purchases first.' It provides negative guidance: 'Never call for thinking/advice' and 'Never ask for a bank card.' This fully addresses when and when-not to use the tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it states the concrete consequences of both states ('spend only gray test coins in test stores' vs 'hide test stores and spend real coins'), a permission boundary, and an operational directive ('After a real wallet top-up, suggest turning test mode off'). This is rich behavioral context, not merely a restatement of the tool's name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence earns its place: purpose, then triggers, then policy boundary, then redirection, then a suggestion rule, then state consequences. The description is front-loaded with the core operation and immediately tells the agent when to fire it. No filler or redundancy; the length is justified by the density of distinct operational facts.

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-boolean-parameter tool with no output schema and no annotations, this description is operationally complete: an agent knows when to call, what each state does, what the agent may and may not change, and how to route a closely related intent elsewhere. The only gap is the exact response format, which is minor for a toggle operation and not covered by an output schema.

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%, and the schema already documents enabled fully ('true = test stores + gray coins. false = live stores + real coins, hide test shops'). The description's behavioral clauses largely echo that same meaning ('spend only gray test coins in test stores' / 'hide test stores and spend real coins'), adding no genuinely new information beyond what the schema provides. 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 opening sentence, 'Turn AgentPay test mode on or off,' is a specific verb+resource statement that leaves no ambiguity about the operation. It also distinguishes itself from siblings by clarifying this is 'the only *policy* setting the agent may change' (contrasting with get_spending_policy) and explicitly redirecting home-address saves to save_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?

The description gives explicit invocation triggers, including quoted natural-language phrases from the owner ('включи тестовый режим', 'хочу в настоящие магазины') and a post-condition ('after a real top-up when they agree to leave the sandbox'). It also names the alternative tool for a related but distinct intent (save_delivery_address), leaving no ambiguity about when to choose this tool over a sibling.

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

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

With no annotations present, the description carries the full behavioral burden and does substantial work: it discloses persistence semantics ('so the next purchase can reuse it'), a structural constraint ('Persist structured data only'), and a fidelity guardrail ('Never invent fields the owner did not confirm'). It falls just short of 5 because it never clarifies whether updating merges with existing preferences or replaces 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?

Four sentences, zero waste, with the action and primary triggers front-loaded. Every sentence earns its place: purpose+triggers, exclusion, post-clarify routing, and data-fidelity constraints. No redundancy with the schema.

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

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

For a write tool with a fully unconstrained nested object and no output schema, the description covers the critical invocation decisions: when to persist, when not to, and what must never be written. The remaining gaps — allowable category values and an example data shape — are meaningful but the description is complete enough for the common onboarding and lasting-rule flows.

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 0%, so the description must compensate. It adds meaning to `data` via 'Persist structured data only' and 'Never invent fields the owner did not confirm,' and it illustrates `category` with three concrete rule examples. However, it never defines the valid category vocabulary or the expected shape of the data object, leaving the agent to guess for an unconstrained additionalProperties 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 opens with a specific verb+resource pair — 'Update stored preferences for a category' — and anchors it with concrete trigger examples («всегда 2.5%», «не покупай Whiskas», «размер 50»). It clearly distinguishes itself from the read-side sibling get_user_preferences and from sibling save_delivery_address, so an agent can select it 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?

Explicit when-to-use conditions are stated: after a lasting rule or after the onboarding phrase. It also gives an explicit when-not: 'Do not use for one-off orders,' and a routing rule for clarify answers that should stick. This is the strongest possible usage guidance for an agent deciding between one-off versus durable persistence.

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

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

With no annotations, the description carries the full burden. It discloses important behavioral constraints such as 'Do not invent a code' and 'Do not spend until granted', plus post-success behavior in testMode (telling the owner via sayToUserRu). It also mentions opening recovery.openUrl when NEED_BROWSER_GRANT. It does not mention potential side effects like persisting credentials or return values, but the constraints and flow steps are well covered.

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 bit longer than necessary but every sentence adds value: primary purpose, triggers, edge cases, and cautions. It is front-loaded with the main action and then flows through conditional logic. Some redundancy exists (e.g., 'pairing code is optional' repeats the schema), but overall it is efficient and structured.

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

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

Given the tool is part of a multi-step flow, the description covers when to call, how to handle failures (NEED_BROWSER_GRANT), prerequisites (no ap_ yet → begin_agent_link), optional parameters, and post-success actions (testMode). It references sibling tools appropriately and provides sufficient guidance for an agent to use it correctly without needing extra details.

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 description only repeats that the pairing code is optional. It adds no new meaning beyond the schema's 'Optional 6-character pairing code from the AgentPay cabinet'. Baseline 3 is appropriate since the schema already fully documents the 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?

The description clearly states the tool finishes the AgentPay connection ('Finish AgentPay connect'), and distinguishes it from siblings by specifying triggers ('Call when the user says «проверь MCP» or after poll_agent_link returned apiKey and you installed it') and the alternative begin_agent_link for starting the flow. This prevents confusion with polling or other connection steps.

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 provides when-to-use conditions and exclusions: it says to call this tool after poll_agent_link returns an apiKey, and explicitly warns to call begin_agent_link first if no ap_ yet. It also states pairing code is optional and gives handling for NEED_BROWSER_GRANT, leaving no ambiguity about when to invoke this tool versus alternatives.

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