Statable Analytics

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description doesn't need to restate those. It adds useful behavioral context: duplicate names are refused (funnel_exists), exit_page must be last, and the result can be read with funnel_report. This goes beyond the schema 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 compact and front-loaded: it defines the core concept first, then constraints, then scope, then error behavior, then where to read results. Every sentence adds value and there is 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?

For a creation tool with no output schema, the description covers the essential input semantics, constraints, and error behavior. It doesn't describe the success response format, but that's a minor gap given the tool's simplicity and the reference to funnel_report for reading results.

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 only 40%, so the description compensates by explaining the structure of steps with concrete examples and the scope enum values. It also clarifies the duplicate-name behavior. However, it doesn't explain strict_order beyond what the schema says, and site is only referenced via list_sites in the schema, not the description.

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 creates a funnel, defines it as an ordered list of 2+ steps, and provides concrete step type examples. It distinguishes itself from siblings like update_funnel and funnel_report by focusing on creation and referencing the report tool for reading results.

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

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

The description gives explicit constraints: exit_page must be last, duplicate names are refused, and scope options are listed. It doesn't explicitly say when to use this vs update_funnel, but the creation context is clear and the duplicate-name refusal provides a clear condition for 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 declare this is a non-read-only, idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely extra behavior: the three-way mutual exclusivity of inputs and the duplicate-name rejection (goal_exists), which the annotations cannot express.

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

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

Three short sentences, front-loaded with purpose then the input constraint then the failure mode. No filler, no restatement of the title.

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 6-param mutation tool with a fully documented schema, annotations covering safety, and a stated error case, the definition covers what an agent needs to call it correctly. It omits only minor detail such as the return payload, which is acceptable given there is no output schema but not ideal.

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, but the description adds the OR-relationship between event_name, path, and scroll_depth that the flat schema cannot express. The operator code meanings are duplicated from the schema, so the gain is real but modest.

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

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

States a specific verb+resource ("Add a goal to a site") and immediately defines what a goal can be, which separates it from update_goal and list_goals in the sibling set. An agent can tell this is the creation tool without opening the schema.

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

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

Gives the key selection rule among the three goal types ("EITHER a custom event, OR a page, OR a scroll depth — give one of the three, not several") and names the duplicate-name failure. It does not explicitly route to update_goal for modifying existing goals, so it stops short of full when/when-not 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 include idempotentHint: true, but the description adds crucial context: duplicate URLs are REFUSED with site_exists rather than silently returned, and retries replay the first result. It also reveals the response contains a tracking code, which is beyond the schema 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 front-loaded with the primary action and return value, then adds response example, constraints, and follow-up guidance. It's dense but not overly long; the example response is arguably extra but useful for understanding the output shape.

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

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

For a tool with no output schema, the description provides a partial response example and covers idempotency, duplicate handling, and the recommended next step. It doesn't specify error handling beyond duplicates, but that's not required. Overall it's complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (url, hobby, timezone) with descriptions. The description adds no new parameter details beyond the schema; it only restates the URL scheme requirement already present. 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 states a clear verb and resource: 'Add a site to this account and get back its id and tracking code.' It distinguishes itself from sibling tools like create_funnel and create_goal by focusing on site creation, and even names the follow-up tool get_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 states when to use it ('Add a site to this account'), when it will refuse (duplicate URL), and what to do next ('Follow with get_tracking_snippet'). It also explains idempotent retry behavior, leaving no ambiguity about invocation 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 establish readOnlyHint=true and destructiveHint=false, and the description adds non-obvious behavior: the 5-minute active window, unique-visitor dedup semantics, and the exact JSON shape returned. It does not cover error behavior or rate limits, but those risks are low for a read-only counter.

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 short sentences, no filler, and the core scope is front-loaded. The return-value example is compact and earns its place because there is no output schema.

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

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

For a one-optional-parameter read-only tool, it covers the safety profile via annotations, the return contract via the example, and counting semantics via the 5-minute window. The only notable absence is routing guidance to sibling analytics tools, which is already reflected in the usage-guidelines score.

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 single optional site parameter is already documented thoroughly. The tool description adds almost nothing about parameter formatting, but per the baseline this is acceptable because the schema carries the full burden.

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: 'Realtime count of unique visitors active in the last 5 minutes for a site.' This clearly scopes the tool to current active visitors and, with the return shape, distinguishes it from siblings like visitors_over_time and query_stats.

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 realtime and 5-minute wording implies this is for current-count use cases, but the description never states when to prefer it over visitors_over_time or query_stats, nor gives exclusions. The optional-site semantics are left to the schema rather than explained as usage 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?

Beyond the readOnlyHint and destructiveHint annotations, the description reveals the exact JSON response shape, states that steps are ordered, and clarifies that conversion_rate is cumulative from the entering step rather than step-to-step, with dropoff relative to the previous step. This is rich, non-obvious behavioral disclosure.

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 first, then output format and metric semantics, then the prerequisite. There is no filler, repetition of annotations, or unnecessary schema re-statement.

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

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

With no output schema, the description fully compensates by providing the return shape and the precise definitions of conversion_rate and dropoff. Combined with 100% parameter schema coverage, the agent has everything needed to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already documents site, period, filters, and funnel_id in detail. The description adds only the sequencing hint to obtain funnel_id from list_funnels, which mirrors the schema. 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 first sentence names a specific verb (Run), a specific resource (saved conversion funnel), and a distinctive result type (per-step, NON-tabular). This clearly differentiates it from list_funnels or create_funnel and makes the tool's function 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?

The description explicitly says to get funnel_id from list_funnels first, establishing the correct call sequence. It does not explicitly contrast this tool with query_stats or other tabular reporting alternatives, so it stops just short of full when-to-use versus 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, making safety clear. The description adds critical behavioral nuance: 'An empty allowed list means no restriction, not nothing allowed.' This is a high-value semantic caveat that prevents misinterpretation of filter response data. It also clarifies the meaning of public_dashboard for permission semantics. A small gap is the lack of mention of pagination, but for a single-sited getter this is not a significant missing behavior.

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 and front-loaded with purpose. The response example is placed immediately after the purpose to ground the agent in expected output. The caveats about empty allowed lists and public_dashboard are concise and information-dense. Every sentence earns its place; there is 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?

For a simple read-only tool with one parameter dar en, the description covers purpose, response shape, and key semantic caveats. The output schema is absent, but the inline example compensates sufficiently for common use. A slight omission is not listing all possible response fields (e.g., hostnames, countries) in prose, though the example covers them. Given the tool's low complexityeries, the description is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents that 'site' is the site_id from list_sites. The description does not add new parameter semantics beyond the schema, but the schema itself is clear. Baseline 3 is appropriate because the description adds no extra guidance about format, examples, or defaults for the parameter beyond what schema provides.

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

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

The description opens with a specific and meaningful explanation of the tool's purpose: 'Who gets counted on a site, and who may look at the stats.' This clearly identifies the resource (site filters) and the operation (get). The description also distinguishes this from sibling update_site_filters and from list_sites by focusing on filter access rules rather than general site listing or modification.

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 clearly implies the tool is for retrieving site access/filter configuration Ian. It names related operations in siblings: update_site_filters for modifying filterschers, list_sites for obtaining site IDs, and query_stats for stats consumption. The context signal 'site_id from list_sites' in input schema further reinforces when to use this tool. Although not explicitly saying 'use when you need the current filters,' it provides sufficient contextual guidance through the response semantics and routing hints.

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 context: it explains the response structure, the meaning of 'locked' features, and the 'requires' field, which are not evident from annotations. It also notes the access requirement, which is useful. Minor gap: it doesn't mention pagination or error cases, but for a read-only settings tool this is sufficient.

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 but information-dense. It front-loads the core purpose, then provides a concrete response example and explains key fields. Every sentence earns its place: purpose, response shape, field semantics, and access note. No fluff or repetition.

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

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

For a read-only tool with one parameter, full schema coverage, and no output schema, the description is complete. It explains the response format, field meanings, and access requirements. An agent has everything needed to call it correctly and interpret the result. The lack of an output schema is compensated by the inline response example.

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 single parameter 'site' is fully documented in the schema. The description adds context by referencing 'site_id from list_sites', which helps the agent understand the expected value. It doesn't need to add more since the schema already covers the 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's purpose: it retrieves tracking settings, including which features are enabled, which exist, and their byte costs. It distinguishes itself from the sibling update_tracking_settings by explicitly referencing it as the tool for changing settings. The verb 'get' and resource 'tracking settings' are specific and 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?

The description explicitly states when to use this tool: to read tracking settings, and notes that it requires the same access as changing them, referencing update_tracking_settings as the alternative for modifications. This provides clear context and an explicit exclusion, guiding the agent to the correct tool 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 mark it read-only, and the description reinforces this with 'it reports the code, it does not install or verify anything.' It also adds a non-obvious hazard: installing a rebuilt tag from script_url is wrong, and the data-id is the only channel for the counter's site id on hobby sites. This exceeds annotation coverage with actionable detail.

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 doing work: purpose, response shape, install rule, hobby-site edge case. Front-loaded with the core purpose and no redundancy.

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

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

With no output schema, the description supplies a concrete response JSON with types, plus the installation caveats needed to use the result correctly. Missing error/verification behavior is covered by the read-only note. An agent has everything needed to call and consume it.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description contributes no extra parameter-level semantics beyond the response example showing 'type' as "default" and the site_id integer, which is useful context but doesn't compensate beyond 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?

States the artifact precisely: the script tag and its load URL, and gives a concrete response example. The resource (tracking snippet) is distinct from get_tracking_settings because it returns installable code, not settings. Though no sibling is named, the output example makes the 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?

Explicitly frames the tool as an installation step: 'Install snippet verbatim; do not rebuild a tag from script_url.' The hobby-site data-id caveat tells agents when additional care is needed. It doesn't name alternatives, but the installation context leaves little ambiguity.

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 establish that the tool is read-only and non-destructive. The description adds value by revealing the exact return shape with fields such as id, name, scope, and steps_count, which is useful behavioral context beyond what annotations provide.

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?

A single tight sentence states the purpose and downstream use, followed immediately by a compact JSON example. There is no filler or redundant restatement of the title.

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 list tool with one optional, fully documented parameter and no output schema, the description is complete: it explains purpose, provides a concrete return sample, and the schema covers the site parameter. An agent has everything needed 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?

The input schema has 100% description coverage for the single optional 'site' parameter, so the schema carries the semantic load. The description adds no extra parameter-level detail, which matches the baseline of 3 for high schema coverage.

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

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

The description identifies the specific verb 'List' and resource 'conversion funnels configured for a site', and states the discovery purpose: obtaining a funnel_id for funnel_report. This clearly separates it from sibling tools like list_goals, create_funnel, and funnel_report.

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 gives a clear usage context: use this for discovery before calling funnel_report. It does not spell out exclusions or alternatives like list_goals, but the stated purpose is enough for an agent to select it appropriately.

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 known. The description adds meaningful behavior: it clarifies the response contains configured goals (not performance), and provides a sample response with field types and nullability, going beyond what annotations convey.

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 and front-loaded: it states the core purpose, the alternative, and then a representative response. No fluff or repetition; the example is valuable but not excessive.

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 list with one parameter, the description is nearly complete: it covers purpose, alternative, and response format (as no output schema exists). Minor gaps like error handling or pagination are not critical for this tool type.

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 describes the sole parameter 'site' as 'site_id from list_sites' with 100% coverage. The description adds no additional meaning about the parameter itself, so a 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 uses the specific verb 'list' and clearly identifies the resource as 'goals CONFIGURED on a site', explicitly excluding performance data. It names the sibling tool top_goals and instructs when to use it instead, 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?

Directly states the differentiation: 'Use top_goals for conversion numbers.' This provides an explicit alternative and clarifies the context (configuration vs. performance), leaving no ambiguity about when to select this tool over 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 establish read-only and non-destructive behavior, so the description adds useful context: the return shape, the per-event association, and the count/first_seen fields. With no output schema present, the inline return example is particularly valuable. Minor ordering/limits are not disclosed, but that is not essential for this read-only tool.

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 one tight sentence that states the operation, adds the discovery purpose, and includes a concrete return example. There is no filler or repetition of the title.

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 is complete enough for a simple two-optional-parameter read-only tool. It gives the return format explicitly despite the lack of an output schema, and the schema covers the parameters. It does not explicitly state how period affects the returned count, which is a small ambiguity, but it does not seriously hinder an 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%, so the schema already fully documents site and period. The description does not add much beyond that about the parameters themselves; its value is in clarifying the conceptual output rather than 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?

The description names a specific resource—custom-property keys a site has recorded—and ties each key to its event. It also explains this is discovery for the event:props:<key> breakdown in query_stats, making the tool's purpose immediately distinguishable from siblings like list_sites or top_custom_events.

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 clearly positions this tool as a discovery step before using query_stats, which tells an agent when it is appropriate. It does not explicitly list exclusions or alternatives for when it should not be used, but the intended workflow 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: timezone handling, event:name and event:goal breakdown semantics, the fact that events/conversion_rate are breakdown-only and rejected on aggregate/time-series queries, and metric unit definitions such as visit_duration in seconds and bounce_rate as a 0-100 percent.

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 core purpose and return shape, then moves into operational details. It is dense but appropriate for a complex analytics query with many modes. Some sentences repeat schema details, such as the dynamic event:props dimension requirement, but most content earns its place by adding semantics not present in the structured schema.

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

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

Given no output schema, the description provides a return-shape example and explains key metric and breakdown semantics. Annotations cover safety, and the schema carries detailed parameter documentation. The description fills the remaining gaps needed to invoke the tool correctly, including timezone behavior, breakdown limitations, and metric units.

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 71%, so the schema already documents many parameters in detail. The description compensates meaningfully by explaining metric semantics and units, event:name and event:goal breakdown behavior, and when metrics like events or conversion_rate are rejected. It does not cover every parameter, such as limit or compare, but those are well described in 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 states a specific verb and resource: 'Run a read-only analytics query for one site: aggregate totals, a time series, or a top-N breakdown.' It clearly frames the tool as a general analytics query with three output modes. It does not explicitly distinguish itself from specialized sibling tools like top_pages, visitors_over_time, or top_custom_events, so it stops short of a 5.

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

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

The description gives implied usage guidance by mapping dimensions to query modes: 'Zero = aggregate; one time dimension ... = time series; one breakdown dimension = top-N.' However, it never names or contrasts the specialized sibling tools, so an agent must infer when to use query_stats instead of top_pages, visitors_over_time, or top_custom_events.

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, covering the safety profile. The description adds valuable behavioral context by detailing the output format and noting that the dimension value is an ISO alpha-2 code that drops into a country filter, but it does not mention edge cases or limitations.

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 sentence that efficiently conveys purpose and output structure, with the key information front-loaded and a concrete example. It is highly scannable with zero 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?

With no output schema, the description compensates by fully specifying the return structure, including dimensions, labels, and metrics. Given the read-only annotation and complete parameter documentation, this is adequate for a simple top-list tool, though error handling and pagination are not addressed.

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 fully documents all three parameters with descriptions (100% coverage), so the baseline is 3. The description does not add significant parameter-specific meaning beyond the output format hint, which is marginal.

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 countries by visitors for a site' and provides a detailed return structure with example output, clearly distinguishing it from sibling top_* tools by specifying the dimension (country). The verb and resource are 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?

The description does not offer guidance on when to use this tool versus alternatives like top_pages or top_sources. It only describes what it does without mentioning conditions or exclusions, leaving the agent to infer usage 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 mark the tool as read-only and non-destructive. The description adds valuable behavioral context by defining the response envelope, distinguishing raw event counts from unique visitors, and clarifying that pageview/engagement events are excluded.

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 and front-loaded with the core purpose, followed by the exclusion and a precise result example. Every sentence contributes useful information 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?

With all parameters documented in the schema and no output schema present, the description provides the necessary result shape and metric semantics. An agent has enough information to invoke the tool and interpret its response 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 site, limit, and period are already fully documented. The description does not add parameter-level meaning beyond the schema, matching the baseline for high schema coverage.

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

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

The description clearly identifies a specific resource (custom events, excluding pageview/engagement), the operation (top by count), and the scope (for a site). It also shows the return shape, so an agent can distinguish this from sibling top_* 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 scope is clear—custom events by count for a site—and it explicitly excludes pageview/engagement events. However, it does not name alternatives or state when to prefer this tool over top_pages, top_goals, or other analytics siblings, so usage guidance is mostly implied.

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

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

Annotations already mark the tool read-only and non-destructive. The description adds value beyond annotations by defining the exact response shape and clarifying that 'visitors' means unique converters, 'events' means total conversions, and 'conversion_rate' is unique converters as a percentage of all visitors in the period.

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 tool's purpose and then gives a compact, illustrative JSON example. The structure is efficient, though the inline JSON sample makes it slightly longer than necessary.

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?

There is no output schema, so the description carries full responsibility for explaining return values. It does so concretely with a result shape and definitions of each metric. Combined with the schema, all information needed to invoke the tool correctly is present.

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 parameters (site, limit, period) are fully documented in the schema. The description adds no extra parameter semantics, but it does not need to; 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 states a clear resource ('the site's configured goals') and an operation ('ranked by conversions'). It distinguishes the tool from page/country/custom-event counterparts, though it does not explicitly name a sibling or boundary. The exact output sample reinforces the intent.

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?

Usage is implied by the purpose: use this when you need goal rankings by conversion metrics. There is no explicit guidance on when to prefer this over siblings like top_custom_events or list_goals, nor any when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the exact response JSON structure, which is useful context beyond annotations. However, it does not disclose other behavioral traits like pagination limits, error handling, or the effect of omitting parameters, which the schema partially covers.

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

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

The description is a single sentence that front-loads the purpose and includes the response format inline. It is efficient and avoids fluff, though the embedded JSON snippet makes it slightly verbose. Still, it is appropriately sized for the tool's simplicity.

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

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

The tool has no output schema, but the description provides the exact return structure, covering the results format. All parameters are optional and documented in the schema. The description is sufficient for an agent to call the tool correctly, though it omits edge cases like the behavior when multiple sites share a domain (covered in the schema) and potential error conditions.

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

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

Schema description coverage is 100%, so all three parameters (site, limit, period) are fully documented in the input schema. The description itself adds no parameter-specific detail; it only describes the output. With high 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 clearly identifies the tool as returning top pages ordered by visitors for a site, with a concrete response structure showing exact dimensions and metrics. This distinguishes it from sibling tools like top_countries or top_sources, which target different 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 purpose is implied by the name and description (page-level data), but no explicit guidance is given on when to prefer this tool over top_countries, top_sources, or other top_* siblings. There are no stated exclusions or conditions, leaving the agent to infer from the tool name.

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 value by specifying the exact response shape, which the annotations do not provide. It does not disclose sorting order or limit application, but the schema covers limit defaults.

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

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

Two sentences with zero fluff. The first states the core purpose, the second provides a compact, concrete output example. Everything 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?

With no output schema, the description supplies the response shape, and the schema covers all optional parameters. The tool is simple enough that an agent can call it correctly. Minor gaps like explicit sorting order are implied by 'top'.

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 fully documents all three parameters. The description's output example indirectly clarifies what 'sources' means via the dimension key, but does not add direct parameter-level semantics 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 the tool returns top traffic sources by visitors for a site, with an explicit example dimension (visit:source) and metrics (visitors, bounce_rate). This makes it easily distinguishable from siblings like top_countries, top_pages, and top_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?

No guidance is given on when to use this tool versus the many similar top_* siblings or query_stats. The agent is left to infer selection from the name alone, with no mention of alternatives or conditions.

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

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

Annotations already indicate non-readOnly, non-destructive, and idempotent behavior. The description adds valuable behavioral details beyond annotations: omitted fields are left alone (partial update), it returns the updated site, and it refuses duplicate URLs with a specific error (site_exists). These are critical for correct invocation and are not present in the schema or 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 four short sentences, each carrying distinct information: the action and fields, the partial-update behavior, the return value, and a failure condition. It is front-loaded with the primary action and has no redundant phrasing or filler. 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?

For a tool with four parameters (one required), no output schema, and annotations covering the safety profile, the description is complete. It explains the mutation behavior, the return value, and the error condition. An agent has everything it needs to correctly invoke the tool and interpret the result, without needing to infer missing details.

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

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

With 100% schema description coverage, the schema already documents each parameter's format and optionality. The description adds the crucial semantic that omitted fields remain unchanged, which is not inferable from the schema alone. It also reinforces that 'url' is one of the changeable fields. This adds meaningful value beyond the structured 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 states a specific verb ('Change') with a specific resource ('a site') and enumerates the exact fields (url, timezone, week start). This clearly distinguishes it from sibling tools like update_funnel or update_goal, which target different resources. It also mentions the return value, making the intent 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?

The description provides clear context by naming the exact fields that can be changed and the behavior of partial updates. It does not explicitly name alternative tools for creation or other updates, but the scope is evident from the tool name and sibling context. The condition about rejected duplicate URLs gives a specific when-not scenario, but there are no explicit exclusions for other use cases.

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?

With readOnlyHint=true and destructiveHint=false already in annotations, the description adds meaningful behavioral context beyond safety: the data is daily, timezone-adjusted to the site, and returned in a specific JSON shape. It does not contradict the annotations and gives the agent concrete expectations about the result format.

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 sentence that front-loads the core behavior, then provides a compact example response. There is no filler, redundant boilerplate, or repetition of schema details. Every part contributes to understanding the tool.

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

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

Given no output schema, the description correctly supplies the return format. Both parameters are fully documented in the schema, the annotations cover the safety profile, and the timezone behavior is the one non-obvious contextual detail an agent needs. Nothing critical is missing for a read-only two-parameter query 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%, so the baseline is 3 and the schema already documents both site and period. The description does not add new input semantics for either parameter, though the example result helps an agent understand what the parameters ultimately produce. This is adequate but not additive.

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, identifiable operation: returning a daily visitors and pageviews time series for a site. It adds precise scope ('in the site's own timezone') and shows the exact response envelope, which clearly distinguishes it from real-time tools like current_visitors and aggregate tools like query_stats.

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 phrase 'daily visitors and pageviews time series' implies this is the tool for historical daily traffic reporting, but the description never explicitly says when to prefer it over alternatives such as current_visitors or query_stats. It is a usable, purpose-informed description, but it leaves sibling differentiation to inference.

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