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

The description adds substantial value beyond the annotations: it warns that the key enters the chat transcript, states the save location (~/.marketplace-mcp/cabinets.json) with chmod 600, and notes that the key is never echoed. This is exactly the kind of behavioral context the agent needs for a credential-handling write operation, and it does not contradict the annotations (readOnlyHint=false, idempotentHint=true).

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: the critical warning is front-loaded, arguments are clearly listed, and there is no unnecessary fluff. It is a bit longer than necessary due to the placeholder and examples, but overall it is efficient and scannable.

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 omits essential details for correct use: it does not specify the required credential fields for Yandex Market (the '{fields}' placeholder is never filled), nor does it explicitly state which marketplace this tool serves. Given that this is a write operation storing sensitive data, an agent would not be able to construct valid credentials without additional 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?

With 0% schema description coverage, the description must explain all parameters. It does explain credentials (dict), name (optional with fallback), and the boolean flag. However, the credentials parameter uses a placeholder '{fields}' and only provides examples for Ozon and WB, not for the actual Yandex Market service this tool targets. This is a significant omission that prevents correct invocation.

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

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

The description clearly states the tool adds or updates a cabinet (a named set of API credentials) from chat. The verb-resource pair is specific, but it fails to differentiate from sibling add_cabinet tools for other marketplaces (e.g., wb_add_cabinet, ozon_add_cabinet) — it doesn't mention Yandex Market and even gives examples for Ozon and WB, which could mislead the agent.

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 an explicit alternative (the installer) and a usage condition (requires i_understand_key_goes_to_chat=true), which helps the agent decide when to use this tool. However, it does not mention when to use this specific tool versus the other marketplace-specific add_cabinet tools, so the guidance is partial.

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, and the description reinforces the read-only safety profile ('nothing here changes data, so it runs without confirmation'). It adds useful behavioral context: the return envelope shape ('{"ok": true, "status", "data"}') and the error envelope mention. It doesn't detail rate limits or auth, but the read-only safety is well covered.

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

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

The description is compact and front-loaded: the core action and target are in the first sentence, followed by the safety note, sibling routing, and parameter explanations. 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?

Given the tool's complexity (generic catalog-based executor) and the presence of an output schema, the description covers the essential context: what it executes, how to find operation_id, what the parameters mean, and the return envelope. It doesn't explain the error envelope format in detail, but the output schema and the pointer to ym_search_methods cover most needs.

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 explains operation_id as 'id from the catalog (see ym_search_methods)', path_values as 'values for {placeholders} in the path', query as 'query-string parameters', and body as 'JSON request body (a few read endpoints take one)'. This adds meaning beyond the bare schema, though it could be more explicit about how path_values map to placeholders.

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 ('Execute'), a resource ('one READ endpoint from the catalog'), and the key selector ('by operation_id'). It also names the target API and explicitly contrasts with ym_write_method and ym_delete_method, making it easy to distinguish from siblings.

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

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

The description explicitly says when to use this tool: for read-only endpoints, and explicitly says to use ym_write_method for changes and ym_delete_method for deletion. It also points to ym_search_methods for finding operation_id, giving clear routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. The description adds valuable behavioral context: it does NOT reveal secret values, and it returns a specific JSON structure with ready/missing/required fields. This goes beyond the schema and 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?

Three sentences, each earning its place: what it does, what it doesn't do, and the exact return shape. Front-loaded with the core purpose, then the critical caveat, then the JSON contract. No waste.

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 check tool, the description is complete. It states the purpose, the safety boundary (no secret revelation), and the exact return format. An agent has everything needed to call it correctly and interpret the result.

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 0 parameters, so the schema is trivially complete. The description adds no parameter info because none is needed. Baseline 4 for 0 params 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 clearly states the tool checks whether required credentials are present in the environment, with a specific verb and resource. It also explicitly distinguishes itself from sibling auth-check tools by noting it does NOT reveal secret values, which is a key differentiator.

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 doesn't explicitly name alternatives or exclusions, but the context of sibling tools (e.g., ym_set_price, ym_get_campaigns) makes the use case clear. A clear 'use this when you need to verify auth before calling other YM tools' would push it to 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this by stating the action deletes or irreversibly changes data. It adds valuable context beyond annotations: both confirm_write=true and i_understand_this_modifies_data=true are required, and 'nothing is sent without both,' which is a strong safety behavior not visible in the schema.

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 most important fact (DESTRUCTIVE), followed by the target API, safety requirements, arguments, and return format. Every sentence earns its place, and the Args list is compact and readable without unnecessary elaboration.

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 destructive catalog method with six parameters and no schema descriptions, the description is nearly complete: it names the target API docs, explains all parameters, gives the required confirmation flags, and states the return envelope. It could slightly expand on optionality of path_values/query/body and prerequisites like authentication, but these are minor gaps given the output schema and existing 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?

Schema description coverage is 0%, so the parameter documentation in the description carries the full burden. It explains each of the six parameters: operation_id is a catalog id from ym_search_methods, path_values fill path placeholders, query is query-string parameters, body is a JSON body, and both boolean flags must be true. This fully compensates for the schema's lack of 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 identifies a specific action: 'Execute one DESTRUCTIVE endpoint: deletes or irreversibly changes data.' It conveys the scope (a single catalog endpoint from the Yandex Market Partner API) and the destructive nature. It does not explicitly name sibling tools like ym_call_method or ym_delete_raw to differentiate, but the catalog-based operation_id makes the distinction reasonably clear.

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

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

The description implies when to use the tool: for a destructive endpoint whose id was obtained via ym_search_methods. However, it does not explicitly state when not to use it or contrast it with alternatives such as ym_call_method (non-destructive) or ym_delete_raw (raw endpoint).

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 mark this destructiveHint=true and readOnlyHint=false; the description adds the confirmation-flag requirement and the open-world scope, and states the success/error return envelope. It could add irreversibility side-effect warnings, but it meaningfully supplements 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 destructive warning is front-loaded, followed by a compact Args list that maps one-to-one to the schema. There is minimal redundancy and no unrelated content.

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

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

Given the destructive raw-path nature and sparse schema, the description covers what an agent needs: path format, method, all arguments, mandatory safety flags, and the response envelope. No critical calling requirement is left undocumented.

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?

Despite 0% schema description coverage, the description documents all 7 parameters with useful specifics (path syntax, method constraint, host default, confirm flags). Every parameter receives meaning beyond its raw name.

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

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

The first sentence names the operation ('Delete data at ANY path, including paths not in the catalog'), with a specific verb, resource, and scope. This clearly distinguishes it from catalog-scoped delete_method 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 communicates the key usage condition: use for arbitrary paths, including unlisted ones, and only with DELETE plus both confirmation flags. It does not explicitly name a sibling alternative or provide when-not-to-use guidance, but the context is otherwise 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to restate the read-only nature. It adds useful context by listing what the catalog record includes (safety level, pagination style, rate limit), but does not disclose additional behavioral traits like failure modes or auth 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?

One tight, front-loaded sentence with no filler. The enumerated fields are directly useful to an agent deciding whether this tool returns what it needs.

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

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

For a simple one-parameter lookup tool with an output schema present, the description is nearly sufficient. The only notable gap is the operation_id sourcing and format, which is not explained in either the schema or 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?

The schema has 0% description coverage, so the description carries the full burden for explaining operation_id. It only indirectly implies that operation_id identifies the endpoint ('for one endpoint'), but gives no guidance on its format, where to obtain it, or how it relates to the search/map tools.

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 ('Return') and resource ('full catalog record for one endpoint'), then enumerates exactly what the record contains. This clearly distinguishes it from sibling operations like call_method or search_methods, which execute or discover endpoints rather than describe them.

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 usage context is implied: use this when you need metadata about a single known endpoint. However, it does not explicitly say when not to use it or point to alternatives such as ym_search_methods or ym_map for discovering operation_id values.

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 the description adds substantial behavioral detail: it handles multiple pagination styles, manages cursor fields, applies a max_items cap to protect context, and returns a structured summary with truncation status. This goes well beyond what annotations reveal.

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

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

Every sentence earns its place: the main behavior is front-loaded, pagination styles are summarized compactly, and the Args section is a clean scannable list. No filler or redundant restatement.

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

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

For a 7-parameter tool with no enums and an output schema present, the description is complete: what it does, how pagination is handled, how parameters interact, the safety cap, and the return shape are all covered. Nothing an agent needs to invoke 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 fully compensates by explaining every parameter: operation_id is a read endpoint from the catalog, query/body/path_values are base parameters with cursor fields managed, items_path overrides the array path, limit controls page size, and max_items is a hard cap. This adds real 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 opens with a specific verb and resource: 'Auto-paginate a read endpoint and return every row in one response.' It clearly distinguishes this from single-call tools like ym_call_method by emphasizing pagination and bulk return.

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 clearly states the use case: any read endpoint from the catalog where all rows are needed, with cursor fields automatically managed. It does not name alternatives or exclusions explicitly, but the context is strong enough that an agent can infer when to choose 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral context by explaining that the response contains both campaigns[].id and campaigns[].business.id, which are needed downstream. It also documents the return envelope shape. It doesn't mention pagination behavior beyond the page_token parameter, but the annotations plus the response format description provide solid transparency.

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 core purpose and the critical 'call this first' guidance appear in the first two sentences. The parameter explanations and return format are concise and each 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?

For a simple list tool with two optional parameters and an output schema, the description is nearly complete. It covers the purpose, the critical dependency context, parameter semantics, and return shape. The only minor gap is that it doesn't explicitly describe pagination looping behavior, but the paging object in the return format and the page_token parameter make that inferable.

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 explains page_token as 'pageToken from a previous page (empty for the first page)' and limit as 'page size (<=100)', adding meaning beyond the bare schema properties. This is sufficient for an agent to use both parameters 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 states a specific verb ('List') and resource ('the seller's shops (кампании)') and explicitly identifies the key fields returned (campaignId and businessId). It also distinguishes itself from other Yandex Market methods by noting it should be called first because nearly every other method needs these IDs.

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 usage guidance: 'Call this first: nearly every other Yandex Market method needs a campaignId or businessId.' This clearly tells the agent when to use this tool and why it precedes other calls, effectively routing around 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?

The description adds the endpoint and return shape, which is useful, and the readOnlyHint is consistent with the read-only nature of listing offers. It does not document auth requirements, rate limits, or potential errors, but the annotations already cover the read-only aspect.

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

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

The description is compact and front-loaded with the core purpose, followed by parameter details and response shape. It avoids boilerplate while still covering the essential invocation 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?

The description includes the endpoint, all parameter meanings, and the return envelope, making it self-sufficient for a basic call. It lacks error semantics and pagination iteration hints, but for a read-only listing tool the provided context is strong.

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

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

Schema parameter descriptions appear absent (0% coverage), but the description compensates by explaining every argument: business_id, offer_ids, page_token, and limit. It adds real meaning with types, defaults, and the pagination token semantics.

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 lists the seller's offers with their Market card mapping, using a specific verb and object. It distinguishes itself from order/stock tools by mentioning 'offerMappings', but it doesn't explicitly contrast it with sibling tools like ym_get_orders or ym_get_stocks.

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 is provided about when to prefer this tool over alternatives such as ym_get_orders or ym_get_stocks. The endpoint and args are specified, but there is no decision-making context for 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 mark the tool as readOnly and openWorld, so the safety profile is covered. The description adds meaningful behavioral detail: pagination via page_token, page size limit <=50, date formats, status filter options, and the JSON response envelope.

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 one-line purpose, an Args list, a Returns line, and a pagination hint. Every sentence adds useful information; nothing is redundant or padded.

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

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

For a read-only list tool with an output schema, this is complete. It covers parameter detail, response shape, pagination, and cross-tool relationships to ym_get_campaigns and ym_fetch_all, giving an agent everything needed to call and iterate correctly.

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

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

Schema coverage is 0%, so the description carries full parameter documentation. It explains every parameter: campaign_id source, status values and comma-separation, date format for from_date/to_date, page_token meaning, and limit maximum.

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 and resource: 'List orders of one shop' with the exact GET endpoint. It clearly scopes to a single campaign/shop via campaign_id and is easy to distinguish from sibling tools like ym_get_offers or ym_get_stocks.

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 helpful context such as campaign_id coming from ym_get_campaigns and explicitly routes pagination-heavy workflows to ym_fetch_all. However, it does not explicitly state when to choose this tool over alternatives like ym_get_orders vs ym_get_offers, or 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 declare readOnlyHint=true, and the description adds the cabinet-wide scope, the endpoint, pagination parameters, and the exact price fields returned. This is useful behavioral context beyond the structured metadata. No contradiction with the readOnlyHint is present; the mention of POST is an HTTP detail, not a mutation claim.

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 logically structured: scope, endpoint, args, and return format. There is no filler, and the key return path is front-loaded. The noun-phrase opening is slightly awkward but 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?

With an output schema present and every parameter explained, an agent has enough information to invoke this read-only tool correctly. The only missing context is explicit when-to-use guidance and any authentication caveats, but those are minor for a read getter with readOnlyHint and openWorldHint already set.

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 full responsibility for parameter meaning. It explains business_id as cabinet id, offer_ids as a comma-separated filter with empty meaning all, page_token as a continuation token, and limit as page size capped at 200. This fully compensates for the schema's lack of 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 names the resource ('base prices for all shops of the cabinet') and the return shape ('result.offers[].price'), making it clear this is a read operation. The tool name ym_get_prices reinforces the purpose and distinguishes it from the sibling ym_set_price. It would be cleaner with an explicit 'Get' verb, but the intent 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?

There is no explicit guidance on when to use this tool versus alternatives like ym_set_price or other getters. The readOnlyHint and return structure imply viewing, but the description never states exclusions, prerequisites, or the preferred context. An agent must infer usage from the name and arguments.

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 safety profile is known. The description adds value beyond that: it restricts verbs to GET, HEAD, OPTIONS, explains the return envelope ({"ok": true, "status", "data"} or error), and notes that body is rare but sometimes needed. It does not mention auth or rate limits, but those are likely handled by the service layer. 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-sentence purpose, a target API reference, safety constraints and sibling pointers, then a clean args list with defaults and examples. It is a bit long but every part earns its place. The most important scoping information (read any endpoint) is front-loaded. No redundant 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 a generic raw-read tool, this description is complete. It covers purpose, usage boundaries, all parameter semantics, return format, and error envelope. It even notes the rare body case. With annotations covering read-only and open-world behavior, and an output schema present, nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must fully explain parameters. It does: path (full path starting with '/', example), method (safe verb, default GET), host (override, default service host), query (query-string params), body (JSON body, rare on reads). All five parameters are given clear semantics with examples, fully compensating 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?

States a specific verb (read) and resource (ANY endpoint by path), explicitly covering endpoints missing from the catalog. It clearly distinguishes from ym_write_raw and ym_delete_raw, which are mentioned as alternatives for data changes. This makes its purpose unmistakable and differentiates it from the many 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?

Explicitly tells when to use this tool (read-only raw access to any endpoint) and when not to (use ym_write_raw for changes, ym_delete_raw for deletions). It also implies use for endpoints not covered by catalog-specific tools, and provides the target API documentation link. This is strong guidance on selection among 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 declare readOnlyHint=true, and the description adds a specific return format ('JSON list of {operation_id, method, path, safety, summary}'), which goes beyond the annotation. It also doesn't contradict any annotation and clarifies the safety field in the output. A strong addition for an agent to know exactly what to 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?

The description is concise: a single purpose sentence, an arg explanation with example, and the return format. It's front-loaded with the most critical information, and every sentence adds value. 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 simple read-only listing tool with one parameter, the description covers the essential aspects: purpose, parameter usage, and output format. It does not mention potential errors or pagination, but these are not critical for a listing operation. The inclusion of the output schema reference (though not shown) is handled by describing the return JSON structure, which is sufficient for an agent to interpret results.

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

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

The input schema only lists 'section' as a string with no description, and schema coverage is 0%. The description compensates by defining what 'section' means (a section name), directing to ym_list_sections for valid values, and giving an example. This is valuable context that 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 states a clear verb ('List') and resource ('all endpoints in one section'), making the tool's purpose immediately understandable. It also aligns with the readOnlyHint annotation and differentiates from sibling tools like ym_get_campaigns and ym_list_sections by specifying the output 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?

It instructs how to get a valid 'section' by referencing ym_list_sections and provides a concrete example ('statistics'). It does not explicitly mention when not to use this tool, but the context is clear that it's for browsing endpoint definitions, not for executing calls. This is sufficient guidance for an 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 carry readOnlyHint=true and openWorldHint=trueikuha. The description adds useful behavioral context: it is a POST endpoint that returns warehouse-level stock and supports pagination via page_tokenasia, and optionally includes turnover. 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?

Four compact lines cover purpose, endpoint, every parameter, and return shape. No filler or redundancy; the information is dense and scannable.

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 that an output schema exists, the description does not need to detail return fields. It explains the endpoint, all parameters, and the high-level data shape. Missing only minor operational details like rate limits or auth requirements, but what is present is sufficient 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?

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It covers all five: campaign_id (shop id), offer_ids (comma-separated filter, empty=all), with_turnover (per-offer turnover), page_token (pagination), and limit (page size, <=200). This fully compensates for the schema's lack of 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, actionable purpose: 'Stock per offer per warehouse for one shop, with optional turnover,' reinforced by the explicit endpoint. This clearly distinguishes it from sibling price/order/offer tools even without reading 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?

The description clearly explains scope (per-shop stocks) and parameters, but it does not explicitly say when to choose this over related tools like ym_get_offers or ym_get_prices, nor does it state exclusions like draft/archived campaigns or authorization prerequisites.

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 the description's 'Return' wording is consistent with that read-only behavior; there is no contradiction. The description adds useful content-level detail about what the returned plan contains, but it does not disclose additional behavioral context such as authentication requirements, errors, or rate limits. Since annotations carry 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?

The description is compact: two purposeful sentences plus a one-line args block. The main purpose is front-loaded, and every clause contributes information without restating 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?

This is a single-parameter, read-only retrieval tool with an output schema available, so the description does not need to explain return values in depth. It covers the tool's purpose, the nature of the returned plan, and how to source the parameter value. Nothing essential 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 input schema provides only 'name' with a type and no description, so 0% schema coverage leaves the parameter semantically empty. The description compensates by explaining that name is a workflow name and points to '{svc}_list_workflows' for valid values. For a single parameter, this is meaningful and sufficient guidance.

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 'Return the full plan for one workflow' – a specific verb, resource, and scope – then details the plan's contents: ordered steps, each naming a catalog operation_id and why, plus interpretation guidance and common mistakes. This clearly distinguishes it from listing workflows or fetching workflow data, even among many 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 only usage guidance is implicit in the parameter line: 'workflow name (see {svc}_list_workflows)', which suggests consulting list_workflows first for valid names. There is no explicit statement of when to choose this tool over alternatives or when not to use it, so the guidance is present but minimal.

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 the description consistently describes a read-only listing. It goes beyond the annotations by disclosing the exact return shape ('active', 'cabinets', 'fields_needed') and a security guarantee that secret values are never returned, which adds meaningful behavioral 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 two concise sentences: the first front-loads the action and scope, and the second provides the return format and an important secrecy guarantee. Every word earns its place; there is no fluff or 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?

For a zero-parameter read-only listing tool with an output schema and readOnlyHint annotation, the description is complete. It names the resource, clarifies what the response contains, and warns about secret values, which is sufficient for an agent to select and invoke the tool correctly.

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

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

The tool accepts zero parameters, so the input schema fully covers parameter semantics. Baseline for zero parameters is 4; the description reinforces what data will be returned but does not need to elaborate on parameters. No gap exists.

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: 'List configured cabinets for this marketplace and which one is active.' It clearly identifies the operation (list), the object (cabinets), and a distinguishing extra (active status), making it easy to separate from sibling tools like ym_add_cabinet or ym_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 context is clear: use it when you need to see configured cabinets and the active one for this marketplace. However, it does not explicitly state when not to use it or name alternatives such as ym_use_cabinet or wb_list_cabinets, so usage guidance is mostly implied rather than 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 establishes that this is a read-only operation, and the description adds useful detail about the return scope: sections plus endpoint counts. It does not mention auth, network effects, or rate-limit behavior, but the annotation covers the safety profile adequately.

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?

A single sentence fully conveys the tool's action and result shape with no wasted words. The core action 'List' is front-loaded, followed by the object and the count 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 parameterless read-only listing tool with an output schema present, the description is complete: it states the action, the resource, and the distinguishing output measurement. An agent has enough information to invoke the tool without further clarification.

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

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

The tool has zero parameters and the schema covers all of them trivially, so the description carries no parameter-documentation burden. The baseline for a zero-parameter tool is 4, and nothing here reduces that score.

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 API sections' and adds the detail 'how many catalog endpoints each contains,' which clarifies what the result includes. It distinguishes the tool from lookup-style siblings like ym_get_section and ym_describe_method, though it does not explicitly name any alternative.

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 no guidance about when to use this tool instead of related tools such as ym_map, ym_search_methods, or platform-specific list_sections variants. No exclusions, prerequisites, or routing hints 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=true annotation already signals a safe read operation. The description adds the return format (JSON array of objects with name, category, and when_to_use), which is useful behavioral information beyond the annotation. No hidden side effects or special constraints are mentioned, but none appear to exist.

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

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

Two sentences deliver the core purpose, the marketplace scope, the output format, and the pointer to the follow-up tool. No filler, no redundant restatement.

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

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

For a parameterless list tool with an output schema, the description covers everything an agent needs: what it lists, what the entries look like, and how to proceed when more detail is needed. The companion get_workflow tool is also referenced, making the API surface navigable.

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 Secret, so there is no parameter documentation burden. The empty schema is consistent with the description, and the return fields are described enough to make the output meaningful.

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 clear verb-object structure ('List ready-made analytical workflows') and scopes it precisely to 'this marketplace', differentiating it from tools like wb_list_workflows. It also distinguishes itself from the related get_workflow operation by positioning the latter as the fetch-full-details counterpart.

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 when a full step-by-step plan is needed, which creates useful routing guidance. It does not explicitly state 'use this when you only need an overview' or list other alternative tools, but the contrast with get_workflow is clear enough.

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?

readOnlyHint=true already signals safety; the description adds behavioral detail about the no-args vs entity-argument branching and the 'you are here' orientation value. No contradiction with annotations.

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

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

Two concise, information-dense sentences. The purpose is front-loaded, followed immediately by usage examples and a clear directive. No wasted words.

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

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

For a read-only map with one optional parameter and an output schema, the description covers all necessary invocation context: what it does, when to use, and how arguments change behavior. 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 schema provides no description for the 'entity' parameter, but the description compensates by explaining its purpose with concrete examples and the default behavior. It doesn't fully enumerate valid entity values, but the map itself can provide that.

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

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

Description clearly states the tool's role as a high-level map of business entities and their go-to methods, with specific usage variants. It distinguishes itself from sibling action tools (call/write/delete) by framing the tool as the 'big picture' orientation resource.

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?

Offers explicit guidance: call with no args for the whole map, or pass entity to list methods for one entity, and instructs to use it before guessing. It doesn't name sibling alternatives or explicitly state when not to use it, so it falls short of 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered by structured data. The description adds a meaningful side effect beyond annotations: if the removed cabinet was active, another cabinet becomes active. However, it does not disclose other behavioral details like permanence, error behavior for nonexistent names, or authorization 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 compact and front-loaded with the core operation, followed by the key side effect and the parameter explanation. Every sentence earns its place, and there is no redundant restatement of the tool name 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 simple single-parameter destructive action, the description covers the operation and the most important side effect. Since an output schema exists, return values do not need to be described. Minor gaps remain around prerequisites and exact name matching, but the overall context is adequate for typical use.

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 parameter meaning. It does identify 'name' as 'the cabinet to remove,' which is useful and more informative than the schema's bare 'Name' label. However, it does not clarify what form the name takes, how to discover valid values, or whether it must exactly match a stored cabinet name.

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

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

The description uses a specific verb ('Delete') and a clear resource ('a stored cabinet'), and the active-cabinet fallback adds a useful behavioral detail. It is immediately distinguishable from sibling tools like ym_use_cabinet and ym_add_cabinet. No ambiguity remains about what operation this tool performs.

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 does but gives no explicit guidance on when to choose it over alternatives. It does not mention when not to use it or point to related tools such as ym_use_cabinet or ym_add_cabinet. The active-cabinet fallback is a consequence, not usage 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 declare readOnlyHint=true, so the description doesn't need to cover that. It adds the return format (JSON list) and ordering ('best first'), which are useful behavioral details. No contradictions with annotations, but the description doesn't disclose additional constraints like authentication or pagination, though these 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 extremely concise and well-structured: a one-line summary, a bulleted args list, and a return note. Every sentence adds value, with examples and constraints 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?

The tool has an output schema, so the description doesn't need to detail return structure. It covers the essential aspects: query semantics, limit bounds, and result ordering. It lacks guidance on when to use it relative to sibling search tools, but that is a minor gap given the read-only nature and clear 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 documents both parameters: query with free-text examples, and limit with a range (1-50). This adds significant meaning beyond the bare schema, which only lists 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 searches the endpoint catalog by keyword, with a specific verb and resource. It also notes bilingual support. While it doesn't explicitly differentiate from sibling search_methods for other marketplaces, the 'ym_' prefix and 'endpoint catalog' phrasing make the purpose clear.

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

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

There is no guidance on when to use this tool versus alternatives like ym_describe_method or ym_map, nor any mention of when not to use it. The usage context is only implied by the description of searching the catalog.

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 this as non-read-only and idempotent, and the description adds crucial behavioral context beyond those hints: the key enters the chat transcript, the confirmation flag is mandatory, the key is validated against the marketplace, stored locally with chmod 600, and never echoed back. This materially improves an agent's understanding of side effects and risks.

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 purpose, then gives a focused security warning, parameter guidance, and postconditions. Every sentence provides useful information; no filler or redundant restatement of the tool name exists, and the `Args` section maps cleanly to 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?

The description covers when to use the tool, the security risk, the required confirmation flag, default cabinet behavior, validation, local file permissions, and what happens on success. The main gap is the missing concrete shape of `credentials`, which keeps it from being fully self-contained, but the overall invocation context is otherwise well covered.

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 meaning for `cabinet` and `i_understand_key_goes_to_chat`, including defaults and constraints. However, `credentials`, the only required parameter, is described only as 'dict with the required fields ({fields})' — the actual required fields are left as an unresolved placeholder, and schema coverage is 0%, so the agent still cannot confidently construct the required 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?

The description opens with a specific verb and resource: 'Change / rotate the API key from chat'. It also gives concrete trigger examples ('e.g. the old one expired or leaked'), making the tool's purpose unambiguous and distinct from the many set-key siblings by clarifying that this is the chat-based rotation path.

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

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

It explicitly says when to reach for this tool ('old one expired or leaked') and names the safer alternative ('the installer, where the key never enters chat'). It also explains the default cabinet behavior so that common cases like 'my key expired' work without extra configuration.

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=false, destructiveHint=false, idempotentHint=true. The description adds valuable context: it explicitly says 'WRITE', requires confirm_write=true, explains the discount_base semantics (strikethrough price must be higher than price; 0 = no discount), and notes the currency quirk ('RUR', not 'RUB'). This goes beyond what annotations 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 compact and front-loaded with the core action and endpoint, followed by the critical write confirmation requirement. The Args list is efficient. Slight redundancy with the endpoint and the WRITE label, but no wasted sentences.

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 6-parameter mutation tool with 0% schema coverage, the description covers all parameters, the required confirm_write flag, the currency quirk, the discount_base constraint, and the success response format. The output schema exists, so return values are already structured. Nothing an agent needs to call this 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. It explains every parameter: business_id (cabinet id), offer_id (seller's SKU), price (new price with example), discount_base (pre-discount price or 0 to clear), currency (RUR default, with the RUR/RUB gotcha), and confirm_write (must be true). This fully compensates for the empty 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 verb ('Set'), a precise resource ('base price of ONE offer for all shops of the cabinet'), and the exact API endpoint. It clearly distinguishes this from sibling tools like ym_get_prices (read) and wb_set_price/ozon_set_price (different marketplaces).

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 clearly indicates this is a write operation requiring confirm_write=true, and the endpoint path makes it clear this is for Yandex Market. It doesn't explicitly name alternatives or when-not-to-use, but the context is clear enough for an agent to select it over read tools or other marketplace price setters.

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 provide idempotentHint=true and readOnlyHint=false, so the description doesn't need to restate those. The description adds meaningful behavioral context: switching the active cabinet affects subsequent API calls and uses credentials. This is a state-changing operation with a persistent side effect, which is disclosed. It could mention whether the switch persists across sessions, but the core behavior is transparent.

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

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

The description is extremely concise: one sentence plus a parameter note. Every word earns its place. The key behavioral fact (subsequent calls use its credentials) is front-loaded, and the parameter reference is clearly separated.

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

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

For a single-parameter state-switching tool, the description is nearly complete. It explains the effect, the parameter, and where to find valid values. The output schema exists but is not described; however, for a switch operation the return value is likely trivial. A minor gap is not stating whether the switch is persistent across sessions or how to verify the active cabinet.

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 'name' is 'the cabinet to activate' and points to ym_list_cabinets for valid values. This adds meaning beyond the bare schema. However, it doesn't specify the format or constraints of the name (e.g., exact match, case sensitivity), leaving some ambiguity.

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

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

The description clearly states the tool's function: 'Switch the active cabinet' and explains the consequence ('Subsequent API calls use its credentials'). This is a specific verb+resource that distinguishes it from other cabinet operations like list/add/remove. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate from the other *_use_cabinet tools across providers, though the ym_ prefix already scopes it.

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: before making API calls that need a specific cabinet's credentials. It references ym_list_cabinets as the source for valid names, which is useful routing guidance. It doesn't explicitly state when not to use it or mention alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false, destructiveHint=false), so the description's main added behavioral value is the confirm_write guard: 'nothing is sent without it.' It also discloses the response shape and target API. It stops short of describing auth requirements, rate limits, or side-effect granularity, but the annotation coverage lowers the burden; there is 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 compact and front-loaded: purpose, safety guard, sibling routing, then a scannable Args list and return envelope. 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?

For a generic catalog-driven executor, it provides the essential loop: discover operation_id via ym_search_methods, supply path/query/body, and pass confirm_write=true. The output envelope is stated, and an output schema is present, so return-value detail isn't required. It could have explicitly pointed to ym_describe_method for per-endpoint parameter requirements, but the catalog pointer largely covers this.

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 parameter meaning, and it does: operation_id comes from the catalog, path_values fill {placeholders}, query holds query-string parameters, body is the JSON request body, and confirm_write must be true. This adds significant meaning beyond the bare schema types.

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 and resource: 'Execute one WRITE endpoint from the catalog: create or update data.' It further distinguishes itself from siblings by noting that irreversible operations live in ym_delete_method and reads in ym_call_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?

It gives an explicit precondition and safety rule: 'Requires confirm_write=true; nothing is sent without it.' It also tells the agent where to route other operation types (ym_delete_method for irreversible, ym_call_method for reads) and where to find operation IDs (ym_search_methods).

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=false, openWorldHint=true, destructiveHint=false. The description adds meaningful behavioral context: it supports only POST/PUT/PATCH, requires confirm_write=true, and returns a specific JSON envelope or error envelope. It also notes the host override behavior. This goes beyond the annotations and helps the agent understand side effects and safety 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 compact and front-loaded with the core purpose, then the API link, then method constraints, then parameter list, then return format. Every sentence earns its place. The parameter list is a bit dense but still readable. Minor deduction for the 'Args:' block being a bit telegraphic, but overall 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?

Given the tool has an output schema and annotations, the description covers the essential operational details: allowed methods, required confirm_write flag, path format, host override, and return envelope. It doesn't explain error cases beyond 'error envelope', but that is acceptable given the output schema exists. It is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains method (POST/PUT/PATCH only), path (full path beginning with '/'), host (override, defaults to service default), query (query-string parameters), body (JSON request body), and confirm_write (must be true). This adds meaning beyond the bare schema titles and defaults, though it could be slightly more explicit about the body being optional.

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 ('Create or update data') and a specific resource ('at ANY path, including paths not in the catalog'), which clearly distinguishes it from catalog-bound tools like ym_write_method. It also names the target API and HTTP methods, leaving 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 description explicitly says it can write to any path, including non-catalog paths, which implies when to use it (when the path is not in the catalog or when you need raw access). It also states the constraint 'requires confirm_write=true' and lists allowed methods. However, it does not explicitly say 'use ym_write_method for catalog paths' or name alternatives, so it misses the explicit 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.