Server Quality Checklist

Tool Scores

• xmlstock_wordstat_regions_treeB
  3.2/5.0
  Behavior2/5

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

  Only mentions that requests are paid. With no annotations, the description should disclose more behavioral traits (e.g., read-only nature, rate limits, authentication). The cost note is useful but insufficient.

  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?

  Single, front-loaded sentence with no redundant words. Every part adds value: what it returns, how it's used, and cost.

  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 tool without output schema, the description covers the essential output and usage context. Could mention format or limitations but not critical.

  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 is 100% and already describes the single parameter 'account'. The description adds 'ПЛАТНО за запрос' but not additional semantics beyond the schema. Baseline 3 is appropriate.

  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 tool returns a tree of Yandex Wordstat regions with id, name, and path, and that the id is used as a region parameter in other requests. It distinguishes from sibling xmlstock_wordstat_regions by emphasizing 'tree' (hierarchical), though not explicitly.

  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 on when to use this tool versus alternatives like xmlstock_wordstat_regions or other siblings. Does not specify prerequisites or context for using the region IDs.

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

• xmlstock_balanceA
  3.6/5.0
  Behavior2/5

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

  No annotations are present, so the description must carry the full burden. It notes it's a free service call and checks keys, but does not disclose side effects (likely none), required authentication, rate limits, or whether it is read-only. This is insufficient for full 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?

  Two concise sentences that front-load the main purpose and include a notable secondary function (key check). No wasted words.

  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 the tool has one optional parameter, no output schema, and no annotations, the description covers the main outputs (balance, daily consumption, key check) and the fact it is a free call. Some users might want more detail on the exact structure of the output, but it is largely adequate.

  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 schema describes the single optional parameter 'account' with a note about multi-account profiles. The description does not add further meaning beyond stating it checks keys. Since schema coverage is 100%, the baseline of 3 is appropriate.

  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 states the tool shows balance and daily consumption of an XMLStock account and also checks keys. The verb and resource are explicit, and it distinguishes from sibling tools like xmlstock_images or xmlstock_serp, which handle other domains.

  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?

  Description mentions it's a free service call, implying it can be used without cost, but lacks explicit guidance on when to use it versus alternatives or when not to use it. No exclusions or comparisons to sibling tools are provided.

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

• xmlstock_imagesA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains the paid nature of requests and the meaning of 'truncated: true' when results end earlier than requested. It also lists the return fields, adding valuable context beyond a generic search description.

  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, front-loaded with purpose, no wasted words. It communicates cost, return shape, and pagination semantics efficiently.

  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?

  Despite lacking annotations and an output schema, the description compensates by explaining the return structure and truncated flag. The schema covers parameters thoroughly. Missing usage guidance and authentication notes, but for a search tool with strong schema support, this is nearly complete.

  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 is 71%, with descriptions for most parameters. The description itself does not add parameter-specific details beyond what the schema already provides, such as depth pagination and safeSearch behavior. Since the schema handles parameter semantics well, a baseline of 3 is appropriate.

  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: 'Поиск по картинкам Google через XMLStock' (search Google Images via XMLStock). It specifies the resource (Google Images), the verb (search), and distinguishes from siblings like xmlstock_serp or xmlstock_news by focusing specifically on images.

  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?

  No explicit guidance on when to choose this tool over alternatives. The paid-per-request warning implies cost-conscious use, but the description does not mention exclusions or alternative tools. The context is clear for an image-specific search, but there is no active comparison.

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

• xmlstock_videoA
  4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly reveals the paid-per-request nature, the shape of the return value, and the meaning of the 'truncated' flag, which is valuable behavioral context. It could mention failure modes or rate limits, but for this tool the key behaviors are 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 only two sentences, front-loaded with the tool's purpose and the critical paid-per-request warning. Every sentence adds value: the first states what it does and costs, the second details the return shape and truncation behavior. No filler or redundancy.

  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 video search tool with no output schema and no annotations, the description together with the schema is largely complete. It covers what the tool does, cost, return fields, and truncation semantics. Missing details such as alternative tool guidance and specific error behavior are not critical for this level of complexity.

  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?

  Input schema covers 71% of parameters with descriptions, including depth, region, account, safeSearch, and searchDomain. The description itself does not add parameter semantics beyond mentioning depth in the context of truncation. Query and device are self-explanatory, so the schema coverage is sufficient and a baseline score of 3 is appropriate.

  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 performs Google video search via XMLStock ('Поиск по видео Google через XMLStock') and specifies the returned fields. This is a specific verb+resource combination that distinguishes it from sibling tools like xmlstock_images, xmlstock_news, and xmlstock_serp.

  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 this tool is for video search results and warns that it is paid per request, but it does not explicitly state when to use this tool versus alternatives or mention exclusions. There is no direct comparison with sibling tools like xmlstock_images or xmlstock_serp, leaving usage context somewhat implicit.

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

• xmlstock_wordstat_dynamicsA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the paid nature ('ПЛАТНО за запрос'), the automatic month-stretching rule ('для month период автоматически растягивается на целые месяцы'), and returns the format '[{ date, count, share }]'. These are meaningful behavioral details beyond the input schema, though it doesn't cover all potential quirks like authentication or error handling.

  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 information-dense, covering purpose, cost, parameter syntax, an edge-case behavior, and return format in a few sentences. It is not overly verbose, though the structure is a bit run-on with multiple clauses. Overall, every sentence contributes useful 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?

  Given the tool has 6 parameters and no output schema, the description provides a solid foundation: it explains the return shape, cost implication, and a special case for month period. It does not elaborate on region/account parameters, but those are already described in the schema. The description is sufficiently complete for a parameterized query tool.

  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 67%, leaving query and period without descriptions. The description compensates by explaining the period enum values ('day/week/month'), the date format for from/to, and the month-stretching behavior. It also clarifies the return structure, which helps infer query semantics. This adds value beyond what the schema specifies.

  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 'Динамика частотности фразы по времени' (frequency dynamics over time), specifying the resource (Yandex Wordstat via XMLStock) and the distinguishing scope (time dynamics) from sibling tools like xmlstock_wordstat. This makes the tool's unique purpose immediately obvious.

  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 conveys that this is for historical frequency dynamics and warns 'ПЛАТНО за запрос' (paid per request), which is useful context. However, it does not explicitly state when to use this tool vs alternatives like xmlstock_wordstat, nor does it mention exclusions or prerequisites. The usage context is implied but not directly contrasted with siblings.

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

• xmlstock_wordstat_regionsA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries full burden. It discloses the paid nature, the 24h cache for region names, and the additional paid request on cold cache—good transparency. It does not mention auth requirements, error cases, or rate limits, but covers the most critical behavioral traits.

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

  Conciseness5/5

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

  The description is compact and front-loaded with the core purpose, then provides return format and a key warning. Every sentence adds value; no filler or 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?

  Given no output schema, the description adequately specifies the return structure and important usage caveats. It lacks explicit guidance on when to choose this tool over siblings, but the context signals and sibling names help. It is fairly complete for a simple two-parameter tool.

  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?

  Schema coverage is 50%: the 'account' parameter is described in the schema, but 'query' only has minLength. The description mentions 'для фразы' (for a phrase) which hints at the query parameter but does not clarify format or semantics for either parameter. It adds little value beyond the schema.

  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 returns regional demand distribution for a phrase ('Распределение спроса по регионам для фразы'), specifies the exact return shape, and distinguishes it from siblings by noting it is paid and more expensive than top/dynamics. This is a specific verb+resource+scope.

  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 implies use when regional breakdown is needed and hints at cost trade-offs ('дороже топа/динамики'). It also warns about an extra paid regionsTree request on cold cache, which guides usage. However, it does not explicitly name alternative tools or state when not to use it.

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

• xmlstock_wordstatA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description must carry the full burden. It discloses the pay-per-request cost, return format, and supported operators, which are critical behavioral traits. However, it omits details like rate limits, authentication requirements, and error handling.

  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 a single, well-structured paragraph that efficiently conveys the tool's purpose, cost, return structure, and query syntax. No unnecessary words.

  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 the tool's complexity (3 parameters, no output schema, no annotations), the description covers inputs, outputs, and cost adequately. It could be enhanced with error scenarios or region ID format examples, but is largely complete.

  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 67% (2 of 3 parameters have descriptions). The description compensates for the missing query parameter description by explaining the operators in detail, adding significant meaning beyond the schema.

  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 retrieves Yandex Wordstat frequency and top queries, with specific return structure and operators. It distinguishes itself from siblings like xmlstock_wordstat_dynamics and xmlstock_wordstat_regions.

  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 does not explicitly state when to use this tool versus alternatives. The usage context is implied by the tool's purpose, but no comparisons or exclusion criteria are provided.

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

• xmlstock_newsA
  4.4/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently discloses the cost ('ПЛАТНО за запрос'), the return structure (position, url, title, source, date, snippet), and the truncated flag's meaning. This goes beyond basic purpose and helps the agent anticipate behavior. No contradictions with annotations (none 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?

  The description is compact and efficient: two main clauses that cover purpose, cost, return format, and a key edge case. It is front-loaded with the purpose and avoids redundancy with the schema.

  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 compensates for the lack of an output schema by explicitly listing the returned fields and the meaning of the truncated flag. This covers the core behavioral contract. Some aspects like authentication are not mentioned, but the tool context (sibling auth tools) and schema descriptions fill the gaps. Overall it is sufficiently complete for a search tool with a well-defined schema.

  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 input schema already provides detailed descriptions for 5 of 7 parameters (depth, region, safeSearch, searchDomain, account), giving schema coverage of 71%. The tool description adds minimal parameter-specific detail beyond what the schema already states, mainly reiterating the cost per request. Therefore, a baseline score of 3 is appropriate.

  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 'Поиск по новостям Google через XMLStock' (Search Google news via XMLStock), naming a specific verb and resource. The 'новости' (news) qualifier distinguishes it from sibling tools like xmlstock_serp, xmlstock_images, and xmlstock_video.

  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 establishes clear context for when to use the tool: for Google news searches. It also notes that queries are paid, but it does not explicitly name alternatives or 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.

• xmlstock_set_credentialsA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses key behaviors: file path, permissions, immediate effect, mask in response, and multi-account suffix. No contradictions.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the main action, no wasted words. Efficient and clear.

  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?

  Covers workflow, file location, permissions, immediate effect, multi-account, and masked response. Lacks details on error handling or overwriting behavior, but sufficient for a credential setter.

  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 description coverage is 100%, so baseline is 3. The description does not add significant new semantic information beyond what the schema already provides per parameter.

  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 states the tool saves XMLStock keys to a specific file with permissions 600 and applies immediately without restart. It distinguishes itself from sibling tools (auth_status, balance, etc.) by focusing on credential setting.

  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?

  Implies usage for setting or updating credentials, advises to pass only updated fields, and explains multi-account support via the 'account' parameter. Lacks explicit when-not-to-use or comparisons to siblings, but context makes it clear.

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

• xmlstock_auth_statusA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries full burden. It explains that the tool returns masked keys and indicates missing ones, and provides usage instructions. However, it does not specify the exact return format or any potential side effects, though for a status check this is minor.

  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 sentences, front-loaded with the essential purpose and followed by critical usage guidance. Every sentence adds value with no redundancy.

  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?

  Given the tool's simplicity (no parameters, no output schema, no annotations), the description is fully complete. It covers purpose, behavior, and context of use thoroughly.

  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 no parameters, so schema coverage is 100%. The baseline for 0 parameters is 4 since no additional parameter descriptions are needed.

  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 that the tool checks authorization status, listing which keys are set (masked), which are missing, and how to obtain them. It distinguishes itself from sibling tools like xmlstock_balance or xmlstock_images by focusing on authentication status.

  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?

  Explicitly instructs to call this tool first at the beginning of work with xmlstock. It also provides a clear action plan: if credentials are missing, request values from the user and save via xmlstock_set_credentials. This is optimal guidance.

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

• xmlstock_serpA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full burden and does an excellent job: it discloses that each request is paid, empty results are still billed, depth>10 is paginated with each page as a separate paid request, and device=mobile restricts returned fields. It also reveals the mapping of safeSearch to filter and the behavioral differences of yandex_xml (no SERP features, additional result fields).

  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 long but information-dense; every clause contributes operational details (pricing, limits, field behavior, parameter applicability). It is structured with semicolons and logical groups, though one paragraph is a bit sprawling. Given the complexity, the length is justified, but a tighter organization with bullet points could improve scannability.

  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?

  The tool is complex (3 engines, 17 params, pagination, cost implications, fields differences), and the description covers all critical aspects without an output schema: it explains the full return structure, empty-result behavior, pagination, device restrictions, yandex_xml-specific fields, and parameter mappings. This is complete enough for an agent to use the tool effectively.

  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?

  Even though schema description coverage is 82%, the description adds critical semantics beyond the schema: depth is explained in terms of pagination and per-engine limits (up to 30 for google/yandex, 1000 for yandex_xml), region works for all engines and maps Yandex IDs, and safeSearch's off/moderate/strict maps to different underlying parameters. It also clarifies that engine=yandex_xml changes the meaning of multiple parameters (device, searchDomain, etc.) making them not applicable.

  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 begins with a specific verb+resource: 'Слепок выдачи Google/Yandex через XMLStock' (snapshot of Google/Yandex results via XMLStock), clearly stating the tool's purpose. The detailed return structure and mention of engine variants (google/yandex/yandex_xml) distinguish it from sibling tools like xmlstock_images, xmlstock_news, and xmlstock_video.

  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 clear usage context, including when to prefer yandex_xml (official API, up to 100 results per paid request) over the live yandex engine, and explains that SERP features/packs are absent in yandex_xml. It also notes device=mobile limitations and lists parameters that are not applicable in certain modes. However, it does not explicitly contrast with sibling tools for non-SERP searches, so it stops short of full alternative guidance.

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