Server Quality Checklist

Tool Scores

• regionsA
  4/5.0
  Behavior4/5

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

  Annotations (readOnlyHint, idempotentHint, destructiveHint) already convey safety and non-destructiveness. The description adds behavioral context beyond annotations: it specifies the data time range (last 30 days), the output fields (count, share, affinityIndex), and explains the meaning of affinityIndex ('>100% = above-average interest, <100% = below'). This is valuable behavioral detail not present in 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?

  The description is two sentences long, front-loading the main purpose in the first sentence. Every sentence provides essential information: first the core functionality, second the parameter details and cross-reference to sibling tool. No redundant or extraneous text.

  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 tool has two parameters (both described), rich annotations, and no output schema. The description explains output fields (count, share, affinityIndex) and provides interpretation of affinityIndex. It references list_regions for name resolution. It does not mention potential pagination or limits, but the fixed 30-day window and single-phrase input make this acceptable for a query tool. Completeness is high for the complexity level.

  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 covers both parameters with descriptions (phrase and regionMode enum). The description adds a summary of regionMode ('all, cities, or regions/oblasts') and mentions mapping via list_regions, but this largely repeats schema information. Parameter semantics are adequately handled by the schema, so the description adds minimal extra meaning.

  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 'Returns how demand for a phrase is distributed across regions over the last 30 days,' clearly stating the verb ('returns'), the resource ('demand distribution'), and the scope. It distinguishes itself from sibling tools like list_regions by mentioning how to map region ids to names, and the phrase 'across regions' differentiates it from other analytical 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 description does not explicitly state when to use this tool versus siblings like dynamics or top_requests. It provides some guidance via the regionMode parameter (all, cities, regions) and mentions using list_regions for name mapping, but lacks a clear when-to-use or when-not-to-use statement relative to other tools.

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

• top_requestsA
  4.2/5.0
  Behavior4/5

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

  Beyond the annotations (readOnlyHint, idempotentHint), the description adds crucial behavioral details: the 30-day time window, the fact that counts can arrive as strings (int64), and the optional parameters for narrowing results. This enriches agent understanding beyond safe-operation flags.

  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-load the core functionality and behavior, with no unnecessary words. Every sentence adds value, making it highly concise and well-structured for quick agent comprehension.

  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 complexity (4 parameters, no output schema), the description explains the two result types, data type nuance for counts, and parameter effects. It could mention result ordering or error handling, but overall covers essential context for effective use.

  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%, so the description does not need to compensate. It provides an example for 'phrase' and reiterates parameter roles, but adds little new meaning beyond what's already in the schema's descriptions. 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 it returns search-demand for a phrase over the last 30 days, specifying two distinct result types (containing phrases and related queries) plus totalCount. It distinguishes itself from sibling tools like 'list_regions' and 'raw_request' by focusing on keyword discovery and demand gauging.

  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 says 'Use it to discover keywords and gauge demand,' providing a clear context of use. However, it does not mention when to avoid using it or suggest alternatives among siblings, such as when dynamic data is needed instead.

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

• dynamicsA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's additional details (e.g., 'share is the fraction of all Yandex searches' and the alignment constraint for toDate) add useful behavioral context without contradicting 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?

  The description is two sentences: the first clearly states output and purpose, the second covers parameter constraints. It is front-loaded, concise, and contains no fluff.

  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 6 parameters, no output schema, and high complexity, the description explains the output structure and key parameter constraints. It omits error conditions or empty results, but overall is fairly 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 description coverage is 100%, so baseline is 3. The description adds extra meaning by explaining 'share' and the alignment requirement for toDate, improving understanding beyond the schema alone.

  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 demand over time with a specific data structure (date, count, share) and explicitly calls out its use for seasonality and trend analysis. This distinguishes it from sibling tools like list_regions or top_requests.

  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 suggests usage for seasonality and trend but does not provide explicit when-to-use or when-not-to-use scenarios or alternatives. However, the purpose is clear enough to infer appropriate context.

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

• raw_requestA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds that folderId is auto-injected and body is sent as JSON, providing useful behavioral context beyond 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 sentences with zero waste. Front-loaded with purpose and includes essential usage 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?

  Adequately covers purpose, usage, and parameter behavior. Lacks description of the response format, but given it's an escape hatch, this is acceptable.

  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 100%. Description adds that folderId is injected automatically, which is not in the schema, enhancing understanding of the body 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?

  Clearly states it's an escape hatch for endpoints without dedicated tools, with an example path. Distinguishes from sibling tools like dynamics and top_requests.

  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?

  States it's for endpoints without a dedicated tool and that all endpoints are POST, giving clear context. Lacks explicit when-not-to-use but sufficiently implies usage.

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

• list_regionsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. Description adds that the tree is large and stable, justifying caching strategy.

  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 concise sentences with no waste. First sentence states the core return value, second explains usage, third advises caching.

  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 0-parameter, read-only tool with no output schema, the description completely covers the behavior, return content, and caching recommendation.

  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?

  Tool has 0 parameters, so schema coverage is 100%. Description does not need to add parameter semantics; baseline 4 applies.

  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?

  Clearly states the tool returns the reference tree of regions supported by Wordstat, including IDs and labels. Distinguishes from siblings by specifying it's a reference tree used as input for other tools.

  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?

  Explicitly instructs to fetch once and cache due to large stable tree. Describes how the output feeds into other tools via regionIds/regionMode, providing clear usage context.

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