Server Quality Checklist

Tool Scores

• generate_buyer_queriesA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description bears full burden. It discloses the two-step process (discovers brand profile then writes query pack) and provides cost information. Does not mention authentication or rate limits, but these are less critical for a generative preview tool.

  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, each valuable. First sentence states action and process. Second sentence gives usage context and cost. No redundant information. Very concise.

  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 one parameter, no output schema, and siblings, the description provides enough context: what it does, when to use (before check_visibility), and cost. Lacks detail on output format (what a 'query pack' contains), but the tool is simple enough that this is acceptable.

  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% (single parameter 'domain' fully described). Description adds only 'brand site' context, which is already implicit. Baseline score of 3 is appropriate as no additional parameter meaning is needed 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?

  Description clearly states the tool generates buyer questions for a brand, with specific verb 'generate' and resource 'buyer questions'. It explicitly differentiates from sibling 'check_visibility' by noting it is used 'before a paid check_visibility run'.

  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 explicit usage context: preview or seed prompts before a paid check_visibility run. Does not mention when not to use or alternatives like shopping_check or get_snapshot_diff, but gives clear and actionable guidance for its primary use case.

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

• get_snapshot_diffA
  4.2/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. It discloses that the operation is free and reads saved snapshots, implying read-only behavior. This adds useful context, though it could mention error cases (e.g., no prior runs) or any rate limits.

  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 with zero waste. The first sentence front-loads the core purpose and result, and the second sentence adds usage and cost. Every 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 tool with one parameter and no output schema, the description provides the key aspects: purpose, what is compared, and cost. However, it lacks details about output format or edge cases (e.g., only one run exists), which would improve completeness.

  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 does not add any meaning beyond the input schema. The schema already fully documents the domain parameter (100% coverage). Baseline 3 is appropriate since the description adds no extra param details.

  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 verb 'compare' and the resource 'two most recent check_visibility runs for a domain', and specifies what is returned (score and per-engine deltas). This distinguishes it from sibling tools like check_visibility (which runs checks) and others.

  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 to see what changed between runs', providing clear context for when to use. However, it does not explicitly state when not to use or mention alternatives, which would earn a 5.

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

• check_visibilityA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden. It discloses the cost range ($0.05-$0.30/run) and a cap ($0.50 default), which is critical for decision-making. It does not mention other behavioral aspects like rate limits or idempotency, but the read-only nature is implied by 'check'.

  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 extremely concise: two sentences plus a cost note. It is front-loaded with purpose and then provides essential cost context. 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 4 parameters and no output schema, the description covers the core functionality and cost. It explains the engine defaults and quick mode. It does not specify the return format, but 'score' suggests a numeric result, which is likely sufficient for an agent.

  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%, so the baseline is 3. The description adds value by explaining that 'quick' uses an 8-prompt pack (cheaper, faster), and that 'engines' defaults to all with keys present. This goes beyond the 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 clearly states the tool's purpose: asking AI engines questions and scoring brand visibility. The verb 'score' and resource 'AI Visibility Score' are specific, and the tool distinguishes itself from siblings like 'generate_buyer_queries' or 'shopping_check' by focusing on visibility scoring.

  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 when to use: 'Use when you want the AI Visibility Score for a domain.' It also provides cost information and default cap. However, it does not mention when not to use or explicitly contrast with sibling tools.

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

• shopping_checkA
  4.4/5.0
  Behavior4/5

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

  No annotations, so description carries full burden. Discloses cost structure, default cap, that it's larger than brand check, and sorting behavior. Does not specify read-only status but implies it.

  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?

  Concise with no wasted words. Purpose is front-loaded, followed by usage guidance and cost. Each sentence serves a clear function.

  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 purpose, usage, cost, limitation (no discovery), sorting, and return structure. Lacks explicit output field names, but describes return content adequately for agent understanding.

  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%, so baseline 3. Description adds value by explaining ordering of products parameter, the role of aliases/descriptor, and cost implications for max_cost. Provides usage context beyond 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?

  Description uses specific verb 'Check' and resource 'AI engines recommend specific PRODUCTS.' It clearly distinguishes from sibling 'check_visibility' by stating 'Use for SKU-level questions; use check_visibility for the brand as a whole.'

  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 states when to use (SKU-level questions) and when not (no product discovery, list must be supplied). Compares with sibling check_visibility. Does not mention other siblings but provides sufficient context.

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