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 a meaningful downstream trait: future spikes within 24h will list the annotation as a possible cause. It omits other behavior the agent would want — whether annotations can be edited or deleted, idempotency, and any permission 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?

Three short sentences with the core purpose front-loaded, and the parenthetical examples ride along compactly. 'Log what you ship or run' is slightly redundant with the opening sentence, but the overall density is high.

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 3-param, 1-required write tool with no annotations and no output schema, the description covers purpose, examples, and the key downstream effect, so it is close to adequate. It still leaves the required 'label' semantics and edit/delete lifecycle unaddressed, which matters for correctly invoking a write 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 coverage is only 33% (only 'ts' is documented), so the description must compensate. It partially does: the parenthetical maps to the 'kind' enum values and 'Log what you ship or run' hints at 'label' content. But the required 'label' param's format and 200-char limit are left entirely to the schema, and 'kind' defaults are unstated.

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 ('Record'/'Log') and the resource's role: an annotation that ties events like deploys and launches to traffic. The 24h spike-causation framing makes the tool's purpose unambiguous against read-only siblings like find_traffic_spikes and explain_spike. It stops short of naming a sibling explicitly, so it earns a solid 4 rather than 5.

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

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

The examples '(deploy, launch, post, email, ad)' and the closing 'Log what you ship or run' tell the agent clearly what situations warrant a call. However there is no exclusion guidance (e.g., not for organic changes) and no mention of alternatives, so it is clear context without boundaries.

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 it does add real behavioral context: it returns the funnel with its first results, and visitors are matched within a single UTC day (a meaningful analysis constraint). It does not disclose permissions/auth requirements, whether re-creating a funnel with an existing name overwrites or errors, or any idempotency semantics for this write 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?

Front-loaded with the core action ('Save a funnel'), followed by the domain definition, the step grammar, the return behavior, and the matching constraint. Dense but each clause earns its place; 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?

No output schema exists, and the description fills that gap by stating it returns the funnel with first results. For a 3-param write tool the calling-critical knowledge (step format, count limits, matching window) is present; only mutation semantics such as permissions and name-uniqueness behavior are absent.

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 67%, but the critical gap is the `steps` array, whose items have no schema description at all. The description compensates well, defining the '/'-prefix page rule, the trailing-'*' prefix-match rule, and the fallback custom-event interpretation, plus the 2-8 count matching the schema's min/max. The `range` and `name` semantics remain schema-driven.

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 gives a specific verb+resource ('Save a funnel') and goes further by defining what a funnel actually is (an ordered list of 2-8 steps visitors move through), which is unusually informative. It does not explicitly distinguish itself from siblings like get_funnel or delete_funnel, but 'Save' vs 'get'/'delete' is reasonably self-evident.

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

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

Usage is only implied: the agent can infer this is the write path for funnels from 'Save a funnel,' and the valid step grammar is spelled out. There is no explicit when-to-use/when-not guidance and no reference to the get_funnel/delete_funnel alternatives that share the resource.

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 disclosure burden and does well: it states the operation is a write that persists a log entry and that downstream traffic, spikes and conversions are attributed to it. It still omits permission requirements, whether duplicate source+campaign pairs are deduped or error, and whether the call is idempotent.

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, front-loaded with purpose then usage then follow-up call; no filler. Every sentence changes what the agent does.

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, and the description does not say the call returns the shareable tagged link the agent needs to publish — that is the one notable hole. Otherwise purpose, usage policy and follow-up workflow are complete for a 5-parameter creation 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 all five parameters are already documented with defaults and examples (medium default 'social', url default '/'). The description only adds the UTM framing and the single-campaign constraint; it does not explain how source/medium/campaign map to UTM parameters beyond what the schema 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?

States a specific verb and resource ('Create a UTM-tagged link') plus the side effect ('log it so later traffic... credited to it'), which separates it cleanly from siblings like add_annotation or create_funnel. An agent can tell exactly what this produces and why.

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

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

Gives a prescriptive usage rule ('Use a new link for every post, email or ad you publish') and explicitly sequences the follow-up tool: 'After it is published, call add_annotation...'. This is when-to-use plus named alternative/next action, not 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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about irreversibility, required permissions, or what happens to associated data. For a destructive mutation tool this is a significant gap.

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 with no wasted words. Brevity here is appropriate, though the space it saves is spent on necessary behavioral detail that never arrives.

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 destructive tool with no annotations, no output schema, and undocumented optional parameters, the description is too thin. An agent cannot determine safe invocation conditions or the result of the call from what is provided.

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 0% and both parameters are optional, so the description's 'by name or id' is the only signal for the two fields. It does not explain precedence if both are supplied, or what happens if neither is given, which is a real ambiguity given required=0.

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 and resource: 'Delete a saved funnel', with the identifying selectors 'by name or id'. This clearly separates it from siblings like create_funnel and get_funnel, though it does not explicitly name those alternatives.

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

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

No guidance on when to invoke this versus alternatives, nor any caution about the destructiveness of the operation. The agent is left to infer that a delete should only follow confirmed intent.

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 does well: it discloses the analytic output shape (ranked causes with lift, % and share) and the time window examined (annotations in the preceding 24h). It doesn't state read-only status or failure modes for an invalid spike_id, but the read-analysis nature is evident.

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, front-loaded with the core purpose ('Ranked causes for one spike') followed by the evidence categories and time window. No filler, though the enumeration is long.

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

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

For a one-parameter read tool with no output schema and no annotations, the description is fairly complete: it explains what the output contains and the 24h window. The main missing piece is how spike_id is sourced and the absence of a link to find_traffic_spikes.

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 spike_id parameter has 0% schema description coverage, so the description must compensate. It implies spike_id identifies 'one spike' but never explains the ID format or where to obtain it, leaving a clear gap for the only required parameter.

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

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

The description states a specific resource (one spike) and what it returns (ranked causes: referrers/UTM, landing pages, custom events, plus annotations). It's clear an agent can tell this apart from a discovery tool like find_traffic_spikes, though it never names that sibling explicitly.

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

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

Usage is only implied: the tool operates on a single spike_id, which suggests it's called after a spike is identified, but no when-to-use, when-not, or alternative tool is named. An agent must infer that spike_id comes from find_traffic_spikes.

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 it does disclose the detection heuristic, the ordering, and that each result carries likely causes. It says nothing about read-only semantics, rate limits, pagination beyond 'limit', or what happens when no spike exists in the window.

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 sentence that front-loads the definition of a spike, then ordering, then payload. No filler, no restatement of the tool name, and it packs three useful facts without becoming a run-on.

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 convey what comes back - and it does, telling the agent results are ranked and annotated with likely causes. Combined with 100% schema coverage on both params, that is nearly enough; only edge-case behavior (empty results, window limits) is unaddressed.

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% - both 'limit' (max 50, default 10) and 'range' (max 90d, default 7d) are fully documented in the schema. The description adds no new parameter detail, not even tying the hourly detection granularity to the 'range' window. Baseline 3 is appropriate.

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

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

States a specific verb+resource (detect traffic spikes) and even operationalizes it: 'hourly pageviews far above the same hour in prior weeks'. The sorting ('biggest first') and payload ('likely causes') are spelled out. It stops short of naming the sibling explain_spike, so an agent must infer how the two divide labor.

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

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

Usage is implied rather than stated: this is the discovery tool and explain_spike is presumably the drill-down, but the description never says when to use one over the other, nor any prerequisites or exclusions. An agent can guess the workflow but is not told it.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral traits: results are ordered 'newest first' and conversions are constrained to a 'same-day' attribution window. It stops short of stating the read-only nature explicitly or covering result limits/pagination, but the ordering and metric-window disclosures are meaningful beyond structured data.

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

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

Two short sentences, zero waste, with the metric definition front-loaded and the parameter behavior trailing. Every clause 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-parameter read tool with no annotations and no output schema, the description covers the key unknowns: what is returned, ordering, the attribution window, and the source of campaign identifiers. Only secondary details such as time-range scoping or result limits are absent.

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 0%, so the description must compensate, and it does: the single 'campaign' parameter is explained as optional with the semantics of omission ('Omit campaign for all') and its valid values tied to create_tracked_link output. It adds no format/syntax detail for the string value, keeping it just short of a 5.

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 and resource (get campaign results) plus the exact metrics returned (traffic and same-day conversions) and the data source, tying it to the sibling create_tracked_link. An agent can distinguish it from list_events, get_overview, or top_sources without opening a 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?

Explicitly tells the agent how to retrieve everything ('Omit campaign for all') and anchors the tool to campaigns created via create_tracked_link. It does not, however, contrast this with metric-adjacent siblings like get_overview or top_sources, so the when-not case is only partially covered.

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 by enumerating the returned metrics (reached, share of first step, share of previous step, lost, biggest drop). It implies a safe read via 'get' but does not state permissions or the exact output shape.

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 tight sentences with the purpose front-loaded and the parameter modes packed into the second. No filler, every clause 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?

There is no output schema, so the description usefully explains the return metrics, and it covers all three invocation modes. It is nearly complete for a read tool, missing only the max-90d/default-range behavior that the schema already documents.

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 50% (id and name are undocumented in the schema), and the description compensates by explaining that name or id select a saved funnel while steps defines an unsaved one. This adds meaning beyond the structured fields for the two bare parameters.

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

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

States a clear verb and resource ('get_funnel' -> 'Where visitors drop off') and details exactly what the tool surfaces per step (reached, share of first/previous, lost, biggest drop). The purpose is unambiguous, though it doesn't explicitly contrast itself with siblings like create_funnel or delete_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 spells out the three invocation modes clearly: 'Pass name or id for a saved funnel, steps to try an unsaved one, or nothing to get every saved funnel.' That is strong when-to-use guidance, though it stops short of naming alternative tools for adjacent tasks.

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. It usefully discloses the shape of each action (evidence, steps, suggested tracked link, measurement), which tells the agent this is a derived/analytical read rather than raw data. It says nothing about cost, latency, data-volume prerequisites, or how many actions come back — gaps that matter for a computed-insight 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?

Two sentences, front-loaded with what the tool returns before the usage instruction. The parenthetical enumeration is dense but each item earns its place by clarifying the output; minor verbosity keeps it off a 5.

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 is right to spell out the return contents in detail, and it does so well. Missing only operational context (volume of actions, minimum data needed, whether it can be called repeatedly), which is minor for a single-parameter derived-insight 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?

Only one parameter and schema coverage is 100%, so the schema fully documents the range format, default, and 90d cap. The description adds no additional meaning about the lookback window, so the baseline of 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?

States a specific resource (ranked, concrete growth actions) and enumerates the actual output categories — channels to double down on, pages to promote, spike causes, best publish time — which effectively separates it from raw-data siblings like top_sources and get_timeseries. It never names an alternative sibling explicitly, 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?

"Use this to build and then execute a marketing plan" gives a clear situational trigger and even hints at downstream execution (e.g. the suggested tracked link, tying to create_tracked_link). No when-not-to-use condition or explicit alternative is offered, so it is clear context without exclusions.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the content of the response, which is the most relevant behavioral trait for a read-only analytics summary, and 'Start here' signals entry-point semantics. It does not state permissions, freshness/aggregation behavior, or any limits, which is a gap but modest for a clearly read-only metrics 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?

Two compact sentences with zero filler; the metric content is front-loaded and the orienting cue ('Start here') is placed last where it lands naturally. Every phrase 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 single-parameter, optional-arg read tool with no output schema, the description adequately conveys what comes back (summary metrics plus top sources/pages/events). It does not explain response shape or granularity, but the enumerated contents largely cover the return-value gap. Complete enough for an agent to call 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%, and the range parameter's schema already documents accepted formats and the default. The description only alludes to 'the range' and the 'previous equal-length period', adding no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description names specific outputs (visitors, pageviews, period-over-period change, top sources/pages/events), which clearly identifies it as a summary/dashboard tool. It stops short of explicitly differentiating itself from siblings like get_timeseries, top_sources, or top_pages, which also surface related metrics. 'Start here' hints at orientation but isn't a hard disambiguation.

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?

'Start here' is genuine implied guidance that this is the entry point, useful for an agent orienting in a large analytics toolset. However, no alternative is named and no condition for when to use a more targeted sibling (e.g. top_sources) instead is given. Usage is implied rather than specified.

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 are provided, so the description carries the full burden, yet it discloses almost nothing behavioral: no default range, no 90-day cap, no indication of whether results are paginated, cached, or returned as an ordered array. The only behavioral hint ('bucketed by hour or day') merely restates the enum.

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 with no filler; the metric and the bucketing dimension come first. It is efficient, though the terseness borders on under-specification rather than true economy.

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 annotations and no output schema, the description is the only place an agent could learn the response shape, ordering, or default behavior, and it supplies none of that. For a 2-parameter analytics tool that returns a series, this leaves important 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?

Schema coverage is 50%: 'range' is documented in-schema with format, default, and max, while 'granularity' is left to its enum values alone. The description's 'bucketed by hour or day' adds meaning to that enum, so it partially compensates, but it adds nothing about the range format or default.

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 concrete resource and metric set (pageviews and unique visitors over time) plus the bucketing dimension, which is enough to distinguish it from sibling list/summary tools like get_overview or top_pages. It stops short of explicitly contrasting itself with any sibling, so it is clear but not fully differentiated.

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 when-to-use guidance, no mention of when to prefer this over get_overview, find_traffic_spikes, or query_visits, and no stated prerequisites. The agent must infer the use case purely from the metric names.

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 it partly meets it by disclosing the shape of the result set (ranked channels, growth, conversion rate, recurring spike causes). It does not state that this is a read-only aggregation, whether results are cached or rate-limited, or how "recurring" spikes are determined — meaningful gaps on an unannotated 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?

Two sentences, no filler, and the high-value content (what the tool returns) is front-loaded before the invocation advice. Every clause 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?

There is no output schema, so the description usefully enumerates the returned evidence categories, which is the main thing an agent needs to trust the result. It is nearly complete for a single-optional-parameter tool; only the read-only/mutation status and any result limits go unstated.

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

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

Schema description coverage is 100% and the single `range` parameter is fully documented in the schema with format examples and a default. The description adds nothing about the lookback window, 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 names a concrete composite resource — channels ranked by conversions with growth and conversion rate, growing pages, and recurring spike causes — so an agent knows exactly what comes back. It stops short of distinguishing itself from overlapping siblings (top_sources, top_pages, find_traffic_spikes, explain_spike), leaving the agent to guess whether this is a superset or a different cut of the same data.

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?

"Use this before proposing marketing ideas" gives one clear situation for invoking the tool, which is real guidance. It offers no when-not condition and never names the sibling tools (top_sources, top_pages) that partially overlap, so the agent must infer whether to call this instead of, or in addition to, them.

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 that results are ranked by count, but does not state whether the operation is read-only, what permissions are required, or any rate limits or pagination 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?

A single front-loaded sentence that precisely conveys the resource and ranking without any wasted words.

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

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

For a simple two-parameter read tool with no output schema, the description is adequate about what is returned. However, it lacks usage guidance and behavioral context, which leaves gaps even for a low-complexity 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 description coverage is 100%, with both 'limit' and 'range' fully documented including defaults and bounds. The description adds no parameter details beyond what the schema already 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 states the specific resource ('custom events from agentlytics.track') and how they are ordered ('ranked by count'). It implies a list operation but does not use an explicit verb, and sibling differentiation is only implicit against the other ranked analytics tools (top_sources, top_pages, etc.).

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 choose this tool over siblings like get_overview, top_sources, or query_visits. The phrase 'from agentlytics.track' hints at custom events, but there are no explicit usage conditions or 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?

With no annotations, the description carries the burden and delivers useful behavioral context: 'Only counts are returned' sets return expectations (no raw rows), and 'the site stores no IP addresses or user agents' prevents futile queries for that data. It omits auth/permission and rate-limit behavior, but for a clearly read-only analytics query this is solid disclosure.

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

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

Front-loaded purpose statement followed by four compact, parallel examples and a closing caveat. Every sentence earns its place; the examples are somewhat dense but directly actionable and not padded.

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

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

For an 11-parameter tool with no output schema or annotations, the description adequately covers intent, parameter combinations, and return scope ('only counts'). No output schema exists so return-value detail need not be elaborated, though auth/error behavior is left unstated.

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

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

Schema description coverage is 100%, so the baseline is 3, but the examples add genuine value by demonstrating how parameters combine (os=iOS + country=US; browser=Firefox + group_by=source; event=signup + group_by=country; page=/pricing + group_by=day). This shows interaction patterns the schema alone does not.

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 behavior: counting pageviews/custom events and unique visitors matching filters, optionally grouped. It is clear and concrete, but it does not distinguish itself from overlapping siblings like get_timeseries, get_overview, or top_pages/top_sources/top_countries, which this tool can effectively emulate via group_by.

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

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

Usage is conveyed only through worked examples (iOS US visitors, Firefox source breakdown, signups per country, page views per day). There is no explicit statement of when to choose this tool over the sibling top_* / get_timeseries tools, and no exclusions or prerequisites, so the agent must infer the boundary.

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 disclosure burden and does add real behavioral value: newest-first ordering, the daily-rotating `visitor` code and its limitation, and that no IPs or user agents are stored. It omits auth/permission requirements and any rate-limit or result-format notes.

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

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

Two sentences with the core behavior front-loaded ahead of the caveats. The second sentence is slightly sprawling with two separate concerns (visitor code, IP storage), but no sentence is wasted.

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 10-parameter read tool with no output schema, the privacy notes on visitor/IP meaningfully aid interpretation of results. However, with 30% parameter coverage and no description of the return structure beyond the visitor nuance, gaps remain that an agent must resolve from the schema alone.

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 30% (type, limit, range documented), so the description must compensate. It enumerates the filterable dimensions (time, page, source, country, browser, OS, event properties), which maps several params to concepts, but adds no format or syntax detail such as what 'time' accepts or how referrer/event interact.

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 resource and ordering: 'most recent individual visits (newest first)'. Referencing that it matches 'the same filters as query_visits' implies a row-level listing counterpart to a presumably aggregated sibling, but the distinction between the two tools is left implicit rather than stated.

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?

Naming query_visits as a filter-reference implies a companion relationship, but there is no explicit when-to-use-this-vs-that guidance or exclusion criteria. An agent must infer that this returns raw rows while siblings like top_pages/get_overview return aggregates.

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 it does disclose one genuinely useful data caveat: pre-tracking visits surface as 'Unknown'. However it says nothing about sort direction, return shape, or whether results are a fixed enumeration or dynamic — only the category list and the Unknown handling are covered.

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 compact sentences with the core ranking purpose front-loaded, followed by the data caveat. The enumerated category list is the only slightly expendable content, but it is informative enough to earn 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 simple read-only ranking tool with two optional, well-documented parameters, the description is minimally adequate. It lacks any return-format or ordering detail, and with no output schema and no annotations the description could reasonably carry more, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (limit, range) are already fully documented with defaults, bounds, and format examples. The description adds no parameter-level meaning 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?

States a specific verb+resource: browsers ranked by pageviews. The enumerated categories (Chrome, Firefox, Safari, etc.) clarify the exact dimension being ranked. It doesn't explicitly distinguish itself from the other 'top_*' siblings (top_systems, top_pages, top_countries), but the resource name is 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?

No indication of when to use this vs top_systems, top_pages, top_countries, or get_overview. There is no context about the intended use case (e.g. audience analysis) and no exclusions or prerequisites.

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 are provided, so the description carries the burden alone, and it does disclose one genuinely useful behavioral detail: the 'XX' sentinel value returned for unknown countries. However, it says nothing about read-only semantics, result ordering beyond 'ranked', or how the lookback window bounds results.

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 that names the resource, the ranking metric, and the one output quirk, with zero filler. Nothing could be cut without losing 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?

For a simple read-only ranking tool with fully-described parameters and no output schema, the definition covers the essentials plus the 'XX' caveat. It falls short only on ordering/tie-breaking behavior and explicit sibling routing, which are minor gaps here.

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 both the limit cap (50, default 10) and the range window (max 90d, default 7d) are fully documented in the schema. The description adds no parameter-level detail, 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 a specific verb (ranked by pageviews) and resource (visitor countries), making the dimensional slice immediately clear. It is implicitly distinguishable from siblings like top_pages or top_browsers by the 'countries' dimension, but it never explicitly contrasts itself with 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools. An agent must infer from the name alone that this is the country-dimension counterpart to top_pages/top_browsers/top_sources.

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 are provided, so the description carries the full burden of behavioral disclosure, and it supplies almost nothing: no statement that this is a read-only listing, no mention of sort direction, pagination, or what a returned page record contains. Only the ranking metric ('by pageviews') is 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?

It is a single five-word fragment with zero padding, and the ranking metric is front-loaded. It is efficient, though the fragment form is terse to the point of being an incomplete sentence.

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 list tool with no annotations and no output schema, the description should at least say what is returned (page identifier plus views) and confirm it is a safe read. Against roughly twenty analytics siblings, this definition is too thin to let an agent call it confidently.

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% with clear descriptions and bounds for both limit (1-50, default 10) and range (max 90d, default 7d), so the schema does the heavy lifting. The description adds no additional syntax or format guidance beyond the schema, which matches the baseline for fully documented parameters.

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

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

The fragment 'Pages ranked by pageviews' names the resource (pages) and the ranking metric (pageviews), so the agent can infer a top-N listing. However, it is not a verb+resource statement and gives no scope qualifiers, leaving it just above vague. It does implicitly distinguish itself from siblings like top_sources and top_countries by naming pages.

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 on when to choose this tool over the many other top_* and analytics siblings, nor any stated prerequisites such as a required site/workspace context. The agent must infer usage entirely from the tool name.

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

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

No annotations are provided, so the description carries the full burden. It does disclose meaningful behavior in the attribution fallback chain (UTM source, else referrer host, else direct) and the ranking metric, which is real added value. However, it says nothing about read-only nature, response shape, or limits beyond what the schema states.

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 sentence with zero filler, front-loading the resource and appending the grouping rule and ranking metric. Nothing is redundant.

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 default-parameterized, read-only analytics aggregate with no output schema and no annotations, the sentence covers what the tool returns (ranked sources) and how sources are derived. Only minor gaps remain, such as how ties or direct traffic volume behave.

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% — both 'limit' (max 50, default 10) and 'range' (max 90d, default 7d) are fully documented in the schema. The description adds no syntax or semantics beyond that, 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?

States a specific resource (traffic sources), the ranking metric (pageviews), and the grouping rule (UTM source, else referrer host, else direct). That resource is inherently distinct from siblings like top_pages, top_countries and top_browsers, though the description never names them to make the distinction explicit.

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 when-to-use guidance, no prerequisites, and no routing to or away from alternatives such as top_pages or get_overview. The one-line description leaves the agent to infer the use case entirely from the title.

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 does add one genuinely useful data caveat — pre-tracking visits surface as 'Unknown' — which tells the agent how to interpret an unexpected category. However it says nothing about ordering guarantees beyond 'ranked', result size limits, or how the two params interact with the output.

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 tight sentences: the enumeration of categories is front-loaded and immediately useful for matching against a user's question, and the 'Unknown' caveat is a separate, non-redundant sentence. Nothing is padded.

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 aggregation with a fully documented schema and only two optional params, the description covers what the tool returns (ranked OS pageview breakdown) and a key interpretation caveat. It is missing explicit ordering/units detail, but a reader could invoke it correctly.

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

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

Schema description coverage is 100%: 'limit' (max 50, default 10) and 'range' (e.g. "24h", "7d", max 90d, default "7d") are fully documented in the schema already. The description adds no additional parameter meaning, so the baseline of 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 names a specific resource (operating systems) and the metric (ranked by pageviews), plus enumerates the exact categories returned. It's clearly distinguishable from top_pages/top_countries/top_browsers by dimension, though it never names those siblings or says 'the OS breakdown' explicitly as a routing cue.

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 when-to-use guidance at all — no indication of when an agent should pick top_systems over top_browsers, get_overview, or query_visits, and no mention of prerequisites or the default lookback behavior being appropriate for which questions.

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