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

Annotations already declare readOnlyHint=true and openWorldHint=false, establishing this as a safe read operation, so the bar for behavioral disclosure is lower. The description adds meaningful context by explicitly stating 'Returns stored data' and pointing to refresh_brand for freshness — a key behavioral trait that prevents agents from expecting live data. This is valuable context beyond 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?

The description is two sentences, front-loaded with the core purpose, and every clause earns its place. The example queries and the refresh_brand note are high-value additions with zero waste.

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?

The tool has an output schema (so return format need not be explained), full schema coverage of both parameters, complete usage examples, and a clear alternative-path note. The description covers what the tool does, when to use it, what it returns (stored data), and when not to use it — complete for this complexity level.

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 100%: brand_id is 'Stable identifier of the tracked brand to inspect' and engines is fully documented with its enum options and default behavior. Since the schema handles all parameter semantics completely, the description isn't required to add param info, landing at the baseline of 3.

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?

The description clearly states the verb ('Get'), the resource (AI visibility data for a tracked brand), and scope (which AI assistants cite the brand, for which prompts, and competitor comparison). It distinctly separates this from siblings like get_visibility_history and compare_competitors by focusing on the current snapshot of citation data.

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?

Provides explicit example user queries ('how visible am I on AI?', 'who's citing my brand?', 'show me my AI visibility score') as triggers. Critically, it names a sibling alternative (refresh_brand) and explicitly directs when that should be used instead ('for fresh data, call refresh_brand'), satisfying the when/when-not requirements.

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=true, so the safety profile is covered. The description adds the category-scoping context and the exact outputs (SoV percentages, winning prompts). However, it doesn't disclose behaviors like how competitors are determined by default, the granularity of prompt-level detail, or availability of the data for different categories.

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?

Three sentences, all dense with useful information: purpose, return values, and trigger examples. Zero filler or redundancy. The description front-loads the core function and enumerates concrete outputs before giving usage examples.

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?

The tool has an output schema (which covers return format), good annotations (readOnlyHint), and 100% schema parameter coverage. The description provides trigger examples, expected outputs, and scoping context. Given this richness, the description is complete—nothing critical 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 100%, with all three parameters described in the schema. The description's main value-add is explaining that competitor_domains defaults to the brand's configured competitors when not provided, which supplements the schema's phrasing. The core parameter semantics are handled by the schema, so baseline 3 is appropriate.

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?

The description uses a specific verb+resource combo ('Compare a brand's AI visibility against competitors') and lists exact return values (share-of-voice percentages, prompts the user wins/loses). It clearly distinguishes from siblings by focusing on competitive comparison vs single-brand visibility (check_visibility, get_visibility_history).

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?

The description explicitly provides example user queries ('who beats me in AI search?', 'compare me to my competitors', 'why does [competitor] get cited more?') making trigger conditions crystal clear. Sibling tools like check_visibility and get_content_gaps handle single-brand or gap analysis, whereas this tool is specifically for competitive comparison, which the examples reinforce.

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?

Description discloses that this generates prompts using Claude Haiku, requires an API key, and replaces active prompts while preserving historical run data. Annotations note readOnlyHint=false (mutation) which the description aligns with by stating prompts are replaced. Adds the API-key requirement and data-preservation 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.

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

Two sentences, efficient and front-loaded with the core action. Each clause earns its place, though it could arguably be trimmed slightly. No wasted words.

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?

Given an output schema exists (return values don't need explanation), 100% schema coverage, and clear annotations (mutation confirmed), the description fully covers prerequisites, effects, data safety, and usage context. Complete for a moderately complex mutation tool.

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 100% for both parameters. The description reinforces brand_id as the target and the count's default/range appears in schema. The description doesn't add heavy param detail but schema fully covers it, so baseline 3-4 is appropriate given high coverage.

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?

Specific verb+resource ('Regenerate the buyer-intent prompt set for a tracked brand') with clear scope and the model used. Distinguishes from siblings: siblings cover visibility, gaps, competitors, and brand tracking, while this uniquely handles prompt generation.

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 states when to use (user wants better/more prompts, upgrade from starter prompts after adding Anthropic key) and what prerequisites exist (requires ANTHROPIC_API_KEY). Clearly contrasts with generic starter prompts as the alternative.

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 declare readOnlyHint=true, so safety is covered. The description adds value by explaining the structure of each citation (prompt, response excerpt, and whether it is a linked citation, mention, or paraphrase), which goes beyond the schema. 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.

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

The description is two sentences, front-loaded with purpose, and includes usage examples without redundancy. Every sentence earns its place; no filler or repetition.

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 read-only annotations, a full output schema, and clear usage guidance, the description is sufficient for an agent to select and invoke the tool. It does not mention ordering or pagination, but those are not critical for this straightforward read operation.

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 100% and all parameters have descriptive comments. The description does not add parameter-specific syntax or semantics beyond what the schema provides, so it stays at the baseline of 3 for high schema coverage.

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?

The description uses a specific verb ('Get') with a clear resource ('actual citation events') and details the content (prompt, response excerpt, citation type). It distinguishes itself from siblings like check_visibility and get_visibility_history by focusing on citation events rather than aggregate visibility, and it provides example user queries.

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 states when to use: 'Use when the user asks...' followed by three concrete example queries. This gives clear context for invocation, but it does not mention when NOT to use or mention alternatives, so it stops short of a 5.

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=true, so the agent knows this is a safe read operation. The description adds context about what the tool produces (prioritized topics and formats, gap analysis vs competitors winning same prompts) but doesn't disclose things like whether recommendations require a tracked/refreshed brand or how current the data is. With readOnly annotation covering the safety profile, a 3 is appropriate.

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?

The description is fairly compact at three sentences and front-loads the core purpose. The example user phrases add practical value but could be tightened; still, it's efficient with no wasted sentences.

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?

The tool has a full input schema (100% coverage), an output schema, and clear readOnly annotations. The description explains what the output represents (prioritized topics/content formats to close gaps) and when to use it, which is sufficient given the rich structured data already present. It doesn't need to explain return values since an output schema exists.

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 100%, so both parameters (brand_id, max_recommendations) are fully documented in the input schema. The description doesn't add parameter-specific details beyond what the schema provides, so baseline 3 is appropriate.

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?

The description clearly states the tool returns content recommendations based on AI visibility gaps, specifically prioritized topics and formats to close gaps versus competitors. It uses a specific verb (get) with a clear resource (content gaps) and distinguishes itself well from siblings like check_visibility or generate_prompts.

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?

The description provides explicit example queries that should trigger this tool ('what should I write to improve AI visibility?', 'what content gaps do I have?', 'how do I get cited more by AI?'). While it doesn't name alternative tools to use instead, the clear trigger phrases effectively guide appropriate usage.

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=true, so the safety profile is covered. The description adds useful scoping detail (per-engine breakdown, time-series nature) beyond the schema. However, it doesn't describe pagination or the time-series return structure, though the output schema exists to handle that, keeping the bar lower. A 3 is appropriate given annotations carry the safety 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?

The core description is efficient—a single purpose sentence followed by usage examples. The example queries earn their place by providing concrete trigger patterns. Slightly padded with three near-synonymous example questions, but all serve the same differentiation purpose, so minor deduction only.

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?

Tool complexity is moderate (3 params, 1 enum, output schema present). The description covers the purpose, per-engine breakdown, and temporal use cases. The output schema handles return-value documentation, so the description doesn't need to. Could add a note about data freshness or range limits, but days min/max are already in the schema.

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 100%, so all three parameters (days, brand_id, granularity) are documented in the schema. The description adds the temporal framing ('growing or shrinking', 'trend') but doesn't add syntax or format details beyond what the schema already provides. Baseline 3 is correct when schema does the heavy lifting.

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?

Specific verb+resource+scope: 'get' the time-series history of a brand's AI visibility score, broken down per engine. It clearly distinguishes from siblings like check_visibility (single-point check) and compare_competitors, and explicitly states the per-engine breakdown which adds specificity.

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?

Provides explicit example queries that map to this tool ('how has my AI visibility changed over time?', 'is my visibility growing or shrinking?', 'show me the trend for the last month'). This gives agents concrete trigger patterns and clearly implies when to use it versus the sibling check_visibility tool.

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=true and openWorldHint=false. The description adds useful context beyond annotations by explaining it's a local-database lookup and that its primary purpose is supporting other tools by providing brand_id values. It discloses the return content comprehensively without repeating what the output schema already likely conveys.

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?

Two sentences, zero waste. The first sentence delivers the core purpose and field list; the second gives concrete usage triggers. Everything earns its place with no redundancy.

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 0 parameters, an output schema present, and readOnly annotations in place, this description is complete. It names the result fields, ties into the tool ecosystem via brand_id lookup, and gives concrete usage triggers. Nothing is left unaddressed for a list-style tool.

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 has zero parameters, and schema coverage is 100%, so there are no parameter semantics to document. Per rubric, a 0-param tool gets baseline 4. The description appropriately doesn't waste space on parameters that don't exist.

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?

The description states a specific verb+resource ('List every brand tracked in the local database') and enumerates exactly what fields are returned (domain, category, competitors, refresh frequency, active prompt count). It explains how to use this to look up brand_id for other tools, which distinguishes it from the sibling tools that operate on specific brands.

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?

The description provides explicit usage context: use when the user asks 'which brands am I tracking?' or to look up the brand_id other tools need. This gives clear when-to-use guidance and implies how it fits within the broader tool family, though it doesn't explicitly name alternative tools or state when NOT to use it.

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 provide readOnlyHint=false and openWorldHint=true but the description adds substantial behavioral detail: it returns immediately with run IDs rather than results, results arrive asynchronously in 30-60 seconds, and it only executes engines with configured API keys. This is meaningful context beyond what the annotations convey, explaining the async nature and dependency requirements.

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?

Three sentences that each earn their place: the first states the primary function and scope, the second provides usage triggers when to invoke, the third explains the async return behavior. No fluff, no repetition of schema content, and the most important information (what it does) is front-loaded.

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?

The tool is relatively simple with only 2 parameters and full schema coverage. An output schema exists so return-value documentation is not needed. The description covers the action, the engines involved, when to use it, the immediate return behavior, and the async timing of results. For a trigger-style tool, this is complete and well-suited to its complexity level.

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 100%, so the schema already documents both parameters well (brand_id as stable identifier, engines with its enum values and omission semantics). The description reinforces engine behavior by naming the concrete engines and noting the 'optional engine filter' default behavior of refreshing all configured engines. The description adds minimal value beyond the schema since coverage is complete, justifying the baseline 3.

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?

The description clearly states what the tool does: 'Manually trigger a fresh AI visibility scan for a tracked brand.' It names the specific action (refresh/scan), the resource (brand), and enumerates the engines covered (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews). It also distinguishes its context from sibling tools like get_visibility_history (which reads history) and check_visibility (which checks current state) by focusing on the on-demand refresh action.

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?

The description provides explicit usage triggers: 'Use when the user asks refresh my data, rerun the scan, or I want fresh data right now.' It explains behavioral constraints (only runs engines with API keys configured, runs against current prompt set) and clarifies what happens upon invocation (returns run IDs immediately, results in 30-60 seconds). This gives strong when-to-use guidance with clear context.

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 readOnlyHint=false and openWorldHint=true, which cover mutation and side effects. The description adds significant behavioral detail beyond this: the dual-mode prompt generation (Claude Haiku when ANTHROPIC_API_KEY is set, otherwise three generic starter prompts), explaining the conditional behavior based on env configuration. This is genuinely valuable context an agent wouldn't infer 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?

The description is well-front-loaded with the core purpose in the first sentence, followed by operational details. It's dense with useful info (trigger phrases, env-dependent behavior, follow-up action) but each sentence earns its place. Slightly longer than minimal, but every clause adds value.

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 mutation tool with openWorldHint=true, the description covers the key behavioral facets: side effects (DB creation), conditional prompt generation, and the required refresh_brand follow-up. It doesn't detail return values, but an output schema exists which flags this context signal, so that's acceptable. The main gap is not clarifying how competitors/aliases/exclude_terms fully affect behavior, but the schema already documents their semantics.

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 100%, so all 8 parameters are documented in the schema itself. The description doesn't add parameter-specific details beyond what's already there, but it does clarify the prompt_count behavior in context (generation of buyer-intent prompts). Baseline 3 is appropriate given full schema coverage.

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?

The description uses a specific verb+resource ('Start tracking a brand's AI visibility') and clearly explains what the tool does: creates the brand in the local DB and generates buyer-intent prompts. It distinguishes itself from siblings by noting the upgrade path to generate_prompts and the follow-up refresh_brand call.

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?

Provides explicit trigger phrases ('track my brand', 'add my site', 'start monitoring acme.com') and a clear when-to-use scenario (when another tool reports the brand doesn't exist). Also names the alternative tool generate_prompts and the required follow-up refresh_brand, giving strong usage context.

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