Server Quality Checklist

Tool Scores

• ym_get_offersA
  3.6/5.0
  Behavior3/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose4/5

  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.

  Usage Guidelines2/5

  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.

• ym_list_sectionsA
  3.6/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose4/5

  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.

  Usage Guidelines2/5

  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.

• ym_describe_methodA
  3.7/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters2/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• ym_get_pricesA
  3.8/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose4/5

  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.

  Usage Guidelines2/5

  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.

• ym_remove_cabinetA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint: true. The description adds a meaningful behavioral detail beyond that: if the removed cabinet was active, another becomes active. This is a significant side effect an agent could not infer from the schema alone.

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

  Conciseness5/5

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

  The description is only two sentences plus a single-line Args explanation. It is front-loaded with the action and the key side effect, with zero fluff or repetition. Every word serves a purpose.

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

  Completeness3/5

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

  For a one-parameter destructive tool, the description covers the main behavior and side-effect, and the output schema exists. However, it lacks any guidance on error conditions, prerequisite credentials, or what constitutes a valid 'name', and it neither includes nor disclaims platform scope explicitly.

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

  Parameters4/5

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

  Schema coverage is 0%, so the description must carry the parameter meaning. The line 'name: the cabinet to remove' explicates the input, which is useful and clear. It does not cover what happens when the name doesn't exist, but for the sole required parameter, the core semantics are provided.

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

  Purpose5/5

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

  The description opens with a clear verb-plus-resource pairing (‘Delete a stored cabinet’) and adds a non-obvious consequence for active cabinets. This clearly separates it from cabinet add/use/list operations; the ym_ prefix in the name handles cross-platform differentiation.

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

  Usage Guidelines2/5

  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, nor any mention of when not to use it or prerequisites. The only implied usage is removing a cabinet, but no context or exclusion rules are provided.

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

• ym_add_cabinetA
  4/5.0
  Behavior5/5

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

  Beyond annotations, the description discloses critical behaviors: the key goes into the chat transcript, confirmation is required, the cabinet is saved to ~/.marketplace-mcp/cabinets.json with chmod 600, and credentials are never echoed. This goes well beyond the annotations and is highly valuable for safe use.

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

  Conciseness4/5

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

  The description is well structured: purpose, warning, safe alternative, args, and persistence details. It front-loads the most important risk. The placeholder and off-service examples add some noise, but overall it is appropriately sized and organized.

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

  Completeness3/5

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

  The description covers safety, storage, naming fallback, and the confirmation flag well. However, it lacks the actual resolved credential fields for YM and does not clarify how 'update' matches an existing cabinet. For a credential-writing tool, those are important gaps.

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

  Parameters3/5

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

  The description documents all three parameters: credentials as a dict, name as optional with a fallback naming behavior, and the required confirmation flag. However, the central credentials field still contains an unresolved placeholder '{fields}', and the examples are for Ozon and WB, not YM. Since the schema only has additionalProperties with no descriptions, an agent still cannot reliably construct valid YM credentials.

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

  Purpose4/5

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

  The description clearly states the verb+resource: 'Add or update a cabinet (a named set of API credentials), from chat.' This is specific and understandable. However, it does not explicitly differentiate itself from sibling tools like ym_set_key or ym_use_cabinet, which could overlap with 'update' behavior.

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

  Usage Guidelines4/5

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

  The description gives clear context: this is the chat-based path for adding/updating credentials, and it warns that the key enters the chat transcript. It names a safe alternative (install.py / double-click) for when that is not acceptable. It does not enumerate sibling-tool alternatives, but the when-not guidance is explicit.

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

• ym_check_authA
  4/5.0
  Behavior5/5

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

  The description adds meaningful behavior beyond the readOnlyHint annotation: it explicitly states that secret values are NOT revealed and only variable presence is reported. It also discloses the exact JSON return shape, giving the agent a clear model of the tool's behavior.

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

  Conciseness5/5

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

  Three short sentences, front-loaded with the core purpose, followed by a key constraint and return format. No filler or redundancy; every sentence earns its place.

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

  Completeness5/5

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

  For a simple parameterless read-only auth check, the description is fully complete: it states purpose, safety behavior, and return format. The output schema exists, so additional return-value documentation is unnecessary. Nothing needed for correct invocation is missing.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline is 4. The description correctly avoids inventing parameter meaning and focuses on behavior and output, which is appropriate for a parameterless check.

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

  Purpose4/5

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

  The description clearly states it checks whether required credentials are present in the environment, naming the specific resource (credentials) and the action (check). It does not explicitly differentiate from sibling auth-check tools like wb_check_auth or ozon_check_auth, but the purpose is unambiguous.

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

  Usage Guidelines2/5

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

  The description implies the tool is for verifying credential presence, but it provides no explicit guidance on when to use it versus the many sibling auth-check tools, nor does it mention typical pre-call usage. An agent must infer the appropriate context.

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

• ym_get_sectionA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that it returns a JSON list with specific fields, but provides no additional behavioral context such as authentication requirements, rate limits, or whether this makes a network call versus reading local metadata.

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

  Conciseness5/5

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

  The description is short and front-loaded with the core purpose. The Args section and return format are concise, with no filler or redundant information.

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

  Completeness4/5

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

  For a simple read-only list tool with one parameter and an output schema, the description is largely complete. It documents the parameter source and return fields; the main gap is the lack of explicit guidance on when to use this tool versus related lookup tools.

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

  Parameters4/5

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

  The input schema only describes 'section' as a string, so the description adds essential meaning by explaining it is a section name, pointing to list_sections for valid values, and giving an example. The use of the placeholder {svc} instead of the concrete 'ym' prefix is slightly ambiguous, preventing a perfect score.

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

  Purpose5/5

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

  The description states a clear action and resource: list all endpoints in a section. It distinguishes itself from sibling tools like ym_list_sections (lists sections) and ym_describe_method (describes one method) by specifying scope.

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

  Usage Guidelines3/5

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

  The usage context is only implied by 'List all endpoints in one section.' It references {svc}_list_sections for finding valid section names, but it does not explicitly state when to choose this tool over alternatives like ym_search_methods or ym_map, 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.

• ym_use_cabinetA
  4/5.0
  Behavior4/5

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

  With annotations already marking this as non-read-only and idempotent, the description adds the key behavioral fact that switching the cabinet changes context so subsequent API calls use its credentials. This is precisely the stateful side effect an agent needs to know.

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

  Conciseness5/5

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

  Two short sentences, no redundancy. The behavior is front-loaded and the parameter guidance is placed exactly where needed.

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

  Completeness4/5

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

  For a one-parameter state-switch tool with no output schema, the description covers the operation, its lasting effect on subsequent calls, and where to discover valid arguments. It could mention prerequisites like adding the cabinet first, but this is not essential for invoking the tool.

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

  Parameters3/5

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

  Schema coverage for the single parameter is 0%, so the description must carry the meaning. It does explain that 'name' is the cabinet to activate and points to {svc}_list_cabinets for valid values, though it does not specify whether the value is an ID or display name.

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

  Purpose5/5

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

  The description states a specific verb and object ('Switch the active cabinet') and immediately clarifies the operational effect: subsequent API calls use that cabinet's credentials. This clearly distinguishes it from sibling operations like add, remove, or list cabinet.

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

  Usage Guidelines3/5

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

  The description implies its use case (changing the active credential context) and tells the agent to see {svc}_list_cabinets for the name argument. It does not explicitly contrast with add_cabinet or remove_cabinet, so the guidance is partial but adequate for a simple state-switch tool.

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

• ym_get_workflowA
  4.1/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• ym_search_methodsA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description adds useful behavioral details: it returns a JSON list, orders results 'best first', and supports both Russian and English. These go beyond the annotations and help the agent anticipate output. It does not mention pagination or auth, but those are less critical for a search endpoint.

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

  Conciseness5/5

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

  The description is two short sections: a one-sentence purpose statement followed by a compact parameter breakdown. Every sentence adds value, no filler, and important info (return format, constraints) is front-loaded. It is efficiently structured for quick parsing.

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

  Completeness4/5

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

  Given it has a simple parameter set and an output schema exists, the description covers the necessary invocation details: parameters are explained, return format is stated, and read-only behavior is conveyed via annotations. The only missing contextual aid is usage guidance, but that is already scored under dimension 2. Overall, it is complete enough for an agent to call correctly.

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

  Parameters5/5

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

  The input schema provides no descriptions for the parameters (coverage 0%), so the description carries the full burden. It explicitly defines 'query' as free text with examples, and 'limit' with a range (1-50). This fully compensates for the schema gap, giving the agent everything needed to set the parameters correctly.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Search the endpoint catalog by keyword' and adds a specific capability (works in Russian and English) that distinguishes it from other search tools. The verb 'Search' and the object 'endpoint catalog' are specific, and it is clearly different from siblings like ym_describe_method or ym_map.

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

  Usage Guidelines2/5

  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. It does not mention what scenarios call for this search method vs. ym_map for browsing structure or ym_describe_method for details. The description only explains what it does, not when it is the right choice.

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

• ym_get_stocksA
  4.3/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• ym_call_rawA
  4.4/5.0
  Behavior4/5

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

  Beyond the annotations, the description explains how safety is inferred from the HTTP verb (GET=read, POST/PUT/PATCH=write, DELETE=destructive) and notes confirmation requirements and the return envelope. The mention of 'Same confirmation rules as {svc}_call_method' is useful context but weakened by the unresolved placeholder.

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

  Conciseness5/5

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

  The description front-loads the core purpose and safety model, then presents a tight bulleted argument list and a one-line return contract. Every sentence carries load-bearing information, and there is no filler.

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

  Completeness4/5

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

  For a raw endpoint executor, the description covers purpose, safety, all parameter roles, and the response shape. It could be more complete by resolving the confirmation-rule placeholder and by explicitly steering catalogued endpoints to ym_call_method, but overall the agent has enough to invoke it correctly.

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

  Parameters4/5

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

  Schema description coverage is 0%, but the description compensates by explaining method, path, host, query, body, and the two confirmation flags. The confirmation parameters are only labeled as 'confirmations,' without differentiating when each should be set, which is a meaningful gap for safe invocation.

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

  Purpose5/5

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

  The description states a specific action ('Execute ANY endpoint') and clearly identifies the resource scope: endpoints beyond the catalog, with 'full API coverage.' It distinguishes itself from catalog-scoped siblings such as ym_call_method by emphasizing that it can reach uncatalogued endpoints.

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

  Usage Guidelines4/5

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

  The description gives clear context: use this tool for any endpoint, even ones not in the catalog, which implies it is the raw fallback for uncovered API operations. It does not explicitly say 'for catalogued endpoints use ym_call_method instead,' but the catalog contrast provides adequate selection context.

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

• ym_fetch_allA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true; the description adds that it auto-paginates, manages cursor fields, has a hard cap (max_items) to protect context, and returns a 'truncated' flag. This discloses the multi-call behavior and context-protection tradeoff beyond the annotations. It does not address rate limits or error propagation, but the safety profile is already covered.

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

  Conciseness5/5

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

  The description is structurally sound: a one-sentence summary, a line on supported pagination styles, a clean bulleted Args list, and a return shape. Every sentence earns its place, and key facts (read-only, defaults, hard cap) are front-loaded or clearly labeled. No redundant schema repetition.

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

  Completeness4/5

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

  For a generic fetch-all tool with an output schema, the description covers the necessary call parameters, the output envelope, and the context-protection cap. It lacks an explicit note on selecting operation_id (e.g., via ym_map or ym_describe_method) and on error handling, but the presence of an output schema and sibling discovery tools mitigates that gap. Overall sufficient for an agent to invoke correctly.

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

  Parameters4/5

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

  With 0% schema description coverage, the Args section compensates by explaining operation_id, query/body/path_values, items_path, limit, and max_items. It clarifies that cursor fields are managed and that the array path defaults to the catalog value. The grouping of query/body/path_values is slightly terse but usable, and default values are noted.

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

  Purpose5/5

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

  States 'Auto-paginate a read endpoint and return every row in one response' – a specific verb, resource, and outcome. The mention of multiple pagination styles distinguishes it from a single call_method, and the read-only scope differentiates it from write tools. Clear enough even among many fetch_all siblings.

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

  Usage Guidelines4/5

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

  The description says it is for read endpoints and that cursor fields are managed, implying it is for retrieving full datasets rather than single-page calls. It does not explicitly name when *not* to use it (e.g., for writing or single records), but the read/auto-paginate context provides reasonable guidance. No alternatives are named, so it stops 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.

• ym_get_ordersA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• ym_list_cabinetsA
  4.5/5.0
  Behavior4/5

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

  Annotations already mark this as read-only, and the description adds valuable behavioral detail: the exact JSON return shape, the presence of fields_needed, and the guarantee that secret values are never returned. No contradictions with annotations.

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

  Conciseness5/5

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

  Two short, information-dense sentences. The main purpose is front-loaded, and the return format and security guarantee each earn their place without any filler.

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

  Completeness5/5

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

  For a parameterless listing tool with read-only annotations and a documented output shape, the description is fully sufficient. An agent can invoke it correctly without consulting additional context.

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

  Parameters4/5

  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 are no parameter semantics to document. The description appropriately focuses on the return value instead, matching the baseline for a parameterless tool.

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

  Purpose5/5

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

  The description states a specific verb ('List'), a clear resource ('configured cabinets'), and adds differentiating context ('for this marketplace and which one is active'). It is easy to distinguish from sibling list_cabinets tools for other marketplaces.

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

  Usage Guidelines4/5

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

  The description clearly indicates this tool is for the current marketplace's cabinets and adds the unique behavior of identifying the active cabinet. It does not explicitly name alternatives or state when not to use it, but the marketplace-specific phrasing provides sufficient context among siblings.

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

• ym_list_workflowsA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• ym_mapA
  4.5/5.0
  Behavior4/5

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

  Annotations already supply readOnlyHint=true, so safety is clear. The description adds meaningful behavioral detail: no args returns the full map, an entity parameter filters to methods for that entity, and the map is designed for quick orientation ('you are here', 'orients you fast'). 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.

  Conciseness5/5

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

  Three purposeful, front-loaded sentences. Each adds value: the first states the tool's role, the second explains exactly how to call it, and the third gives a strong usage heuristic. No filler or repetition.

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

  Completeness5/5

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

  For a simple, read-only, one-optional-parameter tool with an output schema, the description is complete. It tells the agent what the tool is for, how to invoke both modes, and when to reach for it. Return-value details are already covered by the output schema, so no additional explanation is needed.

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

  Parameters4/5

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

  Schema description coverage is 0%, but the description compensates well. It explains that the single optional parameter 'entity' selects a business entity ('reviews' or 'stocks/prices/orders/…') and that omitting it returns the whole map. It doesn't enumerate all valid values, but the open-ended '…' appropriately signals extensibility.

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

  Purpose5/5

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

  Description clearly identifies the tool as a capabilities map for the API: 'The big picture: business entities this API covers and the go-to methods for each.' It also specifies exact behaviors (whole map vs. per-entity method listing), which distinguishes it from sibling tools like ym_search_methods or ym_describe_method without needing to open them.

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

  Usage Guidelines4/5

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

  Provides concrete usage guidance: 'Call with no args to see the whole map' and 'pass entity="reviews" ... to list every method of one entity.' It also advises when to use it: 'Use this before guessing.' It stops short of explicitly naming alternatives or giving exclusion criteria, so it earns a 4 rather than a 5.

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

• ym_set_priceA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• ym_get_campaignsA
  4.6/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• ym_set_keyA
  4.7/5.0
  Behavior5/5

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

  The description goes far beyond annotations by disclosing that the key enters the chat transcript, requires explicit user acknowledgment, is validated on success, saved locally with chmod 600, and never echoed back. This is highly transparent about side effects and security behavior, exceeding what the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) convey.

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

  Conciseness5/5

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

  The description is well-structured: a one-sentence purpose, a prominent security warning, and a compact Args list. Every sentence adds value, the critical caveat is front-loaded, and there is no redundancy. It is appropriately sized for a security-sensitive write operation.

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

  Completeness5/5

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

  For a tool that sets an API key, the description covers the essential operational details: the security risk, the required confirmation flag, cabinet selection behavior, validation, local storage, and output reporting. An output schema exists, so the lack of return-value details is acceptable. The description is complete enough for an agent to use the tool correctly.

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

  Parameters4/5

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

  Despite 0% schema description coverage, the description explains all three parameters meaningfully. 'cabinet' is fully described with its default resolution logic, and 'i_understand_key_goes_to_chat' is clearly flagged as mandatory. 'credentials' is described as a dict with required fields, though the exact fields are left as a placeholder ('{fields}'), which is somewhat vague but still indicates the structure.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Change / rotate the API key from chat' with a specific verb (change/rotate), a resource (API key), and a context (from chat). It also implies the target marketplace (Yandex Market) via the 'ym_' prefix and mentions 'marketplace' in the text, distinguishing it from sibling set_key tools for other marketplaces.

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

  Usage Guidelines4/5

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

  The description provides usage context, such as the default cabinet behavior ('my key expired just works') and the mandatory i_understand_key_goes_to_chat flag. It also mentions an alternative (the installer) that is safer, though it doesn't explicitly state when to prefer this tool over that alternative or other set_key tools. Still, it gives clear situational guidance.

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

• ym_call_methodA
  4.8/5.0
  Behavior5/5

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

  The description discloses exactly how the guardrails behave: read endpoints run immediately, writes require confirm_write, destructive endpoints require both confirm_write and i_understand_this_modifies_data. This meaningfully exceeds the annotations (destructiveHint=true) by explaining the safety mechanism and that nothing is sent for destructive endpoints without explicit confirmation.

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

  Conciseness5/5

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

  The purpose is stated in the first sentence, the safety escalation (read → write → destructive) is in a clear three-line block, and every parameter has a one-line definition. No filler; high signal density.

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

  Completeness5/5

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

  For a generic endpoint executor, the description covers prerequisites (operation_id from ym_search_methods), argument categories, write/destructive guardrails, and the response envelope. The catalog linkage and output-shape note make it self-sufficient despite the absence of an output schema.

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

  Parameters5/5

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

  With schema descriptions at 0%, the description compensates fully: it defines operation_id as a catalog ID, path_values as placeholder substitutions, query as query-string parameters, body as the request JSON, and both safety flags with exact conditions. This is exactly the extra meaning an agent needs to invoke the call correctly.

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

  Purpose5/5

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

  Opens with a specific verb and resource: 'Execute one catalog endpoint by operation_id.' This immediately frames the tool as the execution counterpart to discovery tools like ym_search_methods and ym_describe_method, and the read/write/destructive breakdown further sharpens what it does.

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

  Usage Guidelines4/5

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

  Provides clear operational guidance: operation_ids come from {prefix}_search_methods, writes require confirm_write=true, destructive calls require the additional i_understand_this_modifies_data=true, and reads run immediately. It does not explicitly contrast with siblings like ym_call_raw, so the when-to-use-vs-alternative guidance is good but not exhaustive.

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