Server Quality Checklist

Tool Scores

• get_time_seriesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare the tool read-only and idempotent. The description adds valuable behavioral context: the result includes 0-100 values plus volume when available, and it instructs the agent to inform the user when plan limits are reached. These details go beyond the structured annotations and help the agent set expectations, so a score of 4 is warranted.

  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 sentences, each serving a distinct purpose: core definition, use case, exclusions/alternatives, and error-handling guidance. The most important information is front-loaded and there is no redundancy or fluff. This is a model of concise, action-oriented description writing.

  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 has an output schema, so return shapes need not be repeated. The description covers the core scope, value range, conditional volume field, usage intent, alternatives, and even an edge-case user communication instruction. For a two-parameter tool with rich schemas and sibling context, this description is fully adequate for an agent to select and invoke the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100% and the parameter descriptions in the schema are extremely detailed, especially for 'source' with per-source validation rules and examples. The tool description adds only a small amount of parameter-related meaning (one keyword and one source per request) beyond what the schema already provides. With full schema coverage, the baseline of 3 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?

  The description states a specific verb and resource: 'Full historical series for one keyword and one source' with the value range (0-100). It clearly distinguishes this tool from siblings by naming what it is not for (live trending boards, growth questions) and naming the alternatives. This leaves no ambiguity about the tool's core function.

  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 when-to-use guidance ('Use for charting or custom math'), explicit when-not-to-use guidance ('Not for live trending boards'), and names the two sibling tools (get_top_trends, get_growth) as alternatives. It also provides situational handling for rate limiting and quota exhaustion, which is exactly the kind of contextual usage an agent needs.

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

• get_growthA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark the tool as read-only and idempotent. The description adds useful non-obvious behavior: values are on a 0-100 scale, absolute volume is included when available, windows are preset strings, and rate-limited or quota-exhausted requests should be communicated to the user as a plan limit. This goes well beyond the structured 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 dense but efficient: it starts with the core operation, then adds output semantics, sibling guidance, source caveats, and error handling. Every sentence adds useful information and there is no filler or tautology.

  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 output schema exists, return-value details are not needed in the description. The description covers the key invocation decisions: which sibling to prefer, source semantics, window presets, output scale, and rate-limit behavior. An agent has enough context to call the tool correctly.

  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%, with detailed keyword and source descriptions and the full list of preset windows in the schema. The description reinforces key ideas like comma-separated sources and Android bundle IDs for app sources, but it does not materially add parameter meaning beyond what the schema already provides. Baseline 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 opens with a specific verb and resource: 'Point-to-point growth for a keyword on one or more sources.' It also distinguishes itself from sibling tools by saying to prefer it over get_time_series for growth questions and clarifying that app sources are not the live boards on get_top_trends. This makes the tool's purpose clear and separable from its siblings.

  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 explicitly states when to use this tool: 'Prefer this over get_time_series for growth questions.' It also clarifies what this tool is not for by distinguishing app downloads/app rankings from get_top_trends live boards. The rate-limit instruction adds actionable guidance for handling failed calls.

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

• get_top_trendsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is known. The description adds substantial behavioral context beyond these hints: the board is live, exactly one feed type per call, default sort is current rank, rank_change compares against a prior snapshot with specific windows, and certain store feeds are live boards rather than keyword lookups. The rate-limit/quota handling instruction is also a clear behavioral disclosure. There is 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?

  The description is dense but every sentence earns its place: core purpose, category requirement, sort/window semantics, differentiation from store keyword lookups, alternative tools, and rate-limit handling. It is front-loaded with the essential purpose and does not contain redundant or filler text.

  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 moderate complexity, the rich schema descriptions, the presence of an output schema, and the read-only/idempotent annotations, the description covers all remaining decision points an agent needs. It explains which feed types require category, how sorting and windows work, how to distinguish this tool from siblings, and how to respond to rate limiting or quota exhaustion. Nothing critical is missing for correct selection and invocation.

  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 already documents every parameter with 100% coverage, so the baseline is 3. The description adds meaningful cross-parameter semantics that the schema does not fully convey: which specific feed types require 'category', that 'sort' defaults to current rank and 'rank_change' enables climber comparisons using a 'window', and that the tool is exclusively for live boards rather than keyword or history data. This raises the value above baseline, but because the schema already carries strong per-parameter descriptions, it does not reach 5.

  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 specific, concrete definition: 'Live top-trending board for exactly one feed type. No keyword.' This immediately conveys the resource and its core behavior, and it distinguishes the tool from keyword-based or history-based lookups. It also names the sibling alternatives (get_growth, get_time_series) and explains when they are the correct choice, making the scope unmistakable.

  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 when-to-use and when-not-to-use guidance. It states which feed types require the category parameter, that sort='rank_change' is for climbers with a prior snapshot, and that App Store/Google Play boards are live and not keyword searches. It directly addresses alternatives: 'For an app's history use get_growth or get_time_series... Do not use get_time_series for live boards.' It even instructs how to handle rate limits and quota exhaustion.

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