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

No annotations are provided, so the description carries the behavioral disclosure burden. It covers key behaviors: exit_page must be last, scope defaults to 'visitor', duplicates are refused, and the result is read via funnel_report. This goes well beyond a bare 'create' statement, though it does not discuss permissions or undo 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?

Three concise sentences carry a lot of useful information without filler. The purpose is front-loaded, followed by concrete examples and constraints, making the description efficient and scannable.

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

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

For a 5-parameter create operation with no output schema and no annotations, the description is fairly complete: step shape, constraints, duplicate behavior, and follow-up reporting are all covered. The only notable omission is prose guidance on strict_order, but the schema already documents that parameter adequately.

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 only 40%, and the description compensates by explaining the steps parameter in detail with valid examples, the exit_page ordering rule, and the scope values/default. It adds real meaning beyond the schema, though name and site are left to the schema or are self-evident.

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 'Add a funnel' and immediately defines the resource as an ordered list of 2+ steps. It provides concrete step examples, which makes the tool's purpose unmistakable and distinguishes it from related tools like update_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 clearly orients the agent toward creating a new funnel and says to read results with funnel_report, which is useful routing guidance. It also warns that duplicate names are refused, implying the agent should avoid re-creating existing funnels. However, it does not explicitly call out update_funnel as the alternative for modifying an existing funnel.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the exclusive-or validation and the goal_exists failure for duplicate names, but it doesn't mention required permissions, side effects beyond creation, or what the success response looks like.

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 front-load the purpose and then efficiently pack the cardinality rule, operator definitions, and duplicate-name behavior. Every clause earns its place with no redundancy or filler.

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

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

Given six parameters, no output schema, and no annotations, the description plus the rich schema documentation cover how to construct any valid goal and what to expect on a duplicate. It doesn't mention the success return value, but that's a minor gap for a create operation.

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 cross-parameter semantics by grouping event_name, path+operator, and scroll_depth as exclusive alternatives, and by clarifying what the operator values mean. This goes beyond the individual property 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 opens with a specific verb+resource ('Add a goal to a site') and immediately defines the goal resource as one of three concrete types (custom event, page path, scroll depth). This clearly differentiates it from sibling tools like update_goal, list_goals, and create_funnel.

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

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

It provides explicit construction rules: choose exactly one of the three goal types, not several, and gives the operator mapping. It also warns about duplicate names. It doesn't explicitly say 'use update_goal for modifying an existing goal,' but the create/update distinction is implied by the sibling set.

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 no annotations provided, the description carries the full burden and does so impressively. It discloses that duplicate URLs are refused with site_exists, that retries replay the original result, and that the response includes id and tracking code. This goes well beyond the schema.

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

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

The description is front-loaded with the core action and result, then packs critical behavioral details into a few tight sentences. Every clause earns its place, including the rationale for refusing duplicate URLs.

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?

Even without an output schema or annotations, the description is complete for a 3-parameter creation tool. It gives a response shape, explains duplicate and retry behavior, and points to the necessary next step, so an agent can 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 coverage is 100%, so the baseline is 3. The description reinforces the URL scheme requirement and includes timezone in the response example, but it does not add substantive new meaning to the hobby or timezone parameters beyond what the schema already states.

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: 'Add a site to this account' and specifies the exact outcome ('get back its id and tracking code'). It is clearly distinct from sibling tools like list_sites and update_site, even without naming them.

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 creation use case is obvious, and the description adds concrete guidance about URL requirements, duplicate rejection, and idempotent retries. It also recommends following with get_tracking_snippet, though it doesn't explicitly contrast with update_site or other 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?

With no annotations, the description carries the burden and does a good job: it defines the rolling window, uniqueness semantics, and exact return payload. It does not explicitly mention read-only status, auth needs, or failure modes, but those gaps are modest for such a simple metric 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?

One tight sentence with an embedded JSON example. The key behavioral facts are front-loaded, and every word earns its place.

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

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

For a one-optional-parameter read tool with no output schema, the description plus the detailed schema are nearly sufficient. The inline JSON example compensates for the missing output schema, though the description itself leaves multi-site key handling to the schema.

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

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

Schema coverage is 100%, so the schema already fully documents the optional site parameter. The description adds no extra parameter-level meaning, making the baseline 3 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 specific verb ('count'), a precise resource ('unique visitors active in the last 5 minutes for a site'), and provides a concrete return example. This clearly distinguishes it from time-series or top-N sibling tools.

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

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

The description implies the use case—current/live activity versus historical trends—through 'realtime' and the 5-minute window. However, it never explicitly says when to prefer this tool over siblings like visitors_over_time, nor gives exclusions or 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?

With no annotations provided, the description carries the full burden, and it delivers: it discloses the exact JSON return shape, that steps are ordered, conversion_rate is cumulative against the first step rather than step-to-step, and dropoff is measured against the previous step. These are non-obvious behavioral details that materially affect interpretation.

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, then provides a compact inline return schema followed by the crucial semantic clarifications. Every sentence earns its place, and the inline JSON example is justified 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?

The description is nearly complete for a tool with no output schema: it documents the return shape, semantics, and prerequisite. Minor gaps remain: 'entering' and 'all_visitors' are not explicitly defined, and there is no mention of behavior for unknown funnel_id, but these do not block correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds only the sequencing hint 'Get funnel_id from list_funnels first,' which is useful but largely redundant with the funnel_id schema description. It does not add meaningful new parameter-level meaning.

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: 'Run a saved conversion funnel and return its per-step result.' It also distinguishes itself from siblings by emphasizing 'NON-tabular' output and by referencing list_funnels as the source for funnel_id, making its role clear relative to list/create/update funnel 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?

It clearly establishes the usage context: run a saved funnel, obtain funnel_id from list_funnels first. It does not explicitly state when not to use this tool or name tabular alternatives like query_stats, but the purpose is clear enough to guide selection.

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

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

With no annotations, the description bears the full disclosure burden, and it delivers: the exact response shape is shown, and the non-obvious semantics of empty allowed lists and public_dashboard are explicitly clarified. This prevents misinterpretation of an empty list as 'nothing allowed' and clearly defines public access.

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 front-loads the core purpose, then gives a compact but complete response example and two critical semantic caveats. Every sentence earns its place; there is no filler 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 one-parameter read tool with no output schema, the description is fully self-sufficient: it explains what is returned, how to interpret the values, and what the access implications are. Nothing needed to call it correctly is missing.

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

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

The single parameter is fully covered by the schema ('site_id from list_sites'), so the description does not need to add parameter details. The description adds no new parameter semantics 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 opening line 'Who gets counted on a site, and who may look at the stats' precisely identifies the tool's resource (site filters) and separates it from the stats-querying siblings. It is a specific verb+resource description, not a tautology, and the response sample further confirms it returns filter configuration.

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 that this tool is for reading a site's inclusion/exclusion and access rules, so an agent knows to use it when it needs those settings. It does not explicitly name alternatives such as update_site_filters or state when not to use it, so it falls short of full routing 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?

With no annotations, the description carries the full behavioral disclosure burden and does so thoroughly. It explains the exact response shape, the meaning of ends_at, the edge case for free accounts, and explicitly states that the tool takes no arguments.

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. Every sentence adds meaningful information: scope differentiation, response schema, field semantics, and an edge-case clarification. No redundant or filler content is present.

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

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

Given the tool's simplicity (zero parameters, no output schema, no annotations), the description is remarkably complete. It provides the full response structure, explains the tricky field semantics, and clarifies ambiguous status values, so an agent can invoke it and interpret results 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?

There are zero parameters and the schema is empty, so the description only needs to confirm that no arguments are required, which it does. The baseline for zero-parameter tools is 4, and the description fully covers the only relevant semantic point.

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 the account's plan state, explicitly distinguishing it from a site's state. This differentiates it from the sibling tools, which are site- or stats-oriented. The response format and status meanings make 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?

The description makes it clear that this tool is for retrieving account-level subscription/plan information, not site-specific data. It does not explicitly name alternatives or exclusion conditions, but for a parameterless getter with no sibling providing subscription data, the usage context is sufficiently 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 no annotations provided, the description carries the full behavioral burden and delivers: an inline JSON response example showing the exact return shape, semantic disclosure of locked (cannot be changed) and requires (must be on for the feature to work), and an explicit access requirement. This is far above the typical read-tool description.

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 purpose is front-loaded and every sentence earns its place: response shape, field semantics, and the access note. The inline JSON example is verbose but justified because there is no output schema to carry the return-format burden.

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-parameter read tool with no output schema and no annotations, the description is nearly complete: it documents the return format inline, explains non-obvious field semantics, and states access requirements. The only real gap is error behavior on an invalid site_id.

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% — the site parameter is already documented as 'site_id from list_sites.' The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description states exactly what the tool retrieves: which tracking features are on, which exist, and what each costs in bytes. It also differentiates itself from the sibling update_tracking_settings by framing the content as what the installed script actually does, so an agent can distinguish read from write without opening either 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?

The description routes the agent to update_tracking_settings for the change operation, implying this tool is for reading, and notes the access prerequisite ('needs the same access as changing them'). It does not explicitly enumerate when-not-to-use cases or alternative siblings like get_tracking_snippet, but the read/write contrast gives clear context.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it states the operation is read-only, does not install or verify anything, warns against rebuilding the tag, and documents the hobby-site data-id behavior. This is well beyond a minimal description.

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, front-loaded with the core purpose, then a compact response example, then the two important caveats. No filler; every sentence adds operational 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?

The tool is simple, and the description covers the response shape, the read-only safety profile, and the critical installation edge case. With no output schema and no annotations, the description gives an agent enough to call the tool correctly without further inference.

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 the site and type parameters. The description adds a response example and usage cautions but does not add parameter-level meaning beyond the schema, matching the baseline for high coverage.

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

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

The description opens with a concrete resource: the script tag and URL to install on a site. It clearly identifies the retrieval intent and distinguishes this tool from configuration-oriented siblings by framing the output as installation code and noting it is read-only.

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 context is clear: use this when you need the installation snippet for a site. It adds explicit guidance to install the snippet verbatim and not rebuild it from script_url. It does not name an alternative tool or state when not to use it, so it stops short of full routing 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?

There are no annotations, so the description carries the full burden. It provides an exact sample return shape with field names, which is valuable behavioral transparency. It does not mention auth, errors, or explicit read-only safety, but the verb 'List' and the return sample make the behavior clear.

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 focused sentence plus a compact JSON sample. It front-loads the core action and purpose, and every element adds value without redundancy.

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

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

For a simple listing tool with one optional parameter, this is complete: it states scope, purpose, relationship to funnel_report, and the return structure in the absence of an output schema. No critical information 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 fully documents the 'site' parameter. The description adds only general site context and does not need to repeat parameter details; baseline 3 applies.

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

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

The description states a specific verb ('List'), a specific resource ('conversion funnels configured for a site'), and a clear discovery purpose ('get a funnel_id for funnel_report'). This differentiates it from related tools like list_goals 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?

The description gives explicit usage context: use it to discover funnel IDs before calling funnel_report. It does not enumerate exclusions or compare against alternatives, but for a dedicated list tool this is reasonably 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?

There are no annotations, so the description carries the behavioral burden. It provides the full response shape, including nullable fields and allowed operator values, and clarifies that this is a configuration-focused listing rather than a performance query. It does not discuss pagination, authentication, or error behavior, but for a simple single-parameter list tool the provided detail is strong.

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, immediately distinguishes it from top_goals, and includes a compact response example. Every sentence contributes either to disambiguation or to understanding the return format, with no filler.

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

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

With one parameter, full schema documentation, and an explicit response shape in the description, the agent has everything needed to invoke the tool correctly and interpret its output. The tool is simple enough that missing authentication or rate-limit details are not critical gaps.

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

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

The schema documents the only parameter ('site') and even tells the agent to source it from list_sites, so schema coverage is 100%. The description adds context by saying 'goals CONFIGURED on a site,' but does not add meaningful parameter-level detail 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 lists configured goals on a site, explicitly contrasting with performance data by saying 'what it measures, not how those goals performed.' It also names top_goals as the alternative for conversion numbers, making the distinction from a sibling tool immediate.

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

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

It explicitly says to use top_goals when conversion numbers are needed, providing a clear when-not-to-use rule and naming the alternative tool. The description also frames this tool as the correct choice for configuration/measurement definitions.

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 no annotations provided, the description carries the full burden and does well by stating what is returned and including a concrete response shape. 'List' also implies a read operation. It does not cover edge cases like empty results or auth requirements, but the core behavior is clear.

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, dense sentence states the purpose, connects it to a related tool, and includes a sample return payload. Every element earns its place and there is no redundant wording.

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 is simple with two optional, well-documented parameters. Since no output schema exists, the description compensates by providing a concrete response example. The description, together with the input schema, gives an agent everything needed to call and interpret the result.

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 provides 100% parameter documentation, including site resolution behavior and period formats/defaults. The description adds no parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('List') with a precise resource ('custom-property keys a site has recorded') and clarifies its role as discovery for the event:props:<key> breakdown in query_stats. This clearly distinguishes it from sibling list tools like list_sites or list_goals.

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

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

The description identifies the intended use case: discovering recorded custom-property keys before using the event:props breakdown in query_stats. It gives clear context but does not explicitly state when not to use it or name alternative tools.

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 no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses response structure, nested stats behavior when date_range is supplied, units for each metric, timezone approximation caveats, and free-plan implications. This goes well beyond a minimal listing tool description.

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 every sentence earns its place. It front-loads the core purpose and response format, then adds the hobby-plan caveat, metric units, and timezone precision caveat in a logical order. There is no filler or repeated schema information.

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

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

There is no output schema, so the description must fully document the return shape and behavior, and it does. It covers the site object, nested stats, metric semantics, units, plan implications, and the recommendation to use query_stats for precision. An agent has enough context to call the tool and interpret results correctly.

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

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

The input schema already provides 100% coverage for date_range, so the baseline is 3. The description adds meaningful semantics: nested stats are never flat, units are defined, and timezone accuracy is called out as approximate. This clarifies interpretation beyond the schema's raw parameter text.

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 defines the operation, the scope (API-key-readable sites), and distinguishes it from other site-related tools by emphasizing the listing and scoping behavior.

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 routing guidance: it explains that site_id should be used with other tools, that hobby sites require the get_tracking_snippet script, and that query_stats should be used for timezone-exact numbers. It stops short of explicitly enumerating when not to use list_sites versus each sibling, but the context is strong.

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 no annotations available, the description carries the full burden and does so thoroughly. It discloses read-only semantics, site-local timezone behavior, the meaning of event:name and event:goal breakdowns, breakdown-only metrics that get rejected in other modes, metric units, comparison behaviors, and dynamic event:props requirements.

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 the tool is complex with seven parameters and rich behavior. It is well structured: core purpose first, then return shape, timezone, breakdown semantics, metric restrictions, units, and dynamic dimensions. Each clause adds necessary information rather than repeating schema content.

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

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

For a complex query tool with no output schema, the description is remarkably complete. It covers return shape via an example, timezone handling, metric meanings and units, breakdown-only restrictions, compare range requirements, ambiguous-site failure behavior, and the dynamic dimension pattern. An agent has enough context 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?

Though the schema already has roughly 71% coverage, the description adds substantial meaning beyond the enums: exact unit definitions for visit_duration, bounce_rate, views_per_visit, and counts; explanation of event:goal metrics; restrictions on when events/conversion_rate are valid; and the dynamic event:props dimension pattern. This meaningfully clarifies how parameter values behave.

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: 'Run a read-only analytics query for one site' and names the three supported shapes (aggregate totals, time series, top-N breakdown). It is clear, but it does not explicitly differentiate itself from sibling tools like top_pages or top_sources, which are specialized versions of the same kind of query.

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 usage context is clear: use this for one-site analytics queries needing aggregate, time-series, or top-N results. However, no alternatives are named and there is no explicit guidance about when to prefer query_stats over the sibling top_* or visitors_over_time tools; usage is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden and does a good job: it exposes the exact response shape and clarifies that the dimension value is an ISO alpha-2 code while the display name lives in labels. It does not discuss sorting or error behavior, but 'top' implies the ordering and this is not a destructive or complex operation.

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 information-dense sentence that leads with the core purpose, then provides the return format and key field semantics. Every clause adds value, though the embedded JSON example makes it slightly longer than strictly 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's return-shape disclosure is essential and is handled well. Parameter defaults and site-matching nuances are covered by the input schema. Minor gaps like explicit sort order and timeout/error behavior exist, but the tool is simple enough that these are not critical.

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 all three parameters (site, limit, period) with meaningful details. The description adds no parameter-specific semantics, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Top countries by visitors for a site.' This clearly distinguishes it from sibling tools like top_sources and top_pages, and the country filter reference confirms it is a country-level 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?

The description gives the scope ('for a site') and hints at a downstream use ('drops straight into a country filter'), so an agent can infer when to call it. However, it never explicitly contrasts it with sibling tools or states when-not-to-use it, leaving some selection burden on the agent.

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

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

With no annotations, the description carries the behavioral burden and does so well: it gives the exact JSON shape and defines both metrics ('events' as raw occurrence count, 'visitors' as unique users). It also discloses that pageview/engagement are excluded. It could add sort direction or side-effect note, but for a read-style reporting tool it is transparent enough.

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 compact, opening with the core purpose and using the embedded JSON to convey the return format efficiently. The parenthetical 'data-statable-event' is slightly jargon-heavy, but every clause 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?

With no output schema, the description compensates by specifying the response structure and metric meanings, and the schema covers all parameter constraints. Missing an explicit statement of sort order and edge-case behavior (e.g., empty results), but overall an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the parameters are already fully documented and the description does not need to repeat them. The description's metric definitions relate to the output rather than parameter semantics, so it adds no extra parameter-level meaning beyond the baseline.

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

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

The description names a specific resource (custom events, 'data-statable-event'), a specific aggregation (top by count for a site), and explicitly excludes pageview/engagement, which separates it from sibling top_pages. The verb 'Returns' plus the example makes 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?

The 'pageview/engagement excluded' detail implies when this is appropriate, but there is no explicit statement of when to use top_custom_events versus alternatives such as top_pages or top_goals. The tool name and phrase 'for a site' provide context, but the agent must infer selection criteria.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the exact response shape and explains that visitors means unique converters, events means total conversions, and conversion_rate is unique converters as a percentage of all visitors in the period. This goes well beyond the schema.

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

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

The description is front-loaded with the core purpose and includes a concrete response example that earns its place because there is no output schema. It is slightly dense due to the inline JSON, but remains well-structured and free of fluff.

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

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

Given that no output schema exists, the description usefully provides the return shape and semantic definitions. It is slightly incomplete in that it does not state sort direction explicitly or describe edge cases like no matching goals, but it is still strong enough 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 description coverage is 100%, so the schema fully documents the site, limit, and period parameters. The description does not add much parameter-level meaning beyond referring to the period in the metric definition, so the 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 states the tool ranks the site's configured goals by conversions, which is a specific verb plus resource. It does not explicitly contrast itself with sibling tools like list_goals or top_sources, but the ranking-by-conversions phrasing makes the core purpose clear.

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 intended usage is implied: this is for seeing configured goals ordered by conversion performance. However, it does not explicitly say when to prefer this over list_goals, query_stats, or top_custom_events, nor does it mention any exclusions or 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?

With no annotations, the description carries the full behavioral burden. It discloses the return shape with an example, which is helpful, but it does not explicitly state sort order, read-only behavior, or failure modes such as ambiguous site matching. The example adds some transparency but not comprehensive behavioral context.

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 brief, front-loaded with the tool's purpose, and includes a compact JSON example that clarifies the return contract. Every part earns its place and there is no filler.

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

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

For a simple query tool with three optional parameters fully documented in the schema, the description plus schema is sufficient for invocation. Since there is no output schema, the inline JSON example compensates well. It loses the final point because it omits explicit sorting semantics and any guidance about choosing among sibling top_* tools.

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

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

Schema description coverage is 100%, so the schema already documents site, limit, and period. The description adds no extra meaning for these parameters; it only shows the output shape. This matches the baseline of 3 for fully documented schemas.

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

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

The description clearly states the tool returns top pages by visitors for a site, naming the specific resource ('pages') and metric ('visitors'). It is clear on its own, but it does not explicitly differentiate itself from sibling top_* tools such as top_sources or top_countries, 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?

No guidance is given on when to use this tool instead of sibling tools like top_sources or top_custom_events. It does not mention any exclusions, alternatives, or conditions that would route an agent here versus elsewhere.

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 no annotations, the description carries the full burden for behavioral disclosure. It does reveal the exact result JSON, including the dimension key 'visit:source' and metrics 'visitors' and 'bounce_rate', but it does not state read-only behavior, sort direction beyond the word 'top', or possible failure modes.

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 exceptionally compact: a one-line purpose statement followed by a concise JSON example that shows the exact response structure. There is no verbosity or redundant information; every word earns its place.

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

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

Despite lacking an output schema and annotations, the description compensates with a concrete result example, and the fully-covered parameter schema handles invocation details. Some ambiguity remains around what 'visitors' counts and no usage context is provided, but the essential calling information 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 site, limit, and period parameters are already thoroughly documented. The tool description adds no parameter-level meaning beyond the example output shape, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource ('traffic sources for a site') and the ordering metric ('by visitors'), and the example return shape reinforces what is retrieved. However, it uses a noun phrase rather than a verb and does not differentiate from sibling tools like top_pages or 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?

No guidance is given about when to choose top_sources over siblings like top_pages, top_countries, or query_stats. The description only states the general purpose; there are no alternatives named or conditions for exclusion.

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 no annotations provided, the description carries the burden of behavioral disclosure. It reveals a critical behavior: omitted steps are removed, which prevents an agent from assuming partial updates are safe. It does not discuss effects of omitting optional fields like scope or strict_order, but the core replace behavior is clearly disclosed.

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

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

The description is one compact sentence that states the action, the object, and the most important behavioral caveat. It is front-loaded with the verb and resource, and 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 a 6-parameter mutation tool with no output schema and no annotations, this description is adequate but not complete. It clearly communicates replacement semantics and step removal, but it leaves ambiguity about whether omitting optional fields resets them, and it does not provide guidance on expected response or prerequisites.

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 33%, so the description needs to compensate. It adds meaningful semantics for the steps parameter by explaining whole-funnel replacement and step removal. However, it does not clarify the meaning or update behavior of optional parameters like scope and strict_order.

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 operation ('Replace a funnel's definition') and the resource, immediately distinguishing it from create-style tools. It also clarifies the replace semantics by noting that omitted steps are removed, not kept.

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 is for updating an existing funnel and gives a clear instruction to send the whole funnel. However, it does not explicitly mention when to prefer this over create_funnel or provide any exclusionary 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?

With no annotations, the description carries the full behavioral burden. It clearly reveals the critical destructive-overwrite behavior: omitted fields are cleared, not kept. This is non-obvious and valuable. It does not cover other side effects, but for the main behavior 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?

Two tightly written sentences with no filler. The purpose is front-loaded and the critical behavioral warning follows immediately. Every word earns its place.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description is incomplete. It provides the key overwrite warning but omits parameter semantics for most fields, usage context, and any mention of constraints or enum meanings. An agent would need to guess at several parameter purposes.

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 only 29%, with just site and goal_id documented. The description does not explain the meaning of name, path, operator, event_name, or scroll_depth, nor the operator enum values. 'Send the whole goal' is not parameter-level guidance and fails to compensate for the schema gap.

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 'Replace' and resource 'a goal's definition,' clearly indicating this modifies an existing goal rather than creating or listing one. It is distinguishable from siblings like create_goal and list_goals, though it does not explicitly name an alternative.

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 provided on when to use this tool versus create_goal, update_funnel, or other sibling tools. The instruction to 'Send the whole goal' is about invocation mechanics, not about selecting the tool in 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?

No annotations exist, so the description carries the full burden. It discloses key behavioral traits: omitted fields are left alone, the updated site is returned, and duplicate URLs are refused with the site_exists code. This is strong transparency for a mutation tool, though it doesn't mention permissions or the failure mode for a nonexistent site.

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

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

Three sentences with no filler. The core action is front-loaded, and each sentence contributes unique information: what changes, how omissions behave, and a key rejection case.

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 low-complexity update tool, the description covers the essentials: target fields, partial update behavior, return value, and an error condition. It does not cover the nonexistent-site case or permission prerequisites, but the schema's site_id reference to list_sites provides some context. Overall it is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value beyond this by explaining partial-update semantics and a specific error condition tied to the url parameter. That goes above the baseline 3.

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: 'Change a site's url, timezone or week start.' It clearly enumerates the mutable fields, making the tool's purpose unmistakable. It also separates it from sibling update tools like update_goal and update_funnel by focusing on site settings.

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 usage: it is for updating an existing site's settings. The partial-update note ('Omitted fields are left alone') is a useful usage guideline. However, it never explicitly states when not to use this tool or points to alternatives like create_site for creating a new site, so the guidance is only implied rather than explicit.

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 no annotations, the description carries the full burden and meets it well. It discloses partial-update behavior, full replacement semantics with concrete examples, that filtering only affects new traffic, and that the response returns the resulting state plus an 'updated' list.

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

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

The description is compact, front-loaded, and every sentence earns its place. The key behavioral rule is stated immediately, followed by examples and response details, with no filler 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?

Despite having no output schema, the description tells the agent exactly what to expect: the resulting state plus an 'updated' key naming changed fields. It also covers the tricky replace-vs-omit semantics, the read-first workflow, and the delayed effect on data collection, making the tool fully understandable.

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 meaningful semantics: omitted sections stay untouched, sent sections replace entire settings, empty arrays clear lists, and 'allowed non-empty = count only these.' This goes beyond the schema's per-field descriptions.

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

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

States a specific action and scope: 'Change who gets counted, and who may look,' which clearly identifies this as a site filters update tool. It also distinguishes itself from the read-only sibling get_site_filters by implying that reading the current state is a separate step.

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

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

Provides a clear read-modify-write workflow: read the current state with get_site_filters, apply the edit, and send it back. It also explains which payload sections to include. It does not explicitly state when not to use this tool, but the guidance is strong enough for an agent to select 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?

With no annotations, the description carries full responsibility and does an excellent job: it warns that the selection is fully replaced, any omitted feature is disabled, and the script is rebuilt and republished with a CDN propagation delay. These are critical behavioral traits beyond the basic schema.

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

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

The description is compact and well-structured: purpose first, then the critical replacement warning, then the prerequisite, then the side-effect timing. Every sentence contributes actionable information with no redundancy.

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

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

For a two-parameter mutation tool with no output schema and no annotations, the description covers all necessary aspects: what changes, how the parameter should be provided, how to get valid values, and when the change takes effect. Nothing critical is missing for correct invocation.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds significant value by clarifying that 'features' is the complete list, not a delta, and that an empty array disables all optional features. It also instructs calling get_tracking_settings first for valid IDs.

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: 'Set which tracking features the site's script includes.' This clearly distinguishes it from get_tracking_settings (reading) and update_site (general site updates), and the replacement behavior is stated up front.

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?

Clear context is provided: the tool is for setting tracking features and should be preceded by get_tracking_settings to obtain valid IDs. It does not explicitly state when not to use it or name alternatives beyond get_tracking_settings, but the purpose is specific enough that an agent can route 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It does well by revealing that results are in the site's own timezone and by providing a concrete JSON example showing the dimensions and metrics keys. It does not mention error cases, rate limits, or pagination, but for a simple read-only reporting tool the returned structure and timezone behavior are the most important behavioral details and they 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 two sentences with zero filler. It front-loads the core purpose, then provides the exact return shape in a compact JSON snippet. Every part earns its place, and the inline example is far more useful than prose describing the output.

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 is simple (two optional parameters, no output schema), and the description adequately compensates for the missing output schema by showing exactly what the response looks like. The parameter meanings are fully covered by the schema. It is missing only an explicit relationship to sibling tools, which is handled more under usage guidance, so this dimension is otherwise complete.

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

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

The input schema already documents both parameters thoroughly (100% coverage), including the site_id/domain matching behavior and the period pattern/defaults. The description adds no additional parameter-level meaning beyond what the schema provides, so the 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 states that the tool returns a daily visitors and pageviews time series for a site, and even specifies the site's timezone and the exact output shape. It does not explicitly use a verb like 'retrieves' or 'returns' at the start, and it does not name a sibling tool to distinguish itself from, so it falls just 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?

There is no guidance about when to use this tool versus alternatives such as query_stats, current_visitors, or top_pages. The description implies this is the time-series reporting tool, but it never states when it should be preferred or when another sibling should be chosen instead.

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