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

Annotations already mark the tool read-only; the description adds that it 'returns stored data' rather than performing a live fetch, which is behaviorally important. It also discloses what data is included (assistants, prompts, competitor comparison) without contradicting the readOnlyHint.

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 with no filler: lead with the data returned, give concrete user-phrase triggers, then state the freshness caveat and refresh alternative. Every sentence adds decision-relevant 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?

Given an output schema and safe read-only annotations, the description is largely sufficient; the stored-data caveat and refresh routing are important. It could be more explicit about when to prefer get_visibility_history or compare_competitors, but the trigger phrases compensate.

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 the description does not need to explain the parameters. It reinforces the meaning of the engine filter by naming the supported assistants, but adds no new mechanics beyond what the schema already provides.

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 names a specific verb and resource ('Get the latest AI visibility data for a tracked brand'), enumerates the assistants, prompts, and competitor comparison it covers, and distinguishes itself from refresh_brand. It does not explicitly delineate overlap with siblings like get_citations or compare_competitors, but the core purpose is unmistakable.

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 trigger queries ('how visible am I on AI?', 'who's citing my brand?', 'show me my AI visibility score') and an explicit alternative when data must be fresh ('call refresh_brand'). This gives an agent a clear basis for selecting this tool and routing to another when needed.

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)Skip and openWorldHint=false. The description adds useful behavioral context beyond that: it returns share-of-voice percentages and prompt-level wins/losses, and mentions brand-configured competitors. No mutation or side effects are implied, consistent with 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?

Three sentences with zero filler: the first states the action and scope, the second lists return values, and the third gives direct invocation triggers. The most actionable information is front-loaded, and every sentence earns its place.

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 a 3-parameter schema with 100% coverage, a full output schema, and read-only annotations, the description supplies everything an agent needs to decide when to invoke the tool and what to expect back. No critical behavioral or usage details are 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%, so parameters are already documented. The description adds minimal semantic value beyond the schema, mostly reinforcing that the comparison is category-scoped and competitors may be the brand's configured set. This meets the baseline but does not elevate it.

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 ('Compare'), a precise resource ('a brand's AI visibility against competitors'), and the category scope ('same category'). It also names concrete outputs (share-of-voice percentages, winning prompts), which clearly differentiates it from siblings like check_visibility or get_citations.

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 'Use when' clause lists three concrete user intents ('who beats me in AI search?', 'compare me to my competitors', 'why does [competitor] get cited more?'). This gives clear context for invocation, though it does not explicitly name alternative tools or when-not-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?

Beyond the annotations, the description adds valuable behavioral context: it explicitly says the tool 'Replaces the brand's active prompts' while 'historical run data is preserved,' and it calls out the ANTHROPIC_API_KEY requirement and the use of Claude Haiku. This gives an agent a clear picture of side effects and prerequisites beyond the destructiveHint and openWorldHint 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 three sentences with no filler: the first states the core operation and prerequisite, the second discloses the side effect, and the third gives clear usage guidance. Every sentence earns its place and the most important information 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?

For a tool with only two parameters, one required, and an output schema present, the description is complete. It covers what the tool does, when to use it, the key prerequisite, and the destructive side effect. Nothing essential is missing for an agent to select and invoke it 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?

The input schema already documents both parameters fully (100% coverage), including defaults and constraints for count and the meaning of brand_id. The description does not add parameter-specific details beyond the schema, so the baseline of 3 applies. It does provide general context about what the prompts are for, but not enough to raise the score.

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 ('Regenerate') and resource ('buyer-intent prompt set for a tracked brand'), making the tool's purpose immediately clear. It goes beyond the title by specifying the model (Claude Haiku) and the fact that it replaces active prompts, which also helps differentiate it from sibling tools like list_brands or refresh_brand.

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 gives explicit when-to-use guidance: 'Use when the user wants better or more prompts, or to upgrade from the generic starter prompts after adding an Anthropic key.' It also states the key prerequisite. However, it does not mention when not to use it or name direct alternative tools, so it falls slightly 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 mark this as read-only and closed-world focused. The description adds behavioral context by detailing exactly what each citation event includes and notes the 'matched brand URL from engine-native citation data when available,' which sets expectations about conditional data. No destructive or surprising behavior is hidden.

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 concise and well-structured: the first sentence defines the tool's core purpose, the second sentence itemizes the return data, and the final sentence gives user-facing triggers. Every sentence earns its place, with no redundancy or 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?

Given the tool is read-only, has an output schema, and fully documented parameters, the description covers what the tool does, what it returns, and when to use it. Minor omissions like pagination or rate limits are not critical here, but an explicit 'when not to use' might slightly strengthen completeness.

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%, with each parameter (days, engine, brand_id) already documented with defaults, ranges, and enums. The description adds no parameter-specific semantics beyond what the schema provides, so the baseline score of 3 applies.

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 specific action: 'Get citation events where AI assistants mention the brand.' It also enumerates the event contents (prompt, response excerpt, link presence, matched brand URL), which makes the resource unambiguous. The name and content are distinct from sibling tools like check_visibility or 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 says 'Use when the user asks...' and provides three concrete example phrasings. It does not list when not to use it or direct to an alternative, but the context is clear enough and the sibling set makes the selection decision straightforward.

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 mark the tool read-only and open-world, and the description adds meaningful context beyond them: it returns prioritized topics/formats and performs a gap analysis against competitors winning the same prompts. No destructive or unexpected behavior is hidden.

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 tight sentences: the first states purpose and output, the second gives direct invocation examples. Every sentence earns its place with no filler or 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 a rich input schema, an output schema, and read-only annotations, the description is nearly complete for a straightforward recommendation tool. It could mention that the brand must already be tracked, but that is implied by the schema's 'tracked brand' wording.

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 input schema covers both parameters with 100% description coverage, and the tool description does not add extra parameter-level detail. A baseline of 3 is appropriate since the schema carries the semantic weight.

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 names a specific verb and resource: 'Get actionable content recommendations based on AI visibility gaps.' It also states the concrete output, prioritized topics and content formats, which clearly distinguishes it from siblings like check_visibility or compare_competitors.

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 three user-query triggers for when to use the tool, making the use case clear. It does not state when not to use it or name 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?

The description is consistent with the readOnlyHint annotation (a read operation) but adds little beyond that. It mentions the breakdown per engine, which is a useful behavioral trait, but does not disclose other traits like rate limits, authentication, or data freshness. With the readOnly annotation lowering the bar, the description provides marginal added transparency, hence a 3.

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 with no fluff; the core purpose is front-loaded and the example queries provide immediate usage context. Every word earns its place.

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 and readOnly annotation, so the description does not need to explain return values or safety. The examples cover the main use cases. A minor gap is that it does not mention whether a brand must be tracked before history is available (suggested by track_brand sibling), but this is not critical for correct invocation.

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 parameters (brand_id, days, granularity) are already documented. The description adds no parameter-specific meaning beyond the usage example ('last month' implying days=30), which is not substantial. Baseline 3 applies because the 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?

The description clearly states the tool gets a time-series history of AI visibility score, broken down per engine, which is a specific verb+resource. This distinguishes it from siblings like check_visibility (which likely returns current values) and compare_competitors (which compares across 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 user query examples ('how has my AI visibility changed over time?', 'is my visibility growing or shrinking?', 'show me the trend for the last month') that signal when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks the when-not/alternatives element for 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 indicate readOnlyHint, idempotentHint, and nondestructive behavior document the safe profile. The description adds useful context about the local database scope, return content, and the brand_id lookup purpose, going 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.

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

Two sentences, no filler, with core action and returned fields front-loaded. The usage trigger appears immediately after, making the definition efficient and scannable.

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 output schema covers return values, annotations cover safety, and the description covers scope, contents, and usage context. An agent has everything needed to select and invoke this tool correctly without missing details.

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 zero parameters stub parameters in the schema at 100% coverage, the baseline is 4. The description adds no parameter-specific semantics because none exist, and none are needed.

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 ('List') with a clear resource ('every brand tracked in the local database') and enumerates the returned fields. It clearly distinguishes itself from siblings like track_brand and refresh_brand by focusing on read-only listing.

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 gives explicit triggers: when the user asks 'which brands am I tracking?' and when looking up brand_id for other tools. It lacks explicit when-not-to-use guidance, but the invocation context is clear and sufficient for a zero-parameter read 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 destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context beyond that: engines run sequentially and the tool returns only after all scans finish (blocking behavior). This extra detail is useful for an agent deciding whether to call 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?

All four sentences earn their place: purpose, behavior, usage triggers, and completion semantics. It is front-loaded with the core action and has no filler, making it easy to parse quickly.

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 the tool's low complexity (2 parameters, one required), the presence of an output schema, and annotations covering safety profile, the description provides everything an agent needs to decide when and how to invoke it 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?

Schema description coverage is 100%, so the input schema fully documents both brand_id and engines, including the enum values and the default behavior when engines is omitted. The description adds no significant parameter-level meaning beyond what the schema already provides.

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 ('trigger'), a specific resource ('fresh AI visibility scan for a tracked brand'), and enumerates the engines involved. It clearly distinguishes itself from siblings like check_visibility or get_visibility_history by emphasizing 'fresh' scan triggering rather than reading existing 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?

It provides explicit trigger phrases ('refresh my data', 'rerun the scan', 'I want fresh data right now') that map to user intents. However, it does not explicitly name alternatives or exclusion criteria, so it stops short of the highest bar.

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=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds genuinely useful behavioral context: the conditional Claude-Haiku-vs-generic-prompts behavior depending on ANTHROPIC_API_KEY, and the DB-creation side effect. No contradiction with annotations; the only gap is it doesn't spell out idempotent re-tracking behavior, which the annotation partially covers.

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, front-loaded with the core purpose, and every sentence earns its place: purpose, conditional behavior, then usage triggers. Slightly long due to the enumerated trigger phrases, but they add routing value rather than bloat.

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 an 8-parameter mutation tool with an output schema, the description covers purpose, side effects, conditional behavior, and follow-up actions. Could note what happens if the brand already exists (idempotency semantics), but idempotentHint=true and the output schema reduce the burden.

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 well-written parameter descriptions (aliases, exclude_terms, prompt_count all documented). The description adds minimal param-level detail beyond the schema, which is acceptable at the baseline-3 level; it doesn't need to compensate for coverage gaps.

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 ('Start tracking a brand's AI visibility') and names its concrete effects: creates the brand in the local database and generates buyer-intent prompts. It also routes to siblings (refresh_brand for first scan, generate_prompts for upgrade), clearly distinguishing it from the list/visibility/compare tools.

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 lists trigger conditions ('use when the user says track my brand, add my site, start monitoring acme.com, or when another tool reported the brand doesn't exist') and gives a follow-up action ('After tracking, call refresh_brand to run the first scan'). Names generate_prompts as the alternative for upgrading prompts. Little 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.