invisit

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds operational behavior beyond that: rows past limit are silently dropped, the 200 cap is hard, and a single higher-limit call is preferable to two calls. It does not describe what a row looks like or how detail affects volume beyond the schema's own note.

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 the verb and scope, then the alternative datasets, then the operational caveat. The dimension enumeration is dense but every item is load-bearing for enum selection; no filler sentences or restated title material.

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, the description covers dimension choice, filter composition, time-window defaults, truncation behavior and the special event_properties pairing. The remaining gap is the return shape (value column plus visits/metric columns and how detail changes columns), which the agent must 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 91%, so parameters are already well documented and the baseline is 3. The description adds some mapping value by expanding enum names into human concepts ('sources' = traffic sources or UTM campaigns, 'pages' = all/entry/exit) and by tying event_name to event_properties, but it repeats schema content on filters and limit rather than extending it.

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 ('Ranks one dimension by visits over a window') and then enumerates the concrete dimension families (pages entry/exit, sources, geo, devices, outbound clicks, custom events) so an agent can map intent to a dimension value without trial and error. It is clearly distinct from siblings like get_overview and get_timeseries, which return aggregates over time rather than per-value rankings.

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 concrete routing guidance: use filters to produce segmented breakdowns with a worked example, and switch dimension to crawlers/links/event_properties for the non-visit datasets. It also warns to raise limit instead of double-calling. What it lacks is explicit when-not-to-use guidance naming the sibling tools (e.g. use get_overview for totals or get_timeseries for trends).

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 readOnly, idempotent, closed-world, non-destructive behavior, so the description only needs to add the non-obvious constraint — that results depend on the heatmaps tracker feature being enabled and that get_site is how you verify it. It also characterizes the returned metrics (rage clicks, dead clicks, scroll-depth percentages), which annotations do not cover. It doesn't mention empty results when the tracker is off or any data-retention caveats.

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 the purpose, then the two result modes, then the prerequisite. Every clause carries information an agent needs before calling; there is no restatement of the name or 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 9 parameters, no output schema, and high schema coverage, the description does its main job: it describes what comes back in each mode and discloses the feature-flag prerequisite. Minor gap — it doesn't note that output is a ranked, limit-capped list or what an empty result means when the tracker is disabled.

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 89%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: it explains that page_path acts as a mode switch that changes the entire result shape, whereas the schema only says 'e.g. /pricing'. Hostname is contextualized as only relevant with page_path when a site serves several hostnames. Limit, device, and the date/period interplay are left to 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?

States a specific resource (click positions and scroll depth) with a verb-like framing and then splits behavior into two explicit modes keyed on page_path: page ranking with rage/dead clicks and scroll depth, versus per-page element ranking with CSS selectors and 25/50/75/100% reach buckets. That level of specificity makes it unmistakable against siblings like get_link_clicks or get_breakdown.

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 when-to-use rule for each mode ('Without page_path...', 'with page_path...') and a prerequisite: the heatmaps tracker feature must be enabled, checkable via get_site. It stops short of explicitly steering away from related siblings (e.g., link clicks or general breakdowns), so it's strong context rather than full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavior: results are reported over a window and against the previous equivalent window, which the agent would not know from annotations or schema. It does not state response shape or how the comparison is expressed, which slightly limits it.

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

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

Two sentences, both load-bearing: the first front-loads the capability and the per-link vs split-by-dimension dichotomy, the second routes site-traffic queries elsewhere. No filler, and the enumeration of dimensions mirrors the enum without wasting 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 an 8-parameter, read-only analytics query, the description covers scope, comparison behavior, and the link_id/by interaction, with the schema handling formats, defaults and bounds. The notable gap is the return shape: with no output schema, the agent cannot tell how the previous-window comparison is represented in the response.

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 baseline is 3. The description goes beyond it by explaining the interaction between link_id and by — omit link_id for all links, supply it to split one link by referrer/country/device/etc. — which the per-property schema text does not make explicit.

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 verb+resource (clicks and visitors on short links) plus the two output shapes: per-link rows, or a single link split by a chosen dimension. It also explicitly disclaims site-traffic reporting and points to get_overview/get_breakdown, so an agent can separate this from its closest siblings 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?

Gives clear routing context: use this for link clicks, not for site traffic, which lives in get_overview and get_breakdown. It also implies the by/link_id combination for drilldowns. It stops short of naming alternatives like get_timeseries or criteria for choosing among the remaining click-related views, so no explicit when-not beyond the site-traffic exclusion.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: every metric is compared against the previous window of equal length, and detailed mode expands the payload at token cost. Filter/timezone semantics are left entirely to the schema.

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

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

Two tight sentences: the metric list comes first, then the detail-mode expansion and the 'most questions in one call' framing. No filler, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description carries the burden of describing return values, and it does so by enumerating the headline metrics and the extra detailed-mode dimensions. The seven-parameter surface (filters, period/from/to, timezone) is only covered by the fully documented schema, so the description is adequate but not self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does enrich the 'detail' parameter by spelling out what 'detailed' actually returns (top 5 pages, sources, countries, devices), which goes beyond the schema's vague 'adds columns and splits', but it says nothing about period, filters, or timezone handling.

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 exact metrics returned (visits, pageviews, events, bounce rate, visit duration, pages per visit) and frames the tool as the headline summary, which implicitly separates it from the drill-down siblings like get_breakdown and get_timeseries. It also states that 'detailed' adds top-5 pages, sources, countries and devices, so an agent can tell what the tool covers without opening the 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?

It gives a clear usage signal: this answers most 'how is the site doing' questions in one call, implying it is the default entry point rather than a drill-down tool. It also contrasts concise vs detailed on cost/coverage. It does not explicitly name alternatives (e.g., when to prefer get_breakdown or get_timeseries), so it stops short of full when/when-not 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context by defining the recency window and enumerating the content of the response, which helps an agent recognize this as a low-cost snapshot rather than a full report. It stops short of stating the exact window length or any result caps.

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 scoping constraint ("last few minutes") followed by the returned dimensions. Every clause carries information and there is no filler.

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

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

With no output schema, the description does the work of telling the agent what comes back, and it covers that well for a one-parameter read tool. The main residual gap is the imprecision of "last few minutes" and no mention of result limits, but nothing essential to invoking 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 coverage is 100% and the single site_id parameter already documents that a name, slug or domain resolves in addition to the ID from list_sites. The description adds nothing about the parameter, 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 and scope: current visitors, described as "who is on the site in the last few minutes," and enumerates the dimensions returned (active visits, top pages, countries, devices, latest events). This clearly separates it from historical siblings like get_timeseries or list_visits, though it never names an alternative directly.

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 "last few minutes" framing implies this is the tool for live monitoring rather than historical analysis, which is enough for an agent to infer intent. However, there is no explicit when-to-use statement, no excluded cases, and no pointer to a sibling for longer ranges.

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 is a read-only, idempotent, non-destructive operation, but the description adds important context beyond them: the requirement for a connected payment provider, the paid-plan gate on transactions, the reporting currency, and the comparison against the previous window. It still does not discuss rate limits or transaction pagination behavior, so it is not exhaustive.

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

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

The description is three tight sentences: metrics and currency first, show-mode behavior second, prerequisite and plan gate last. Every sentence adds useful information and there is no redundant restatement of the tool name or annotations.

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 so by naming the metrics, charge counts, prior-window comparison, and currency. It also covers the payment-provider prerequisite and paid-plan limitation. Minor gaps remain around transaction pagination and exact summary output shape, but an agent has enough to call it correctly.

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

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

Schema description coverage is high at 86%, so the schema already documents most parameters. The description adds meaning beyond the schema by explaining the distinct return behavior of show=daily and show=transactions, which the enum alone does not convey.

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 exact revenue metrics returned (gross, refunds, fees, net, charge counts, change vs previous window) in the site's reporting currency, making the tool's purpose clear. It does not distinguish itself from siblings such as get_overview or get_timeseries, 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?

The description explains the show modes (daily for per-day net revenue, transactions for latest charges/refunds/disputes) and states prerequisites such as a connected payment provider and paid plan for transactions. It does not say when to choose this tool over sibling tools like get_overview or get_breakdown, leaving alternative selection implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value by disclosing a time window ('events refused in the last 24h and why') and the breadth of returned configuration, but the phrase 'alerts and their channels (with manage)' is ambiguous and nothing is said about permissions, response size, or nesting.

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 no filler: a dense but purposeful content list followed by the diagnostic use case. The enumeration is long but each item is information an agent needs to know the response covers, and the usage cue is short and clear.

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 return content, and the enumeration largely does that — including diagnostic-relevant signals (data arrival, refused events). Minor gaps remain around what 'with manage' means and whether alerts are writable from here, but an agent can call this correctly and interpret the result.

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

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

There is exactly one parameter, and schema coverage is 100% — the schema itself says 'site_id from list_sites, or the site name.' The description adds no syntax, format, or lookup guidance beyond that, so the baseline 3 applies; the schema does the work here.

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 and scope ('One site's configuration and health') and enumerates the concrete contents: allowed domains, refusal counts, currency, tracker features, alerts, install snippet. That enumeration clearly distinguishes it from the report siblings (get_overview, get_timeseries, run_funnel), though it never names an alternative 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?

It gives an explicit triggering condition: 'Use it to diagnose missing data before reading reports,' which routes the agent here ahead of the analytics siblings. It stops short of stating when not to use it (e.g. for listing all sites, use list_sites, or for metrics, use the report 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 the safe read-only, idempotent profile, so the description is free to add context: the response includes timeline annotations that fall inside the window, and supplying event_name changes the returned series to that event plus conversions. That is genuine output-shape information beyond the structured fields, though default interval and timezone behavior are left to the schema.

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

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

Three short sentences, front-loaded with what is returned, followed by use case and then the alternate mode. No filler or 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?

For an 8-parameter read tool with no output schema, the description covers purpose, bucket granularity, window semantics implicitly, and the event_name variant. Filters and timezone handling are only in the schema, but since their descriptions are complete, nothing critical 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 coverage is 100%, so every parameter already carries its own description; the description only echoes interval choices and the existence of event_name. Its one real addition is that event_name returns conversions per bucket rather than plain visits, which the schema does not say. Baseline 3 applies since 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 resource and metric (visits and pageviews) plus the bucket granularity (hour/day/week) over a window, which is enough to distinguish it from aggregate tools like get_overview. It never names a sibling, so the boundary versus get_breakdown or get_heatmap must be inferred.

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 it to find when something changed" gives a clear investigative use case, and the event_name clause explains the alternate mode of operation. There is no explicit when-not guidance or named alternative for drill-down vs. breakdown queries.

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 is a read-only, idempotent, non-destructive query, so the description does not need to repeat that. It adds real value by disclosing that the data is real-user (field) data, that values are reported at a percentile with good/poor sample shares, and that `by` vs. `over_time` change the shape of the result. It does not mention pagination or row caps beyond what the schema says.

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 dense sentence that leads with what the tool returns and then covers mode selection; no filler or repetition. The nested clauses ('set by ... or over_time ...') make it slightly harder to parse than it needs to be.

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 10 parameters, no output schema, and no nested objects, the description does a reasonable job sketching the returned content (percentile value, good/poor share, ranked or time-bucketed rows). It leaves defaults (p75, 30d) and the from/period interaction to the schema, which is acceptable, but an agent gets no explicit note that by and over_time are mutually exclusive modes.

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 90%, so the schema carries most parameter meaning. The description still adds non-obvious semantics: `by` ranks instead of returning the summary, `over_time` yields one metric per day bucket, and the percentile framing explains what the returned number means. That is meaningful added meaning beyond the per-parameter strings.

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 (real-user Core Web Vitals: LCP, INP, CLS, FCP, TTFB) and states what is returned (a percentile value plus the share of good/poor samples). It also distinguishes its two output modes (ranked `by` vs. per-day `over_time`). It never explicitly contrasts itself with siblings such as get_breakdown or get_timeseries, 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?

It gives genuine mode-selection guidance: use `by` to rank pages/countries/browsers for one metric, or `over_time` to see when a metric changed. It does not say when to prefer this tool over the 17 siblings (notably get_breakdown and get_timeseries), nor when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing that the default view is scoped to the published version while the by-id view exposes all versions. It does not address pagination, auth requirements, or how archived rules interact with the result set.

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 first establishes what event rules are, the second delivers the mode semantics. Nothing is repeated from the schema and 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 read-only two-mode listing tool with no output schema, the description conveys the shape of results reasonably well (rules plus versions). However, it leaves include_archived undefined and gives no hint of result limits or ordering, so an agent could call it correctly but not fully predict the response.

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 site_id is described), so the description must compensate. It does explain event_rule_id's effect in mode terms, but says nothing about include_archived, which is undocumented in both schema and description — a real gap for a filtering flag.

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 (event rules) and what they are ('turn clicks, form submits and page views into named custom events without code'), then says precisely what the call returns in each mode. It is specific enough to distinguish from siblings like list_links or list_visits, though it never names those siblings 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?

It gives a clear conditional: omit event_rule_id to list rules with their published version; supply it to expand every version and its rules. That is genuine when-to-use guidance for the one ambiguous parameter. It stops short of exclusions or pointing at any alternative 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes ordering ('newest first') and the shape of returned rows, which is genuine added value. It says nothing about pagination behavior or whether a truncated result set is signalled, which is the main remaining behavioral gap for a list tool capped at 100 rows.

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 compact sentence with the resource front-loaded and no filler. It reads as a noun phrase rather than a complete statement, but every clause (source, ordering, returned fields) 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?

There is no output schema, so the description usefully enumerates the returned columns and the sort order. With only four fully documented parameters and complete annotation coverage, the definition is sufficient to invoke the tool correctly; only pagination semantics are 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 all four parameters (limit, search, status, site_id) are already documented, including the enum values and the site_id resolution hint. The description adds no parameter-level meaning beyond the schema, 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 ('messages visitors sent through the feedback widget') and adds scope details: ordering ('newest first') and returned fields ('id, status and the page'). It is clearly distinguishable from siblings such as list_visits or list_links, though it never states an explicit verb like 'List' and doesn't name an alternative.

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

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

There is no when-to-use guidance and no mention of alternatives or exclusions (e.g. when to use list_feedback vs. other visitor-data tools). Usage is only inferable from the resource name, so the agent must guess the context in which this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description earns credit for disclosing the payload shape — setup stage and any still-missing DNS records per domain — which is genuinely useful behavioral context for a tool with no output schema.

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

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

One compact sentence with no filler, and the most useful detail (missing DNS records) is present. It is a sentence fragment lacking a main verb and reads more like a return-value blurb than a lead statement, which slightly weakens front-loading.

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

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

For a one-parameter read tool with no output schema, the description covers what is returned (domains plus setup stage and outstanding DNS records) well enough to set expectations. It stops short of saying whether all site domains are returned and whether results are ever empty or paginated.

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 fully documented in the schema, including that it accepts a name or an ID from list_sites. The description adds nothing further about parameters, 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 identifies the resource precisely — custom short-link domains, contrasted with the default go.example.com — but it is a noun phrase with no verb, so the listing action is only implied by the tool name. It does implicitly separate this from list_links and list_sites, though it never names 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 mention of prerequisites (e.g., needing a site_id first), and no steering toward or away from sibling tools such as list_sites or list_links. Usage must be inferred from the name and the single site_id parameter.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered newest first and the click figures are constrained to a 30-day window, which prevents misreading the metric as lifetime totals.

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 filler, and the highest-value facts (scope, ordering, metric window) are front-loaded before the search semantics.

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

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

For a read-only list tool with no output schema, the description covers scope, sort order, metric window and search behavior. It could still note that limit is the only pagination control (no cursor/offset), but nothing essential to a correct call 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 coverage is 67%, with 'search' carrying no schema description at all; the description fills that gap precisely by stating it matches slug, title or destination. site_id and limit are already documented in the schema, so the description adds value exactly where it was missing.

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

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

Names a specific resource ('the site's tracked short links') and adds distinguishing scope: newest-first ordering and clicks scoped to the last 30 days. It doesn't explicitly contrast itself with siblings like get_link_clicks or list_link_domains, but the resource is unmistakable.

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

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

There is no when-to-use or when-not-to-use guidance. An agent must infer that this is the enumeration tool versus get_link_clicks (per-link click data) or list_link_domains, and nothing states prerequisites or what to do when the result is empty or exceeds limit.

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 readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely new context: results are scoped to sites the caller can read, and the returned ids are the shared key consumed by other tools. It says nothing about result size or ordering, which keeps it below 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 short sentences, zero filler, with the call-ordering advice placed last as the actionable takeaway. 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, but the description conveys the return value's key content (readable sites and their ids) and the call-ordering expectation, which is sufficient for a no-argument list tool. Only pagination or result-size guidance is missing, a minor gap.

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 baseline of 4 applies; there is nothing for the description to disambiguate. It does at least make clear that no site identifier needs to be supplied to call it.

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 (list sites) plus the payload — 'the id every other tool takes' — so the agent knows what it gets back. It implicitly separates itself from get_site and list_workspaces, though it never names them, so it falls short of full 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?

'Call this first unless you already know the id' gives an explicit ordering rule and the condition under which to skip it. It does not name the alternative tools (get_site, list_workspaces) that an agent might otherwise reach for, so it stops 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 already establish read-only, non-destructive and idempotent, so safety is covered. The description adds real behavioral context beyond that: results are ordered newest first, cursoring via next_cursor walks toward older visits, and visit_id retrieves a visit 'at any age' regardless of window. It does not discuss rate limits or response size, but the ordering and pagination semantics are the important disclosures.

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 core capability is front-loaded in the opening clause ('Drill below the aggregates'), followed by a compact enumeration of returned fields and a short pagination note. The main sentence is dense and long, but every clause carries information an agent needs to choose a mode.

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 eight parameters and no output schema, the description has to convey what comes back, and it does: per-visit landing/exit, source, country and device for lists, and pages, events and referrer for a single visit. Both invocation modes are covered, so an agent can call it correctly without further documentation.

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 88%, so the baseline is 3. The description still adds meaning the schema does not spell out, notably that visiting by visit_id is not bound to the date window ('at any age') and that the cursor exists specifically to fetch older visits. The from/to/period interplay is left to the schema, which already documents the override.

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

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

The description states a specific verb and resource ('the visits that started in a window, newest first'), and it explicitly positions the tool below the aggregates, which separates it from siblings like get_breakdown, get_overview and get_timeseries. It also names the record-level fields returned (landing/exit, source, country, device) and the second mode keyed by visit_id.

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

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

It gives a concrete selection cue: use this when the question is 'what did people from X actually do', i.e. when aggregate breakdowns are not enough. The two modes (window listing vs single-visit drilldown via visit_id) have clear triggers. It stops short of explicit when-not guidance or naming a sibling alternative by 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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds real value beyond that: it discloses the returned shape (members with roles, plus open invitations) and that all mutation paths live in the dashboard, so an agent knows this tool can never change membership.

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 filler. The read scope is front-loaded and the dashboard-mutation boundary follows immediately; 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, no-output-schema read tool this covers what an agent needs: what is returned, which scope it applies to, and that writes are impossible here. A brief note on ordering, pagination, or behavior for a large workspace is the only thing missing, and it 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% and the single 'workspace' parameter is documented as name, slug or id with a default of the only workspace, so the schema carries the semantics. The description only implies scoping ('one workspace') without adding format or default behavior beyond what the schema states, which is the baseline-3 case.

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 ('the people in one workspace with their roles') plus the secondary payload ('invitations still open there'), which lets an agent distinguish it from list_workspaces and from the analytics siblings. It omits an explicit verb like 'list', but the noun phrase and title make the operation 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 second sentence usefully excludes mutations ('Members, roles and invitations are changed in the dashboard'), telling the agent not to look for write capability here. However, it never names an alternative tool or states the condition for calling it, e.g. how it relates to list_workspaces or when to prefer this over fetching a workspace object.

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

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

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful scope by saying results are limited to workspaces the user belongs to and include the user's role, but it does not describe pagination, ordering, 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?

Two short sentences with no wasted wording; the first front-loads what the tool returns, and the second is a useful cross-reference to list_sites.

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 zero-parameter list tool, the description says what is returned and cross-references list_sites. Missing pagination or ordering details are minor given the low complexity and annotations.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately does not need to explain parameter usage.

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

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

The description clearly identifies the resource as the workspaces the caller belongs to and adds that each includes the caller's role, and it explicitly distinguishes itself from list_sites. It stops short of fully distinguishing from list_workspace_members or stating an explicit verb, so it is strong but not perfect.

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 implies usage by scoping results to the caller's own workspaces and points to list_sites for site-level data. However, it gives no explicit when-not guidance and does not mention other relevant alternatives such as list_workspace_members.

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 readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds the step-interpretation rule and the default-list behavior when neither steps nor funnel is given, which is genuinely useful. It says nothing about result shape, limits, or how drop-off is computed (e.g., strict order, time window between steps).

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 question the tool answers, then the two input modes. No filler or redundancy.

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

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

For a read-only analytics tool with a 9-parameter, well-documented schema and no output schema, the description covers the essential decisions: step format, step count bounds, and the saved-funnel alternative mode. The main remaining gap is what the response contains, which matters since no output schema exists.

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 89%, so the baseline is 3, and the description adds real meaning on top: the '/' prefix distinguishes page paths from custom event names in steps (the schema documents no item semantics at all), and it clarifies the steps-or-funnel exclusivity. It does not explain breakdown, filters, or period/from interaction.

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 analysis: counting visits through ordered steps and where they dropped off, plus the page-path vs custom-event rule for steps. It doesn't name any sibling tool for contrast, so it doesn't reach a 5, but the verb and resource are unambiguous.

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

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

It gives concrete usage conditions: pass 2-8 steps, or a saved funnel name/id, and omitting both lists saved funnels. That last clause overlaps with list-oriented siblings but is a useful routing hint. It does not explicitly say when not to use it or name an alternative tool for conversion questions.

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