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

Annotations indicate destructiveHint=false and idempotentHint=true, but the description discloses critical behaviors: the key will be placed in the chat transcript, and the cabinet is saved to ~/.marketplace-mcp/cabinets.json with chmod 600 and is never echoed. This adds significant context about data handling and security 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 well-structured with a clear warning first, then a concise list of arguments, and storage details. Every sentence adds value: risk, alternative, parameter details, and persistence information. It is not overlong and is front-loaded with the most critical information.

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

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

For a tool with 3 parameters (one nested object) and an output schema, the description is complete. It explains parameter formats, default behavior, security implications, and storage location. No critical information is missing for an agent to correctly invoke the tool.

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

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

Schema description coverage is 0%, but the description fully explains the 'credentials' parameter with concrete examples for Ozon and WB, the optional 'name' parameter with default naming behavior, and the 'i_understand_key_goes_to_chat' flag with its required value. This compensates completely 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 clearly states the tool's purpose: to add or update a cabinet (a named set of API credentials) from chat. It distinguishes itself from the safe alternative (installer) and from sibling tools like wb_add_cabinet and ozon_add_cabinet by mentioning the security risk of putting keys in chat.

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

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

Explicitly states when to use: when adding or updating a cabinet from chat, and explicitly warns about the security risk, requiring the user to confirm with i_understand_key_goes_to_chat=true. It also recommends the installer as a safer alternative, providing clear guidance on when not to use 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, destructiveHint=true), the description discloses critical gating behavior: destructive requests are not sent unless both confirm_write and i_understand_this_modifies_data are true, and read/write behaviors are differentiated. It also specifies the success and error envelope, adding real behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with the core purpose, followed by clear safety rules, a compact argument list, and a return-type statement. The minor repetition of confirmation requirements in both the prose and argument list reinforces important safety conditions 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?

For a generic catalog dispatcher, the description covers the method catalog source, path/query/body inputs, write/destructive guards, and return envelope. It does not explicitly explain how avito_call_method differs from avito_call_raw or avito_fetch_all, which would make selection more robust, but the core operational details are 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 must carry the explanatory burden for six parameters. It provides a useful one-line meaning for each parameter, especially explaining operation_id's source and the semantic distinction between confirm_write and i_understand_this_modifies_data. It remains generic for path_values, query, and body, giving no format or example details, but it is sufficient for a flexible dispatcher.

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 'Execute one catalog endpoint by operation_id,' which names a specific verb and resource and clearly identifies the dispatch role of the tool. It implies distinction from siblings like avito_fetch_all and avito_call_raw through 'one' and 'catalog endpoint,' but it does not explicitly contrast itself with those 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?

It gives practical guidance on when confirmation flags are required: read endpoints run immediately, write endpoints need confirm_write, and destructive endpoints need the extra acknowledgement. However, it does not explicitly state when to choose this tool over avito_call_raw, avito_fetch_all, or other sibling tools; the guidance is about invocation conditions rather than tool 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 description explains that safety is inferred from the HTTP verb (GET=read, POST/PUT/PATCH=write, DELETE=destructive) and mentions confirmation rules, which adds value beyond the annotations. The annotations indicate destructiveHint=true and readOnlyHint=false, but the description details the verb-based safety inference and confirmation parameters, which is useful. However, it doesn't detail potential side effects beyond modification, like rate limiting or irreversible changes, but the confirmation mechanism is a strong addition.

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 clear opening sentence, a safety note, a parameter list in bullet format, and a return value description. Each sentence serves a purpose, and it is front-loaded with the core purpose. It is slightly verbose in listing every parameter, but this is necessary for a raw call tool. Overall, it is efficient and clear.

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

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

Given the complexity of a raw API caller with 7 parameters and no schema descriptions, the description covers all essential aspects: what it does, how safety is determined, confirmation requirements, parameter semantics, and return format. The output schema exists, so return details are not repeated. It is complete for an agent to correctly select and invoke this tool.

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

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

The schema provides minimal descriptions for the parameters, with 0% coverage. The description compensates significantly by explaining each parameter's role (e.g., method as HTTP verb, path as full path, host as override, query and body as request components) and the confirmation flags. This is much more informative than the bare schema, earning a high score despite 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 clearly states the tool's purpose: to execute ANY endpoint, even those not in the catalog, providing full API coverage. It specifies the verb (execute), resource (endpoint), and scope (any), distinguishing it from sibling tools that are catalog-specific, such as avito_call_method or avito_describe_method.

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 endpoints not covered by catalog tools and indicates when to use it (when you need full API coverage). It does not explicitly name alternatives or say when NOT to use it, but the context of 'ANY endpoint' and the existence of catalog methods suggests it is for cases beyond those. It could be improved by explicitly stating to prefer catalog methods when available.

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

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

Annotations declare readOnlyHint=true, which aligns with the description's non-mutating nature. The description adds value by explicitly promising not to reveal secret values — a key behavior not inferable from annotations alone. It also discloses the return format, which is helpful for downstream use.

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 concise sentences with no fluff. The first sentence quickly states the function, the second emphasizes the security guarantee, and the third states the return format. All essential information is front-loaded, making it easy for an agent to parse and act.

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 check tool with a clear output schema, the description fully covers what an agent needs to know: what it does, what it doesn't do, and what it returns. There's no missing information given the low complexity.

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

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

The tool has zero parameters)Skip the redundancy. The description clarifies that no parameters are needed, which is implicit in an empty schema. Since there are no parameters, the baseline for this dimension is high (4) even without description. The description adds no param info because there are none, so it doesn't need to compensate. Given the rule '0 params = baseline 4', and the description's clarity about the tool's purpose, a 5 is justified.

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

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

States a specific verb ('check') and resource ('credentials'), and the environment context. Distinguishes itself from sibling auth checks (e.g., 'wb_check_auth', 'ozon_check_auth') by the 'avito_' prefix and the explicit mention of environment credentials. It clearly indicates it is a readiness check for authenticated use.

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 it (checking credentials before operations) but does not explicitly state when to use it versus alternatives like 'avito_set_key' or 'avito_whoami'. It doesn't mention prerequisites or exclusions, but it clearly says it does NOT reveal secrets, which is a useful boundary.

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 readOnlyHint annotation already signals safety, and the description adds useful behavioral detail: cursor fields are managed, max_items caps context, and results may be truncated. This enriches the agent's understanding of side effects beyond what annotations alone provide, with no contradiction.

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

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

The description is front-loaded with the core purpose and then uses a compact Args block to define parameters. It is somewhat verbose but every line adds necessary details for this multi-parameter tool, 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?

Despite the lack of schema descriptions, the description provides enough operational context to correctly use the tool: supported pagination styles, the return payload keys, the cap on items, and the cancellation via operation_id. It could additionally explain how to discover valid operation_ids from the catalog, though this is arguably covered by sibling catalog/describe tools.

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 useful meaning to every parameter, especially items_path, limit, max_items, and the managed pagination fields. It could still clarify value formats for items_path and how path placeholder substitutions are handled, which keeps it from 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 first sentence states a specific behavior: auto-paginate a read endpoint and return every row in one response. This clearly distinguishes it from sibling call/raw/get tools, which handle single requests or specific data types rather than full pagination.

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 a read endpoint is paginated and all rows are needed. However, it never explicitly contrasts it with alternatives like avito_call_method or the more specific avito_get_items/get_orders tools, so the agent must infer substitution logic.

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 `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 already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds that it returns a JSON list of endpoint metadata (operation_id, method, path, safety, summary), which is useful behavioral context beyond the schema. It does not disclose pagination, error behavior, or whether the section must exist, but given the read-only annotation, 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?

The description is compact and front-loaded: the first sentence states the action and resource, followed by a concise Args/Returns breakdown. Every sentence earns its place, though the Returns line is somewhat redundant with the output schema.

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

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

For a simple one-parameter read-only tool with an output schema, the description is mostly complete. It explains the parameter source and return shape. However, it does not clarify what happens for an invalid/unknown section, whether the list is sorted, or how this relates to sibling discovery tools like avito_search_methods and avito_map.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain that 'section' is a section name and references {svc}_list_sections for valid values, with an example. This adds meaning beyond the bare schema property, but it is terse and does not enumerate possible sections or format constraints.

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

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

The description states a specific verb ('List') and resource ('all endpoints in one section'), and clarifies the output format. It is distinguishable from sibling tools like avito_list_sections (which lists sections) and avito_describe_method (which describes a single method), though it does not explicitly name those siblings.

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

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

The description implies usage: call it with a section name obtained from {svc}_list_sections. It gives an example section ('statistics') and notes the return type, but it does not explicitly state when to prefer this over avito_search_methods, avito_map, or avito_describe_method, nor does it mention any exclusions.

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, and the description goes beyond that by explicitly stating that secret values are never returned and describing the JSON shape. For a safe read-only list operation, this is useful behavioral disclosure without contradiction.

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

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

The description is brief and front-loaded with the core action, followed by a precise return-shape note and a data-safety guarantee. Every sentence adds value and none repeats the schema.

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

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

For a zero-parameter, read-only listing tool with annotations and an output schema, the description covers purpose, active-cabinet semantics, needed fields, and the important secret-nondisclosure behavior. Nothing required to call it correctly is missing.

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

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

The tool has zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. The baseline of 4 for zero-parameter tools applies.

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

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

The description uses a specific verb ('List') and resource ('configured cabinets') and clarifies it reports the active cabinet. This distinguishes it from marketplace-specific section/method/cabinet management tools like avito_add_cabinet or avito_get_section.

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 intended usage is implicit: call it to see configured cabinets and the active one for Avito. It gives no explicit when-not guidance or comparison with sibling tools such as avito_use_cabinet or wb_list_cabinets, but the context is reasonably inferable for a zero-parameter read operation.

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?

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds useful behavioral detail beyond that: the no-arg default returns the whole map, and the entity argument scopes results to one entity's methods. This is meaningful context for an agent deciding how to invoke it.

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

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

The description is two sentences with no filler, front-loads the tool's core purpose, and then immediately provides the two invocation patterns. Every sentence earns its place, and the examples are tightly integrated.

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, read-only discovery tool with one optional parameter and an output schema already present, the description covers purpose, usage, default behavior, and parameter semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden for explaining the 'entity' parameter. It succeeds by giving example values (reviews, stocks, prices, orders), explaining that omitting it returns the whole map, and defining what the parameter does. This fully compensates for the bare 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 identifies the tool as a high-level discovery index: it shows the business entities the API covers and the go-to methods for each. It explains the two main behaviors (whole map vs. per-entity method list), which distinguishes it from sibling search/describe tools, although it does not name those siblings explicitly.

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

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

It gives explicit invocation guidance: call with no args for the full map, or pass entity='reviews' (etc.) for a single entity's methods. The instruction 'Use this before guessing — it orients you fast' provides a clear when-to-use signal, though it stops short of naming alternative tools or stating when not to use it.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds a meaningful behavioral trait beyond the annotations: deleting an active cabinet automatically promotes another cabinet to active. This is valuable context, though it does not cover failure modes or permission requirements.

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 short sentences plus a one-line Args block. It leads with the action, then the key side effect, with no filler, no repeated schema information, and no unnecessary wording.

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 an output schema present and a single, well-explained parameter, nothing critical is missing. The active-cabinet fallback is disclosed, and annotations cover safety. It stops short of saying what happens if the name is unknown or nonexistent, but that is minor for such a simple destructive tool.

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

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

The input schema has 0% description coverage, leaving 'name' as a bare string with title 'Name'. The description's 'Args: name: the cabinet to remove' supplies the necessary semantic mapping, making clear that name identifies a stored cabinet. This fully compensates for the bare 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 starts with a specific verb and resource: 'Delete a stored cabinet.' It also discloses the side effect ('If it was active, another becomes active.'), which clarifies the tool's exact scope. This clearly distinguishes it from sibling cabinet-list/add/use 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 states what the tool deletes but gives no explicit guidance on when to use it versus related tools like avito_use_cabinet or avito_add_cabinet. Usage is implied by the verb 'Delete' and the resource 'cabinet,' but no exclusions, prerequisites, or alternative routing are provided.

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 that this is a safe, read-only operation. The description adds useful behavior by noting that it returns a JSON list of matching endpoints sorted best-firsttw. It does not mention rate limits or errors, but those are less critical for a read-only search tool.

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

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

The description is concise, well organized, and free of unnecessary detail. The purpose is stated first, arguments are clearly labeled, and examples are directly useful.

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

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

The description covers the core invocation details: keyword search, multilingual support, limit, and result format. It could be slightly stronger by directing users to map or describe_method for browsing or details, but nothing essential is missing for a read-only search tool.

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

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

The description adds real value beyond the schema: it explains that query is free text, gives Russian and English examples, and clarifies the limit range. Both parameters are covered with enough context for an agent to use them correctly.

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 searches the endpoint catalog by keyword grados and explicitly mentions Russian and English support. This distinguishes it from execution tools like avito_update_price and from other platform-specific search tools.

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

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

The description gives practical usage details with query examples and a limit parameter, but it does not explain when to prefer this tool over related tools such as avito_map or avito_describe_method. The intended use is implied, 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?

Goes well beyond annotations: discloses that the key enters the chat transcript, requires an explicit acknowledgment flag, validates the key on success, saves locally with chmod 600, and never echoes it back. This adds significant context beyond the basic readOnly/destructive hints.

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 security warning up front, followed by concise parameter explanations. Every sentence adds value, and the length is justified by the sensitive nature of the operation.

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 security implications, default behaviors, validation, and storage details. Given an output schema exists, the description provides all necessary information for correct invocation without redundant return-type explanation.

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%, but the description fully compensates. It explains the credentials dict's purpose, the cabinet parameter's default and fallback behavior, and the i_understand_key_goes_to_chat flag's requirement. Each parameter is given meaningful context.

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: to change or rotate an API key, with a concrete use case (expired or leaked). It distinguishes itself from sibling set_key tools (e.g., wb_set_key, ozon_set_key) by explicitly mentioning the marketplace and the security caveat.

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

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

Provides explicit when-to-use guidance (key expired/leaked) and alternatives (installer, seller cabinet rotation). Also clarifies default behavior for cabinet selection, making it easy for an agent to decide when 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?

Annotations declare idempotentHint=truehare= and readOnlyHint=false (so it's a mutation), but the description clarifies that the effect is persistent: 'Subsequent API calls use its credentials.' This is a key behavioral trait—the tool changes state for future calls—which is not fully captured by the annotations. It doesn't mention side effects like needing authentication, but the idempotent hint implies repeated calls are safe, and the description adds enough context for safe invocation.

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 and front-loaded with the core purpose in the first sentence. The second sentence explains the argument. No wasted words; every sentence contributes to understanding the tool's purpose and usage.

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

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

The tool has a single parameter and a simple action sequence: switch cabinet and use credentials. The description explains the effect on subsequent callsiki and where to get the cabinet name (references list_cabinets). It doesn't detail output (though there is an output schema, which likely covers return values), and it doesn't explain error cases, but for this simple switching action, the context provided is sufficient for an agent to execute correctly.

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

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

The schema describes 'name' as a string with no additional details. The description adds value by indicating that 'name' is 'the cabinet to activate' and references the list tool for valid values. This is helpful for selecting the correct parameter value. However, since there's only one parameter and the description is brief, it doesn't add extensive semantic detail, but it does clarify the meaning beyond the bare 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 explicitly states the tool's function: 'Switch the active cabinet. Subsequent API calls use its credentials.' This clearly identifies the verb (switch), the resource (cabinet), and the consequence (API calls use its credentials). It differentiates from siblings by the action and the 'use' prefix in the name, though it doesn't name a specific sibling to avoid.

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 it: when you need to change the active cabinet before making subsequent API calls. However, it does not explicitly state when not to use it or mention alternative tools (e.g., list cabinets to see available ones). It references '{svc}_list_cabinets' for the argument, which provides some guidance on where to get valid names, but leaves the decision-making 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?

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.