Server Quality Checklist

Tool Scores

• analyze_citation_structureA
  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 destructiveHint=false, and the description reinforces this with 'Read-only: no side effects, safe to retry.' It adds useful non-obvious context about quota cost and free-tier limits, which annotations do not 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 front-loaded with the core purpose, then briefly covers side effects, cost, return shape, and sibling alternatives. Every section earns its place, and the arguments section is compact yet informative.

  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?

  Although there is no output schema, the description documents the exact return shape, including field types and the domain-list limit. Combined with the one documented parameter, quota information, and sibling routing, an agent has everything needed to call this 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?

  The input schema has 0% description coverage, so the description must compensate for the keyword parameter. It does so by defining it as 'the topic/query to analyze' and providing a concrete example ('how to reduce churn'). This is sufficient for a single simple 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?

  The description states a specific verb ('Analyze') and resource ('structural shape of the AI-generated answer actually cited for a keyword'), and enumerates concrete dimensions such as leading list, opening passage length, and source domains. It clearly distinguishes this tool from siblings by naming batch and gap alternatives.

  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: to understand what a winning AI-search answer looks like before writing content. It also names alternatives with conditions: use the batch variant for multiple keywords and analyze_citation_gap when the user has their own page and wants the gap.

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

• find_citation_leadersA
  4.9/5.0
  Behavior5/5

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

  While the annotations already declare readOnlyHint=true and idempotentHint=true, the description builds on this with 'Read-only: no side effects, safe to retry' and adds the quota cost ('Costs 10 quota units/call (free tier: 3 checks/month total across all tools)'). It also details the exact return structure, including conditional fields, which goes well beyond the annotations without contradicting them.

  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 organized into scannable sections (purpose, usage guidance, args, returns) and front-loads the core value proposition. It is slightly verbose with examples and caveats, but every sentence contributes to correct usage, so it earns a 4 rather than a 5. A tighter edit could trim redundant phrasing like 'Read-only: no side effects' (already implied by the annotation) to improve 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?

  Despite having no output schema, the description fully documents the return JSON, including nested objects and the conditional 'compare_domain_present' field. Combined with explicit parameter details, platform constraints, quota information, and sibling references, an agent has everything needed to call this tool correctly without external lookup. The description fully compensates for the lack of structured context.

  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 the context signal reports 0% schema coverage, the description compensates with an 'Args:' section that explains every parameter in plain language, provides an example value for 'keyword', lists valid options for 'platform' (including a default), and clarifies the 'compare_domain' format. This adds far more meaning than the sparse schema, making the tool callable with confidence.

  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 ('Find which domains dominate AI-answer citations for a topic/keyword') and immediately distinguishes itself from siblings by framing the use case as 'who's winning AI search for this topic' or 'is my competitor cited more than me for X.' It also names a sibling (check_ai_visibility) as an alternative, making the tool's unique purpose 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?

  Provides explicit when-not-to-use guidance: 'Use check_ai_visibility instead if you already know which domain you care about and just want its own citation count, not a leaderboard.' It also discloses platform limitations ('Perplexity and Gemini aren't available') and gives example queries, so an agent knows exactly when to select this tool over alternatives.

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

• analyze_citation_gapA
  5/5.0
  Behavior5/5

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

  The description goes beyond the annotations by disclosing cost ('Costs 1 quota unit/call'), safety ('no side effects, safe to retry'), and error behavior ('or {"error"} if either side couldn't be fetched/parsed'). This adds meaningful operational context beyond readOnlyHint, idempotentHint, and destructiveHint.

  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?

  Every sentence earns its place: purpose, use case, safety/cost, return shape, alternatives, and arguments. The key distinction is front-loaded, and the return format is detailed but justified because there is no output schema.

  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 lack of an output schema, the description fully specifies the return structure, the error case, cost, read-only behavior, and the correct alternative tool. An agent has everything needed to call this tool correctly and interpret its results.

  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 description coverage at 0%, the description fully compensates by explaining each parameter: keyword is 'the topic/query to check' with an example, and your_url is 'full URL of your own page to compare' with an example. The schema only provides property names, so this semantic enrichment is essential and well done.

  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 ('compare'), a specific resource ('your own page's structure against the AI-generated answer actually cited for this keyword'), and a concrete outcome ('concrete gaps to close'). It also explicitly distinguishes the tool from analyze_citation_structure, so an agent can select it without ambiguity.

  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 this to answer what should I change on this page to get cited' and an explicit alternative: 'Use analyze_citation_structure instead if you just want the winning answer's shape'. This leaves no inference to the agent.

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

• analyze_citation_structure_batchA
  5/5.0
  Behavior5/5

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

  Annotations already supply readOnly/idempotent/destructive hints, but the description adds significant behavioral context not covered by annotations: quota cost per keyword, free-tier limits, and per-keyword error fallback behavior ('that keyword's entry just carries an 'error' field instead'). It also clarifies 'safe to retry' and return shape, going well 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.

  Conciseness5/5

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

  The description is front-loaded with the core purpose and remains focused throughout. While it is longer than a brief one-liner, every sentence contributes necessary information: usage context, cost, error behavior, return format, and parameter examples. No filler or redundancy beyond a brief repetition of annotation hints, which is harmless.

  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 no output schema, the description fully explains the return payload: a 'results' list with per-keyword details and a 'summary' object with aggregate counts. It also covers batch semantics, error handling, quota, and the relationship to the single-keyword sibling tool, making it complete for the tool's complexity.

  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 schema has 0% description coverage for the 'keywords' parameter, so the description compensates effectively by providing concrete examples (['how to reduce churn', ...]), defining the parameter's purpose ('topics/queries to analyze'), and specifying the max length (10). This adds real semantic value that the schema lacks.

  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 with a specific verb ('Analyze the structural shape of the winning AI answer') and identifies the exact aspects analyzed (list, opening length, sources). It distinguishes itself from the sibling 'analyze_citation_structure' by explicitly framing itself as the batch version for multiple related keywords.

  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 provides explicit when-to-use guidance: 'Use this for content planning across a topic cluster' and names the alternative: 'instead of calling analyze_citation_structure once per topic.' It also mentions quota costs and error handling, giving the agent clear context for decision-making.

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

• analyze_citation_trendA
  5/5.0
  Behavior5/5

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

  Annotations already include readOnlyHint and idempotentHint, but the description adds valuable context: quota costs (1 unit/call, free tier limit), real measured zeros versus gaps, and data source limitations (DataForSEO begins 2025-08-01). 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?

  The description is long but every sentence earns its place—purpose, usage, returns, parameters, alternatives, and constraints are all included without fluff. It is front-loaded with the core purpose and structured logically.

  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?

  With no output schema and only basic schema, the description provides a full return format, parameter constraints, behavioral notes, and tool alternatives. It is complete enough for an agent to invoke correctly without ambiguity.

  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%, but the description fully explains each parameter: domain format (bare, no https/www), platform options with defaults and unsupported values, and months default/cap with reason. This exceeds schema documentation and provides crucial context.

  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: tracking how a domain's AI-citation count changes month over month, with a specific verb ('track') and resource ('domain's AI-citation count'). It explicitly contrasts with check_ai_visibility for current counts, distinguishing it from 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 Guidelines5/5

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

  The description provides explicit when-to-use guidance ('answer is our AI visibility improving'), names an alternative tool (check_ai_visibility) for a different need, and notes platform limitations (Perplexity and Gemini unavailable). This gives the agent clear decision criteria.

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

• check_ai_visibilityA
  5/5.0
  Behavior5/5

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

  Annotations already declare read-only, idempotent, and non-destructive. The description reinforces these ('Read-only: no side effects, safe to retry') and adds cost information (10 quota units/call, free tier limit) and platform limitations. Return format is explicitly documented, covering behavior 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?

  The description is front-loaded with the core purpose, then moves to usage guidance, return format, and alternatives. Each sentence adds essential information for correct invocation—no filler or redundancy. The parameter explanations are integrated efficiently.

  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?

  Despite having no output schema, the description fully specifies the return object with field names and types. It also covers quota, platform coverage, and alternatives, providing everything an agent needs to decide on and execute the 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?

  Schema description coverage is 0%, but the description fully compensates. It explains the domain format requirements ('bare domain... no https://, no www') and enumerates the accepted platform values with a default and an explicit note on unavailable options. No parameter meaning is left to inference.

  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 ('check how many times a domain is cited') and explicitly names the platforms supported. It also differentiates from siblings by name in the usage section, making the purpose 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?

  Provides explicit when-to-use scenarios ('is my brand/domain visible in AI search') and directly names two alternative tools with the conditions that select them. Also clarifies platform availability (Perplexity and Gemini aren't covered), leaving no ambiguity.

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