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?

The description goes beyond the annotations by explicitly stating that a duplicate name is refused (goal_exists) and that the three goal types are mutually exclusive. The idempotentHint annotation is complemented rather than contradicted: retrying after a duplicate would not change state. It does not disclose permissions or response details, but the core behavioral constraints are present.

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 in the first sentence and constraints following. The operator value explanations repeat the schema somewhat, but they are brief and support the mutually exclusive choice described earlier.

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 six parameters and no output schema, the description covers the essential invocation logic: which parameter groups are valid, how operator matching works, and what happens on duplicate names. It does not describe the success response, but the input-side guidance is sufficient 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?

The schema already documents every parameter, so the baseline is 3. The description adds critical semantics the schema does not encode: the one-of-three exclusivity and the pairing of path with operator. This materially improves an agent's ability to construct a valid call.

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, 'Add a goal to a site,' and immediately distinguishes goals from the sibling tools like create_funnel and create_site. It also enumerates the three possible goal forms, so an agent knows exactly what object this tool creates.

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 clear context for when to call the tool: when adding a new goal. It also provides strong usage constraints—choose exactly one of event, page, or scroll depth—and warns that duplicate names are refused. It does not explicitly name alternatives like update_goal or list_goals, but the context is clear enough to avoid misuse.

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?

Even though annotations already indicate a read-only, non-destructive operation, the description adds valuable behavioral semantics: the meaning of each status, when ends_at is omitted, and that status 'none' with only_hobby true means a free account rather than a missing subscription. 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 earns its place: scope, response format, ends_at semantics, the free-account caveat, and argument count. It is front-loaded with the essential scope and then provides structured detail.

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 parameterless read-only tool, the description is nearly complete: it documents the response shape, statuses, ends_at behavior, and a key edge case. The only small gap is that the 'only_hobby' field's general meaning is not fully defined outside the specific 'none' case.

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 takes zero parameters alert, and the schema coverage is 100% (empty schema). The description explicitly states "Takes no arguments," which reinforces the schema and prevents the agent from trying to pass parameters.

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 immediately identifies the tool as returning "the account's plan state — not a site's," which clearly distinguishes it from site-level sibling tools. It also enumerates the exact response shape, making the tool's purpose concrete 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 gives a clear scope and an explicit exclusion: it is for the account's plan state, not a site's. It does not name alternate tools, but no direct sibling alternative is obvious, and the exclusion helps an agent decide when this tool is appropriate.

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 and destructiveHint, and the description adds substantial behavioral context: response shape, hobby-plan limitations and snippet installation, nested stats placement, units for metrics, and server-time approximation caveats. Nothing contradicts 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 long but dense and front-loaded: purpose first, then response format, then important caveats. There is minor redundancy with the schema's nested stats example, but each section carries meaningful operational detail an agent would otherwise miss.

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 provides a complete response example, field semantics, units, plan behavior, and a precision caveat. For a read-only tool with one optional parameter, everything needed to call and interpret it 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 baseline is 3; the description adds meaning beyond the schema by explaining metric units, the 'never flat on the site object' nesting rule, and timezone approximation. The date_range parameter itself is already fully documented in the schema, so this enrichment is helpful but not extraordinary.

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: 'List the sites this API key can read.' This clearly distinguishes it from sibling list tools like list_funnels and list_goals, and from create/update site tools. The scope ('this API key can read') removes ambiguity about authorization.

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 practical guidance: use site_id with other tools, and use query_stats when timezone-exact numbers are needed. It clearly implies when list_sites is appropriate, though it does not exhaustively enumerate all sibling alternatives.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral detail: the exact return JSON shape, timezone handling in the site's own timezone, how event:name and event:goal breakdowns behave, which metrics are breakdown-only, and units for each metric. This far exceeds annotation coverage and contains 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 each sentence carries distinct information: return shape, timezone, breakdown semantics, breakdown-only metrics, and units. The main purpose is front-loaded in the first sentence. Its length is justified by the tool's complexity, though it stops short of being lean.

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?

Despite having no output schema, the description explains the return structure and important behavioral quirks. It covers return format, timezone, metric semantics, and breakdown constraints. Missing details like pagination and compare behavior are already documented in the schema, so the description is sufficiently complete for an agent to invoke 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 descriptions cover site, limit, compare, filters, date_range, and dimensions (71%). The description supplements the undocumented metrics parameter by defining each metric's unit (e.g., visit_duration = average seconds per visit, bounce_rate percent) and by clarifying constraints like `events`/`conversion_rate` being breakdown-only. It does not repeat schema content, adding value where coverage is missing.

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 'Run' with resource 'read-only analytics query' and explicitly names the three output forms: aggregate totals, time series, or top-N breakdown. This clearly distinguishes it from specialized sibling reports like current_visitors and top_countries.

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 states the tool is for one site and enumerates the query forms, giving a clear usage context. However, it provides no explicit guidance about when to prefer sibling tools (e.g., top_countries for a single country breakdown, visitors_over_time for time series). Thus it is clear context but without exclusions.

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?

The description discloses a critical behavioral trait not captured in annotations: full replacement semantics, where omitted steps are removed rather than kept. This is essential for an agent to avoid accidentally deleting steps. It is consistent with readOnlyHint=false and idempotentHint=true, and no contradiction exists.

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, front-loaded sentence that states the action and then immediately provides the critical caveat. It contains no filler and does not repeat schema details. Every word contributes value.

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

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

For an update tool without an output schema, the description covers the primary behavior and the key destructive nuance about omitted steps. Minor ambiguity remains about whether optional fields like scope and strict_order are also reset when omitted, though the 'whole funnel' phrasing suggests they should be included. Overall, it provides sufficient context for an agent to call 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?

The description adds meaningful semantics for the steps parameter, clearly indicating that all steps must be supplied and omitted ones are removed. However, with schema description coverage at only 33%, the description does not clarify the meaning of name, scope, or strict_order, leaving significant gaps. It partially compensates for the schema's limited 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 it replaces a funnel's definition with a specific verb and resource. The added note about omitted steps being removed distinguishes it from a partial-edit tool. It implicitly contrasts with create_funnel, making its 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?

The description implies this tool is for updating an existing funnel and instructs the caller to send the whole funnel. However, it does not explicitly state when to use this over create_funnel or other update tools, nor does it mention exclusions. The usage guidance is present but implicit.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description reveals the key behavioral trait: omitted fields are cleared, not kept. This is exactly the kind of side-effect disclosure that prevents an agent from assuming merge semantics.

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 with no filler. The warning about omitted fields is front-loaded right after the action statement, making the most important usage caveat immediately visible.

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

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

For a mutation tool with no output schema, the description covers the essential invocation caveat and the full-replacement semantics. It does not describe return values, but that is not critical for correct use, and the schema plus annotations handle required fields and idempotence.

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 description adds the critical whole-object semantic and explains that optional fields are not truly optional-preserving: omitting them clears them. However, schema description coverage is only 29% and the description does not clarify meaning of parameters like operator or scroll_depth, so it only partially compensates for the low coverage.

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

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

The description uses a specific verb and resource: 'Replace a goal's definition.' This is sharper than the tool name 'update goal' and clearly differentiates the operation from patch-style edits, while the resource 'goal' distinguishes it from sibling update_funnel/update_site.

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 direct usage rule: send the whole goal, and explicitly warns against sending only changed fields. It does not name alternatives or state when to prefer create_goal, but the guidance is concrete enough for an agent to call it correctly.

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?

Beyond the annotations, the description discloses important behaviors: omitted sections are untouched, sent sections replace entire settings, partial updates can clear allow/block lists, filtering only affects new traffic and not collected data, and the response includes the resulting state plus an 'updated' array. This is rich, non-obvious behavioral context that helps the agent predict consequences.

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, partial-update semantics, replacement behavior with examples, recommended usage pattern, effect timing, and response shape. It front-loads the core purpose and semantics before diving into details.

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 nested object structure and no output schema, the description is complete. It explains partial update semantics, replacement behavior, effect on existing data, and what the response contains. An agent has enough context to call this tool correctly without guessing.

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 meaningful semantics beyond the schema: it explains that sending a section replaces the entire setting rather than merging, and provides concrete examples like clearing the country allow list or emptying blocked_ips. This materially improves parameter understanding, though the schema already covers individual field formats.

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 clear, specific statement: 'Change who gets counted, and who may look.' It names the resource (site filters) and the operation (change/update), and the sibling list includes get_site_filters, so the read vs. update distinction is obvious.

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 an explicit, actionable pattern: read current state with get_site_filters, apply the edit, and send it back. This tells the agent when to use this tool versus the read sibling. It could be stronger by explicitly naming alternatives for non-filter updates, but the guidance is clear and practical.

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 important behaviors beyond the annotations: it replaces the entire selection, anything omitted is turned off, and the action rebuilds/republishes the script with a CDN propagation delay. This is exactly the kind of contextual behavioral information an agent needs and is not present in idempotentHint or destructiveHint.

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

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

Three sentences, each earning its place: the core purpose, the critical replacement caveat, and the prerequisite plus propagation effect. The information is front-loaded and free of 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 only two parameters, full schema coverage, and no output schema, the description covers all essential context: what is changed, how the selection should be provided, how to get valid values, and when the change takes effect for visitors. Nothing important 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 description coverage is 100%, so the schema already documents both parameters. The description reinforces the 'complete list, not a delta' semantics for features and adds the pragmatic reminder to fetch valid ids first, but it mostly restates what the schema already conveys.

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: 'Set which tracking features the site's script includes.' This clearly identifies the tool's job and distinguishes it from get_tracking_settings and get_tracking_snippet. The replacement caveat further sharpens the purpose.

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

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

The description gives an explicit prerequisite ('Call get_tracking_settings first for the valid ids') and explains the correct calling pattern by saying the caller must send the complete feature list. It does not explicitly name alternatives or when not to use this tool, but the purpose and precondition make its use context 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?

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.