Staats

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

With readOnlyHint=true already conveying safety, the description adds valuable behavioral details: the after-window is clamped to now, route-level pageviews appear when the annotation recorded routes, and a note may be returned indicating truncated or missing data. It also instructs the agent to relay the note and qualify percentages, which is transparent about response 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?

The description is compact, with each sentence earning its place: the core function, the window behavior, the routing detail, the timing caveat, and the note-handling instruction. It is front-loaded with the primary purpose and contains 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?

Given the output schema exists and the annotations cover safety, the description covers everything an agent needs: what is measured, how the window works, special-case behavior, and how to handle caveats in the response. Nothing important is left unstated for correct invocation and interpretation.

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 meaning beyond the schema by explaining window_days as 'N days preceding vs following' and highlighting the after-window clamping behavior. This enriches the agent's understanding of the parameter's practical effect without being redundant with the schema.

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

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

The description states a specific verb ('compare') and resource ('recorded annotation') with the exact metric ('visitors and pageviews in the N days preceding vs following it'). It clearly distinguishes from sibling tools that address other analytical questions or site management, making it unambiguous what this tool is for.

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 use the tool (after an annotation has been recorded) and includes explicit guidance to 'wait a few days after shipping.' It does not name alternative tools or state when not to use it, but the annotation-specific framing makes the usage context strong 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?

The description goes beyond the sparse annotations by explaining post-creation behavior: the connection already covers the new site, and installing the script tag is the only setup needed. It also discloses that the response includes ready-made privacy policy wording and advises confirming with the owner before editing visitor-facing pages. No contradiction with annotations 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 three sentences, each earning its place: core action, setup implication, and response guidance with a necessary safety note. It is compact and logically ordered, though the second sentence could be marginally tighter. Overall, 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 create operation, the description covers the key behavioral expectations: new site creation, script tag retrieval, connection status, and the privacy policy content in the response. An output schema exists to document return values, so the description doesn't need to explain the full response structure. It gives enough context to call correctly and know the next step.

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% description coverage for both required parameters (name and domain). The tool description does not add further parameter-specific meaning; it focuses on tool behavior. Since the schema carries the parameter documentation burden, 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 uses a specific verb and resource: 'Create a new site on this account and get its script tag.' It clearly identifies the action and distinguishes it from siblings like delete_site and list_sites. The mention of getting the script tag adds specific output-related purpose beyond just creation.

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 first sentence makes the usage context clear: use this when a new site is needed on the account. The additional note that the connection already covers the new site and only the script tag needs installing clarifies the setup implications. It doesn't explicitly name alternatives, but the resource-focused purpose makes when-to-use unambiguous.

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?

Goes well beyond the destructiveHint by disclosing that the operation is permanent and irreversible and destroys every event and annotation. This is precisely the behavioral context an agent needs before invoking a delete tool, and it does not contradict the idempotentHint.

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 front-loaded sentence conveys the key warning, permanence, scope, and action. Every word contributes; 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?

Between the annotations, fully documented schema, output schema, and this description, an agent has all safety and invocation context needed. This is complete for a destructive two-parameter tool.

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

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

The input schema already documents both parameters at 100% coverage, including the exact-domain requirement and the warning against inferred/guessed confirm values. The description restates the confirm requirement but adds no new parameter-level information.

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

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

States a specific verb ('PERMANENTLY delete'), the resource ('a site'), and the full scope ('ALL its analytics data — every event and annotation'). This differentiates it from the sibling site tools such as create_site, update_site_context, and get_site_context.

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?

Clearly instructs to confirm with the owner before calling and specifies what to pass in confirm. It does not explicitly name alternatives or state when not to use, but the destructive context and sibling list make the intended use clear.

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

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

The description goes well beyond the readOnlyHint annotation by explaining the visitor-count rule (step N requires step N-1), the daily identity rotation causing undercounting, and the stored-funnel fallback behavior. These are non-obvious behaviors an agent must know for correct 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 three dense sentences with no wasted words. It front-loads the core definition, then delivers the counting caveat, then the usage instruction. 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?

With the output schema present, all parameters documented in the schema, and annotations declaring read-only behavior, the description's added caveats and usage context make it complete. An agent has enough to choose, invoke, and interpret this 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics by illustrating the exact step object structure for both paths and events, and by referencing the site context's stored funnel. This elevates it above baseline.

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

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

The description clearly defines the tool as an ordered conversion funnel across up to 5 steps and specifies the step format (path or event) and counting rule. It stops short of naming sibling tools or using an explicit verb like 'compute' or 'return', and does not explicitly distinguish itself from siblings like 'journeys'.

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 a clear usage directive: if a stored funnel exists in site context, run those steps when asked how the site is doing and compare against the previous period. It also warns about the undercounting caveat for multi-day journeys, but it does not state explicit exclusions or alternative tools for different scenarios.

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 readOnly, so no extra safety disclosure is needed. The description adds meaningful context beyond that: it warns that the result includes quota status and instructs the agent to surface approaching/grace/blocked states to the owner with the upgrade link, which is useful behavior an agent would not otherwise know.

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

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

Three short sentences each carry distinct information: what the tool returns, how period works, and how to handle quota status. It is front-loaded with the core output list and contains 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?

An output schema exists, so the description does not need to enumerate every return field; it still conveys the main content categories and the quota edge case. It could add a note about when the overview is appropriate versus portfolio_overview, but that is covered by the usage dimension and the description is otherwise complete for a read-only snapshot 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 schema documents both site and period fully. The description only repeats the period examples and default without adding extra meaning, so it provides no value beyond the schema.

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

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

The description lists concrete outputs (visitor/pageview totals, top pages, top referrers, per-day series) and names the resource as a site overview, so an agent can tell it returns a high-level traffic snapshot. It stops short of explicitly contrasting it with siblings like portfolio_overview, but the single-site scope is reasonably clear from the content.

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

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

The description implies use for a quick overview of traffic and quota, but it never states when this tool should or shouldn't be chosen over alternatives such as portfolio_overview, funnel, or compare_around. The period and quota guidance are operational details, not selection criteria.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful semantic context beyond that: the meaning of well-known keys, the session-start convention for notes, and the canonical funnel steps. This makes expectations about the returned content clear without conflicting with annotations.

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

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

The description is compact and information-dense: it states the purpose, lists the well-known keys, and closes with a direct usage instruction. Every sentence earns its place and the most actionable guidance is front-loaded.

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

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

For a simple read-only tool with one optional parameter and an output schema, the description covers content scope, key semantics, retention context, and when to call it. Nothing needed for correct selection or invocation is obviously 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%, and the optional site parameter is already well documented in the schema with guidance about data-site codes and tracked projects. The tool description adds no extra parameter meaning, 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 title and name make it clear this is a retrieval tool for site context, and the description specifies the resource: what the site is, what the owner wants, and data-retention settings. It is clearly distinct from update_site_context by implication, but it does not explicitly differentiate itself from siblings like list_sites or 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?

The description gives explicit usage direction: 'Read this before making recommendations,' and the notes key adds session-start behavior by flagging open agenda items to check and clear. It does not state when not to use it or point to alternatives, but the timing guidance 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?

The description adds substantial behavioral detail beyond the readOnlyHint annotation: consecutive repeats are collapsed, only the first 10 steps define a route, and visitor identity rotates daily so a route describes a group rather than a person. This gives the agent critical expectations about grouping semantics and privacy boundaries that the schema and annotations do not 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 dense but every sentence earns its place: purpose, sibling differentiation, step syntax, deduplication/truncation rules, contains behavior, and identity rotation are all covered without filler. It is front-loaded with the main purpose before moving into usage and edge-case semantics.

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 analytics tool with 6 optional parameters and an output schema, the description covers the conceptual model, route grouping rules, the conversion-event representation, contains-filter workflow, and the daily identity limitation. Combined with the readOnly annotation and schema coverage, nothing critical is missing for an agent to select and invoke this 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 schema already documents all 6 parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond that by explaining the step format for path vs #event and by clarifying what the contains parameter actually does at the route level, which helps the agent construct correct parameter values.

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 verb-resource pairing: "routes visitors actually take, grouped into identical sequences and counted, busiest first." It explicitly distinguishes journeys from funnel by naming what each does, so an agent can tell them apart without inspecting schemas.

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

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

It gives an explicit when-to-use rule: "Use this when you do NOT already know the steps: funnel measures a path you name, journeys discovers the ones you did not think to check." It also advises how to use the contains filter by running the tool once with and once without it, which is actionable 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds useful behavior beyond it: results are ordered newest first, and the period defaults to '90d'. It does not mention pagination or result limits, but the output schema exists to cover return shape, and no contradiction with annotations is 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 a single sentence that front-loads the core resource and ordering while including the only essential default. Every word earns its place with no filler or redundancy.

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

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

For a simple read-only listing tool with two optional parameters fully documented in the schema, a readOnlyHint annotation, and an output schema present, the description is complete. It explains what annotations are, how they are ordered, and the default time window. No critical missing context would prevent an agent from invoking 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 fully documents both 'site' and 'period'. The description's only parameter-related statement, 'period defaults to 90d', merely repeats information already present in the schema's period description. Thus the description adds no meaningful semantic value beyond the schema.

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

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

The description clearly identifies the resource as 'Recorded deploy/change markers' and specifies ordering ('newest first'), so an agent understands this is a read-oriented listing tool. It does not explicitly use a verb like 'list' or 'return', relying on the title, and it does not differentiate itself from sibling tools such as record_annotation, though the noun phrase makes the distinction reasonably inferable.

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 no explicit guidance on when to use list_annotations versus alternatives like record_annotation or compare_around. It mentions the period default, which is parameter usage rather than tool-selection guidance. No when-to-use or when-not-to-use conditions are 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context about the account scope and the included fields, but it does not disclose additional behavioral traits such as pagination, ordering, or any access requirements. With annotations covering the safety profile, this is adequate but not exceptional.

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 core purpose and immediately states the account scope and key output fields. Every word 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?

For a parameterless read-only list tool with an existing output schema, this description is complete. It tells the agent what the tool returns and the scope of the data, which is sufficient to select and 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?

The tool has zero parameters, so the input schema leaves no ambiguity. The description adds semantic value by clarifying what will be returned for the account, making it clear that no additional arguments are needed.

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 all sites on the account and specifies the key output contents: public site codes and ready-to-paste script tags. It is specific about verb and resource, though it does not explicitly differentiate itself from sibling tools like get_site_context or get_overview.

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 is for retrieving all sites on the account, with no filtering or parameters. It implies the appropriate use case but does not explicitly state when to prefer it over alternatives or mention 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?

Beyond the readOnlyHint annotation, the description discloses sorting behavior (busiest first), comparison semantics (change vs the previous period), inclusion of shared sites, and flagging behavior for shared sites. This gives the agent a clear picture of the tool's output shape and behavior without needing to invoke it.

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 entire relevant behavior is captured in one compact sentence, with the most important content (what is returned) front-loaded and the default parameter appended at the end. Every clause adds value: scope, metrics, comparison, ordering, and shared-site flagging.

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, single-optional-parameter portfolio summary with an output schema present, the description covers all essential decision factors: metric types, site scope, comparison delta, ordering, shared-site flagging, and default period. Nothing critical is missing for an agent to select and invoke this 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 schema already fully documents the single 'period' parameter with examples and the default value. The description repeats the '7d' default but does not meaningfully extend the schema's parameter documentation. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the resource (every site this account can use), the metrics returned (visitors, pageviews), and the temporal comparison, with a clear scope spanning owned and shared sites. It distinguishes itself from the 'get_overview' sibling by emphasizing portfolio-wide aggregation across all accessible sites.

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 for portfolio-wide traffic analysis and explicitly notes that shared sites are included and flagged, but it does not name alternatives or state when not to use this tool versus get_overview or list_sites. Usage context is clear enough to infer, but the description stops short of explicit 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?

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds useful operation details such as supported metrics, dimensions, and period formats, but it does not disclose additional behavior beyond what annotations and schema already 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, front-loaded with the core action, and every sentence earns its place. The lists of metrics, dimensions, and period styles are dense but directly useful, 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?

Given the rich schema, output schema, and annotations, the description is nearly sufficient for correct invocation. It covers the main options and enums, though it could be stronger by explicitly indicating when a sibling tool like funnel or get_overview would be more appropriate.

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 description mostly restates enum values and period options that already exist in the schema. It adds no significant new meaning beyond the structured parameter descriptions, 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 and resource: 'Break a metric down by a dimension with optional equality filters,' and enumerates valid metrics and dimensions. It is clear about what the tool does, but it does not explicitly distinguish it from sibling analytics tools such as funnel or get_overview.

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 usage context: query a metric, optionally group by a dimension, optionally filter by equality, and choose a period. It does not mention when not to use this tool or point to alternatives, 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?

Annotations already communicate non-idempotence and non-destructiveness. The description adds useful context beyond the schema: call frequency, one annotation per change, required text style, and how including commit/routes affects compare_around. No contradiction with annotations.

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

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

Every sentence earns its place: tool purpose, when to call, text quality rule, and optional enrichment rationale. It is front-loaded with the primary verb and resource and contains no filler or tautology.

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, 1-required tool with a full schema and an output schema, the description covers the call trigger, content standards, and the rationale for optional fields. The only unresolvable details (site code handling, return value) are already covered by the schema and output schema respectively.

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 value by explaining the purpose of commit and routes ('so compare_around can also report before/after traffic scoped to those routes') and by prescribing text format with a concrete example and a counterexample. It does not add much for ts or site, but the schema already documents those.

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: 'Mark a moment on a site timeline' with concrete event types (deploy, content change, campaign start). It also clearly differentiates from siblings by positioning list_annotations as the reading counterpart and compare_around as a downstream consumer.

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 an explicit trigger: 'Call this every time you ship a change to the site' and adds guidance like 'one annotation per meaningful change'. It also explains how commit and routes benefit compare_around, but it never explicitly names when-not-to-use alternatives, so exclusions are left largely to inference.

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

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

Annotations already mark the tool as idempotent and destructive, and the description adds valuable behavior beyond that: fields are merged, events merge per entry, null deletes a key, and name/domain update the site record rather than context. These are concrete, non-obvious behaviors an agent needs to know.

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

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

The description is three short sentences with no filler. The main action is front-loaded, and the two most important behavioral caveats follow immediately. It does not repeat what the schema already documents.

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 complex with 10 parameters and nested objects, but the schema, annotations, and output schema cover the remaining details thoroughly. The description supplies the essential cross-cutting behavior needed for correct invocation, including merge semantics, null deletion behavior, and the distinction between context fields and site-record fields.

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 individual parameters are already well documented. The description adds cross-cutting meaning that the schema cannot express, especially the global merge contract and the events per-entry merge rule. It also clarifies that name and domain are record-level updates.

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: 'Save or amend what a site is for.' It further clarifies the tool's scope by distinguishing context fields from name/domain updates to the site record itself. This makes it clearly distinguishable from the read-only sibling get_site_context.

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 context is implied by the verbs 'save or amend' and the merge/null semantics, but there is no explicit statement about when to choose this tool over alternatives such as get_site_context or create_site. The reference to the funnel tool is about parameter shape, not tool 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?

Given the readOnlyHint annotation, the description adds substantial behavioral value beyond the annotation: it explains that findings clear statistical floors, that empty results mean nothing looks broken, that error samples are sanitized, and that deployed annotations are attributed as the nearest plausible cause. This gives the agent realistic expectations about sensitivity, privacy, and failure attribution.

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 front-loaded with the core purpose and maintains focus on what the agent needs: signal types, fields, meaning of empty results, and timing. It is a long single sentence in places, but every clause contributes a distinct useful fact rather than padding.

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

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

With an output schema present, the description does not need to explain full return structure, but it still covers the essential operational context: when to run it, what a null result means, and what categories of findings to expect. The only minor gap is not explicitly routing to a sibling alternative, but the description stands alone well for this diagnostic tool.

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

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

Schema description coverage is 100%, and the description restates the '7d' default already present in the schema. It does not add significant new meaning for the 'site' parameter, though it does reinforce the default period. Baseline 3 is appropriate since the schema carries the parameter documentation 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 identifies a specific diagnostic resource: signs of visitor-facing breakage, including JS errors and behavioral friction like nav_loop and refresh_burst. It clearly distinguishes the tool's purpose from generic query or overview tools by enumerating the concrete signal types, so an agent can understand what this tool uniquely reports.

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 usage instruction: 'Check it after every deploy.' It also clarifies that an empty result is meaningful, which helps an agent interpret output correctly. It does not name alternatives or state when not to use it, but it provides enough context for typical use.

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 the description adds useful behavioral context by enumerating the kinds of statistically notable events returned and the inclusion of annotations. This goes beyond the structured annotation data without contradicting it.

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 packs useful detail into a single sentence with a clarifying list. The trailing 'period: 7d default' is slightly awkward but still earns its place as a quick reference.

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 analytical tool with an output schema and fully documented optional parameters, the description covers the main behavioral scope and even mentions annotation inclusion. It does not over-explain return values, which the output schema handles, but it could be stronger with explicit sibling routing.

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 only restates the '7d' default for period, adding no new semantic meaning beyond what the 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 clearly identifies what the tool does: it surfaces notable movements in a period—unusual traffic days, referrer surges, first-time referrers, page share jumps, and annotations—without requiring raw-number scanning. This is specific enough to distinguish it from raw query tools, though it does not explicitly contrast it with siblings like what_broke.

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 explicit guidance on when to use this tool versus alternatives. The phrase 'without scanning raw numbers' implies it is a high-level summary tool, but no conditions, exclusions, or sibling comparisons are provided.

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