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

Beyond the annotations (non-read-only, idempotent, non-destructive), the description reveals the key security side effect (key in chat), local file storage path and permissions, and naming fallback behavior. This adds meaningful context beyond the schema flags.

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 well-structured with a purpose statement, a security warning, and an Args list. The warning about i_understand is slightly repeated (in the ⚠️ line and the Args line), but this redundancy is minor and does not hurt clarity.

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 mutating tool that stores credentials, the description covers required parameters, side effects (file storage, chat exposure), the required confirmation flag, and naming behavior. Since an output schema exists and annotations already describe safety, no critical information is missing for correct invocation.

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

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

With 0% schema description coverage, the description fully compensates: it explains `credentials` as a dict with service-specific examples, defines `name` as optional with a fallback rule, and mandates `i_understand_key_goes_to_chat`. This is far beyond the raw JSON schema.

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

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

The description states 'Add or update a cabinet (a named set of API credentials), from chat.', which names a specific verb, resource, and context. This clearly differentiates it from siblings like avito_list_cabinets, avito_remove_cabinet, and avito_use_cabinet.

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 warns 'This puts the key into the chat transcript', requiring a consent flag, and points to the installer as a terminal-free alternative where the key never enters chat. This gives clear when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnlyHint annotation, the description adds that the tool 'runs without confirmation' and notes that only a few read endpoints require a body. It also discloses the response envelope and error envelope, providing useful behavioral context not present in the annotations.

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

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

The description is well-structured and front-loaded: purpose, target API, read-only behavior, sibling routing, then a compact args list and return format. Every sentence earns its place, and the line breaks make the parameter documentation easy to scan.

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 generic read executor with four parameters and an output schema, the description provides the target API, read-only guarantee, sibling alternatives, parameter roles, and return shape. It could be more detailed about authentication or error envelope specifics, but it gives an agent enough orientation to invoke the tool correctly with the help of avito_search_methods.

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 carries the explanatory burden. It gives meaningful semantics for each parameter: operation_id is sourced from the catalog, path_values fill {placeholders}, query is query-string parameters, and body is a JSON request body for certain read endpoints. While not deeply detailed, it maps each parameter to its role.

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: 'Execute one READ endpoint from the catalog by operation_id.' It clearly differentiates itself from sibling write and delete tools by explicitly naming avito_write_method and avito_delete_method as the alternatives for changing or removing 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?

Usage guidance is explicit and actionable: it states this tool is for read-only operations, names the write and delete sibling tools for data changes, and points to avito_search_methods for discovering valid operation_id values. This leaves no ambiguity about when to choose this tool over its siblings.

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 valuable behavioral context beyond the readOnlyHint annotation: it explicitly states the tool does NOT reveal secret values, only reports which variables are set. It also discloses the exact return shape (JSON with ready, missing, required). This is strong transparency for a read-only check tool, though it could mention whether it validates value format or just presence.

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 extremely concise: two sentences plus a JSON return format. Every sentence earns its place. The key behavioral constraint (does NOT reveal secrets) is front-loaded, and the return format is clearly specified. 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?

Given the tool has zero parameters and a clear output schema, the description is nearly complete. It covers purpose, behavior, and return format. The only minor gap is not listing the specific environment variable names, which would help an agent know what 'required' means in practice. However, the output schema and simplicity of the tool make this a minor omission.

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 schema provides no parameter semantics. The description compensates by explaining what the tool reports (which variables are set, missing, required) and the return format. This is sufficient for a no-parameter tool, though it could list the exact environment variable names expected.

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: checking whether required credentials are present in the environment. It uses a specific verb ('check') and resource ('credentials'), and explicitly distinguishes itself from credential-revealing operations by stating it does NOT reveal secret values. This is unambiguous and distinct from 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 implies when to use this tool: before operations requiring credentials, to verify readiness. It does not explicitly name alternatives or exclusions, but the context of sibling tools (e.g., avito_whoami, avito_use_cabinet) and the clear 'check' purpose provide sufficient guidance. A slight gap is the lack of explicit 'use this when...' 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds value by specifying that both confirm_write and i_understand_this_modifies_data must be true, and that nothing is sent without them. It also describes the JSON return format. This goes beyond the annotations without contradicting them.

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

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

The description is concise, with the destructive intent front-loaded and the argument list clearly formatted. Every sentence contributes value, from the API reference to the return format. No redundant or promotional language.

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 (6 parameters, no schema coverage) and that an output schema exists, the description covers the essential usage: destructive operation, required confirmation, argument meanings, and return structure. It lacks explicit guidance on when to use this vs. avito_delete_raw, but the core invocation requirements are well addressed.

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 0% schema description coverage, the description carries the full burden of parameter explanation. It lists all six parameters and gives functional meanings: operation_id from the catalog, path_values for placeholders, query as query-string, body as JSON, and the two boolean flags that must be true. This is sufficient for an agent to understand each parameter's role, though it could elaborate on path_values format.

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: 'Execute one DESTRUCTIVE endpoint: deletes or irreversibly changes data.' This specifies the verb (execute) and resource (destructive endpoint), and the destructive nature distinguishes it from read-only siblings. It also names the target API, providing concrete context.

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 destructive operations by emphasizing 'DESTRUCTIVE' and the required confirmation flags, but it does not explicitly contrast with sibling tools like avito_write_method or avito_delete_raw. It only references avito_search_methods for operation_id, leaving the agent to infer when this tool is appropriate versus others.

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 provide destructiveHint and readOnlyHint, and the description adds separate context: it is a hard-DELETE operation, requires explicit confirmation flags, and returns a specific JSON envelope. This goes beyond the annotations and helps an agent understand the destructive, confirmation-gated behavior.

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

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

The description is front-loaded with the destructive scope, then lists operational conditions and arguments. It is slightly repetitive about the flag requirement ('Both ... are required' and then each flag 'must be true'), but every line carries essential information and it stays compact.

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 7-parameter raw tool, no parameter descriptions in the schema, and a destructive semantic, the description fully covers the expected path, method, parameters, host, confirmation, and return format. The agent can safely invoke this tool directly from the description.

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 explain all 7 parameters. It does so: path is a full path starting with '/', method is DELETE, host has an override default, query/body are JSON, and the two flags must be true. This fully compensates for the sparse schema.

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

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

The description states a specific verb and resource: 'Delete data at ANY path, including paths not in the catalog,' which clearly distinguishes it from catalog-specific tools like avito_delete_method. It also links to the target API and is concrete about the operation scope.

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

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

The description gives actionable conditions: use it for DELETE only, any path, and require both confirm_write=true and i_understand_this_modifies_data=true. It does not explicitly name alternative tools, but these criteria are clear enough for an agent to choose this tool over other raw operations.

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 readOnlyHint annotation already marks this as non-destructive; the description adds context by specifying what the returned catalog record contains. It does not contradict annotations, but it also does not disclose any other behavioral traits (e.g., whether an API key or prior setup 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?

One tightly packed sentence that front-loads the action and lists the return fields with zero 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?

With a simple one-parameter tool, an output schema, and readOnly annotations, the description covers the core purpose well. The only real gap is the missing explanation of what operation_id represents or where it comes from.

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?

Input schema coverage is 0%, so the description must compensate. It never explains operation_id: what format it takes, where the caller obtains it, or how it links to describe_method. The name is somewhat self-evident, but no concrete guidance is provided.

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 names the exact operation (return the full catalog record for one endpoint) and lists the fields returned. Combined with the verb 'describe_method', it is unambiguous and easily distinguished from call/search 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?

No guidance on when to use this tool over alternatives like avito_search_methods or avito_call_method. The description implies inspection rather than execution, but does not state it, and gives no hint that operation_id likely comes from a search/map 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?

The description adds substantial behavior beyond the readOnlyHint/openWorldHint annotations: it reveals automatic pagination across multiple cursor styles, automatic array-path discovery, cursor-field management, a max_items context-protection cap, and a structured return envelope including a truncated flag. This is exactly the kind of behavioral context an agent needs.

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 main purpose, then uses a compact, scannable Args block with no filler. Every sentence earns its place by adding operational or return-value detail.

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 generic pagination tool with seven parameters and no schema-description coverage, the description is complete: it covers input semantics, pagination styles, defaults, output shape, and the truncation safeguard. The presence of an output schema also means return-value details need not be repeated in full.

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 0% schema description coverage, the description fully compensates: operation_id is defined as a read endpoint from the catalog, query/body/path_values are described as base parameters with cursor fields managed, items_path is an override, limit sets page size, and max_items is a hard cap. Every one of the seven parameters receives meaningful semantic explanation beyond its schema 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 opening sentence, 'Auto-paginate a read endpoint and return every row in one response,' names a specific verb, a resource, and the distinguishing behavior of returning all rows. The mention of supporting offset, last_id, cursor, page, and lastChangeDate styles further separates it from single-page sibling getters like avito_get_items and avito_get_orders.

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 makes the use case clear: this is for fetching complete result sets from read endpoints, with pagination cursor fields managed automatically. It does not explicitly name single-page alternatives or state when not to use this tool, so it stops short of a 5, but the context is strong and not misleading.

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 include readOnlyHint=true and openWorldHint=true, so the safety profile is already declared. The description adds the endpoint path and clarifies it returns real money and bonus balances as a JSON structure. This matches annotations; no contradiction and no destructive behavior to disclose.

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?

Extremely concise: two lines cover the function purpose, endpoint, and return shape with 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?

Tool is trivial (no params, read-only, output schema present), and description gives enough for an agent to know what it returns. Minor gap: no mention that auth/API key context is implied or how errors are reported, but the simplicity and sibling ecosystem make this 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?

There are 0 parameters)Skip; no schema to compensate for. 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?

Description clearly states the tool retrieves wallet balance separating real money and bonus, with an explicit endpoint. The name 'avito_get_balance' matches this well. Sibling tools are all in different marketplaces or broader categories (auth, sections, etc.), so distinguishing is straightforward — though it doesn't explicitly name a sibling, the purpose is specific enough.

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?

No guidance on when to use this vs. alternatives. For a simple balance-checking tool with no parameters, the context is self-evident, but the description doesn't state exclusions or prerequisites like authentication being handled separately. No explicit 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 declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds value by noting the Messenger API requirement and the return JSON shape, which are not covered by annotations. No contradictions.

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 structured with an endpoint line, a prerequisite, then Args and Returns. It's informative but not overly verbose; sentences earn their place. Slight reduction could improve flow, but it remains concise.

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

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

Given the output schema exists and annotations cover read-only behavior, the description provides the essential usage details (endpoint, requirement, parameters, return shape). It lacks error handling or edge-case notes, but for a read-only list tool it is sufficiently 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 fully compensates by explaining each parameter: unread_only (filter), item_ids (comma-separated listing IDs), limit (page size <=100), offset (pagination <=1000). This adds meaning beyond the schema's types and defaults.

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 buyer chats and provides the specific endpoint. It distinguishes from siblings like avito_get_orders and avito_get_items by naming the resource (chats) and indicating the Messenger API context.

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 clear context (buyer chats) and a prerequisite (Messenger API enabled), but does not explicitly mention alternatives or when not to use this tool. The context is unambiguous enough for an agent to select it for chat-related tasks.

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

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

The annotations include readOnlyHint=true and openWorldHint=true, so the description is not required to repeat that it is a read-only operation. However, the description adds valuable behavioral context beyond the annotations: it specifies the rate limit (25 requests/min), the return structure (JSON with ok/meta/resources), and the pagination semantics (1-based page, per_page <100). It does not disclose potential errors or quota exhaustion details, but the rate limit itself is a significant disclosure. No contradiction with annotations.

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

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

The description is dense but efficient: it includes the HTTP endpoint, rate limit, parameter list, return format, and a note about pagination. The text is front-loaded with the primary purpose and key constraints. However, the parameter list is embedded in bullet-less text, which could be more structured for easier parsing, but it is still readable and not overly 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: 5 parameters, no required parameters, no schema descriptions, and an output schema that is not shown in detail, the description provides sufficient information for an agent to call the tool correctly. It covers all parameters, provides example values for status, explains the return structure, and notes the rate limit. However, it does not document the output schema's nested 'resources' array or potential error codes, which would be helpful. The output schema exists in the context, so the description doesn't need to detail return values, but it does briefly. Overall, it is mostly complete for making a correct call.

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 provides parameter names, types, defaults, but no descriptions (coverage 0%), so the description is responsible for explaining parameter meaning. The description clarifies 'status' values (active, removed, old, blocked, rejected), 'category' as Avito category ID with 0=all, and 'updated_from' as YYYY-MM-DD lower bound. However, it does not explain the 'page' and 'per_page' semantics beyond noting page is 1-based and per_page <100, which is covered. The description does not fully compensate for the complete lack of schema descriptions for all params, but it covers most critical details.

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 seller's listings (объявления) with status, category, and URL, and includes the HTTP endpoint. This distinguishes it from sibling tools like avito_get_stocks or avito_get_orders, but it does not explicitly name those alternatives, so it misses the top score for sibling differentiation.

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 usage context: it lists filter parameters (status, category, updated_from) and pagination (page, per_page), and it specifies the rate limit of 25 requests/min. It also directs the agent to use avito_fetch_all for retrieving all pages, which serves as a clear when-to-use alternative, though it doesn't explicitly state when not to use this tool beyond that.

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 openWorldHint=true, which already signal a safe, non-mutating operation. The description adds valuable constraints: max 200 ids, 270-day lookback, and return format. This exceeds the baseline by providing concrete operational limits and output structure, which is helpful for an agent to anticipate API 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 compact, starting with a one-line summary, then the endpoint, constraints, and parameter details in a clear list. Each sentence adds value—no filler. The front-loading of the purpose and endpoint makes it easy to quickly grasp the tool's role.

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 parameter descriptions in the schema, the description fully covers all four parameters and the return format. The output schema exists but is not provided in the prompt; however, the description already explains the return JSON structure, making the tool fully usable. Given its moderate complexity, nothing 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 0%, so the description must compensate for all parameters. It does so effectively: item_ids is described as comma-separated listing IDs, date_from/to are YYYY-MM-DD inclusive, and period_grouping is enumerated with options. The description even explains the output structure, providing full semantic meaning beyond the raw 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 purpose: retrieving views/contacts/favorites per listing per period. It specifies the API endpoint and parameter details, distinguishing it from sibling tools like avito_get_stocks or avito_get_items. The focus on stats metrics makes its unique function obvious.

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 retrieving performance metrics but does not explicitly state when to use this over alternatives like avito_get_items (which likely returns all item details). It provides constraints (up to 200 ids, 270 days) but lacks guidance on exclusions or prerequisites. This is adequate but not 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?

The readOnlyHint annotation already signals safety; the description adds that it returns hasMore paging, order deadline schedules, and availableActions. This goes beyond the annotation and helps the agent understand returned data and how orders can be acted on.

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?

Compact and well-structured: endpoint, scope, parameters, and return shape each take one short block. Every sentence adds information; 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?

Covers invocation scope, all parameter semantics, response envelope, and key returned fields (availableActions, schedules). Enough for an agent to call it correctly without external docs; output schema absence is compensated by the description.

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 provides 0% description coverage, but the description fully explains every parameter: statuses allowed values, date_from as unix timestamp, page 1-based, limit <=20. This is a model example of the description compensating for a sparse 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?

Clearly states the specific verb+resource: retrieving orders placed with Avito Delivery, via a named endpoint, scoped to B2C sellers. This distinguishes it from sibling tools like avito_get_stocks and ym_get_orders.

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

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

Gives clear context: this is for Avito Delivery orders, B2C sellers onlychers. It does not explicitly name alternatives or say when not to use it, but the scope is precise enough to guide selection.

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

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

The annotations already mark readOnlyHint and openWorldHint, and the description adds substantial behavioral context: default method is GET, host can be overridden, body is rare but possible on reads, and the response shape is disclosed. This goes well beyond the structured annotations.

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

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

The description is well-structured, front-loads the core behavior, and every sentence adds useful information. The argument list is terse but complete, with no filler or repetition of schema fields.

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 an open-world raw API tool with five parameters and no endpoint enums, the description provides everything an agent needs: target API reference, method constraints, parameter details, and return envelope. The output behavior is also covered despite the presence of 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 0%, but the description fully compensates by explaining every parameter: path format with example, method defaults, host override behavior, query-string parameters, and body semantics. This is exactly the kind of parameter documentation the schema lacks.

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 action and resource: 'Read ANY endpoint by path, including ones missing from the catalog.' It distinguishes itself from siblings like avito_write_raw and avito_delete_raw by explicitly restricting to safe verbs.

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: read operations via any endpoint, and directs the agent to 'avito_write_raw' for changes and 'avito_delete_raw' for deletions. It also limits usage to GET, HEAD, and OPTIONS, leaving no ambiguity about safe 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?

The `readOnlyHint: true` annotation already indicates a non-mutating operation, and the description adds context by specifying the endpoint and the returned structure. It does not contradict the read-only annotation, but it could have mentioned authentication requirements or pagination limits, though the limit parameter is already in the schema. The description adds useful behavioral context beyond the annotation, but not deeply.

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; the core purpose is stated in the first sentence, followed by the essential alternative and parameter documentation. Every sentence provides useful information without fluff, balancing completeness and efficiency.

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 simplicity of a paginated reviews list and the presence of an output schema that defines the response format, the description covers all necessary information: what is returned, pagination parameters, and the alternative for aggregate scores. The output schema eliminates the need to describe the return format further. The description is complete for effective tool invocation.

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

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

The schema only provides types and defaults for `offset` and `limit` with zero description coverage. The description explains that `offset` is the pagination offset and `limit` is the page size with a maximum of 50, adding crucial semantic meaning beyond the schema. This compensates for the lack of schema descriptions, going beyond 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?

The description clearly states that this tool retrieves published reviews on the seller, listing the specific fields (score, text, deal stage, seller's answer) and the API endpoint (`GET /ratings/v1/reviews`). It is easily distinguished from siblings like `avito_get_ratings_info_v1`, which is explicitly referenced for aggregate ratings. The verb 'get' and resource 'reviews' are 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 tells the user when to use this tool (for published reviews) and directs them to use `avito_get_ratings_info_v1` via `avito_call_method` for aggregate ratings. This clear routing prevents misuse and helps the agent select the correct sibling tool.

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

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

Annotations declare readOnlyHint=true, which matches the read-only nature. The description adds the return structure (list of operation_id, method, path, safety, summary) and the source of the section name, providing useful context beyond the annotations. It does not mention error behavior, but for a simple read operation this is acceptable.

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 with Args and Returns sections. The main purpose is front-loaded, and every sentence adds value without 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?

The tool has a single parameter, an output schema is present (though not shown), and the description covers purpose, parameter source, and return format. It lacks explicit mention of error handling or limits, but for a straightforward list endpoint this is likely 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 schema has no description for the 'section' parameter (0% coverage), but the description fully compensates by explaining it's a section name, directing to avito_list_sections for valid values, and giving an example ('statistics'). This makes the parameter's meaning clear and actionable.

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 all endpoints in a given section, with a specific verb and resource. It references avito_list_sections for obtaining section names, which distinguishes it from sibling tools that list sections or search methods.

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 a pointer to avito_list_sections for the section parameter, implying you need to list sections first. However, it does not explicitly state when to use this tool over alternatives like avito_search_methods or avito_map, leaving the decision to the agent.

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

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

Annotations already flag readOnlyHint=true, and the description adds genuine value beyond that: the 500-id-per-call limit and the returned field list. It also details the HTTP endpoint, though this is mostly mechanical. There is no contradiction with annotations — the POST verb refers to fetching stock info, consistent with a read operation. It stops short of covering failure modes or what happens when ids exceed the batch limit.

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 five tight fragments front-loaded with purpose, then the endpoint, the 500-id limit, parameter format, and return shape. There is no filler, and each sentence earns its place. The mixed prose/code formatting (Args:/Returns JSON:) is slightly informal but clear and efficient.

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 read tool, the description covers the essentials: what it returns, input format, and the batching limit. The presence of an output schema relieves it of explaining the full return envelope, and the readOnlyHint annotation covers safety. Minor omissions — rate limits and invalid-id behavior — are acceptable given the tool's simplicity and available structured metadata.

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 carries the full burden for the single parameter. It fully compensates by stating 'comma-separated Avito listing ids' — a critical formatting detail an agent needs to invoke the call correctly. The batch ceiling (500 ids) also helps an agent shape valid input.

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

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

States a specific resource ('Stock per listing') and does a read operation distinct from its write sibling avito_update_stock. It names the endpoint (POST /stock-management/1/info) and the exact data fields returned (quantity, is_unlimited, is_out_of_stock), leaving no ambiguity about what the tool fetches. Among avito siblings (get_items, get_orders, get_stocks) the stock focus is unambiguous.

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

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

The description conveys the operational constraint 'Up to 500 ids per call', which implies batching for larger inputs, and the tool's read-only purpose is clear from the name and readOnlyHint. However, it never explicitly contrasts this with alternatives like avito_get_items or avito_update_stock, so an agent must infer when to pick stocks over the other avito listing/stock tools.

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

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

The description clearly indicates a read-only retrieval ('Return the full plan') and specifies the content included. It does not mention permissions or error behavior, but for a getter whose safety profile is otherwise implied, this is a minor gap.

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?

Definition is concise: one front-loaded sentence for purpose, one bullet for the parameter. No redundant fluff, no repetition of schema details.

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?

Together with the schema and sibling list, an agent has enough to know what this tool does)Skip, which argument to supply, and where to discover valid IDs. It doesn't state the output shape, but the plan description covers the functionally important parts.

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 description documents the only parameter ('workflow name') and points to the source of valid values ('see {svc}_list_workflows'), adding practical guidance beyond the schema's bare string type. It stops short of giving an example or format.

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 ('Return') and resource ('the full plan for one workflow') and enumerates the concrete contents (ordered steps naming catalog operation_ids, interpretation guidance, common mistakes). This clearly differentiates it from workflow listing and other marketplace 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 tells the agent exactly when to use it (when the full plan for a single workflow is needed) and points to {svc}_list_workflows to resolve the workflow name. It does not explicitly name negative cases or alternatives, but sufficient context is present.

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 holistically, and the description adds important behavioral context: 'Secret values are never returned.' This reassures agents about data sensitivity beyond what the schema or annotations convey, and the explicit JSON return shape clarifies what the agent can expect.

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 compact sentences immediately state the action and return JSON shape, with no filler. The secret-value disclaimer is a single clause that earns its place for safety. This is appropriately sized and 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 zero-parameter read tool, the description is complete: it identifies the resource, states what the output will look like (including the fields_needed array), and sets security expectations. The agent has all necessary context to call the tool correctly without needing 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?

The tool has zero parameters distorted, and schema description coverage is 100%, so the schema carries no burden. The description adds the 'for this marketplace' setup context, but with no parameters to explain, the baseline for a zero-parameter tool is a strong 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 uses a specific verb and resource: 'List configured cabinets for this marketplace and which one is active.' It clearly distinguishes from sibling tools like avito_use_cabinet, avito_add_cabinet, and avito_remove_cabinet by focusing on discovery rather than mutation or selection.

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 the tool is for inspecting configured cabinets and identifying the active one, but it does not explicitly state when to use it versus siblings or provide any exclusions. The context is clear enough for a simple read operation, but there is no direct alternative routing.

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 openWorldHint=false, so the agent knows this is a safe read operation. The description adds the useful detail that the output includes counts of catalog endpoints per section, which is not visible in the schema. However, it doesn't describe the return format or whether the list is exhaustive, but with annotations covering the safety profile, a 3 is appropriate.

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?

One sentence, zero waste, and the key information (what is listed and what counts are included) is front-loaded. 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-only listing tool with an output schema present, the description is nearly complete. It tells the agent what it will get (sections and endpoint counts). It doesn't mention pagination or whether the list is sorted, but those are minor for a discovery tool. The output schema likely covers return structure, so nothing critical is missing.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The schema is trivially complete (100% coverage with no properties). The description adds meaning about what the response contains (section names and endpoint counts), which is the only semantic content needed. Baseline 4 for zero-param tools 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 states a specific verb ('List') and resource ('API sections'), and adds the detail that it returns the count of catalog endpoints per section. This is clear and distinguishes it from tools like avito_get_section, which retrieves a single section's details. It doesn't explicitly name a sibling, but the scope is specific enough.

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 this is the discovery/overview tool for API sections, and the sibling list shows many similar list_sections tools for other marketplaces (ozon_list_sections, wb_list_sections, ym_list_sections). However, it doesn't explicitly state when to use this over avito_get_section or avito_search_methods, nor does it mention any exclusions or prerequisites. Usage context is implied but not 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 already declare readOnlyHint=true (safe read) and openWorldHint=false (known result set), so the description does not need to repeat those. The description adds useful behavioral context: the return format (JSON with fields name, category, when_to_use) and the pointer to get_workflow for detailed steps. This adds value beyond annotations without contradicting them.

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

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

The description is two sentences with zero waste. It front-loads the core action, specifies the output format, and immediately points to the companion tool. Every sentence 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?

The output schema exists (provided as true), so the description need not elaborate further on return values. The description covers the tool's purpose, return format, and how to proceed for more detail. Complete for a no-parameter listing tool; the only minor gap is not explaining 'recipes' in depth, but the context makes it clear.

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 parametersholistic, so parameter semantics is largely irrelevant. The description focuses on the output structure (name, category, when_to_use), which is more relevant here. With no parameters, the baseline is 4, and the description appropriately avoids misleading parameter information.

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 verb ('List') and resource ('ready-made analytical workflows (recipes) for this marketplace'), and immediately distinguishes itself from siblings by naming the companion tool 'avito_get_workflow' for fetching full details. This distinguishes it from the many other 'list_workflows' siblings by the 'avito' context.

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 tells the agent to use {svc}_get_workflow to fetch the full plan for one workflow, providing clear usage context. It does not explicitly exclude alternative tools, but for a list operation, the primary alternative is the get_workflow, which is named. This is clear enough for a no-parameter 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?

The readOnlyHint is already present, but the description adds meaningful behavioral detail: calling with no arguments returns the whole map, and passing an entity lists every method of that entity. It makes the boundary of the tool's behavior clear without repeating the annotation content.

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: one sentence states purpose, the second gives exact call modes, and the third gives practical guidance. No sentence is redundant; the playfully unquoted 'you are here' helps orient the agent without bloating the text.

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 a simple one-parameter optional schema, read-only annotations, and an output schema, the description covers everything an agent needs to know to start using the tool correctly. It also teaches the higher-level strategy of using the map before searching, which is useful 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?

With 0% schema description coverage, the description carries the parameter documentation load. It clarifies that entity is optional, gives the no-argument default behavior, and provides concrete example values like 'reviews' and 'stocks'. A fully exhaustive list of accepted entity values would have earned a 5.

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

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

The description clearly identifies the tool as a map of business entities and their go-to methods, and explicitly distinguishes the two invocation modes: no arguments for the whole map, or an entity name to list methods for that entity. It names the resource and behavior in a way an agent can use without opening the schema.

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 clear when-to-use guidance by saying 'Use this before guessing' and explains exactly when to pass the entity argument. It does not explicitly name alternatives or exclusions, such as using avito_search_methods or avito_describe_method when more detail is needed, which keeps it from 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?

The description discloses the destructive action and the notable side-effect that another cabinet becomes active if the removed one was active. This goes beyond the destructiveHint annotation and adds useful operational 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 compact and front-loaded: it states the operation first, then the side-effect, then the argument. Every sentence earns its place with 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 simple, one-parameter destructive tool, the description covers the operation, the parameter, and the key side-effect. It omits usage alternatives, but the tool is straightforward and an output schema is present.

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 0% schema description coverage, the description supplies the essential meaning: name is the cabinet to remove. This directly maps the single required parameter to the operation, though it adds no finer detail about naming or format.

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 ('Delete') and the specific resource ('a stored cabinet'), and adds a meaningful side-effect detail. This distinguishes it from sibling tools such as avito_add_cabinet, avito_list_cabinets, and avito_use_cabinet.

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 no guidance on when to prefer this tool over cabinet-related alternatives, nor does it mention exclusions or prerequisites. The active-cabinet fallback is a behavioral fact, not usage direction.

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 openWorldHint=false, so the safety profile is clear. The description adds valuable behavioral details: it works in both Russian and English, and returns results 'best first'. These traits are not in the annotations and help the agent set expectations. It does not mention pagination or rate limits, but for a simple search over a catalog this is acceptable given the read-only guarantee.

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. It opens with a single-sentence summary that front-loads the purpose, followed by a compact 'Args' section that explains both parameters in minimal lines. It ends with a clear 'Returns' statement. There is no redundancy or fluff—every sentence earns its place, and the formatting is easy to parse.

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

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

For a read-only search tool with only two parameters and an existing output schema, the description covers all essential aspects: purpose, parameter semantics, return format, and language support. Since an output schema exists (indicated by the context signal), the description does not need to enumerate fields. The description provides enough for an agent to call the tool correctly without further information.

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

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

Schema description coverage is 0%, so the description must fully compensate. It does: for 'query' it specifies 'free text' and gives concrete examples ('остатки', 'stocks', 'update price'), and for 'limit' it states 'max results (1-50)'. This goes beyond the schema's type and default, providing meaning, constraints, and examples that an agent can use directly. This is exactly what a good description should do when the schema is bare.

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: 'Search the endpoint catalog by keyword' – a specific verb (search) with a distinct resource (endpoint catalog). It also highlights bilingual support (Russian and English), which helps separate it from most sibling tools that operate on specific endpoints or sections. The presence of sibling tools like avito_list_sections and avito_describe_method makes the differentiation meaningful; this tool is for searching the catalog, not listing or describing a single item.

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: when an agent needs to find an endpoint by keyword, possibly across many catalogs. It does not explicitly state when NOT to use it or mention alternative tools (e.g., for listing all sections or workflows). However, the purpose is clear enough that an agent can infer the right context. A brief mention of alternatives would push this to a 5, but it's not necessary for a search 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?

Beyond annotations, the description discloses that the key enters the chat transcript, requires an explicit confirmation flag, is saved locally with chmod 600, and is never echoed back. It also notes on success the key is validated and the shop name reported. No contradiction with annotations.

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

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

The description is dense but purposeful: it front-loads the privacy warning, gives a safety alternative, then lists arguments and success behavior. The unresolved `{fields}` placeholder is a content defect, but overall structure is clean and earned.

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

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

It covers default behavior, confirmation requirement, privacy, local file permissions, validation, and success reporting. However, it does not enumerate the required credential fields a caller must provide, and it omits any failure-mode or permission guidance. The presence of an output schema reduces the need to describe return values, but the credentials gap makes the tool not fully self-contained.

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?

Cabinet and i_understand_key_goes_to_chat are well explained, including default behavior and the true requirement. However, credentials is described only as 'dict with the required fields ({fields})', which is an unresolved template rather than concrete field names. Since schema description coverage is 0%, this gap leaves the most important parameter underspecified.

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

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

The description opens with 'Change / rotate the API key from chat', which names a specific verb, resource, and context. It distinguishes this tool from siblings like avito_add_cabinet by targeting key rotation rather than cabinet management.

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 'The safe, terminal-free alternative is the installer, where the key never enters chat' and recommends rotating in the seller cabinet if the key was exposed. It also explains the default cabinet behavior with the example 'my key expired', so an agent knows when and how to call this 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?

Beyond the annotations (readOnlyHint: false, idempotentHint: true), the description discloses the confirm_write prerequisite, rate limit, category restrictions, and the exact JSON return format. These are behavioral traits an agent needs to know and are not present in the annotations or schema. No contradictions with annotations were found.

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, then states requirements and constraints, lists parameters, and finishes with the return format. Every sentence adds value; there is no redundancy or fluff.

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

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

For a mutation tool with a confirmation flag, rate limit, and category restrictions, the description covers everything needed to call it correctly: purpose, parameter meanings, constraints, and return value. It even provides the exact JSON structure. Given the output schema is not separately provided, the inline return description 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 input schema has no parameter descriptions (coverage 0%), but the description explicitly explains all three parameters: item_id as 'Avito listing id', price as 'new price in roubles (integer)', and confirm_write as 'must be true to send'. This fully compensates for the schema's lack of documentation and adds essential meaning.

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 'Set the price of ONE listing', which is a specific verb and resource. It also names the API endpoint and explicitly notes it is a WRITE operation. This clearly distinguishes it from siblings like avito_update_stock while providing a precise scope.

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

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

The description gives clear usage context: it is for setting the price of a single listing, with explicit constraints on allowed categories ('Goods, spare parts, cars, real estate only') and a rate limit (150 requests/min). It also requires confirm_write=true. However, it does not explicitly name an alternative tool for other actions (e.g., stock updates), though the sibling list makes that obvious. This is a clear context with some exclusionary guidance, but no named alternatives.

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

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

Annotations already indicate readOnlyHint=false (write) and idempotentHint=true. The description adds critical behavioral details: confirm_write must be true, quantity=0 hides the 'buy with delivery' button, and the exact response shape. These go beyond the annotations and are essential for correct invocation. 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 well-structured: a one-line purpose with endpoint, a behavioral note, a clear argument list, and the return format. It is a bit long but every sentence adds value. The main purpose is front-loaded, and the argument details are neatly formatted.

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 write operation with three parameters, the description covers everything an agent needs: the purpose, the required flag, the quantity range, and the response schema. There is no missing information about prerequisites, side effects, or error handling. The output schema also exists, so the return format is redundantly specified but harmless.

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 carries the full burden. It explains every parameter: item_id is the listing id, quantity is the available units with a range (0..999999), and confirm_write must be true. It also clarifies that quantity 0 has a UI effect. This fully compensates for the lack of 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 states a specific action ('Set the available quantity'), the resource ('ONE listing'), and even the HTTP endpoint. It clearly distinguishes from sibling tools like avito_update_price (price) and avito_get_stocks (read). No ambiguity about what the 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?

The action itself makes the usage context clear: it's for setting stock quantity, not for price or reading. While it doesn't explicitly name alternatives, the purpose is so unambiguous that an agent would know when to invoke it. There are no exclusion criteria, but none are needed given the specific verb-resource pairing.

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

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

The description discloses the key behavioral side effect: switching the active cabinet affects all subsequent API calls by using that cabinet's credentials. This complements the annotations (readOnlyHint=false, idempotentHint=true) and does not contradict them, making the agent aware that this is a state-changing operation with lasting effect.

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 minimal and front-loaded, delivering the core purpose in the first sentence and the relevant parameter detail in a single Args line. Every sentence earns its place; there is no boilerplate or repetition of schema or 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?

For a tool with one required parameter, an output schema, and no nested objects, the description covers the necessary behavior (switching active cabinet) and parameter provenance. Nothing an agent needs to invoke it correctly is missing, and the output schema handles return-value 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?

The input schema provides only a parameter title 'Name' with no description, but the description fully compensates by explaining 'name: the cabinet to activate (see avito_list_cabinets).' This tells the agent not only what the parameter means but also where to obtain valid values, making it a complete semantic definition.

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 the specific verb-resource pair 'Switch the active cabinet,' clearly identifying the tool's function. It distinguishes itself from cabinet-management siblings such as avito_list_cabinets, avito_add_cabinet, and avito_remove_cabinet by stating that it changes the currently active cabinet and that subsequent API calls use that cabinet's credentials.

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 a clear usage context: use this tool whenever the agent needs to change which cabinet's credentials will govern subsequent API calls. It does not explicitly name alternatives or exclusions, but the side-effect phrase 'Subsequent API calls use its credentials' provides an unambiguous signal of when the tool is appropriate.

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 readOnlyHint annotation already covers safety, and the description adds useful behavioral context: the returned fields, the JSON wrapper, and the credential-verification purpose. It does not describe error behavior for invalid credentials, but this is a low-risk read endpoint.

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 compact sentences lead with the key output, explain why the id matters, and include the return shape. Every sentence earns its place with 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?

For a zero-parameter read-only identity tool, the description covers selection and invocation: what it returns, why the id matters, and how it can verify auth. The output schema covers remaining return 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?

There are no parameters and the input schema is empty, so the description has nothing to add. The baseline for a zero-parameter tool is appropriate here.

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 the resource (authorized Avito account) and the exact fields returned, and it notes the id's downstream role as user_id. It lacks an explicit action verb like 'get' and slightly overlaps with the avito_check_auth sibling, so it is not a 5.

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 two concrete use cases: obtaining the user_id needed by other methods and cheaply verifying credentials. It does not name exclusions or explicitly contrast itself with avito_check_auth, but the intended context is clear.

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

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

Annotations already cover readOnlyHint=false and destructiveHint=false, so the bar is lower. The description adds meaningful behavioral context: nothing is sent without confirm_write=true, create/update are reversible while delete is separate, and the response is a JSON envelope. This is useful safety-relevant information 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 compact and front-loaded: purpose first, then target API, safety condition, sibling routing, parameter list, and return shape. Every line earns its place, and there is 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?

Given the tool's generic nature, the description gives enough to call it correctly: where to find endpoint ids, how parameters map to request construction, the confirmation requirement, and the return envelope. It could add a small example, but the existing content plus the output schema context is largely 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 carry the burden, and it does for all five parameters. It explains operation_id as a catalog id, path_values as {placeholder} substitutions, query and body as request parts, and confirm_write as a required safety flag. The explanations are brief but sufficient for a generic catalog execution 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?

States a specific action plus scope: 'Execute one WRITE endpoint from the catalog: create or update data.' It also differentiates from siblings by naming avito_call_method for reads and avito_delete_method for irreversible operations, so an agent can distinguish it from the other generic execution 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?

Gives clear routing guidance: writes belong here, reads in avito_call_method, irreversible operations in avito_delete_method. It also warns that confirm_write=true is required and that nothing is sent without ithola. It does not explicitly address specialized write siblings like avito_update_price or avito_update_stock, but it covers the main generic-vs-specialist decision.

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 adds the confirm_write requirement, method restrictions, and the return format. It does not detail error handling or side effects, but given readOnlyHint false and openWorldHint true, it sufficiently discloses behavioral traits.

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 purpose, followed by constraints and parameter semantics. Every sentence contributes, with 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?

Given the output schema exists and annotations cover safety, the description is complete enough for an agent to call it correctly. It includes all essential operational details, though it omits explicit authentication prerequisites.

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 0% schema description coverage, the description compensates fully by explaining each parameter: method values, path format, host default, query, body, and confirm_write requirement. This adds significant meaning 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 it creates or updates data at any path, including uncatalogued paths, and lists allowed methods (POST, PUT, PATCH). This distinguishes it from siblings like avito_get_raw and avito_delete_raw, 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 implies usage for arbitrary raw writes, especially paths outside the catalog, but does not explicitly name alternatives or state when to prefer them. It provides clear context but lacks explicit exclusions.

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