PageLens Analytics

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

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's added value is the auth requirement (write key, member or higher), which is genuinely useful and not in the annotations. It doesn't state whether the annotation is editable, removable, or visible to other members, so not a 5.

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 zero waste. The action and its object lead, and the authorization constraint follows without 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?

For a 3-parameter, all-required mutation with no output schema, the description covers the action, the content, and the auth gate. It could still say whether the annotation can later be modified or deleted, but nothing critical to invoking it correctly is 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%: date carries its YYYY-MM-DD format and site_id points to list_sites, but text is undocumented. The description partially compensates by giving example annotation content (release, campaign, outage), clarifying what text should hold, but does not add format or sourcing detail for the other 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 specific verb and resource ('Mark a date on the charts') and grounds it with concrete examples (release, campaign, outage). No sibling tool competes for this job, so the purpose is unambiguous even without explicit sibling differentiation.

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 clear context for use (annotating releases, campaigns, outages) and states the access prerequisite: a write key plus member access or higher. It stops short of naming when NOT to use it or any alternative tool, so it falls short of a 5.

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

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

Annotations declare this is a non-read, non-destructive write. The description adds the auth requirements (write key, member access or higher), which is meaningful behavioral context beyond what the annotations provide. It stops short of describing side effects or the return 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 sentences, front-loaded with the action, followed immediately by the access prerequisite. No 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?

No output schema exists, and the description does not attempt to explain return values (fine). It covers the three goal types and the scroll threshold, plus auth. The main gap is the undescribed name parameter and any confirmation of what a successful creation returns.

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

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

With 60% schema coverage, the description compensates by explaining the type-specific role of threshold ('at least threshold percent (type scroll)'), clarifying that scroll goals drive threshold. The name parameter remains undocumented in both schema and description, so it is not fully complete.

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+resource (Create a goal) and then defines what a goal counts: sessions visiting a page, firing a custom event, or scrolling. This is richer than a tautology, though it never names a sibling to distinguish itself from (e.g., list_goals).

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

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

It provides a prerequisite (needs a write key and member access or higher), which is real usage context, but gives no explicit when-to-use or when-not-to-use guidance relative to list_goals or other create tools. Usage is implied rather than stated.

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

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

Annotations only signal destructiveHint=true; the description goes further by disclosing that deletion is permanent, exactly which data classes are destroyed (events, session replays, profile), and that a write key plus admin access are required. That is meaningful added context for an irreversible mutation.

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

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

Two short sentences, with the destructive scope front-loaded in the first clause and prerequisites second. No filler or repetition of the tool name.

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 2-parameter, no-output-schema tool, the description covers irreversibility, data scope, and authorization needs. It leaves open whether the deletion is synchronous or how confirmation of completion is surfaced, a minor gap given the tool's simplicity.

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 already documents both site_id (from list_sites) and the user_id / 'anon:<visitor_id>' format. The description adds no parameter-level detail beyond what the schema provides, 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 and resource ('permanently delete ... events, session replays and the profile of one user on a site') and enumerates the exact scope of deletion. This clearly distinguishes it from read-oriented siblings like get_user and list_users.

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?

Framing it as 'GDPR erasure' gives clear context for when to reach for this tool (compliance deletion for a single user), and it states the access prerequisites. It does not name an alternative or state when not to use it, so it 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. With no output schema, the description usefully carries the burden of describing return content — breaking out crawler reads vs live fetches vs human visits, purchases/revenue, and robots.txt access — which tells the agent what the result set contains.

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 front-loaded sentence with a dense but purposeful enumeration, and no filler. It is slightly list-heavy, but every element corresponds to a real returned dimension 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 no output schema, the description does the necessary work of summarizing the returned metrics and dimensions, and the schema fully documents the inputs. The one gap is the unresolved relationship to the get_bots_and_ai sibling, which an agent choosing between the two would still have to infer.

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 all seven parameters (dates, period, filters, timezone, segment_id, site_id) are documented in the schema itself. The description adds no parameter-level meaning beyond what the schema provides, 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 subject — how a site appears in AI assistants — and enumerates the metrics it returns (crawler reads, live fetches, human visits, revenue, robots.txt), so the resource is unambiguous. However, it never distinguishes itself from the sibling get_bots_and_ai, which appears to cover adjacent territory, leaving overlap unresolved.

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 or when-not guidance, and no alternatives are named. The closest sibling, get_bots_and_ai, is not referenced at all, so an agent cannot tell which tool to pick when both seem relevant. Usage is only implied by the topic.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). Beyond that the description adds essentially nothing: no note on how results are grouped, whether bot categories are aggregated, sampling, or limits. With annotations carrying the safety burden, the description should have contributed grouping/response context and does not.

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 compact sentence-fragment with zero filler, which is efficient, but the brevity comes at the cost of under-specification rather than being genuinely concise. Front-loading the topic is fine; the problem is that nothing else was said.

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

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

For a tool with seven parameters, a rich filter grammar, and no output schema, the description says nothing about what is returned, how traffic is categorized, or how the categories relate to the filters. The agent can invoke it from the schema alone, but the descriptive context needed to use it well is largely 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 description coverage is 100%, so the seven parameters (date range, period, filters with operator syntax, timezone, segment_id, site_id) are fully documented in the schema itself. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

The description identifies the resource scope (bot and AI traffic, broken into AI crawlers, AI assistants, search engines, and AI-referred human visits) but is a noun phrase with no verb, so the action (retrieve analytics?) must be inferred. It also never distinguishes itself from the sibling get_ai_visibility, which sounds closely related, leaving the agent to guess which one to pick.

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 any alternative tool. Nothing tells the agent when to call get_bots_and_ai rather than get_ai_visibility, get_overview, or get_breakdown.

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

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

Annotations already declare this as a safe, read-only, non-destructive query, so the safety profile is covered. The description adds that results come back as ranked values with visitor and session counts, a useful hint about shape, but says nothing about limit defaults, ordering, or empty-result 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 with no filler. The long parenthetical dimension list is slightly heavy but earns its place by enumerating supported dimensions.

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, so the description carries the burden of describing returns; it only gestures at 'visitors and sessions' without stating the row shape or ordering. Combined with 90% schema coverage on inputs, this is adequate but not fully complete for a 10-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?

Schema description coverage is 90%, so the schema itself documents parameters such as from/to, period, limit, filters, and timezone thoroughly. The description contributes no additional parameter meaning, which is the correct baseline when the schema does the heavy lifting.

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 (top values of one dimension) and enumerates the supported dimensions, so the resource is unambiguous. It does not differentiate itself from siblings like get_pages or get_events, which cover overlapping ground, 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?

Usage is only implied: the agent can infer it is the tool for ranked dimension breakdowns, but there is no explicit when-to-use guidance and no mention of when to prefer get_pages, get_events, or get_overview instead. Adequate but with a clear gap.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the safety profile is covered. The description adds useful shape about the return (grouped by message with occurrence/session/page counts), but says nothing about limits, permissions, or ordering. Adequate given the annotation coverage, not rich.

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

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

A single tight sentence that front-loads the resource and then the aggregation and output dimensions. No filler, no restatement of the name.

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 a fully described schema and annotations carrying the safety profile, the description gives enough to call the tool correctly and hints at the return shape in lieu of an output schema. Only the missing usage/alternative guidance keeps it from being complete.

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

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

Schema description coverage is 100%, so every one of the 8 parameters (dates, period enum, limit, filters syntax, timezone, segment) is already fully documented in the schema. The description adds no parameter meaning 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 verb and resource ('get ... JavaScript errors') and adds the aggregation grain plus the key output dimensions (occurrences, affected sessions and pages). It clearly stands apart from sibling breakdown tools, though it never names an alternative to contrast with.

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: nothing says when error reporting is the right call versus get_breakdown, get_events, or get_journeys, nor any prerequisite or exclusion. The agent must infer usage purely from the scope of the resource name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context about what is actually counted (tracked events and outbound clicks) but says nothing about result ordering, grouping, truncation, or what happens when a site has no events, so it adds only modest value beyond the annotations.

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

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

A single front-loaded sentence defining the two data families returned and the payload shape; there is no filler, hedging, or restatement of the name/title.

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

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

With no output schema, the description carries the burden of describing the return shape, and 'with counts and their properties' is only a hint. It does not clarify whether rows are grouped per event name, how outbound clicks are mixed with custom events, or how results are ordered, which matters for an 8-parameter analytics query whose schema is otherwise rich.

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 each of the 8 parameters (period/from/to interplay, filters syntax, limit cap of 100, site_id source, timezone, segment_id) is fully documented in the schema itself. The description contributes no parameter-level meaning, 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 (get events) and pinpoints the data source: custom events sent via pagelens.track plus outbound clicks, returned with counts and properties. That is materially clearer than a bare 'get events', though it never distinguishes itself from siblings like get_breakdown, which accepts an 'event' dimension and could return overlapping 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?

Usage is only implied: the phrase 'custom events ... and outbound clicks' tells the agent this is the analytics query for event data, but there is no explicit when-to-use, when-not-to-use, or named alternative. The overlap with get_breakdown (which lists 'event' as a filter dimension) is left unresolved, so the agent must guess.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds only the idea of 'most common' aggregation, but says nothing about how paths are ranked, truncated by limit, or computed over the selected period/segment.

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, and the core concept is front-loaded. It is arguably too terse for an 8-parameter analytical tool, but nothing in it 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?

With 8 parameters, no output schema, and an inherently structured return value (ordered path sequences), the agent is left guessing what a 'journey' row looks like. There is no mention of result shape, ordering, or how limit interacts with path depth.

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 all 8 parameters (date range, period, filters DSL, segment_id, site_id, timezone, limit) documented in the schema itself. The description contributes no additional parameter meaning, 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 the resource and its scope precisely: 'page-to-page paths visitors take,' which tells an agent this returns aggregated navigation sequences rather than raw page metrics. It does not name any sibling (e.g. get_pages, run_funnel, get_breakdown) to differentiate the tool, so it falls short of a 5.

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

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

There is no when-to-use guidance and no alternatives named. An agent cannot tell from this sentence why it would call get_journeys instead of run_funnel or get_breakdown for related path/flow questions. Only the implied 'journey analysis' context is present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context not in the annotations: results are compared against a previous period of equal length and a time series is included. It does not cover defaults, limits, or payload size.

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 resource and then enumerates the returned metrics inside a tight parenthetical. Zero filler and no repetition of the tool name.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so by listing the metrics, the period-over-period comparison, and the optional series. Default period and series behavior live in the schema, so the description is complete enough for correct invocation, though it could say more about what the comparison output looks like.

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 every parameter (period, from/to, filters, timezone, segment_id, include_series) is already fully documented in the schema. The description adds no parameter-level detail such as date precedence or filter syntax, 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 specific resource (headline metrics) and enumerates exactly which metrics are returned, plus the period-over-period comparison and time series. An agent can tell it is a summary/overview tool rather than a detailed breakdown, but it never contrasts itself with siblings like get_breakdown, get_pages, or get_realtime.

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 when-to-use or when-not-to-use guidance and no named alternative. The metric list implies a high-level summary role, but the agent must infer on its own whether to reach for this tool versus get_breakdown, get_pages, or get_realtime.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds the concrete return dimensions (visitors, pageviews, entries, bounce rate, time on page), which is useful, but says nothing about pagination, row caps, or how filters interact with segments.

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. It is efficient, though it is arguably too terse for an 8-parameter tool rather than being genuinely concise.

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 8 parameters and no output schema, the description does list the metrics an agent will receive, which partially compensates. But it omits usage context and sibling differentiation, leaving gaps for a tool this configurable.

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 schema documents dates, period enum, limit, filters syntax, timezone, and segment_id in detail. The description adds no parameter-level information beyond the schema, so the baseline 3 applies.

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

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

The description names the resource (pages) and enumerates the metrics returned, so an agent knows it retrieves per-page analytics. However, it never states the action or scope in verb form and gives no signal distinguishing it from siblings like get_breakdown or get_overview, which plausibly return overlapping 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?

There is no when-to-use guidance, no mention of prerequisites (e.g., site_id must come from list_sites), and no exclusions pointing to alternatives. The agent must infer usage entirely from the name and the metric list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds the freshness window (last 5 minutes), which is real behavioral context, but says nothing about refresh cadence, result size, or return shape for a realtime feed.

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

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

A single tight sentence with the scope and time window front-loaded and no filler. Every clause carries 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, single-parameter read tool with annotations covering the safety profile and the schema documenting the parameter, the description covers the essentials (who, when, what they're viewing). Minor gap: no hint at the structure of the realtime response, though no output schema exists to carry it.

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

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

Only one parameter (site_id) and schema coverage is 100%, with the schema pointing to list_sites for discovery. The description adds no format or constraint detail 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 (visitors online) plus the scope qualifier (last 5 minutes) and the payload ('what they are viewing'). This is clearly distinguishable from static reporting siblings like get_overview or get_pages, though it never names an alternative.

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

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

The 5-minute window implies a realtime-monitoring use case, but there is no explicit when-to-use, when-not, or comparison to siblings such as get_overview, list_sessions, or get_session. An agent must infer that this is the live-traffic tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the metric definition (share of cohort returning in later periods) and the identify scope, which is meaningful context. However, it doesn't disclose granularity limitations, minimum cohort size, or return format.

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

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

Single sentence, front-loaded with the core concept and metric definition. No wasted words. Could be slightly richer but is efficient for its scope.

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 analytics tool with no output schema, the description covers the metric but omits the shape of the return (cohort matrix? time series?), defaults for unit/timezone, and any constraints on data availability. An agent can call it, but won't fully know what to expect back.

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% – site_id and timezone have descriptions, but 'unit' (enum day/week) has no schema description. The description implies daily/weekly cohorts via 'daily or weekly cohort,' which compensates for the unit enum, but doesn't clarify defaults or how timezone interacts. Baseline 3 is appropriate given partial coverage.

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

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

The description states a specific verb+resource: cohort retention analysis for identified users, with the metric definition (share of cohort that returned in later periods). It clearly distinguishes from siblings like get_overview or get_breakdown, though it doesn't explicitly name an alternative. The qualifier 'identified users (pagelens.identify)' is useful scoping.

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. The description doesn't say when to pick this over get_overview, get_breakdown, or list_users, nor does it mention prerequisites like needing identified users via pagelens.identify. An agent must infer context from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds two genuinely useful behavioral facts beyond the schema: the data is only available "when connected" (an integration/availability prerequisite) and lags about 2 days, which materially affects date-range expectations. It stops short of noting pagination or response 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 sentences with zero filler: the first front-loads what data is returned and at what grain, the second delivers the freshest-operating constraint (2-day lag). Nothing is repeated from structured fields.

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

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

With no output schema, the description carries the return-value burden and does reasonably well by naming metrics, dimensions and the daily series. It does not describe pagination behavior or how limit/default 10 shapes the response, which is a minor residual gap for a 10-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?

Schema description coverage is 90%, so the schema already documents dates, period, limit, filters, timezone and segment_id in detail. The description's mention of "by query, page, country or device" and the daily series loosely maps to the dimension parameter but adds no syntax or default information 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?

States a specific verb/resource — Google Search Console data for a site — and enumerates the metrics (clicks, impressions, CTR, average position) and breakdown dimensions (query, page, country, device) plus a daily series. This clearly separates it from generic analytics siblings like get_breakdown or get_pages, though it never names a 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?

"when connected" implies a precondition and the scope is clear, but there is no explicit when-to-use vs. alternative guidance (e.g. when to prefer this over get_breakdown / get_pages for the same site). Usage is only inferable from the metric list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, so safety is covered. The description adds one genuine behavioral trait beyond that — the results are returned 'in order' — but says nothing about volume limits, pagination, or what happens with an invalid session_id.

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 short sentence with no filler, and the key scoping fact (one session) is front-loaded. It is efficient, though the terse noun-phrase style makes it feel more like a label than an instruction.

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 sketch the return payload (pageviews plus events, ordered), which is the minimum an agent needs. It still omits permissions, result limits, pagination, and how ordering is defined — notable gaps for a retrieval tool with no annotations about output shape.

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

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

Schema description coverage is only 50%: site_id carries a hint ('Site id from list_sites') but session_id is completely undocumented. The description offers no parameter information at all, so it does not compensate for the gap in the schema.

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

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

The phrase 'Every pageview and event in one session' clearly states the resource returned and scopes it to a single session, which distinguishes it implicitly from list_sessions and get_events. It lacks an explicit verb and never names a sibling, so differentiation is left to inference 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?

There is no when-to-use guidance, no prerequisite (e.g., needing a session_id from list_sessions), and no comparison against get_events or list_sessions. An agent must guess the boundary between this tool and its closest siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description's contribution is the shape of the returned profile (traits, first/last seen, totals, sessions), which is useful but does not address pagination, missing/unknown users, or whether sessions are truncated.

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

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

A single tight sentence with the resource and payload front-loaded and no filler. It stops short of being maximally informative, but 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?

With no output schema, the description does carry the burden of describing returns and does so partially (profile fields plus sessions). It remains incomplete on the undocumented user_id parameter and on edge behavior for unknown or non-identified users.

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%: site_id is documented in the schema ('Site id from list_sites') while user_id has no schema description. The description says only 'one identified user' and adds no format, source, or constraint for user_id, so it fails to compensate for the coverage gap.

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

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

Names the resource precisely ('one identified user') and enumerates the payload (traits, first/last seen, totals, sessions), which implicitly separates it from list_users (many users) and get_session (one session). It lacks an explicit verb, but an agent can tell what it fetches.

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

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

Usage is implied by 'one identified user' plus the required user_id, but there is no explicit statement of when to prefer this over get_session or list_users, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the data is field data 'from real visitors', distinguishing it from lab/synthetic measurements, and it discloses the percentile aggregations returned.

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 with zero filler; the resource is front-loaded and every clause (metrics, percentiles, granularity) carries information an agent needs.

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, but the description compensates by stating what is returned — the specific metrics at p50/p75/p90, overall and per page. Combined with full schema coverage and read-only annotations, this is nearly complete; only pagination or result-size behavior 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%, so all seven parameters (site_id, from/to, period, filters, timezone, segment_id) are already documented in the schema with defaults and format syntax. The description adds no parameter-level detail, 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?

Names a specific resource (Core Web Vitals), enumerates the exact metrics (LCP, INP, CLS, FCP, TTFB), and states the aggregation (p50/p75/p90, overall and per page). No sibling tool covers this data, and the metric/percentile detail makes it unambiguously distinguishable from get_pages 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?

Usage is implied — an agent can infer this is the performance/RUM tool — but the description never states when to reach for it versus get_overview, get_pages, or get_breakdown, nor any exclusions. Adequate but with a clear routing gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world access, so safety is covered. The description adds one genuine behavioral fact beyond that: results are compared against the previous period. It says nothing about pagination, result limits, or what an empty goal set returns.

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 no filler, and the comparison scope is placed where it matters. It reads as a fragment lacking an action verb, which slightly weakens front-loading versus a fully formed leading clause.

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 100% schema coverage and annotations carrying the safety profile, the description only needs to add what the structured fields do not: the comparative output behavior. That is present, and no output schema exists to require return-value explanation, so the remaining gap is minor.

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 seven parameters including the filter operator syntax, timezone, and segment_id are already fully documented in the schema. The description contributes no additional parameter meaning, which matches the baseline 3 for a fully-covered 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 names the resource (goals) and the metrics returned (conversions and conversion rate), plus the comparison scope, so an agent knows what it gets. It stops short of an explicit verb or sibling differentiation, though the contrast with create_goal is reasonably obvious from the name.

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 mention of prerequisites or alternatives. An agent must infer from the name and sibling set that this is the read path for goal reporting, and there is no routing hint toward create_goal or add_annotation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds useful framing about what a segment is and how segment_id is consumed downstream, but says nothing about scope (per-site), ordering, or pagination.

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

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

One sentence, front-loaded with the resource and free of filler. It is efficient, though it spends its words on defining the concept rather than stating the operation, which is a small structural miss.

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

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

A simple one-parameter read tool whose annotations cover safety, so requirements are low. However, with no output schema, the description should ideally say it returns a list of segments (with their ids) for the given site — that return expectation is left implicit.

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 site_id parameter is documented as 'Site id from list_sites', so the schema carries the load. The description never mentions site_id or the per-site scoping of results, adding nothing beyond the schema — baseline 3.

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

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

Names the specific resource (saved segments) and defines what it is with concrete examples ('Paid traffic', 'Mobile in Germany'), which lets an agent distinguish it from sibling lists like list_goals or list_sites. It never states the action verb explicitly (that it returns the collection), but the resource 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?

The clause 'can be applied to any report with segment_id' explains downstream usage of segments rather than when to call this tool versus alternatives. No condition, prerequisite, or sibling tool is named, so the agent gets no 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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the returned field list, which is genuinely useful context, but says nothing about pagination, ordering, or how 'recent' is bounded beyond the schema's period/limit defaults.

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

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

A single tight sentence with no filler and no redundancy. It is marginally less front-loaded than ideal since it enumerates outputs rather than leading with the action, but nothing 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 list tool with no output schema, the field enumeration partially compensates for the missing return documentation, and the schema covers most parameters. Still missing is routing guidance versus get_session and any note on ordering or result volume, leaving clear 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 description coverage is 90%, with defaults, ranges and filter grammar already documented in the schema, so the schema does the heavy lifting. The description contributes no parameter meaning beyond what is structured, making baseline 3 appropriate.

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

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

The name plus the phrase 'Recent sessions with entry/exit page, pages viewed, duration, source, location and device' makes clear this returns a list of sessions and enumerates the fields returned. However, it never distinguishes itself from the singular sibling get_session, so an agent must infer whether to use list vs get.

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 statement of when to use this tool, no prerequisites, and no mention of adjacent alternatives such as get_session, get_journeys, or get_realtime. The agent gets the what but not the when.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that results are permission-scoped and include a 24-hour visitor metric, which is genuine return-context, but it says nothing about pagination, result limits, or formatting.

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 no filler; the resource and its scope plus the key metric are front-loaded. 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 parameterless read-only listing tool with annotations covering safety and no output schema, the description is nearly sufficient. The only gap is the absence of any return-shape hint such as result count or pagination, which is minor 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?

The tool takes zero parameters, so the schema baseline of 4 applies. There are no argument semantics the description needs to compensate for.

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 (List) and resource (websites), and adds scope ('this key can access'), which cleanly separates it from sibling list tools like list_goals, list_segments, and list_users. It does not explicitly name alternatives, but the resource 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?

Usage is only implied: the tool is an enumeration of accessible sites, so an agent can infer it is the entry point for discovering site scope. There is no explicit when-to-use, when-not-to-use, or alternative named among the many sibling get_*/list_* tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, covering the safety profile. The description adds return-shape context (traits, sessions, pageviews, first source), but says nothing about pagination behavior, total counts, or ordering. Some added value over annotations, but not rich.

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 that front-loads the resource and scope. Every clause earns its place by describing returned content; nothing is padded, though the trailing list of returned fields makes it slightly 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?

With no output schema, the description usefully sketches the return shape (identified vs anonymous, sessions, pageviews, first source), and schema coverage is high for the 10 parameters. Only minor gaps remain, such as pagination and result ordering.

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 90%, so the schema already documents nearly every parameter, including date, kind, limit, period and filter syntax. The description's 'identified users (with traits)' loosely maps to the kind enum but adds no syntax or format detail beyond the schema. 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 (list) and resource (users) and adds scope: 'active in the period'. It even enumerates the returned entities (identified users with traits, anonymous visitors with sessions/pageviews/first source), which cleanly separates it from the singular get_user. It does not name a sibling explicitly, so it falls just short of a 5.

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

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

Usage is implied by 'active in the period' plus the kind enum (all/identified/anonymous), but there is no explicit when-to-use vs get_user/list_sessions guidance and no stated exclusions. Adequate context without routing help.

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 read-only, non-destructive, closed-world behavior. The description adds meaningful behavioral context about how steps are evaluated (page, event, scroll threshold), how modes differ, and that compare_previous runs the same funnel over the previous period. It stops short of describing return structure or authentication/rate-limit behavior.

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

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

The description is compact and front-loaded: it states the tool's purpose first, then step semantics, then mode options and compare_previous. Every sentence adds actionable information without repetition 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 10-parameter analytics tool with no output schema, the description covers the essential behavior: what the funnel computes, valid step types, mode differences, and previous-period comparison. Annotations and schema cover safety and most parameter details. Some minor return-shape details are omitted, but they are not critical for correct invocation.

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

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

With 70% schema description coverage, the description fills important gaps: it explains mode enum meanings, step types and wildcard support, scroll threshold semantics, and compare_previous behavior. Other parameters such as filters, period, and timezone are already documented in the schema, so the description appropriately avoids restating them.

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 a specific analysis: 'Conversion funnel: how many sessions completed each step.' It defines what a step is and outlines modes, so the agent knows the resource and operation. However, it does not explicitly distinguish this tool from similar siblings such as get_journeys or get_retention.

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

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

Usage is implied by the funnel description and the explanation of ordered/strict/flexible modes. There is no explicit guidance on when to choose run_funnel over sibling tools, nor any stated prerequisites or exclusions.

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