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

Notes that tags are 'free-form' and 'creates the tag if new', going beyond annotations. Annotations already indicate non-read-only and non-destructive, and description aligns well. Could mention tag limits or removal.

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 keywords for AI triggering, then explains function and gives examples. Efficient but slightly longer than minimal; could be tightened.

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 simple two-parameter tool with full schema coverage and output schema existing, the description provides ample context, use cases, and pairing advice, leaving no gaps.

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 baseline is 3. The description adds context (free-form, tag creation) but not new parameter-specific details beyond schema. Solid but not exceptional.

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?

Opens with explicit trigger phrases like 'tag this site as X' and 'organize my sites', clearly identifying the tool's function. Distinguishes from sibling 'filter_sites_by_tag' by stating they pair together.

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 the tool (e.g., 'tag this site as X') and suggests pairing with filter_sites_by_tag for drill-down. No explicit when-not, but the context is clear.

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 (readOnlyHint, destructiveHint, idempotentHint) already indicate safety. The description adds context: it returns top values with visitor counts, specifies property name constraints, and mentions default date ranges. No contradictions.

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 a single paragraph but well-organized: starts with answer-first pattern, gives examples, then explains parameter details. It is concise without waste, though could benefit from slight structuring.

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 complexity (5 params, 1 required, output schema exists) and sibling list, the description covers purpose, usage, and parameter details adequately. It lacks mention of error handling for missing properties but is sufficient for an AI agent.

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%, baseline 3. The description adds value beyond schema, e.g., for 'limit' it explains default and pagination, and for 'property' it gives a usage example. It does not redundantly repeat schema descriptions.

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 specific verbs and resources (group a custom event property, returns top values with visitor counts) and provides clear examples. It explicitly distinguishes itself from sibling tool get_breakdown for built-in dimensions.

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 context on when to use this tool versus get_breakdown, and gives examples of queries. It does not include explicit when-not-to-use instructions but the alternative is clearly stated.

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 are present (readOnlyHint=false, destructiveHint=false, etc.) and the description adds behavioral details: steps run in order, session timeout (30-min idle gap), min/max steps, and type semantics. 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 concise (3-4 sentences) and front-loaded: first sentence states purpose, then details. No unnecessary words, 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 the complexity of funnel creation (step types, session constraints), the description covers core concepts adequately. An output schema exists, so return values are not needed. Minor gap: could mention if steps must be unique or if there are path/event limits per step, but overall 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 coverage is 100% (all parameters described). The description adds context beyond the schema: explaining session gap, step ordering, and type details (path vs event). This provides meaningful added value.

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 'Create a multi-step funnel for a site' with specific verb and resource. It details step ordering, session semantics, and type matching, which distinguishes it from sibling tools like create_goal or list_funnels.

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 when-to-use guidance: 'Use this when the user says 'track the pricing → signup funnel' or describes a sequence.' It does not mention when not to use or list alternatives, but the context is clear enough.

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 it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that goals appear on the dashboard with conversion count and rate, providing extra behavioral context, but does not elaborate on side effects or prerequisites.

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 with two sentences plus an example usage sentence. It is front-loaded with the main action and efficiently conveys necessary information without verbosity.

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 4 required parameters with full schema coverage, annotations, and existence of an output schema, the description is fairly complete. It explains the two modes and the outcome. It could be slightly more complete by mentioning prerequisites or potential errors, but overall adequate.

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 all parameters. The description reinforces the meaning of 'type' and 'target' with examples, but does not add significant new meaning beyond the 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?

The description clearly states 'Create a conversion goal for a site' and differentiates between the two types ('path' and 'event') with examples. It is distinct from siblings like delete_goal and list_goals.

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 specific user statements that trigger using this tool ('track signups as a goal', 'add a goal for /thank-you'), giving clear context. However, it does not explicitly mention when not to use it or compare to alternatives like create_funnel.

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 and destructiveHint=false, so the agent knows it's a mutation but not destructive. The description adds useful context: return values include 'site row + install snippet + privacy_policy reminder + optional badge.' It doesn't mention what happens on duplicate domain, but overall adds value 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?

The description is five sentences, each serving a distinct purpose: primary function, usage alternative, direct use case, framework selection, and return value. 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 the tool has only 2 parameters, an output schema exists, and annotations are present, the description covers purpose, usage, return contents, and parameter guidance. A minor gap: it doesn't specify behavior for duplicate domains, but this is likely covered by error handling or output 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% for both parameters. The description repeats the framework detection hint from the schema's framework description and adds 'Pass the framework matching the user's project' which adds negligible new information. Baseline 3 is appropriate as schema already documents parameters well.

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's purpose: 'Register a domain in Gizmo and return the install snippet.' It uses a specific verb ('register') and resource ('domain'), and distinguishes itself from sibling tool setup_analytics_for_site by explaining when to use each.

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 guidance: 'For first-time install asks... prefer setup_analytics_for_site' and 'Use create_site directly when the user only wants the site row created... or when integrating from another tool.' This clearly states when to use this tool vs 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 already indicate destructiveHint=true. The description reinforces this with 'Destructive — confirm before calling' and adds a safety guideline. No contradiction.

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 concise sentences plus example phrases. No fluff, all information is relevant and 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?

Given the tool's simplicity (one param, clear destructiveness), the description fully covers what the agent needs. Output schema exists, so return info is handled elsewhere.

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 funnel_id parameter description in the schema tells the agent to get it from list_funnels, which is valuable context. Schema coverage is 100%.

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 starts with 'Remove a funnel by id', which clearly states the action and the resource. It distinguishes from sibling tools like create_funnel or list_funnels by specifying deletion.

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 example user phrases ('delete the X funnel', 'remove that flow') and warns about destructiveness. While it doesn't explicitly list when not to use, the context is clear and sufficient.

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 destructiveHint=true, but the description adds context about historical data disappearing, going beyond the annotation. No contradiction.

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 efficient sentences: first states purpose, second provides usage guidance and warning. 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?

Covers purpose, when to use, parameter source, and destruction consequence. Complete for a simple one-parameter 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 schema has 100% coverage, and the description adds value by suggesting where to obtain the goal_id ('Get one from list_goals'), aiding parameter acquisition.

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 explicitly states 'Remove a conversion goal by id' with a clear verb and resource. It distinguishes from sibling tools like 'create_goal' and 'list_goals' by focusing on removal.

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 keywords for when to use ('delete the X goal', 'remove that conversion goal') and includes a caution about the destructive nature, advising confirmation before calling.

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?

Consistent with annotations (readOnlyHint, no destructiveness). Adds behavioral details: threshold default, skipping low-traffic sites, returning most-recent first. No contradictions.

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?

Single paragraph with no wasted sentences. Each sentence adds unique value: function, method, use cases, scoping, ordering, threshold, edge case. Concise yet comprehensive.

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 100% schema coverage, rich annotations, and an output schema, the description covers purpose, method, parameters, and edge cases completely. No gaps.

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?

Adds meaningful context beyond schema: site_id omission scopes to workspace, date_range default rationale, threshold default and sensitivity meaning. Schema coverage is 100%, but description enriches understanding.

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 it finds unusually high or low traffic days using per-site z-score, with explicit examples like 'spikes this week'. It distinguishes itself from sibling analytics tools by focusing on anomaly detection.

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 use cases ('anything weird?', 'spikes this week') and explains scoping to a single site or entire fleet. Lacks explicit when-not-to-use, but overall 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 already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral context by detailing the returned data: overview, deltas, top 5 pages/referrers, anomaly-day callouts (z-score >= 2), and daily series. It also explains how to interpret the output, enhancing transparency 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?

The description is front-loaded with purpose, then structures the output list and usage advice. Every sentence adds value, though it could be slightly more concise. It is well-organized for an AI agent to parse.

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 complexity (multiple output components) and the presence of an output schema, the description is complete: it covers purpose, behavioral details, and usage guidance. It does not need to explain return values since the 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%, with both parameters well-described (site_id as UUID from list_sites, date_range as enum with defaults). The description adds no new parameter information beyond noting the tool works 'on a specific site' and 'vs prior period.' With high schema coverage, a baseline of 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 starts with 'ANSWER FIRST for any 'why did traffic [spike/drop/change]' question on a specific site,' clearly stating the verb (explain) and resource (traffic change on a specific site). It distinguishes from sibling tools like get_site_traffic and detect_anomalies by positioning itself as the go-to explanatory 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?

The description explicitly says 'ANSWER FIRST' for specific questions, guiding when to use it. It also provides usage instructions like using gainers/losers lists to attribute changes and not pasting raw arrays. While it doesn't explicitly state when not to use it, the context signals and sibling tools imply differentiation.

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 and idempotentHint, so the description adds value by specifying the scope ('every site in the workspace') and relationship to sibling tools, without contradicting 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 concise, front-loaded with usage context, and every sentence adds value including trigger phrases, tool behavior, and relationship to alternatives.

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 simple read-only tool with one parameter and output schema present, the description provides sufficient context about purpose, usage, and how it fits with sibling tools.

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?

Input schema has 100% coverage with description for the single parameter 'tag'. The description does not add additional parameter details, so it meets the baseline for 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 clearly states the tool returns every site with a given tag, includes natural language trigger phrases for use, and distinguishes from sibling tool list_sites by noting they are identical but exposed for different phrasing.

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 says to 'ANSWER FIRST' for specific user queries, mentions pairing with add_site_tags, and clarifies identity with list_sites({tag:...}) to guide agent decision-making.

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 adds significant behavioral context beyond annotations: the snippet is a single anchor tag that inherits font-size and color, should not be styled additionally, and includes ?ref=badge for attribution. Annotations already indicate read-only, idempotent, etc., and description does not contradict.

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 a single paragraph that is front-loaded with the purpose, then provides clear installation rules and constraints. Every sentence serves a purpose, and it is well-structured.

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 has no parameters and an output schema exists, the description fully covers the behavior, return type, and usage context. It is complete for the tool's purpose.

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 no parameters, so baseline is 4. The description adds no parameter information (none needed) but explains the output and usage. This is appropriate given the zero-parameter 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?

The description clearly states the tool returns the official 'Powered by Gizmo' footer badge as a single anchor tag, and specifies when to call it (when user asks to add a badge, link back, or thank Gizmo). This is specific and distinguishes 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.

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

The description provides explicit instructions on where and how to place the badge (inline in existing footer, next to copyright line), what not to do (not wrap in card/box, not separate onto own row), and installation rules. It clearly indicates when to use the 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, destructiveHint=false, idempotentHint=true. Description adds that filters are AND-joined and date ranges have defaults, but does not contradict annotations. No behavioral surprises.

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 paragraphs: first sets purpose and use case, second details parameters with clear examples. No redundancy, every sentence contributes.

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?

Covers all 5 parameters, output schema exists, differentiates from sibling, explains constraints (max limit, date range defaults). Complete for a query tool with solid annotations.

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%, but description adds meaning beyond field types: explains filter logic (AND), provides examples, notes default behaviors for date_range, and clarifies limit's max and pagination. Adds moderate value.

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?

Clearly states the tool provides 'Top-N for any column-backed dimension' and lists the dimensions. Differentiates from sibling `breakdown_by_property` by specifying use for built-in dimensions vs custom event properties.

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 tells when to use this tool: for dashboard breakdown tabs on built-in dimensions. Directs to `breakdown_by_property` for custom properties. Includes filter and date range usage details.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description aligns by stating it returns a snippet (read-only). It adds valuable context: the need for the tracker to be pre-installed, event naming constraints (1-64 chars, specific characters), and property value types (strings, numbers, booleans). Does not contradict 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-structured with clear sentences, covering purpose, usage triggers, prerequisites, post-call action, and parameter details. It is slightly verbose but every sentence adds value. Front-loads the main purpose and 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?

Given the presence of an output schema (context indicates true), the description does not need to detail return format. It covers all necessary aspects: input parameters, usage context, and behavioral expectations. The tool is simple (returns a snippet), so the description 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 coverage is 100%. The description adds meaning beyond the schema by providing example property values (e.g., {plan:'pro'}) and explaining the purpose of properties ('enable breakdown_by_property later'). It also clarifies event_name character rules with examples.

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 specifies 'return the JavaScript snippet for firing a custom event' with explicit examples like `window.gizmo("signup", {plan:"pro"})`. It clearly distinguishes from siblings like get_install_snippet (for installing the tracker) and get_badge_snippet, by focusing on custom event instrumentation.

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 phrases ('track signups', 'fire an event when someone clicks X'), prerequisites (tracker must already be installed, handled by create_site or get_install_snippet), and post-call action (EDIT the user's code to insert the snippet at the right code path). It also advises against merely printing the snippet.

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 read-only, non-destructive, idempotent, and open-world. Description adds value by specifying behavioral nuance: if user asked to install, edit file field names rather than printing snippet. No contradiction.

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?

Four sentences, each essential. Front-loaded with purpose, then usage, then frameworks, then rule. No redundant or filler content.

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 2 parameters and output schema, description covers when to use, how to detect framework, and behavioral rule. Complete for a fetch 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%, but description adds detection logic for framework (e.g., how to detect from package.json) beyond the enum values, which is valuable guidance.

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?

Description clearly states the tool re-fetches the install snippet for an existing site, using specific verb and resource. It distinguishes from siblings like get_badge_snippet and get_event_tracking_snippet.

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 when to use: when snippet was printed but never installed, user switched frameworks, or specific queries. Also provides an install-vs-print rule, differentiating from create_site.

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 idempotentHint=true, so the description adds value by explaining the response structure (overview, top pages, top referrers), filter semantics (AND-joined), and date range options, without contradicting 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 structured in three concise paragraphs, front-loading the purpose. Every sentence adds information, with no fluff, though it could be slightly more streamlined.

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 presence of an output schema, the description covers the main aspects: filter structure, available dimensions and operators, date range options, and sourcing site_id via list_sites. It omits potential pagination or limits but is otherwise sufficient for a tool of this 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 100%, so the baseline is 3. The description repeats the schema's parameter details but adds minimal additional semantic value such as a brief filter example and note about defaults varying, which is helpful but not essential.

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 'Traffic metrics for a single site (overview + top pages + top referrers)', which identifies the tool's specific verb and resource, and distinguishes it from siblings like get_top_pages and get_top_referrers that return only a subset of this 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?

The description implies use for a comprehensive traffic overview of a single site with filters and custom date ranges, but lacks explicit guidance on when to use this tool versus alternatives like get_breakdown or get_time_series, and does not mention 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 already mark it as read-only, idempotent, and non-destructive. The description adds significant context: bucket auto-resolution logic, filter ANDing, date range presets, and optional site_id scoping. No contradictions.

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-structured with clear sections (purpose, bucket/site_id, filters, date range). It is comprehensive without being overly verbose, though some repetition of 'Optional' 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?

For a complex tool with multiple optional parameters and logic, the description covers everything needed: return format, bucket behavior, filter details with example, date range options, and defaults. Output schema exists, so return values are not needed.

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 schema already documents each parameter. The description adds value by explaining bucket auto-resolution, filter combination logic, and providing an example filter and date range presets.

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 it returns time-bucketed visitors/pageviews/events for a date range, one row per bucket. It distinguishes from siblings like get_breakdown and query_events by focusing on metrics over time.

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 explains when to use (time-bucketed data) and details optional parameters like bucket auto-resolution and filters. However, it does not explicitly exclude alternatives or mention when not to use this 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, destructiveHint, and idempotentHint. The description adds context about the return data (top pages by count) and filtering capabilities. No contradictions; behavior is consistent with a safe, read-only query.

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 informative but somewhat verbose, with multiple sentences listing dimensions and operators. It could be more streamlined while retaining clarity. Front-loaded with the main purpose.

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 existence of an output schema, the description does not need to explain return values. It covers all necessary aspects: what it returns, filtering, date range, and scoping. Complete for a query tool with rich annotations.

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 baseline is 3. The description adds value by providing examples of filter usage and listing available dimensions, including custom properties (prop:<name>), which goes beyond the schema descriptions.

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 explicitly states 'Top page paths by event count' with a clear verb and resource. It distinguishes itself from siblings like get_top_referrers and get_breakdown by focusing on page paths.

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 context on when to use filters and site_id scoping, with a concrete example ('top pages from Germany'). It does not explicitly state when not to use it or name direct alternatives, but the usage is clear.

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 (true), destructiveHint (false), and idempotentHint (true). The description adds behavioral context: it returns hostnames by event count, supports AND filters, and has default date ranges. This provides useful detail beyond annotations without contradiction.

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 front-loaded with the primary purpose in the first sentence. It then efficiently covers filter syntax, date range options, and scoping. While it is moderately detailed due to the complexity of filters, every sentence serves a purpose and there is 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?

Given the tool's complexity (filters, date ranges, defaults, scoping), the description thoroughly covers all aspects: purpose, filtering options, date range presets and custom ranges, site scoping, and default limit. Since an output schema exists, the lack of return value explanation is acceptable, making the description highly 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 coverage is 100%, so the schema fully documents each parameter. The description adds meaning beyond the schema by explaining how filters work (AND together), how date ranges default per tool, and how site_id scopes the query. This extra context is valuable for correct usage.

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 retrieves 'top referrer hostnames by event count', which is a specific verb and resource. It distinguishes from siblings like 'get_top_pages' by focusing on referrer hostnames. The mention of filters and site scoping further clarifies the purpose.

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 clear context for when to use the tool: to get top referrers with optional filters and site scoping. It mentions passing site_id to scope to one site and supports date ranges. While it does not explicitly state when not to use or list alternatives, the purpose is distinct enough among siblings.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds no contradictory behavior and provides consistent purpose, but no additional behavioral details.

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-structured with a clear purpose statement followed by detailed parameter explanations. It is appropriately sized and front-loaded, though slightly verbose.

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 an output schema present and annotations covering safety, the description covers all critical aspects: purpose, parameters, and supported operations. It is complete for an overview 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%, providing baseline 3. The description adds significant value by listing available dimensions, operators, date range presets, and an example, which clarifies usage beyond schema descriptions.

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 explicitly states it provides aggregate metrics (visitors, pageviews, etc.) across all sites in the workspace, clearly distinguishing it from site-specific tools like get_site_traffic.

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 implies workspace-wide use but does not explicitly guide when to use this tool over alternatives. It lacks explicit when-not-to-use instructions or prerequisites.

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 destructiveHint=false, so the description aligns. It adds valuable behavioral context about the two classification categories and their priority. There is no contradiction 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 concise at three sentences, front-loaded with the main purpose, and contains no unnecessary words. Every sentence provides 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 the low complexity (one parameter, no required fields, output schema exists), the description is complete. It explains what the tool does, why to use it, and the output ordering. There are no obvious gaps.

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 one parameter ('quiet_days'). The description echoes the default value (7) and adds context about how it affects classification. This adds some meaning beyond the schema, but does not significantly enhance parameter understanding given the 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?

The description clearly states the tool finds abandoned sites, defines two categories ('never_installed' and 'went_silent'), and specifies default parameters. It distinguishes from sibling tools like 'list_sites' and 'summarize_all_sites' by focusing specifically on dead site identification.

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 use cases ('which sites are dead', 'what should I delete', 'what needs investigating') and mentions priority ordering. It does not explicitly state when not to use it or list alternatives, but the context is sufficiently clear for an agent to select the 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by detailing return content (per-step counts, drop-off rate) and highlighting the biggest drop, but does not contradict 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?

Description is moderately long but well-structured: starts with common questions, states functionality, then hints at output and pairing. Each sentence serves a purpose, though could be slightly more concise.

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 presence of output schema and thorough annotations, the description covers all necessary context: what is returned, how to get required parameters, and when an alternative workflow is needed.

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 baseline is 3. Description reinforces that site_id comes from list_sites and clarifies the date_range default, adding slight extra value beyond the 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?

Description explicitly states 'Lists every funnel defined for a site with per-step reached counts + drop-off rate' and provides natural language queries that map directly to this tool. Clearly distinguishes from siblings like create_funnel and delete_funnel.

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 when-to-use guidance via example queries and advises to pair with create_funnel if no funnels exist. Also recommends using list_sites to get the site_id parameter.

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=true, idempotent=true, etc. Description adds that it includes conversion count and rate over a date range, which is useful but not extensive. No contradictions.

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?

Efficient two-sentence structure with a front-loaded list of example queries. Every sentence 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?

Given the simple list functionality and existence of an output schema, the description adequately covers purpose, parameters, and pairing advice. No significant gaps.

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 description repeats parameters (site_id, date_range) without adding semantic details beyond schema. Baseline 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?

Starts with common user queries and states clearly: 'Lists every goal defined for a site with conversion count + rate over the date range.' Distinguishes from sibling 'create_goal'.

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 sample queries that trigger this tool and advises pairing with create_goal if no goals exist. Lacks explicit when-not, but context is clear.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral context: it returns every site in the workspace (scope), includes specific fields, and notes the call is cheap with no events touched. This enhances transparency, though it does not discuss rate limits or authentication needs, which are less critical given 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 three sentences plus a short cost note, each sentence adding distinct value: example queries, return fields, usage guidance, and performance hint. It is front-loaded with the most critical information and contains no filler. Every sentence earns its place, making it highly concise and well-structured.

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 simplicity, the description covers all essential aspects: purpose, return shape, how to use output, and cost. Annotations provide safety and idempotency, schema covers the parameter, and the output schema exists (though not shown). The description does not leave obvious gaps for an agent to misuse this 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 description coverage is 100%, and the schema already explains the tag parameter clearly ('Optional tag name to filter by. Omit to list every site in the workspace.'). The description adds only a slight nuance ('narrows to one group'), which provides minimal extra meaning. With high schema coverage, the baseline is 3, and the description does not significantly improve parameter understanding.

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 starts with explicit example queries ('what sites do I have in Gizmo?', 'list my sites', etc.) and clearly states the tool returns every site in the workspace with specific fields (id, domain, createdAt, ignored status). It differentiates from siblings by emphasizing that it lists all sites with an optional tag filter, and provides a post-usage instruction (using returned site.id for other tools). This makes the purpose highly specific and actionable.

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 advises to 'ANSWER FIRST' for listing queries, indicating primary usage. It explains the optional tag filter and recommends using the returned site.id for other tools. It also notes the call is cheap and touches no events. However, it does not explicitly mention when not to use it or contrast with sibling tools like 'filter_sites_by_tag' for more complex filtering. The guidance is clear but could be more comprehensive about alternatives.

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, destructiveHint, idempotentHint, openWorldHint. The description adds behavioral context: default limit, max cap, filtering mechanics, date range options, and implicit pagination. No contradictions.

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?

Description is structured into clear paragraphs: summary, limits, filters, date range. Every sentence adds value with no redundancy. Front-loaded with key info.

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 5 parameters, full schema descriptions, output schema presence, and rich annotations, the description covers all necessary aspects: default behavior, filtering, date ranges, limits. No gaps for the agent to infer.

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 baseline is 3. The description adds significant value beyond schema: lists all available dims and ops, provides filter example, explains preset and custom date ranges. This enriches semantic understanding.

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 'Query raw events' explicitly, defines default behavior (latest 100, max 1000), and provides pagination advice. The verb+resource is clear and distinguishes from analytic siblings like breakdown_by_property or get_site_traffic.

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?

Description advises pagination for large analyses and notes that defaults vary by tool, but does not explicitly state when to avoid this tool or name alternatives. Some usage context is given, but no exclusions or sibling comparisons.

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 provide readOnlyHint and idempotentHint. Description adds volume-gating with rationale and mention of excluded_low_volume field. No contradiction 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?

Concise two-sentence description front-loads purpose and details. Every sentence adds value 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?

Given 3 simple parameters and existence of output schema, description covers main behavior, direction filter, volume gating, and output field mention. Complete for agent use.

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 baseline is 3. Description adds context on direction values and limit default but does not introduce new parameter semantics beyond 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?

Description clearly states it ranks sites by signed % visitor change vs prior period, with explicit use cases like 'which sites are growing/declining', 'biggest movers', 'what's trending'. This specific verb+resource distinguishes 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.

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

Provides explicit when-to-use examples and explains the direction parameter behavior. Also mentions volume-gating rule. Lacks explicit when-not-to-use or alternatives, but context is clear.

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 indicate not read-only and open world hint. The description adds context about side effects (site creation, snippet return, next steps) but does not fully address idempotency or duplicate site creation. No contradiction 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 dense but every sentence adds value, front-loaded with imperative guidance, followed by parameter details and workflow steps. 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 the tool complexity and presence of sibling tools, the description covers all necessary aspects: when to use, parameter selection, output structure (including example event snippet and next_actions), and post-call agent workflow. Output schema exists so return values are handled.

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%, but the description adds significant value by explaining domain preference (apex domain), providing framework detection clues, and giving examples for event_hint. This goes beyond schema descriptions.

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's purpose as a one-call install workflow for adding analytics, bundling site creation, snippet generation, and next steps. It differentiates from siblings by explicitly noting it is preferred over chaining create_site → get_install_snippet.

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 instructs the agent to use this tool first for any analytics request, explicitly recommends against chaining alternatives, and provides detailed guidance on parameter selection including framework detection from package.json and config files.

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 indicate readOnly, idempotent, and openWorld hints. The description adds behavioral details beyond annotations, such as the default date range (last_7_days) and formatting instructions (lead with fleet_totals, then needs_attention, then top_movers; paraphrase numbers). No contradictions.

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 (4-5 sentences) and well-structured: it starts with the primary use case, then enumerates output components, and ends with formatting instructions. Every sentence adds value without 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?

Given the presence of an output schema and annotations, the description provides sufficient context: it explains the output structure (fleet totals, breakdown, needs attention, top movers, AI leaders) and formatting. It could be more complete by clarifying that the output schema defines precise fields, but overall it covers the needed guidance.

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 single parameter 'date_range' is already fully described in the schema with enum values and default. The description repeats the default range but adds no new semantic meaning beyond the schema, so baseline score of 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 answers broad status questions like 'how is everything doing' and 'give me a status' across the workspace. It details what it returns (fleet totals, status breakdown, needs attention, top movers), distinguishing it from sibling tools that focus on specific sites or metrics.

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 'ANSWER FIRST for any... question', providing clear guidance on when to use this tool for broad overviews. It does not explicitly mention when not to use it, but the context of siblings implies alternatives for more specific queries.

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 safe, non-destructive, idempotent behavior. The description adds detailed behavioral context: it fetches the homepage, scans for the script, and describes three possible return outcomes (installed, no_tag, error) including edge cases like Cloudflare blocks.

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 verbose but well-structured, starting with usage guidance, then behavior, return values, and user-facing advice. Every sentence adds value, though it could be slightly more concise.

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 output schema exists and the description thoroughly covers return values, edge cases, and user guidance, the description is fully complete for this tool's context. Sibling tools are mentioned for context.

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 has 100% coverage with a clear description for site_id. The tool description does not add additional parameter semantics beyond what is in the schema, but schema coverage is sufficient, 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 it verifies if the tracker script is installed by fetching the homepage. It explicitly distinguishes from siblings by positioning itself as the 'answer first' tool for installation verification, contrasting with create_site and get_install_snippet.

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 tells when to use this tool ('ANSWER FIRST for any 'is it working?') and in what context (right after create_site/get_install_snippet). It provides guidance on interpreting results and what to tell the user, offering clear alternatives for different outcomes.

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