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

Discloses irreversibility ('Cannot be undone') and scoping of deletion ('Deletes completions only; the goal definition stays and get_goals still lists it'). This goes beyond the destructiveHint annotation by explaining the exact extent of the destructive action.

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 carries essential information—purpose, constraints, alternatives, side effects. No redundant or vague phrasing; well organized for quick comprehension.

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 (destructive, multiple filters, alternative authentication), the description fully covers prerequisites, behavior, side effects, and output (number of rows deleted). No critical information missing 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?

Every parameter has a description that clarifies its purpose, examples for date formats, and relationships (e.g., websiteId/domain alternatives, visitorId combining with AND). The description adds practical context beyond the schema definitions.

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 action: 'Permanently delete recorded goal completions matching every filter given'. The resource (goal completions) is specific and distinguishes from sibling tools like delete_payments and get_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?

Explicitly says when to use alternatives: 'Use delete_payments for revenue records and update_issue_status for issues.' Also details required filter conditions and that startAt/endAt can be used independently, giving clear operational guidance.

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?

It goes beyond the destructiveHint annotation by warning that deletion is permanent, cannot be undone, and removes revenue from reports and visitor profiles, advising explicit confirmation before proceeding.

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 yet comprehensive, using separate sentences for function, filters, requirements, output, warning, alternative, and authentication. No redundant information.

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

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

All relevant context is covered: purpose, filter semantics, return value, destructive consequences, alternative for reversal, and authentication details. No gaps remain.

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?

Each parameter has a detailed description in the schema, and the description adds clarity on how filters combine with AND and that startAt/endAt are independent. 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 clearly states that the tool permanently deletes payment records matching filters, and explicitly contrasts it with track_payment for reversing charges. It also differentiates from delete_goals by specifying the payment domain.

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 specifies when to use (delete payments) and when not to (use track_payment with isRefund for reversal), lists required filter conditions, and notes authentication requirements with websiteId/domain.

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 annotations already indicate read-only and non-destructive behavior; the description adds useful behavioral details such as default date range, ranking order, pagination semantics, and the meaning of returned rows. No contradictions exist between the description and 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 information-dense but still well organized and front-loaded with the primary purpose. It efficiently conveys defaults, pagination, filtering, and sibling-tool differentiation without unnecessary 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 that an output schema exists, the description does not need to fully document return values, but it still mentions key response elements such as pagination.total and row fields. It also covers defaults and filtering enough for an agent to call the tool correctly in 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?

Schema coverage is 100% and each parameter has a meaningful description. The dimension parameter's enum values are further clarified by explaining which are dedicated-tool dimensions and which are generic-only, and filter parameter descriptions include operator syntax and AND semantics.

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 function: grouping visitors by one of 24 dimensions, ranked by visitors descending, for a date range. It also distinguishes itself as the generic form of the named get_* breakdown tools, which is essential for choosing between this tool and its siblings.

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 explains when to use this tool versus dedicated alternatives, listing dimensions that lack a dedicated tool and those that have one. It also mentions filter combination behavior and default date/limit behavior, giving clear practical guidance.

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 read-only; description adds that rows include value, visitors, revenue, and percentage with pagination, plus default limit and date range. This makes behavior transparent 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?

Information-dense but efficient: main purpose, alternatives, response shape, defaults, and requirements are each addressed in one or two sentences. No 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 complexity (27 params, output schema), description provides sufficient context: how to select among sibling tools, response fields, pagination, default dates, filter application, and auth. Enough for an agent to call and interpret 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 covers all 27 parameters with descriptions; description adds only general statements like 'all filter_* arguments apply' and repeats authentication requirement already in the schema. No new parameter-specific semantics.

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 the exact resource (visitors grouped by browser) and action (get), and distinguishes itself from get_breakdown, get_operating_systems, and get_devices by clarifying what this tool does not do.

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 explains when to use this tool versus alternatives (browser names only, not versions, OS, or devices) and how to combine with filter_browser for other tools. Also notes authentication requirement and applicable filter_* arguments.

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 important behavioral context beyond the readOnlyHint annotation: it explains authentication requirements (websiteId or domain with a workspace token), default values for limit, startAt, and timezone, and pagination behavior via offset and total. These details help an agent understand how the tool behaves without contradicting 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 a single, well-organized paragraph that packs all essential information—purpose, exclusions, output fields, defaults, and authentication—without unnecessary fluff. Each 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?

While the description mentions output fields (value, visitors, revenue, percentage) and pagination.total, it does not provide a full output schema. However, given that this is a read-only reporting tool and the summary of rows is sufficient for an agent to understand the response, it remains largely complete.

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

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

Schema description coverage is 100%, and the parameter descriptions enrich the schema with concrete examples and operator explanations (e.g., filter_country's operator syntax). This goes beyond merely repeating the schema, providing practical usage details.

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 function: retrieving UTM campaigns ranked by visitors for a date range. It also distinguishes itself from sibling tools by explicitly naming alternatives like get_referrers, get_channels, and get_breakdown for other tracking 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 guidance on when to use this tool versus alternatives: it notes that only visits with utm_campaign appear and suggests using get_referrers or get_channels for untagged traffic, and get_breakdown for other UTM parameters. This gives clear direction for an agent.

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 and destructiveHint=false, but the description adds substantial behavior: how channels are classified (from referrer domain and utm_medium/utm_source), default date range (last 30 days), limit default and max (100/1000), pagination via pagination.total, that all filter_* arguments apply, and authentication requirements (websiteId or domain with workspace token). This goes well beyond the annotations.

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

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

The description is dense but every sentence serves a purpose: purpose, classification logic, usage guidance, row content, defaults, and auth. It is front-loaded with the core function, then progressively adds necessary context. 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?

For a tool with 27 parameters, 0 required, and an output schema present, the description covers all critical aspects: what is returned (rows with value, visitors, revenue, percentage), pagination details, default limits, filter applicability, and authentication. The output schema handles return structure, so the description is complete for agent decision-making.

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 each parameter is already described in the schema. The description adds context that all filter_* arguments apply and clarifies default date behavior (startAt/endAt default to 30 days). It also explains the websiteId/domain requirement. This adds value beyond the schema, so a 4 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 groups visitors into GA4-aligned marketing channels, ranked by visitors, for a date range. It names specific channel examples and explicitly differentiates from sibling tools by stating what it is not (get_referrers, get_campaigns) and when to use them instead. The verb 'Get' and resource 'Traffic by Channel' are precise.

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

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

Explicit guidance: 'Use this first for the traffic mix, then get_referrers for the domains behind Referral and Organic Social, or get_campaigns for tagged campaigns.' This tells the agent exactly when to use this tool and when to switch to alternatives, with clear routing logic.

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's burden is reduced. It adds useful context: rows carry value, visitors, revenue, percentage with pagination.total, default 30-day window, and that all filter_* arguments apply. 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 efficiently structured: the core purpose is front-loaded, followed by practical usage advice and alternatives. Every sentence contributes value—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 27 parameters and an output schema present, the description covers all essential aspects: return format, pagination, date defaults, filter operators, and differentiation from siblings. An agent can call this tool correctly without needing additional information.

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 strategic guidance beyond the schema: it explains the filter operator syntax (e.g., 'v', '!v', '~v'), the need to pre-filter with country/region for meaningful results, and the limit range. This enriches parameter understanding beyond the schema's per-field 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 specific verb and resource: 'Get visitors grouped by city, ranked by visitors descending, for a date range.' It also differentiates from sibling tools by explicitly naming get_countries and get_regions as coarser alternatives, making the purpose unambiguous.

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: 'Finest geographic tool and the longest tail' and instructs to pass filter_country or filter_region first for meaningful results. It also advises raising the limit above 100 and names the coarser alternatives, leaving no ambiguity about selection criteria.

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 safety is covered. The description adds valuable behavior beyond that: return fields (value, visitors, revenue, percentage), pagination via pagination.total, default limit (100) and max (1000), default date range (30 days), and the requirement for websiteId or domain with a workspace token. 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?

The description is dense but every sentence earns its place: purpose, sibling differentiation, return details, defaults, and auth requirement. It is front-loaded with the core purpose and scoping, making it efficient for an 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 has 27 parameters, full schema coverage, and an output schema, the description covers all essential context: what it returns, how pagination works, default behaviors, auth needs, and how it relates to siblings. Nothing critical is missing for an agent to call 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 baseline is 3. The description adds a general note that 'all filter_* arguments apply' and clarifies defaults for limit and dates, but it does not enrich individual parameter meaning beyond what the schema already provides. This is adequate 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?

The description opens with a specific verb and resource: 'Get visitors grouped by country, ranked by visitors descending, for a date range.' It immediately distinguishes from siblings by naming get_regions and get_cities as the finer-grained alternatives and get_realtime_map for current data, so an agent can select it unambiguously.

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 this tool versus alternatives: 'Coarsest of the three geographic tools: use get_regions for states or provinces and get_cities for cities, and add filter_country to either to drill into one country. Use get_realtime_map for where visitors are right now instead of over a range.' Also clarifies auth requirement and defaults.

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 and destructiveHint, but the description adds behavioral details not in annotations: 'Three rows at most, so pagination rarely matters' and 'Rows carry value, visitors, revenue, and percentage'. These clarify what the response will look like without contradicting 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 a single, dense paragraph that front-loads the purpose and then efficiently covers usage, behavior, and parameter notes. No redundant or filler sentences; 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 high parameter count and the presence of an output schema, the description provides all necessary context: date range defaults, pagination behavior, row content, filter semantics, and the relationship to sibling tools. No essential context is missing.

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

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

Schema coverage is 100% with each parameter already having a description. The tool description does not add additional semantic meaning beyond the schema descriptions; it only reinforces existing parameter details like websiteId/domain and filter_* operators. Thus 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?

The description clearly states the tool's purpose: 'Get visitors split by device type', identifies the exact resource (device types), and explicitly contrasts with sibling tools (get_browsers, get_operating_systems) to disambiguate.

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 states when to use this tool ('mobile-versus-desktop question') and when to use alternatives, and even directs passing filter_device to other tools for device-specific filtering. This leaves no ambiguity about selection.

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 and destructiveHint=false. The description reinforces the read-only intent by using 'Get' and 'compare conversions', and also notes that goals are created by track_goal, giving helpful lifecycle context. It does not contradict annotations and adds a small amount of behavioral context beyond the annotations.

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

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

The description is a single paragraph but packs in the core purpose, sibling-tool distinctions, default behavior, filtering semantics, pagination, and authentication requirements. While not broken into sections, it is efficient and every sentence contributes useful context. The length is justified given the tool's complexity and the number of parameters.

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 description covers the tool's overall purpose, key usage constraints, and references pagination fields like pagination.total. With the provided schema covering all parameters and context indicating an output schema exists, the description is sufficiently complete. It could explicitly state the output shape (e.g., goal name and visitor count fields), but this is partially covered by the tool name and 'how many visitors completed it' phrasing.

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?

All 27 parameters have descriptions, achieving 100% schema coverage. Many descriptions go beyond the parameter name by providing source endpoints (e.g., 'as returned by get_browsers'), concrete examples (e.g., 'Chrome', 'United States'), and default values. The shared filter-operator explanation is embedded in filter_country, which is slightly awkward but still informative. The descriptions clearly exceed the baseline for covered schemas.

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 'Get every configured goal (custom events plus the auto-created payment and free_trial goals) with how many visitors completed it in the date range', naming the specific resource and action. It also explicitly distinguishes the tool from get_overview, get_breakdown, and get_visitor, giving an agent unambiguous selection guidance.

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 strong usage guidance: when to use this tool ('Use this to compare conversions across goals'), when to use alternatives, the default date range, how filter_* parameters work, pagination via limit/offset, and the requirement for websiteId or domain with a workspace token. This leaves little ambiguity for invocation.

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 safety profile is covered. The description adds valuable behavioral details: response rows contain 'value, visitors, revenue, and percentage with pagination.total,' defaults for limit (100, max 1000) and dates (last 30 days), that 'all filter_* arguments apply,' and the authentication requirement (websiteId or domain with workspace token). This goes well beyond the annotations and helps the agent anticipate response structure and 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 a compact paragraph that front-loads the core purpose and ranking, then quickly covers usage differentiation, response contents, defaults, and auth. Every sentence adds information; there is no fluff or repetition. It's appropriately sized for the tool's complexity.

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 27 parameters, an output schema exists, and annotations are present, the description is remarkably complete. It covers the core function, when to use vs alternatives, response shape, pagination, defaults, filter applicability, and authentication requirements. An agent can confidently invoke this tool correctly based on the description alone, with the schema handling parameter-level 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?

Schema coverage is 100%, so the baseline is 3. The description adds some value beyond the schema: it clarifies that all filter_* arguments apply (relevant given the large filter set), reiterates the auth context for websiteId/domain, and mentions defaults that are also in the schema. It doesn't introduce new parameter semantics not in the schema, but the 'all filter_* arguments apply' note is a useful consolidation. The extra context about authentication requirements and the response fields elevates it slightly above baseline.

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 action: 'Get visitors grouped by hostname, ranked by visitors descending, for a date range.' It names the resource and the ranking, and explicitly contrasts with sibling get_pages ('Use get_pages for paths within a host'), making it easy to distinguish from other get_* tools without inspecting schemas.

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

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

It provides explicit when-to-use guidance: 'Useful when one website tracks several domains or subdomains; a single-domain site returns one row.' It names the alternative tool (get_pages) and explains how to pass filter_hostname to other tools to scope by hostname, leaving no ambiguity about selection.

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 doesn't repeat that. Instead it adds valuable behavioral details: exact error messages for unknown/trial cases, the fact that session detail includes pages/referrers/geography, and the note to surface only what answers the question. 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?

While the description is moderately long, every sentence earns its place. It front-loads the core purpose, then packs in retrieval source, usage scope, failure modes, and auth requirements without fluff. The structure is logical 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?

Given the output schema exists (so return format is covered), the description still adds essential context: error handling, trial limits, the auth token requirement, and a tip on filtering session details. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful context beyond the schema: where to get issueId, that websiteId/domain are alternatives, and that websiteId is ignored with a website key. This clarifies the auth model beyond the property descriptions, so a 4 is warranted.

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 ('Get') and resource ('one AI-detected issue'), and enumerates the exact details returned: occurrences, timestamps, sessions, steps, comments, and linked tickets. This clearly distinguishes it from list_issues (which lists issues) and update_issue_status (which mutates).

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 instructs to obtain issueId from list_issues and limits usage to 'only when you need the evidence behind one issue'. Also gives failure conditions for unknown IDs, cross-website IDs, and free-trial limits, plus the authentication requirement for websiteId/domain. This provides clear when-to-use and when-not-to-use guidance.

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 reinforces the read-only nature and adds meaningful behavioral details beyond annotations, such as the fallback to returning the website list when no selector is given and the workspace-token versus website-key distinction. It does not cover error conditions or rate limits, but the core side-effect profile is well disclosed.

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 distinct value: what is returned, read-only status, when to call it, how to pass parameters, and fallback behavior. It remains focused and free of fluff.

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 parameters are fully described, the explanation is complete for an agent to decide when and how to invoke this tool. It covers caller context, selector semantics, and relationship to sibling tools, leaving no critical 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?

The input schema already covers both parameters with descriptions, and the tool description adds crucial semantics: websiteId is required with a workspace token unless domain is given, while it is ignored with a website key. This goes well beyond the schema and clarifies selector logic.

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 settings for one website, enumerates the specific fields (domain, timezone, currency, KPI goal name, logo, color scheme), and explicitly contrasts it with list_websites for discovery. This distinguishes it well from sibling report and management 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 guidance: call after list_websites to obtain timezone/currency before running date-range reports and pass that timezone to report tools. It also explains selector behavior for workspace tokens versus website keys and advises preferring list_websites when no selector is provided.

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 readOnlyHint and non-destructive annotations already cover safety, and the description adds useful behavioral details: grouping, sorting, response fields, pagination total, default limits, date defaults, and auth requirement. It 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: purpose first, then differentiation from siblings, filter guidance, output/format details, defaults, and auth. Each clause adds value, and the text remains readable despite covering many behavioral aspects.

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

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

Given an output schema exists and annotations are present, the description is complete: it specifies what is returned, how results are ordered, default behavior, pagination, auth, and how it relates to sibling tools. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, and the description adds cross-cutting semantics that help interpret parameters: output rows include value/visitors/revenue/percentage, defaults for limit and dates, all filter_* arguments apply, and filter values should come from the relevant get_* tools. This goes beyond merely repeating 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 the tool returns visitors grouped by operating system, with explicit grouping, sorting, date range, and output fields. It distinguishes this tool from related sibling tools by specifying that get_browsers and get_devices handle browser/device splits and get_breakdown handles os_version.

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 ('names only'), when to use alternatives ('use get_breakdown with dimension os_version', 'get_browsers', 'get_devices'), and how to filter across the suite ('Pass filter_os to other tools'). It also mentions auth requirements, defaults, and that all filter_* arguments apply.

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. The description adds value beyond that by disclosing defaults (date range, timezone), the AND-combination of filters, the 'single row' result shape, and the requirement for websiteId/domain with a workspace token. No contradiction with annotations; a small gap is that pagination behavior is only implied via schema, not described here.

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 compact, front-loaded with purpose, then covers usage alternatives and a key example in two sentences. Every sentence earns its place with no 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?

For a tool with 28 parameters and an output schema, the description covers the core purpose, defaults, filter semantics, alternatives, and auth requirement. It doesn't explicitly discuss pagination or response structure, but those are covered by the output schema and parameter descriptions. Overall, an agent has enough to use 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 coverage is 100%, so all 28 parameters have individual descriptions in the schema. The description adds some interpretive value (filters narrow the whole result, default date/timezone) but largely reiterates what the schema already states. Baseline 3 is appropriate 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 states a specific verb ('Get headline totals') and resource ('one website over a date range'), lists the exact metrics returned, and explicitly names alternatives (get_timeseries, get_* breakdown tools) to distinguish itself. An agent can immediately tell what it does and how it differs from siblings.

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 when-to-use guidance: 'Use get_timeseries for the trend over time and a get_* breakdown tool for the split by page, source, or geography.' It also illustrates a filter combination example and notes the auth requirement, leaving no ambiguity about when to pick 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=true and destructiveHint=false. The description adds substantial behavioral context: output fields (value, visitors, revenue, percentage), pagination.total, default limit (100, max 1000), default date range (last 30 days), and auth requirement (websiteId or domain with workspace token). 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-organized: purpose first, then alternatives, filter guidance, output/defaults, and auth. Each sentence adds value without redundancy, and it is front-loaded with the core purpose. It is appropriately concise given the tool's complexity.

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 27-parameter complexity and presence of an output schema, the description covers purpose, usage alternatives, defaults, auth, and output fields. It mentions pagination.total for offset handling. Nothing critical for an agent to call the tool correctly is missing.

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

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

Schema coverage is 100%, so all 27 parameters are individually described. The description adds only general references to filter_* arguments and the websiteId/domain auth requirement, which is already in the schema. It does not materially enhance parameter understanding beyond the schema baseline.

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 page paths ranked by visitors in descending order for a date range, explicitly framing it as 'which pages get the most traffic.' It also names sibling tools (get_breakdown, get_hostnames) to distinguish scope, making the purpose unambiguous.

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 explicitly instructs when to use alternatives: 'Use get_breakdown with dimension entry_page for landing pages or exit_link for outbound clicks, and get_hostnames when the site serves several domains.' It also gives filter suggestions for source-specific traffic, leaving no ambiguity about selection criteria.

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 safety is covered. The description adds valuable behavioral context: it is point-in-time, takes no date/filter/pagination, returns data[0].visitors, and has a polling rate limit. These details go beyond the annotations and help the agent understand operational constraints.

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 model of efficiency: a single sentence stating the core purpose, a quick disambiguation of scope, explicit alternative routing, return format, a polling constraint, and an auth note. Every sentence earns its place, and the most important information (point-in-time nature) 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 simple tool with 2 parameters and an output schema, the description covers all necessary operational details: what it does, what it does not do (no history/filters/pagination), when to use alternatives, the return shape, rate limiting, and authentication. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds meaningful context: it explains that domain and websiteId are alternatives, that websiteId is required with a workspace token unless domain is given, and that websiteId is ignored with a website key (though the schema already covers the latter). This clarification helps the agent choose correctly, justifying a 4.

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

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

The description clearly states the verb 'Count' and the resource 'visitors active on the site within the last 5 minutes', and immediately distinguishes it from siblings by noting it is point-in-time with no history. It names get_timeseries and get_realtime_map as alternatives, making the tool's unique purpose unambiguous.

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 alternatives: 'Use get_timeseries with interval hour for recent trends and get_realtime_map when you need where those visitors are.' Also gives a polling limit ('Poll no more than once every 5 seconds') and states the authentication requirement ('Requires websiteId or domain with a workspace token'). This leaves no ambiguity about when or how to invoke 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 and destructiveHint=false, so safety is covered. The description adds critical behavioral context: real-time window (last 5 minutes), absence of filters/pagination, polling rate limit (5 seconds), and the requirement for a workspace token. This goes well beyond the annotations and helps the agent avoid misuse.

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 concise sentences. The core purpose is front-loaded, followed by usage differentiation and constraints. Every sentence earns its place with no fluff.

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, return values are documented. The description covers scope, usage alternatives, operational constraints, and auth requirements. For a tool with only two optional parameters and a clear read-only profile, nothing essential is missing.

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

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

The schema provides 100% coverage with descriptions for both parameters, so the baseline is 3. The description adds value by clarifying that these are the only parameters ('Takes only the website selector') and by restating the mutual exclusivity/requirements ('Requires websiteId or domain with a workspace token'), which is slightly redundant but reinforces the semantics.

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 clear verb ('Get') and a specific resource ('visitors active on the site in the last 5 minutes with their geographic location'), and explicitly distinguishes it from siblings like get_realtime and get_countries/get_cities, making the tool's purpose 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 explicitly says when to use this tool versus alternatives ('Use get_realtime when only the count matters, and get_countries or get_cities for geography over a historical date range'), and provides operational constraints (no dates/filters/pagination, polling rate, auth requirements). This leaves no ambiguity about selection and invocation.

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. Description adds meaningful behavior beyond that: row contents ('value, visitors, revenue, and percentage'), pagination via 'pagination.total', default limit (100) and max (1000), default date window (last 30 days), and that all filter_* arguments apply. 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?

Description is concise (4 sentences), front-loaded with the main purpose, then alternatives, then behavior details. Each sentence serves a distinct function with no redundancy or filler. It fits within the typical length for a tool with this many parameters.

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 27 parameters and an output schema, the description covers all essential operational details: auth requirement, defaults (limit, date window), row content, pagination mechanism, and filter applicability. Since an output schema exists, return-value details are already structured, so the description fills the remaining gaps (auth, defaults, pagination) completely.

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 every parameter is already documented in the input schema. The description only notes that 'all filter_* arguments apply,' which is implied by the schema's filter_* parameters. It adds no extra parameter semantics beyond what the schema provides, so the 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?

Description states a specific verb and resource: 'Get referring domains ranked by visitors, descending' and clarifies scope ('which external sites sent traffic in the date range'). It explicitly names sibling alternatives (get_channels, get_campaigns, get_breakdown) and the conditions that distinguish them, so an agent can select it correctly without inspecting schemas.

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

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

Provides explicit when-to-use vs when-not guidance: 'Use get_channels when you want traffic grouped into GA4-style channels... and get_campaigns or get_breakdown with dimension utm_source for traffic identified by UTM tags rather than referrer.' Also states the auth prerequisite ('Requires websiteId or domain with a workspace token').

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, covering safety. The description adds value by disclosing behavioral traits beyond annotations: it mentions that rows carry value, visitors, revenue, and percentage with pagination.total, that limit defaults to 100 (max 1000), and that all filter_* arguments apply with dates defaulting to the last 30 days. This enriches the agent's understanding of the tool's output and behavior 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 information-dense yet efficient, with every sentence contributing meaning. It front-loads the core purpose, then moves to relational context, output characteristics, defaults, and authentication—all in a logical order. No redundant phrases or filler. The structure is ideal for an agent scanning 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 complexity (27 parameters, no required fields), the description is remarkably complete. It covers the output shape (rows with value, visitors, revenue, percentage, pagination.total), default behavior (limit 100, last 30 days), filtering semantics (all filter_* apply), and authentication requirements. An output schema exists, so return details are not needed, and the description adds what the schema does not, such as how to relate to sibling tools and the default pagination behavior.

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 27 parameters, including their types and descriptions. The description adds minimal extra meaning beyond the schema—it mentions filter_region usage and that all filter_* arguments apply, but these are also present in the schema (e.g., filter_region is described as 'Filter by region code as returned by get_regions'). With full schema coverage, the baseline of 3 is appropriate, and the description does not significantly enhance 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 clearly states the tool's function: 'Get visitors grouped by region or state (ISO 3166-2 code such as US-CA), ranked by visitors descending, for a date range.' It also explicitly distinguishes itself from siblings by noting it sits between get_countries (coarser) and get_cities (finer), and explains how it can be combined with filter_country and used to scope other tools via filter_region. This provides a precise, resource-specific purpose that an agent can immediately act on.

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 on when to use this tool versus alternatives: 'Sits between get_countries (coarser) and get_cities (finer); combine with filter_country to list the regions of one country. Pass filter_region to other tools to scope them to one region.' It also notes the authentication requirement (requires websiteId or domain with a workspace token) and defaults, making the decision process 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?

The description explains the response shape (one point per bucket, timestamp, requested fields, revenue split) and the default 30-day/day interval behavior. However, since annotations already mark it read-only, the added behavior is moderate and does not cover details such as pagination mechanics despite the offset/limit parameters being documented in the schema.

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

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

Four concise sentences that front-load the core difference (bucketed metrics), then add usage guidance, defaults, and required-context notes. No unnecessary repetition 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?

The description covers the tool's purpose, its relationship to sibling tools, output shape, defaults, and a key practical warning (hourly buckets over long ranges returns too many points). It does not enumerate all 29 parameters, but the schema already fully documents them with 100% coverage, so this is complete enough for selection and basic 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 coverage is 100% and the description references some parameters (interval, timezone, startAt/endAt defaults, domain vs websiteId). Most parameter details are already in the schema, so the description only adds selective context — for example that 'hour' buckets are for short ranges and that timezone defaults to the website timezone — rather than full parameter documentation.

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 it returns the same metrics as get_overview but bucketed by time intervals, and explicitly differentiates from get_overview (one total) and get_* breakdown tools (dimension split).

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

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

Names the alternative tools explicitly and provides decision criteria: use get_timeseries for trends/charts, get_overview for a single total, and get_* breakdown for dimension splits. Also gives practical notes on interval-to-range matching and timezone defaults.

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

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

Annotations already cover read-only and non-destructive behavior; the description adds meaningful context about personal data handling, privacy minimization, and the error case for invalid IDs. 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 longer than typical but every sentence carries useful information: profile contents, privacy caveat, list limits, aggregate-tool guidance, visitorId origin, and parameter requirements. It remains structured and readable.

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?

Provides complete operational context: what the profile contains, personal-data sensitivity, list caps, null behavior for anonymous visitors, error behavior for unknown IDs, and parameter resolution rules. No important usage context is missing.

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

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

Schema covers all parameters with descriptions. The tool description adds helpful relationships and precedence rules, such as websiteId vs domain with workspace token and the ignored-with-website-key behavior, which goes 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?

Clearly states the exact resource and action: retrieve one visitor's full profile. It distinguishes itself from the many aggregate get_* tools by emphasizing 'one visitor' and the singular profile scope.

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 instructs when to use this tool versus alternatives: use it only for a specific visitor, and use aggregate get_* tools for many visitors. Also documents failure conditions such as unknown visitorId or cross-website access.

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. The description adds substantial behavioral context beyond this, including pagination behavior, default limits, the hiding of suspended issues unless explicitly filtered, and authentication requirements. It does not explicitly state it is read-only, but the annotations cover that, and the added context exceeds the minimal bar.

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 comprehensive yet tightly organized, flowing from what the tool does, to what it returns, to usage guidance, to special cases and requirements. Every sentence conveys necessary information without redundancy, making it efficient and easy to scan for an agent.

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?

It describes the output shape (rows with title, severity, status, sessions affected, first/last seen, plus aggregate counts and pagination.total) and explains when to use this tool vs. get_issue, covering the essential context an agent needs to invoke it correctly. The authentication requirement and suspended-issue behavior are also included, making it fully self-sufficient.

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 already covers 100% of parameters with descriptions. The tool description supplements this by clarifying the relationship between websiteId and domain ('Requires websiteId or domain with a workspace token') and reiterating the limit default, adding meaning beyond what the schema alone provides for the critical authentication parameter.

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 lists issues found by AI analysis, enumerates the types (bugs, broken flows, UX problems), and distinguishes it from get_issue which retrieves details by ID. The intended resource (issue list) and action (list) are explicit, leaving no ambiguity about what this tool does.

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 guidance on when to use this tool ('Start here for what is broken') and when to follow up with get_issue, while also noting the requirement for websiteId or domain with a workspace token. It explains the special handling of suspended issues and default limit behavior, giving clear direction on prerequisites and 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 indicate readOnlyHint and non-destructive. The description adds valuable context about token-scope behavior (workspace vs website key) and the error condition when neither websiteId nor domain is provided, going beyond the annotations.

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

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

The description is concise yet comprehensive, with no wasted words. It is well-structured, presenting purpose, usage, and error behavior in a logical flow.

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?

Provides all necessary context: what it lists, token scope implications, how it fits into the workflow, and the alternative tool. The error message is also specified, making the tool's behavior fully predictable.

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 and the schema is empty, so there is nothing to explain. The baseline of 3 applies as the description cannot add parameter semantics.

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 verb 'List' and resource 'websites the current API token can read'. Also distinguishes from the sibling tool get_metadata, making it easy to select the right 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?

Explicitly instructs to call this first with a workspace token, and states that other tools require websiteId or domain from this list. Also provides an alternative: use get_metadata when the website is already known.

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

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

Annotations only indicate non-readonly, but the description adds critical behavior: the goal is created on first use, each call appends a completion (so repeats count twice), visitorUid attaches completions to sessions/source, and omitting it records anonymously. It also notes the undo path, going well beyond the annotations.

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

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

The description is dense but every sentence carries essential information: purpose, naming, visitor handling, repetition semantics, alternatives, undo, and auth. It is front-loaded with the core action and logically organized, with no wasted words, though it is slightly long.

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 mutating goal-tracking tool with 5 params and an output schema, the description covers naming constraints, visitor attribution, idempotency (repeat behavior), alternatives, undo, and auth requirements. Nothing essential for correct invocation is missing.

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

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

The schema already provides 100% parameter descriptions with clear examples and constraints, so the description adds limited extra meaning. It does reinforce visitorUid's origin and omit-for-anonymous behavior, but this largely duplicates the schema. Baseline 3 applies because the schema carries the semantic load.

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 records a completion of a custom goal, explains the goal is auto-created on first use, and distinguishes it from track_payment and delete_goals. This gives a specific verb, resource, and scope, making it unambiguous among siblings.

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 to use track_payment for revenue instead, mentions undo via delete_goals, and clarifies the authentication requirement (websiteId or domain with a workspace token). It leaves no ambiguity about when to choose this tool over alternatives.

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

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

Annotations only indicate it's not read-only and not destructive. The description goes far beyond: it discloses that repeated transactionId is rejected (not deduplicated), that a new payment records a goal completion, that isRenewal skips that, that isRefund marks a refund instead of adding a row, and how attribution works when no visitor matches. All these behaviors are critical for correct invocation and are not in 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?

Every sentence earns its place. The description front-loads the core purpose, then covers exclusions and behavioral nuances in a logical flow. It is comprehensive but not redundant, and the structure guides the agent from general use to specific edge cases.

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 12 parameters, side effects (goal recording, refunds), uniqueness constraints, and attribution logic, the description covers all essential aspects an agent needs to invoke correctly. It even notes the requirement for websiteId/domain with a workspace token. With an output schema present, it doesn't need to describe return values, and it doesn't.

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?

Although schema coverage is 100%, the description adds meaning beyond field names: it explains that amount=0 records a free_trial goal, that amount with isRefund represents the refund amount, that transactionId must be unique, that isRefund requires an existing transactionId, that visitorUid is strongly recommended, and how customerId/email are used for attribution. This significantly enriches 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 a specific verb and resource: 'Record a payment'. It immediately states the effect (revenue appears in get_overview, get_timeseries, visitor profile) and explicitly contrasts with track_goal ('use track_goal for conversions without revenue') and with automatic provider tracking ('Skip it when the site's provider... is tracked automatically'). This clearly differentiates 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 conditions for use and non-use: when to skip (provider tracked automatically), when to use track_goal instead, and how to handle refunds via isRefund. It also specifies when a transactionId can be reused (only with isRefund). This is the highest level of guidance, leaving nothing to inference.

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

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

The description discloses that only the status changes, that the operation is reversible ('any status can be set again later'), and that it is not a delete. It also reveals error behavior ('unknown id fails with 'Issue not found'') and authentication requirements ('Requires websiteId or domain with a workspace token'). These details go well beyond the annotations (which only indicate non-read-only and non-destructive) and provide critical context for safe invocation.

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 each sentence adds essential information: the core action, the reversible nature, the status semantics, the exclusion from deletion, the source of issueId, error behavior, and authentication. It is front-loaded with the primary purpose and flows logically. No fluff or repetition, though it could be slightly tightened without losing clarity.

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 4 parameters (2 required) and an output schema, the description covers everything an agent needs: what it does, how to obtain issueId, what happens on failure, authentication requirements, reversibility, and semantic guidance for status choices. The presence of an output schema means the description doesn't need to explain return values. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description adds value by explaining the semantic differences between status values (e.g., 'resolved asserts the bug is fixed; suspended hides a known non-problem') and clarifies the relationship between websiteId and domain ('Alternative to websiteId with a workspace token'). This contextualizes the parameters beyond their basic type and required-ness, though the schema already provides baseline 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 starts with a clear verb and resource: 'Set an issue's status' with an explicit enumeration of allowed values (open, in_progress, resolved, suspended). It also differentiates itself from siblings by stating 'Not a delete: issues cannot be removed through this server,' which distinguishes it from delete_goals and delete_payments. This makes the purpose unambiguous and distinguishes it from alternatives.

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 on when to use the tool and how to select the right status: 'Confirm which state the user means before calling: resolved asserts the bug is fixed, suspended hides a known non-problem from the default list_issues result.' It also instructs to get issueId from list_issues and warns about unknown ids. The 'Not a delete' statement clarifies when NOT to use it. It covers both when and how to use the tool, and names the source for the required parameter.

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