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

Goes well beyond the annotations: discloses cost (1 quota unit/call, 30/month shared free tier), confirms retry safety and no side effects, and adds a critical behavioral constraint that the fix_brief never contains the cited answer's text and must be rewritten in the user's own words. It also enumerates the return payload and the error case, which no structured field provides.

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

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

Purpose and cost are front-loaded, and the dense returns block earns its space given there is no output schema. It is longer than ideal and the fix_brief field enumeration could be tightened, but almost every clause carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and 0% parameter coverage, the description supplies both: it documents the full return shape (winning, yours, gaps, possibly_missing, fix_brief) and the error variant, and explains the fix_brief ordering. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it defines each of the 5 params with examples and defaults, and supplies the engine's value set ('chat_gpt', 'gemini', 'perplexity') plus country/language examples that the schema lacks entirely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: comparing the user's own page structure against the AI-cited answer for a keyword and returning an actionable fix brief. It explicitly differentiates from the sibling analyze_citation_structure ('Use analyze_citation_structure instead if you just want the winning answer's shape'), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives explicit when-to-use framing ('what should I change on this page to get cited'), names two alternatives with their selecting conditions (analyze_citation_structure for the winner's shape; check_prompt_coverage first when several keywords and the missing ones are unknown). Nothing is left to inference.

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

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

Goes well beyond the annotations by disclosing the metering model: 1 quota unit per sample, 30 units/month shared across all metered tools, and how that caps single-sample calls. It also warns that answers change run to run, so cross-sample domain frequency is a stronger signal than a single run — real behavioral context an agent cannot get from the schema.

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

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

Purpose and routing are front-loaded, and since there is no output schema the returns block is justified. It is nevertheless long and dense, with the quota explanation and the returns enumeration both sizeable for a 5-parameter read tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description documents the entire return shape (including conditional fields only present when samples > 1), plus cost, defaults, and the run-to-run variance caveat. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: it explains engine values with their real semantics (chat_gpt/gemini are in-app answers; perplexity is the sonar API with web search), gives examples for country and language, warns to write the keyword in the target language, and bounds samples at 1–5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('analyze the structural shape of the AI-generated answer actually cited for a keyword') and enumerates the exact dimensions measured (list-leading, opening length, source count/domains). It is clearly distinguishable from siblings like analyze_citation_gap and analyze_citation_structure_batch, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly routes the agent: use the batch variant for more than one keyword, and analyze_citation_gap when you already have your own page and want the gap rather than the winner's shape. It also gives a concrete use case ('before writing content meant to get cited').

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds real value beyond them: the quota cost (1 unit per keyword, 30/month shared across metered tools) and the partial-failure contract (a per-keyword provider error does not fail the whole batch). Those are meaningful operational disclosures not present in the annotations.

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

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

Well front-loaded: purpose and when-to-use come first, then safety/cost/failure semantics, then the return shape, then args. Slightly long, but nearly every sentence earns its place given the 0% schema coverage and absent output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param batch tool with no output schema, the description supplies the return shape (results list with per-keyword error entries plus a summary object with named fields), the quota model, and the partial-failure semantics. Nothing an agent needs in order to call or interpret it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: keywords are documented with concrete examples and a hard max of 10, country and language are given with defaults, and engine enumerates the valid values ('chat_gpt' default, 'gemini', 'perplexity') plus the one-answer-per-topic behavior. This fully compensates for the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (analyze) and resource (structural shape of the winning AI answer) at batch scope, and explicitly contrasts itself with the single-topic sibling analyze_citation_structure. An agent can distinguish it from siblings like analyze_citation_gap or find_citation_leaders without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit when (content planning across a topic cluster, e.g. before writing several related pieces meant to get cited) and an explicit alternative with its selection rule ('instead of calling analyze_citation_structure once per topic'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantially beyond that: cost (1 quota unit per call, 30 units/month shared across all metered tools), the zero-in-history caveat, and the partial-current-month exclusion behavior. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loaded with purpose, then cost, then return shape, then args — a sensible ordering. The return-shape block is long, but it is justified because no output schema exists; the only minor drag is some repetition around the partial-month/latest-month explanation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the full return contract and does so, including the trend object's possible values and the presence-condition on excluded_current_partial_month. Combined with quota, platform limits, and history depth, an agent has everything needed to call and interpret this correctly.

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

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

With 0% schema description coverage, the description fully compensates: it documents all five parameters with formats ('example.com', no https:// or www), defaults, the 13-month cap with the reason (provider history starts 2025-08-01), and hard platform constraints (chat_gpt is US-only and en-only; use 'google' for other countries).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: tracking a domain's AI-citation count month over month. It explicitly contrasts itself with point-in-time checking ('instead of only ever checking a single point in time'), which cleanly separates it from siblings like analyze_citation_gap or find_citation_leaders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives concrete trigger questions ('is our AI visibility improving', 'did that content push actually move the needle') and a negative guideline: don't make a separate call just to read the current count, since the latest entry already is it. Context for when this beats a single-point check is explicit.

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

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

Goes far beyond the annotations: states quota cost per keyword per sample with the free-tier budget (30 units/month), how per-keyword provider errors are isolated rather than failing the call, the 180-day server-side retention window and how get_check_history reads it back for free, and the critical caveat that samples=1 lets a single answer decide 'cited' so samples=3 is needed before telling someone they are or are not cited. Annotations only declare readOnly/idempotent, so this description carries and exceeds the full behavioral burden.

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

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

Front-loads the core answer and the routing decision before the cost/behavioral detail, and each paragraph covers a distinct concern. It is long, but the length is earned by a 7-parameter, no-output-schema, no-schema-description tool. Slight density cost from the inline edge-case parentheticals.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description documents the full return shape (coverage_pct, not_cited, newly_cited/no_longer_cited, per-keyword fields including mentioned vs cited, previous/change, error entries) and even explains the cited/mentioned distinction that a caller could easily conflate. 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.

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

Schema description coverage is 0%, so the description must compensate, and it does for every parameter: domain format ('bare domain... no https://, no www'), keywords with examples and the max-10 limit, brand with the first-label fallback hazard for dictionary-word domains, country/language defaults plus the instruction to write keywords in that language, engine values, and samples range 1-5 with the reliability caveat. No parameter is left undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (check which prompts/keywords cite a domain) and explicitly distinguishes itself from three siblings: analyze_citation_structure ('what does a winning answer look like'), find_citation_leaders ('who wins this one topic'), and analyze_citation_gap (the follow-up for not-cited keywords). An agent can tell exactly what this tool answers without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit when-to-use ('use this first'), explicit sequencing ('then use analyze_citation_gap on whichever keywords come back not cited'), and explicit exclusions naming sibling alternatives. Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/destructive, so the description earns credit for adding quota economics (10 units/call, 30/month shared, max ~3 calls), provider coverage gaps, and the crucial caveat that absence from top_domains is not evidence of zero citations. It also explains that its measurement universe can legitimately disagree with analyze_citation_structure.

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

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

Front-loaded with purpose, then cost, then returns, then args – a sensible order. It is long (roughly 300 words) and the 'Read-only: no side effects' clause partly repeats the annotations, but nearly every other sentence adds non-redundant, decision-relevant detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully documents the return shape (top_domains, compare_domain_rank, source_mix, etc.) and the interpretation caveats an agent needs. For a 5-param, no-schema tool it is complete.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: keyword meaning plus example, platform enum values with default and what's excluded, compare_domain with exact-match/registrable-domain semantics and a worked example, country default and chat_gpt limitation, and language default with 'it' example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find) and resource (domains dominating AI-answer citations for a keyword), plus the exact user questions it answers ('who's winning AI search for this topic'). It explicitly distinguishes itself from analyze_citation_structure (single live answer vs. tracked mention corpus) and check_prompt_coverage, so an agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives direct routing rules: use check_prompt_coverage 'instead if you already know which domain you care about,' and use the compare_domain arg when you want a specific domain's rank. It also states platform availability limits (Perplexity/Gemini unavailable) and country/language constraints (chat_gpt is US/English only), which are genuine when-to-use conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds context annotations cannot carry: quota cost (10 units/call, 30 unit free tier shared across metered tools) and the important semantic caveat that an empty list means the provider's tracked corpus lacks the domain, not that no answer anywhere cites it.

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

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

Purpose, cost, return shape, and parameter notes are ordered logically and mostly front-loaded. The inline return-value block is long but earns its place given there is no output schema; a couple of parenthetical explanations could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully specifies the return object, field meanings, truncation behavior (total_questions can exceed the returned list), and the key limitation of the data source. Nothing needed to call or interpret the tool is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: bare domain format with subdomains included, platform values with default, limit range (1-20, default 20), country default plus the chat_gpt-only-United-States constraint, and language default plus the en-only constraint for chat_gpt.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: 'Find the questions people ask AI answer engines where a domain is already cited as a source, most-asked first.' It also differentiates itself from siblings by naming find_citation_leaders (same measurement corpus) and check_prompt_coverage/analyze_citation_gap as downstream consumers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly gives the use case ('what does ChatGPT already cite us for') and the follow-on workflow ('pick the keywords to feed check_prompt_coverage and analyze_citation_gap'). It also states when to re-verify with check_prompt_coverage instead of trusting this corpus snapshot.

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

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

Annotations only cover the safety profile (readOnly/idempotent/non-destructive), but the description adds material behavior the agent could not infer: zero quota cost, reads Vantage's own record rather than the data provider, and 180-day per-API-key retention with key-scoped visibility.

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

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

Front-loaded purpose sentence, then cost, then return shape, then args -- a logical order with little waste. The nested Returns block is dense, though it is justified since no output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description compensates by spelling out the return fields, and it fully documents all three parameters plus retention and cost behavior. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: domain is defined as the bare domain with an example, keyword is scoped to a single keyword's history, and limit is bounded 1-200 with a default of 50.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('read back your own earlier check_prompt_coverage results for a domain, newest first') and explicitly frames it as distinct from the sibling check_prompt_coverage, which runs new checks. An agent can select this without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Names the selecting condition ('show progress over time', 'has our citation status changed since last week') and contrasts with the unit-spending alternative, making the when-to-use decision unambiguous. No exclusions are left to inference.

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

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

Annotations only declare read-only/idempotent/non-destructive; the description adds substantial context beyond them: it costs 0 quota units, never touches the paid data provider, reads Vantage's own usage record, and degrades to tier 'unmetered' in stdio/local-dev mode with no HTTP token. This is exactly the operational context an agent needs and could not derive from annotations.

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

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

Purpose and the zero-cost caveat are front-loaded, followed by the return shape and the sibling cost table. Although long, every sentence serves the agent's decision (whether to spend quota, what comes back), so nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description supplies the full return shape ({tier, period, units_used, units_limit, units_remaining}), the quota-cost table for every sibling, and the stdio-mode edge case. An agent has everything required to call and interpret it.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no schema semantics to elaborate. The description instead documents the return shape, which is useful but not a parameter concern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Check how much of this billing period's quota is left') and frames the scope precisely. It clearly distinguishes itself from siblings by naming them and their costs, so an agent knows this is the free quota-inspection tool, not a data-consuming analysis tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives explicit when-to-use ('before spending any of it', to answer 'how many checks do I have left', to check whether a batch call will fit) and reinforces the decision with per-sibling cost figures. No inference about when to prefer this tool is left to the agent.

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