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

The description goes beyond the annotations by disclosing that it makes no network calls and does not reveal the token itself. The readOnlyHint, idempotentHint, and destructiveHint annotations are consistent with this behavior, and the description adds meaningful safety and privacy context.

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

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

The description is three sentences and every sentence earns its place: what the tool reports, what it does not do, and when it should be used. It is front-loaded with the main purpose and contains no 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 zero-parameter, no-output-schema tool, the description is complete. It describes the scope, the specific return content categories, safety protections, and provides an alternative tool for a related but different need.

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 documents nothing, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4; no additional parameter detail is necessary.

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, specific action — showing whether Yandex Merchants is connected — and then enumerates exactly what information it exposes (token presence, source, expiry, file location). It also distinguishes itself from check_access, which performs a live API check.

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

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

It explicitly says when to call this tool: if other tools respond that the connection is not configured. It also explicitly points to check_access as the alternative for a live API access check, giving the agent actionable and unambiguous selection 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the underlying endpoint, the exact response shape, and the absence of a dedicated ping endpoint. It also explains common reasons for failure and how to resolve them, offering rich behavioral context that annotations alone do not provide.

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

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

The description is a single, dense sentence that front-loads the purpose and packs useful information: behavior, return shape, limitation, and troubleshooting. Every clause adds value without redundancy or unnecessary padding.

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 low complexity (0 parameters), rich annotations, and the absence of an output schema, the description provides a complete picture. It explains what the tool does, what it returns, and what to do on failure, making it fully sufficient for an agent to invoke and interpret results.

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, so the baseline is 4. The description correctly omits parameter details and instead focuses on what the tool does and returns, which is appropriate for a parameterless health check.

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 a specific purpose: 'Диагностика подключения' (connection diagnostics) and explicitly describes the exact operation (GET /feeds-info) and expected return values. It distinguishes itself from sibling tools by focusing on a lightweight health check rather than listing feeds or modifying data.

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 clear context on when to use the tool: it acts as a ping endpoint since 'Отдельного ping-эндпоинта в API нет' (there is no separate ping endpoint). It also gives actionable troubleshooting steps for failure cases. However, it does not explicitly contrast with alternatives or state when not to use 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?

The description contradicts the annotation idempotentHint=true. It states 'Код одноразовый' (code is one-time) and lives 10 minutes, implying that calling the tool twice with the same code will fail, which is not idempotent. This is a direct contradiction, so the description fails to align 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 single paragraph that covers essential details without excessive verbosity. It includes the exchange, token storage permissions, immediate feed check, failure handling, and code lifetime. While it is somewhat dense, every sentence contributes useful information, earning a solid score.

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 this is a login completion step with side effects (token storage, feed verification), the description fully covers the workflow: what it does, what to expect after success, how to diagnose wrong-account issues, and how to handle expired codes. No output schema exists, so return values are not needed, and the description is complete for the tool's complexity.

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

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

Schema coverage is 100% and the parameter 'code' already has a clear description. The tool description adds context about the code coming from start_login and being one-time, but this does not significantly enhance the parameter's meaning beyond what the schema already provides (it is a confirmation code from Yandex).

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: it exchanges the confirmation code from start_login for an access token, saves it with restrictive permissions, and immediately verifies by fetching feeds. It explicitly identifies itself as the second step of the connection process, distinguishing it from start_login and other auth tools.

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

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

The description provides explicit sequential guidance: it is the second step after start_login, and if the code is not accepted or feeds are not visible, it instructs to call start_login again and use the correct account. It also clarifies when other tools become usable immediately after success, giving clear usage context.

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

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

With annotations only indicating readOnlyHint=false, the description goes far beyond by disclosing the HTTP method, the ttl_in_hours maximum (720) and its error case (INVALID_TTL), the undocumented behavior of repeated hiding, the response format, the inability to list hidden offers via API, and a rate limit. 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 single, dense paragraph that packs purpose, parameter semantics, response format, a limitation, and a rate limit. Every clause adds value and the most important information is front-loaded. It is slightly run-on but still efficient and readable.

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 mutation tool with no output schema, the description compensates by explicitly stating the response structure ({ status: 'OK' } or { status: 'ERROR', errors: [...] }). It also covers usage context, undocumented behavior, a listing limitation, and operational limits, making it a complete guide for an agent.

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

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

The schema already provides full descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics for ttl_in_hours (max 720, error, default permanent hiding, unknown repeat behavior), which elevates the value beyond the schema. feed_id and offer_id gain no extra semantic meaning from the description, but schema covers them.

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: 'Скрывает одно предложение из Поиска по товарам' (hides one offer from product Search), and even gives the POST /hidden-offers endpoint. The singular 'одно' contrasts with the sibling hide_offers, and the mention of show_offers provides immediate distinction.

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 a concrete use case ('когда товар закончился' – when the product is out of stock) and explains that without ttl the offer stays hidden until explicitly shown via show_offers. However, it does not explicitly name hide_offers as the batch alternative, so guidance is strong but not fully exhaustive.

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 provide hints (readOnly=false, openWorld=true), so the description carries the transparency burden. It adds response format ({ status: OK } or errors), specific error codes, TTL semantics (common ttl for all), and rate limit (50k/min shared with show_offers). Not exhaustive (e.g., no auth requirements or partial-failure behavior) but substantially transparent.

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

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

The description is compact and front-loaded with the main action, then endpoint, TTL behavior, response format, and limits. Every sentence adds value with no redundancy or 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 complex batch tool with no output schema, the description covers the essential aspects: operation, limits, TTL behavior, response format, error codes, and rate limit. Minor gaps include explicit comparison to hide_offer and partial-failure semantics, but overall 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?

Schema coverage is 100%, so baseline is 3. Description adds meaningful nuance: 'Общий ttl_in_hours применяется ко всем предложениям запроса' clarifies that TTL is shared across all offers. Also includes error codes related to invalid parameters (e.g., INVALID_TTL, LIMIT_EXCEEDED).

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

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

Description clearly states the tool's function: 'Массово скрывает предложения из Поиска' — mass-hides offers from Search. It specifies the scope (1–500 per request) and differentiates from the singular sibling hide_offer by the word 'Массово' and the batch size.

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 clear context: batch operation up to 500 offers, shared TTL, HTTP endpoint, and rate limit shared with show_offers. Excludes nothing explicitly but the mass nature makes it obvious when to use this instead of hide_offer. Lacks explicit 'use this for X, not Y' phrasing.

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 annotations (readOnlyHint, destructiveHint), the description adds valuable context: the feed list is scoped to the current OAuth login, the response format is outlined, and limitations about the API are disclosed. 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?

Two sentences, each earning its place: the first states the action and response shape, the second explains its role and limitations. No redundant 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?

Despite having no output schema, the description provides a clear response format and explains the tool's role in the larger workflow. It fully covers what the tool does and how it should be used.

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, so schema coverage is trivially 100%. The description correctly implies no parameters are needed and focuses on the return value. Baseline 4 is appropriate for a no-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 clearly states 'Возвращает список товарных фидов' (returns a list of product feeds) and specifies the exact response structure. It distinguishes from siblings by identifying itself as the entry point for other tools that require feed_id.

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 it is the entry point for all other tools, instructing that their feed_id parameter comes from this response. Also provides exclusions: no feed status, no offers list, and creation/deletion only via dashboard, preventing incorrect use.

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 annotations (destructive, not read-only, not idempotent), the description discloses important behavioral details: it does not affect the environment variable token and does not revoke remote access, which must be done separately. This adds significant transparency about side effects and limitations.

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

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

The description is concise, consisting of three clear sentences, each adding essential information. It is well-structured: first states the primary action, then clarifies what is not affected, and finally notes the remote persistence. No unnecessary 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?

The description provides complete context for the tool's behavior, including its scope (local token only) and the need for separate revocation. Since there is no output schema, return values are not a concern. The description fully covers the tool's operational context.

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

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

The tool has no parameters, so schema coverage is 100%. The description does not need to explain parameters, and the baseline for high coverage is 3. No additional parameter information is required.

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: deleting the saved Yandex Products token from disk. It distinguishes this tool from others by its specific action and title, making its purpose unambiguous.

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

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

The description provides useful usage context by explaining what it does (deletes local token) and what it does not do (doesn't touch env var, doesn't revoke remote access). It implicitly guides when to use it, though it doesn't explicitly state 'use this when you want to log out'. This is sufficient for most cases.

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

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

This is an Annotation Contradiction. The description explicitly lists DELETE as a supported method, which is inherently destructive, but the annotation destructiveHint=false indicates the tool is not destructive. The description also discloses that body is sent raw without transformations, but the destructiveHint mismatch is a serious inconsistency that could mislead the agent.

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

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

The description is concise yet dense: two sentences front-loaded with purpose ('Запасной выход') and immediately covering path, methods, body format, and base URL. Every phrase earns its place with no filler or repetition of schema/annotations.

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 essential context for a raw API request: base URL, method restrictions, body format, and example paths. While it lacks response format and authentication details, these are less critical for a raw pass-through tool. The main gap is the destructiveHint contradiction, but that is already penalized in transparency. Overall, adequate for the tool's complexity.

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

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

Schema coverage is 100% with each parameter described. The description adds significant value by providing wire-format examples ({ offers: [...] }) and clarifying that body is sent without transformations, going beyond the schema's generic descriptions. It also associates methods with specific paths, enhancing parameter understanding.

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

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

The description clearly states it is a direct call to any path of the Yandex Goods partner API, with specific verb 'прямой вызов' and resource. It distinguishes itself from siblings by being a fallback (Запасной выход) that covers arbitrary paths, unlike the specialized sibling tools.

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

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

The description explicitly positions the tool as a fallback (Запасной выход), implying it should be used when dedicated sibling tools (e.g., list_feeds, set_offer_price) are not applicable. It provides concrete method examples and path examples, giving clear context for when to use. However, it does not explicitly name alternative tools or state 'prefer specialized tools when available'.

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 annotations (readOnlyHint=false, idempotentHint=true), the description discloses critical behavioral details: client-side validation of the discount range (5–95%), fixed currency (RUR), and the exact API response shape. This adds significant context beyond annotations.

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

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

The description is compact (3 sentences) and front-loaded with the primary action, followed by endpoint context, validation, currency, and response format. Every sentence contributes unique information with no redundancy.

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

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

Given the absence of an output schema and the presence of four required parameters, the description is remarkably complete: it covers validation, currency, response format, and the distinction from sibling tools. An agent can confidently invoke this tool correctly based on the description 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?

The input schema already provides comprehensive per-parameter descriptions (100% coverage). The description adds the relationship between price and discount_base (the 5–95% rule) and reinforces the required nature of discount_base, providing extra semantic value beyond the schema.

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

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

The description clearly states the tool's function ('Устанавливает скидку') and precisely defines the roles of price and discount_base. It further distinguishes itself from sibling tools by noting it uses the same POST endpoint but requires discount_base, making it the dedicated discount-setting tool.

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

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

The description implies usage for setting discounts with a mandatory discount_base, contrasting with sibling tools like set_offer_price and update_offer_prices. It also provides validation rules (5–95%) and currency constraints, giving clear context for when the tool is appropriate, though it does not explicitly name alternative tools for non-discount price updates.

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 annotations, it discloses auto-inserted currency, discount percentage validation leading to HTTP 400, strict pairing requirement for special-price fields, exact API response format, side effect on duplicate IDs (only first updated), and rate limit of 50k changes/minute. 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?

Every sentence contributes new, actionable information: scope, currency, optional fields with validation, response format, duplicate handling, and rate limit. 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?

Given no output schema, the description fully explains the API response (status OK or ERROR with errors array), and covers edge cases (duplicate IDs) and operational limits (rate). Together with the parameter constraints, it provides a complete operational picture for an agent.

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

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

Schema covers all 6 parameters at 100%, but description adds valuable cross-parameter context: currency always RUR, discount_base must be > price and within 5–95%, and pay_by_price/pay_by_condition are mutually required. This supplements the schema meaningfully.

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

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

Description clearly states it changes the price of a single product offer, specifying the exact endpoint (POST /offer-prices/updates) and the singular scope. This distinguishes it from sibling batch tools like update_offer_prices.

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 notes this is for one element and introduces optional parameter constraints (discount_base + pay_by_price/condition), plus duplicate-ID behavior and rate limit. However, it does not directly name the batch alternative, only implies it via 'c одним элементом'.

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

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

The description adds significant behavioral details beyond annotations: the exact API response format ({ status: "OK" } or error codes), possible error codes (DUPLICATE_OFFER, INVALID_FEED_ID, etc.), and a rate limit shared with hide_offers. These are valuable operational details not present in the annotations alone.

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

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

The description is concise and well-structured: purpose first, then request method and response format, followed by error codes and rate limit. Every sentence contributes useful information with no redundancy.

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

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

With a single parameter fully documented by the schema and annotations providing safety hints, the description covers all essential aspects: what it does, how the API behaves, error handling, and limits. It is complete for the tool's complexity.

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

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

The input schema provides 100% coverage, thoroughly describing the 'offers' parameter and its nested fields (feed_id, offer_id). The description does not add any parameter-specific meaning beyond restating the 1-500 per request limit, which is already present in schema constraints.

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

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

The description clearly states the tool's purpose: 'Возобновляет показ ранее скрытых предложений' (resumes showing previously hidden offers), with a specific verb and resource. It also references the underlying HTTP endpoint (DELETE /hidden-offers), which distinguishes it from sibling tools like hide_offers.

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 implies when to use the tool (for previously hidden offers) and mentions a shared rate limit with hide_offers, giving context. However, it does not explicitly state when not to use it or name alternatives, so it stops short of full when/when-not guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and no parameters. The description explains that the tool returns a link, provides a code, and that the code is useless to outsiders, and also mentions the scope and token. Since annotations cover safety, the description goes beyond to explain the OAuth flow behavior. No contradiction; the description adds meaningful context about the OAuth flow and code exchange.

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

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

The description is a single well-structured paragraph that is information-dense but focused. It covers purpose, user instructions, security, scope, validity, and handoff—all in about 70 words. 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 zero-parameter tool with clear annotations and a descriptive description, this is close to complete. The only minor omission is that it doesn't explicitly state what the response JSON looks like (no output schema), but the description covers the essential flow and security aspects. Given the tool's simplicity and rich annotations, a 4 is fair.

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?

No parameters exist in the schema, and schema coverage is 100%. The description doesn't need to add parameter details. The context signals confirm zero parameters, and the description explains what the user should do with the return value, which is the meaningful semantic. A baseline of 4 is appropriate due to no 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?

Clear verb+resource: 'start' the login flow for Yandex Products, returns an OAuth link. The description distinguishes the overall purpose well, though it doesn't explicitly contrast with sibling finish_login, but the flow is clear.

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?

Excellent guidance: instructs to show the link to the user, provides specific steps (open in browser under the same Yandex login as the YML feed, confirm access, return the code), and states the code's 10-minute validity. Explicitly hands off to finish_login. This covers when and how to use it, and the alternative is implied.

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 annotations, the description discloses critical behavioral details: API endpoint, response format with possible error codes, fixed currency (RUR), and rate limits. This adds far more than the annotations (readOnlyHint=false, idempotentHint=true) and leaves no ambiguity about side effects or limits.

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

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

The description is concise and front-loaded: states the primary action and batch size first, then response format, error codes, and rate limits in a compact sequence. Every sentence adds value without redundancy or 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?

Given the tool's complexity and absence of an output schema, the description fully covers necessary behavioral context: what to expect in the response, possible error codes, rate limits, and how to handle large batches. No critical gaps remain.

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

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

With 100% schema description coverage for the single 'offers' parameter, the schema already fully explains parameter semantics. The description does not add significant parameter-specific detail beyond what the schema provides; it only reiterates currency and batch limits.

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

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

The description explicitly states the tool's purpose: 'Массово обновляет цены' (massively updates prices) and specifies the batch size (1–2000 offers per request). This clearly differentiates it from sibling tools like set_offer_price (single offer) or set_offer_discount (discounts).

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 concrete usage context: batch quoting, rate limit (50,000 changes/min), and guidance to split large volumes into multiple calls. It does not explicitly name alternative tools but implies batch-only use, which is clear from sibling names.

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