Ozerki via AgentPay

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 behavioral detail beyond annotations by specifying the polling nature, the exact status values (draft|chosen), and the chosenOptionId field. It could mention whether the tool is idempotent or any rate limits, but those are not critical given the read-only 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?

Two sentences with zero fluff. The primary action and return type are front-loaded, followed by precise usage timing. 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?

Given there is no output schema, the description fully specifies the return (status and chosenOptionId) and explains the call flow relative to sibling tools. For a simple poll operation with one parameter, nothing essential is missing 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?

The schema has only one parameter, choice_set_id, with no description coverage. The tool description implies its meaning by referencing 'a choice set from present_choices', but does not explicitly state that it is the ID returned by that call. Since the parameter name is self-explanatory and the context is clear, the description adds some value but does not fully compensate for the 0% schema coverage.

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 'Poll' and names the resource 'choice set from present_choices', clearly distinguishing it from siblings like present_choices and create_purchase. It also states the return payload, making the tool's purpose unambiguous.

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

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

Explicitly states when to call: after present_choices when waiting for the owner, or before create_purchase to attach choiceSetId. This provides clear temporal context and ties into the broader workflow, leaving no ambiguity about appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, but the description adds valuable behavioral context: it returns sayToUserRu, side (agentpay vs merchant), and the contact to give the owner. It also instructs not to invent reasons and not to hide the side, which are behavioral rules beyond the annotations. 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 a bit verbose but every sentence carries meaning: the trigger list is extensive, the return content is specified, and the behavioral rules are included. It's front-loaded with the core purpose ('before guessing') and structured logically. Minor redundancy could be trimmed, but it's still efficient for the information density.

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 compensates by specifying the exact return fields (sayToUserRu, side, contact). It also covers usage context and constraints. For a simple two-parameter tool, nothing essential is missing—an agent can call it correctly and interpret the response.

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 both 'q' and 'storeId' are already documented in the schema. The description adds no new parameter-level detail beyond what the schema provides; it just restates the trigger phrases for 'q'. This meets the baseline 3 but doesn't elevate it.

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

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

The description clearly states the tool's purpose: looking up AgentPay operational FAQ. It lists specific trigger scenarios (why SKU looks wrong, missing photo, empty search, etc.) and specifies the return content (sayToUserRu, side, contact). This distinguishes it from siblings like search_products or get_product, which have different roles.

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

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

The description explicitly says 'Call when the owner asks...' followed by a concrete list of triggers, including Russian phrases. It also gives exclusions: 'Do not invent a reason' and 'Do not hide whose side it is,' which are clear usage rules. Though it doesn't name alternative tools, the trigger list is specific enough to route an agent correctly.

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; the description adds substantial behavior beyond that: the full return contract (distanceBasis, complete-basket options, nearbyIncompleteOptions, inStock, lowStockItems, distanceAssessment, deliveryPreview), the NEED_PICKUP_LANDMARK edge case for city-only input, the 'never substitute another nearby pharmacy' constraint in exact mode, and concrete stock-risk thresholds (stockRisk=last_units or inStock<=3). 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?

Purpose and the MUST-call rule are front-loaded, and the density is proportionate to a genuinely complex tool (7 params, no output schema, multiple operational modes). Some redundancy exists — offering delivery appears twice ('offer delivery as an alternative' and 'offer delivery, replacements, or explicit consent to distant pickup') — and a few sentences are agent-policy rather than tool behavior, but nothing is wasted.

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 carries the full burden of explaining return values, and it lists them explicitly. It covers input requirements, edge cases (matched=false, requiresFulfillmentChoice, canPromiseFinalDelivery=false), the two-stage deliveryPreview protocol, brand handling, and handoff routing. Nothing an agent needs to invoke this tool 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 57%, with lat/lon undocumented; the description compensates by clarifying that lat/lon serve as a coordinate alternative to near, and gives a concrete format example for near ('метро Белорусская, Москва') plus the city-only insufficiency rule. However, much of the description's parameter guidance (items naming, exactPharmacy trigger) largely restates what the schema already says, so the incremental value beyond structured data is moderate.

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: 'Ozerki pickup-point resolver for multi-brand Ozerki-network pharmacies,' then sharpens scope with 'MUST be called before handoff when the owner asks for pickup near a place or has no exact delivery address.' This distinguishes it from siblings like prepare_ozerki_handoff (the follow-up) and search_products without needing to open their 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 (pickup near a place or no delivery address), when NOT to call ('If neither landmark nor coordinates are known, ask one short question... do not build a basket yet'), and routes to the sibling follow-up ('Then pass the chosen storeId to prepare_ozerki_handoff'). It also carves out the exactPharmacy=true mode as a distinct invocation path with its own rules.

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

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

Annotations declare readOnlyHint=true, and the description adds context: it returns merchant-synced data, includes a trackedUrl that must be used for links, and details the pick field. It explains the nuance of price source and live vs. synced data, which is beyond annotations. Minor gap: doesn't explicitly mention pagination or rate limits, but annotations already cover safety.

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 and covers many scenarios (live data, pharmacy routing, competitor comparison, quality allegations). It is front-loaded with the core purpose but then goes into detailed policy language that could be condensed. It earns its place but could be structured better with sections.

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

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

Given the complexity (live vs synced data, pharmacy preferences, competitor comparison rules) and no output schema, the description covers return fields, link usage, and use cases thoroughly. It even provides trigger phrases and policy for edge cases, so it's complete for an agent to decide when and how to use it.

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

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

Schema coverage is only 33%, so the description must compensate. It explains q as the owner's search phrase for pick context, and product_id/store_id are implicit. It adds meaning to q and clarifies the role of product_id/store_id in retrieving a specific item, which helps for a tool with sparse 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 gets one ProductCard by product_id + store_id from an allowlisted store. It includes specific return fields and differentiates from siblings like search_products by specifying it's for a single product lookup, not a search.

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: for live data, connect first via begin_agent_link/poll_agent_link; for pharmacy requests, prefer Ozerki and optimize within it, and only compare externally when explicitly asked. It also says 'Call to confirm price and stock before create_purchase' and gives trigger phrases. This is very explicit.

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 supply only the basic read-only/safe profile; the description adds real behavioral context: invite-link owners get preferredStores + preferredStoreRoutingRu, demoOnly requests must avoid Dixy/Ozerki, and testMode changes both the visible store list and the currency (gray coins). The shopping guardrails ('Never invent a shop, never open a random website to pay') are also useful beyond the annotations. I see no contradiction with readOnlyHint/openWorldHint.

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 longer than a typical tool blurb, every sentence contributes a distinct rule: allowlist boundary, return-field caveat, call triggers, demoOnly behavior, sibling routing, and testMode behavior. It is front-loaded with the core purpose and constraint, and the structure flows from invocation to exclusions. This is dense but not 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?

Covers the important invocation conditions: user phrases, demoOnly mode, testMode, invite-link routing, and the forbidden alternative paths. The main gaps are that the ordinary return shape is not described beyond the special-case fields, and peek_stores is referenced as the alternative but is absent from the provided sibling list. Still, for correctly selecting and calling the tool, the description is nearly 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 already documents both parameters at 100% coverage: need examples «техника» and the peek_stores preference, demoOnly's explicit demo/test-catalog condition and exclusion of live stores. The description reinforces demoOnly with the Dixy/Ozerki caveat, but it doesn't materially alter the meaning of either parameter. 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?

Opens with a concrete verb+resource: 'List stores on this agent's allowlist,' and immediately clarifies the domain constraint ('The agent MUST shop only here'). It also signals what the tool is not by pointing to peek_stores for search-like intents and explicitly excluding search_products for «найди/сравни/подбери». No ambiguity remains about what this specific tool does.

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?

Lists explicit user-language triggers: «магазин», «где можно потратить», «спецмагазин», «тестовый магазин». It gives a precise conditional for demoOnly and an explicit alternative: 'For «найди» / «сравни» / «подбери» call peek_stores first, not this dump and not search_products.' That is exactly the when/when-not/alternatives guidance this dimension asks for.

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 show readOnlyHint=false, openWorldHint=false, destructiveHint=false, so description carries burden for side effects. It clearly states what the tool does and does NOT do: 'This does NOT create the final Ozerki order and does NOT pay.' It warns about extCart merging with existing basket, that links don't persist store selection, and that available_darkstore lines have varying conditions. 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 opens with the core purpose, then proceeds through preconditions, steps, warnings, and fallbacks in a logical order. It is front-loaded with the most critical constraint (call only after fulfillment agreed) and ends with strong prohibitions. 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?

Despite no output schema, the description explains all return aspects (handoffUrl, fallbackUrl, canHandoff, recoveryOptions, agentNextRu) and covers edge cases like darkstore availability, flat requirement, and link persistence. It also provides recovery instructions and sibling differentiation. An agent has everything needed to call this tool correctly in any supported scenario.

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%, but the description compensates thoroughly. It explains storeId is mandatory for pickup and must come from explicit owner choice, flat is required for delivery with '-' default, goodsId is specifically the Ozerki id not a feed row, and regionId defaults to 14 for Moscow. It also adds meaning to the response fields (canHandoff, recoveryOptions, agentNextRu) which are not in the schema. This goes beyond the bare parameter names.

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

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

The description states a specific purpose: 'Ozerki-only availability preflight and tracked basket handoff.' It clearly distinguishes itself from siblings like get_ozerki_pickup_options and list_allowed_stores by explicitly mentioning them and contrasting its behavior. The verb 'prepare' with resource 'handoff' 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?

Provides explicit when-to-use ('Call only after fulfillment is agreed'), exact steps for pickup (call get_ozerki_pickup_options, present options, obtain choice, pass storeId) and delivery (flat mandatory). Also gives strong when-not guidance: 'Do NOT call list_allowed_stores' and 'Do NOT make the owner rebuild the basket.' It even describes recovery actions when canHandoff=false, leaving 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?

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false, which is thin. The description compensates with rich behavioral detail: the server filters men's/women's apparel lines, searches each want only in category-matched stores, returns choiceSetId + pageUrl + catalogSearchScopeRu, and always requires sharing pageUrl in chat. It also exposes rendering constraints (canRenderImages=false for ChatGPT/Grok) and follow-up requirements, adding value far 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 long, but every sentence carries operational weight: triggers, special cases, return values, mandatory sharing, and negative constraints. It is front-loaded with the core action, then the mandatory trigger, then domain-specific rules. There is no filler or repetition; the length is justified by the number of critical behaviors an agent must follow.

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

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

Given the tool's complexity, lack of output schema, and multiple domain rules, the description is remarkably complete. It covers triggers, parameter usage for alternatives and bundles, store scoping, apparel gender handling, return fields, follow-up with get_choice_status, and rendering/fallback constraints. An agent has everything needed to invoke the tool correctly in the intended 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?

Even though schema coverage is 75%, the description materially enriches parameter understanding: it explains that kind=bundles is for basket/recipe contexts and that wants must include q for EVERY ingredient in one call. It also clarifies how canRenderImages should be set for certain model contexts and why agentIntroRu exists ('why you are asking, not choosing for them'). This is exactly the kind of semantic depth a schema cannot provide 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: 'Create a comparison page (choice board, 2–4 options with pros/cons).' It clearly distinguishes present_choices from siblings like search_products and get_choice_status by naming its trigger and purpose. It is far from a tautology and gives an agent immediate understanding of what this tool produces.

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

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

The description gives explicit when-to-use rules: 'MANDATORY when search_products returns 2+ similar hits or clarifyHint.action is present_choices — call immediately, do not wait for «сравни».' It also provides concrete when-not-to-use guidance: do not hand-pick SKUs from other stores, do not substitute a markdown table, and do not create_purchase until get_choice_status shows chosen or the owner picks in chat. This leaves no ambiguity about invocation timing.

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, it discloses auth-dependent behavior (public demo catalog without auth, begin_agent_link requirement), feed-availability caveats (availabilityScope, needsFulfillmentConfirmation), output contract (ProductCard fields, clarifyHint/quietHint), routing behavior (preferredStoreRoutingRu, clothingGender hard-filter), and the trackedUrl vs url policy. No annotation contradiction exists.

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

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

The opening sentence is clear, but the description quickly becomes a single wall of text of several hundred words with no paragraphs, bullets, or visual structure. It mixes core search semantics with payment policy, pharmacy comparison politics, auth flows, and repeated Ozerki guidance, making it much harder to scan than its informational richness justifies.

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?

Without an output schema, the description compensates by enumerating the product card fields and response hints. All 11 parameters are covered, auth and demo behavior are explained, and orchestration with sibling tools is specified in enough detail that an agent can invoke the tool correctly in complex scenarios.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial parameter-level meaning: catalogOverview must be shown as catalogOverviewRu with no two-name limit, demoOnly excludes live stores and forces demo-only discussion, location must be omitted when unknown and never defaulted to Moscow, metro/street queries require a follow-up pickup-options call, and regionId should be omitted unless explicitly known.

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 states a specific verb, resource, and scope: 'Search products in allowlisted AgentPay stores.' It further clarifies that the query fields are product-only, not address fields, and names related flows (get_ozerki_pickup_options, present_choices, list_purchases) so the tool is distinguishable from siblings.

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

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

The description gives explicit triggers ('актуальная цена', 'есть в наличии', after 'купи', 'закажи', 'оформи', after peek_stores yes), explicit exclusions ('как обычно' -> list_purchases first, never for thinking/advice), and explicit alternatives (get_product for pricing, web search only after MCP/API failure in the Ozerki profile, get_ozerki_pickup_options for metro/street).

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