Flowsery

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

Annotations already flag destructiveHint=true, but the description adds substantial context: cannot be undone, requires restating website/filters/range and explicit confirmation, deletes completions only while the definition persists, returns the deleted row count, and requires websiteId or domain with a workspace token.

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

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

Front-loaded with the destructive action and confirmation requirement, and nearly every sentence carries unique information. The closing auth sentence partially duplicates the websiteId/domain schema descriptions, a minor redundancy in an otherwise tight block.

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

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

For a destructive, 7-param tool with an output schema, the definition covers prerequisites, confirmation, scope boundaries, and sibling alternatives. Nothing an agent needs to invoke it safely 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 the baseline is 3, but the description adds semantics the schema lacks: filters combine with AND, at least one is mandatory despite zero required fields, and startAt/endAt are independent bounds. This genuinely extends beyond the structured field descriptions.

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

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

States a specific verb and resource ('permanently delete recorded goal completions') with the matching scope ('matching every filter given'). It explicitly distinguishes itself from delete_payments and update_issue_status, and clarifies it removes completions only, not the goal definition get_goals still lists.

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 explicit when-to-use rules and exclusions: at least one of visitorId/name/startAt/endAt is required or the call fails, one date bound alone is allowed, and no range means whole history. It routes revenue deletions to delete_payments and issues to update_issue_status.

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 destructiveHint=true, so the description builds on that with concrete consequences: deletion cannot be undone, removes revenue from every report and visitor profile, returns the number of rows deleted, and fails before reaching the API if no filter is given. It also explains that filters combine with AND and that missing date range deletes across all history. No contradiction with annotations.

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

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

The description is dense but front-loads the destructive action, then flows through filters, required constraints, consequences, alternatives, and auth. Every sentence carries operational or safety-relevant information, which is appropriate for a high-risk deletion tool.

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

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

Given the destructive operation, seven filters, an output schema, and annotations covering the safety profile, the description supplies everything an agent needs: required filter semantics, date-range behavior, auth context, irreversibility, return value, and the correct alternative for refunds. No material gap remains.

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 documents each parameter individually, so the baseline is 3. The description adds combination and requiredness semantics beyond the schema: filters combine with AND, startAt and endAt are independent and one bound alone is allowed, and at least one filter is required. That is meaningful added value, though it does not fully restate per-parameter meaning already 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?

Starts with a precise verb and resource: "Permanently delete analytics payment records." It immediately scopes the action by excluding refunds and provider changes, and later names track_payment as the alternative for refunds, so an agent can distinguish it from siblings without opening any schema.

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

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

Explicitly states when to use the sibling instead ("To record a refund that already occurred, use track_payment with isRefund") and when not to use this tool (refunds, provider changes). It also gives prerequisites: at least one of transactionId, visitorId, startAt, or endAt must be supplied, websiteId or domain with workspace token is required, and explicit confirmation should be obtained first.

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/non-destructive, and the description adds real context beyond them: descending rank order, the returned row fields (value, visitors, revenue, percentage), pagination.total linkage, limit default/max, 30-day date default, that all filter_* apply, and the auth requirement (websiteId/domain plus workspace token).

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?

Information-dense but front-loaded: purpose, then routing, then example, then output/limits, then auth. No filler sentences; each clause carries actionable content.

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

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

For a 29-parameter generic breakdown tool with full schema coverage and an output schema, the description supplies the missing conceptual layer: routing among siblings, filter interaction, defaults, and auth requirements. Nothing needed to call 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 100%, so the baseline is 3. The description nonetheless adds routing value by explaining which dimension values lack dedicated tools and clarifying the generic-vs-dedicated relationship, plus the filter combination model, going modestly beyond the schema text.

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

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

States a specific verb+resource (group visitors by dimension), the output ordering (ranked by visitors descending), and the scoping (date range). It also positions itself against the sibling get_* tools by naming exactly which dimensions have dedicated tools and which do not.

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?

Explicit routing: use this for dimensions without a dedicated tool (with the full list), use the dedicated tool for the enumerated others, and combine dimension with filter_* to drill in, illustrated with a concrete example. Both when-to-use and when-to-prefer-alternatives are covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely new behavior: rows carry value/visitors/revenue/percentage with pagination.total, limit defaults to 100 (max 1000), dates default to last 30 days, and auth requires websiteId or domain with a workspace token. Only minor gap is that the row payload partially duplicates the 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?

Four tight sentences, front-loaded with what the tool returns, then routing alternatives, then output shape/defaults, then auth. No filler and nothing repeats the parameter list verbatim.

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 28-parameter tool, the description covers the essentials an agent needs: defaults, pagination, auth requirement, the universal applicability of filter_* arguments, and how to get sibling breakdowns. With an output schema present it correctly avoids re-documenting return fields in 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 coverage is 100%, so the baseline is 3. The description adds cross-cutting semantics not obvious from the schema alone: that all filter_* arguments apply here, that filter_browser values come from this tool's own output, and that limit/date defaults and the websiteId-or-domain auth rule govern invocation.

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 visitors grouped by browser name'), names the ranking and grouping semantics, and explicitly distinguishes itself from get_breakdown (browser_version), get_operating_systems, and get_devices. An agent can select it without opening any sibling schema.

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

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

Explicitly routes the agent: use get_breakdown with dimension browser_version for versions, get_operating_systems for OS, get_devices for device type, and use filter_browser on other tools to scope them to one browser. This is exactly the when-to-use/when-not framing.

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 (readOnly, non-destructive, closed-world). The description adds real behavioral context beyond that: the data-scope caveat that only visits tagged with utm_campaign appear and untagged traffic is silently absent, the auth requirement (websiteId or domain plus a workspace token), and pagination.total semantics. It stops short of describing rate limits or exact sort tie-breaking, so 4 rather than 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?

Dense and front-loaded: scoping/ranking first, then alternatives, then return shape and defaults, then auth. Almost every clause earns its place, though the row-shape and limit-default sentences partly duplicate the schema and output schema.

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

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

For a 28-parameter read tool with an output schema, the description covers the essentials an agent needs: scope limitations, sibling routing, defaults, pagination, and auth requirements. Return-value detail is redundant given the output schema but nothing required for 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 description coverage is 100%, so the schema already documents all 28 parameters including defaults, filter operators, and value sources. The description largely restates what is already structured (limit default 100/max 1000, dates default to last 30 days, all filter_* apply), adding little semantic meaning 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 and resource (get UTM campaigns / utm_campaign values), specifies ranking (visitors descending) and scope (date range), and explicitly differentiates itself from get_referrers, get_channels, and get_breakdown by naming what those return instead. An agent can immediately tell this apart from its siblings.

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 explicit when-to-use (UTM campaign values ranked by visitors), when-not (only tagged traffic appears; untagged traffic is absent), and names concrete alternatives (get_referrers, get_channels for full source picture; get_breakdown with utm_source/utm_medium/utm_term/utm_content/all_params for other tracking parameters). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: the classification logic (referrer domain + utm_medium/utm_source), the returned fields (value, visitors, revenue, percentage, pagination.total), limit defaults, and the auth requirement of websiteId or domain with a workspace token.

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 dense sentences with the core purpose front-loaded; the channel enumeration is bulky but earns its place by explaining how classification maps to output rows. Nothing is redundant padding, though the channel list could be trimmed.

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 28-parameter tool with an output schema, the description covers everything an agent needs: purpose, sequencing versus siblings, auth requirement (websiteId/domain + workspace token), date and limit defaults, filter applicability, and pagination field. Return values need not be re-explained given the output schema.

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

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

Schema description coverage is 100%, so each of the 28 parameters is already documented, which sets the baseline at 3. The description restates a few defaults (limit 100/1000, last-30-day dates) and generalizes that all filter_* arguments apply, but adds no operator or value syntax beyond what the schema already provides.

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

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

States a specific verb and resource ('Get visitors grouped into GA4-aligned marketing channels'), enumerates the channel set, and specifies ranking and date scoping. It is immediately distinguishable from siblings like get_referrers and get_campaigns, which it names 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?

Explicitly sequences usage: 'Use this first for the traffic mix, then get_referrers for the domains behind Referral and Organic Social, or get_campaigns for tagged campaigns.' This gives both a when-to-use and a condition-based routing to two alternatives.

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

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

Annotations already declare readOnly/non-destructive, and the description adds real context: the response row shape (value, visitors, revenue, percentage, pagination.total), the 30-day default window, and the auth requirement (websiteId or domain with a workspace token). It stops short of richer operational detail such as rate limits or exact pagination semantics beyond pointing at pagination.total.

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

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

Front-loads the core purpose and ordering, then packs constraints into four more sentences with little waste. It is slightly dense, mixing performance tips with output/auth notes, but every sentence 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?

For a 28-param read tool with a 100%-covered schema and an output schema, the description is complete: auth path, date defaults, ranking, pagination hook, and sibling routing are all present. Return values need not be fully explained given the output schema, and the sketch provided is a bonus.

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 28 parameters are already fully documented in the schema, which sets the baseline at 3. The description reinforces a few defaults (limit 100/1000 max, last-30-days window) and notes that all filter_* arguments apply, but adds no operator or format detail beyond what the schema provides.

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

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

States a specific verb and resource ('Get visitors grouped by city'), plus the ordering guarantee (ranked by visitors descending) and the date-range scoping. It also names the coarser alternatives (get_countries, get_regions), so an agent can distinguish it from its 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 explicit when-to-use guidance: pass filter_country or filter_region first to make the long tail meaningful, and raise limit above the default 100 (max 1000) when more rows are needed. It also routes the agent to get_countries/get_regions for a coarser view.

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 real context beyond that: default ranking order, default date window (last 30 days), limit default/max, presence of pagination.total for paging, and the auth requirement (websiteId or domain with a workspace token). Return-field enumeration is partly redundant with the output schema, keeping it from 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?

Dense but front-loaded: routing guidance first, then output shape, then defaults and auth. Every sentence carries information, though the return-field list and limit default partially duplicate the output schema and parameter descriptions.

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 28-parameter analytics query with a full output schema and annotations, the description covers the essential extras an agent needs: sibling routing, default window, pagination mechanism, and authentication requirement. 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 description coverage is 100%, so the schema already documents every parameter including defaults and formats; the description largely restates the limit default and the date default. 'All filter_* arguments apply' is the one additive statement but adds little beyond what the schema shows. 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+ordering ('Get visitors grouped by country, ranked by visitors descending, for a date range') and explicitly positions itself as the coarsest of three geographic tools, naming get_regions and get_cities as finer-grained alternatives. An agent can distinguish it from all 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?

Explicit routing: use get_regions for states/provinces, get_cities for cities, add filter_country to drill into one country, and use get_realtime_map for 'right now' instead of a range. Clear when-to-use and when-to-use-something-else.

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 readOnly/no-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: cardinality ('three rows at most, so pagination rarely matters'), default window (last 30 days), that all filter_* arguments apply, and the auth requirement (websiteId or domain with a workspace token). It stops short of explaining how results are bucketed or what happens with timezone edge cases.

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

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

Front-loaded with the core purpose, then routing, then operational caveats. Every sentence carries distinct information — no filler, no restatement 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 an output schema present the description need not explain return shape, yet it still flags that rows carry value/visitors/revenue/percentage and that cardinality is bounded. Auth requirements, defaults, and scope are all covered for a 28-param tool, leaving nothing an agent must guess before calling.

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 still adds value by noting date defaults and that every filter_* argument applies, and by reframing filter_device as a cross-tool switch rather than just this tool's own filter. That is meaningful semantics beyond the per-parameter schema text.

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

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

States a specific verb and resource (get visitors split by device type), names the exact dimension values, the ranking order, and the time scoping. It explicitly separates itself from get_browsers and get_operating_systems, so an agent can route correctly without opening any 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?

Explicit routing guidance: 'Use this for the mobile-versus-desktop question; use get_browsers or get_operating_systems for the software split.' It also tells the agent the alternative pattern (pass filter_device to another tool) when a single device slice is wanted rather than a 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 readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the auth requirement (websiteId or domain with a workspace token), the 30-day default window, and how filter_* narrows the counted visitors. It stops short of rate-limit or pagination-edge behavior but is solid.

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?

Purpose and routing are front-loaded, then defaults/pagination, then the creation/auth notes. Every sentence carries distinct information with no filler, despite the density required by 28 parameters.

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

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

With an output schema present, return values need not be explained. The description covers what an agent needs to call correctly: scope, defaults, filter semantics, pagination, sibling routing, and auth requirements.

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 baseline is 3. The description adds meaning on top: filter_* narrows the visitors counted, limit/offset page the goal list, and dates default to the last 30 days, plus the note that goals originate from track_goal. This goes beyond restating schema fields.

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 every configured goal) and the exact return content (completion counts per goal in the date range), including which goals are included (custom plus auto-created payment and free_trial). This clearly distinguishes it from sibling tools like get_overview and 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?

Explicitly routes the agent: use get_overview for conversion_rate against the KPI goal, get_breakdown with dimension goal for revenue/percentage, get_visitor for a single person. It also states the alternative and condition, leaving nothing to inference.

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

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

Annotations already declare a safe read-only, non-open-world operation, so the safety burden is lifted. The description adds real behavioral context beyond that: the required auth (websiteId or domain with a workspace token), that limit defaults to 100 and caps at 1000, and that dates default to the last 30 days. It does not discuss rate limits or cross-workspace id caveats, but the coverage is solid.

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

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

Front-loaded with purpose and scope, then alternatives, then output shape, then auth — a sensible ordering. Dense but every sentence carries information; slightly long as a single block with no visual separation for the defaults/auth clauses.

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

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

Despite 28 parameters, the description covers the composite defaults (limit, dates), the alternative tool, the sibling-scoping pattern, the row shape, and the auth requirement. An output schema exists so return-value explanation is not strictly required, yet the row/pagination summary is a bonus. Nothing needed to invoke 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 already 100%, so baseline is 3, but the description adds meaning on top: default/max limit values, the 30-day default date window, that all filter_* arguments apply, and the operand semantics pointer on filter_hostname. That is genuine added value over the per-parameter schema text.

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

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

States a specific verb and resource ('Get visitors grouped by hostname, ranked by visitors descending, for a date range'), plus the distinguishing edge case that a single-domain site returns one row. An agent can immediately tell this apart from get_pages and the other breakdown tools.

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

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

Explicitly names the alternative ('Use get_pages for paths within a host') and the cross-cutting pattern ('pass filter_hostname to any other tool to scope it to one host'), and states when this tool degenerates to a single row. This covers when-to-use and when-not-to-use without inference.

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

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

Annotations already declare readOnlyHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds important auth/selector behavior: workspace-token calls need websiteId or domain, without either it behaves like list_websites, and a website key needs no selector. It does not discuss rate limits or error 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 front-loaded and information-dense, with the purpose and fields stated first. It is slightly longer than necessary because 'Read-only; nothing is changed' repeats the readOnlyHint annotation, but the remaining sentences earn their 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?

Given that an output schema exists and schema coverage is complete, the description does not need to explain return values. It covers the purpose, when to use it, selector behavior, auth-token variations, and the preferred sibling for discovery, making it complete for an agent to call correctly.

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

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

Schema description coverage is 100%, so the schema already defines the three parameters. The description adds meaningful conditional semantics beyond the schema: workspace-token calls should pass websiteId or domain, a website key needs no selector, and calling with neither returns the website list.

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: get one website's settings, and enumerates the key fields returned (domain, timezone, currency, KPI goal name, logo, color scheme). It also distinguishes itself from list_websites by saying list_websites is preferred for discovery.

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

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

It explicitly says to call it after list_websites to learn timezone and currency before running date-range reports, then pass that timezone to report tools. It also gives clear selector guidance: with a workspace token pass websiteId or domain, with neither it returns the website list, and a website key needs no selector.

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, closed-world), and the description adds real context: authentication requirement (websiteId or domain with a workspace token), default window of the last 30 days, default limit of 100 with max 1000, and that all filter_* arguments apply. It restates return fields that the output schema already documents, which caps this 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?

The routing constraints are front-loaded and the sentences are dense without filler. The return-shape sentence (value, visitors, revenue, percentage, pagination.total) is partly redundant with the existing output schema, so the description is slightly longer than strictly necessary.

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

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

For a 28-parameter, zero-required-parameter analytics tool with an output schema already present, the description covers what the schema cannot: auth mode, default time range, ranking order, pagination behavior, and how to reuse the OS filter across sibling tools. Nothing essential for correct invocation 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 the baseline is 3, but the description adds cross-tool semantics the schema does not: filter_os values are names returned by this tool, and the same filter_os can be passed to other tools. It also notes defaults for limit and the date range, though individual parameter syntax is largely 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?

The description states a precise verb+resource+scope: visitors grouped by operating system, ranked by visitors descending, within a date range. It also names the sibling tools that answer adjacent questions (get_breakdown with os_version, get_browsers, get_devices), so an agent can distinguish it without opening other schemas.

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

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

It gives explicit alternatives and the condition selecting each: versions → get_breakdown with dimension os_version, browsers → get_browsers, desktop vs mobile → get_devices. It further states that filter_os can be passed to other tools to scope them to one OS, which is actionable 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 safety is covered. The description usefully adds default window behavior (last 30 days ending now), timezone default from site settings, that every filter_* narrows the whole result, and the auth requirement (websiteId or domain with a workspace token). It stops short of noting rate limits or how pagination/limits interact for a single-row tool, so it is strong but 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?

Four sentences, front-loaded with the metric list, then defaults, then filter semantics, then sibling routing and auth. Every sentence carries information, though the metric enumeration and the routing sentence make it denser than strictly necessary. No filler.

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

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

For a 28-parameter, zero-required read tool with a full output schema and annotations, the description covers the essentials: what it returns, default date/timezone behavior, how filters compose, when to prefer siblings, and the auth requirement. Return-value details are correctly left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above baseline by adding cross-parameter semantics the schema does not state: that every filter_* argument narrows the entire result and that filters can be combined in one call to answer compound questions, plus the websiteId/domain auth distinction tied to token type.

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 ('Get headline totals for one website over a date range as a single row') and then enumerates the exact metrics returned (visitors, sessions, bounce rate, etc.), so the agent knows precisely what this tool produces. It also explicitly distinguishes itself from sibling tools get_timeseries and get_* breakdown tools.

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

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

It gives explicit routing: 'Use get_timeseries for the trend over time and a get_* breakdown tool for the split by page, source, or geography.' It also shows when/how to combine filters with a concrete example ('mobile visitors from Germany' via filter_country plus filter_device), leaving nothing to inference.

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

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

Annotations already establish the safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds real context beyond them: the row shape (value, visitors, revenue, percentage, pagination.total), the default window (last 30 days) and limit default/max, and the auth prerequisite (websiteId or domain with a workspace token). It stops short of describing failure modes or token/key differences in detail, so a 4 rather than 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?

Front-loaded with purpose, ordering and unit, then routing, then response shape and defaults. Dense but nearly every clause carries information. Minor redundancy: 'which pages get the most traffic' restates 'ranked by visitors' and could be cut.

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

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

With an output schema present, the description need not explain return values, yet it still names the key row fields and pagination.total for offset/limit reasoning. Auth requirements and defaults are covered. For a 28-parameter read tool this is close to complete; only edge-case behavior (empty results, invalid token) 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% across 28 parameters, so the schema already documents each argument, including the shared filter operator syntax. The description's contributions (limit default 100/max 1000, dates default to last 30 days, all filter_* apply) largely restate schema content. Baseline 3 is appropriate 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 (get), resource (page paths) and an explicit ordering (ranked by visitors, descending) plus scope (date range). It actively disambiguates itself from siblings by naming get_breakdown with dimension entry_page / exit_link and get_hostnames. An agent can pick this tool without opening any 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?

Explicit routing rules: use get_breakdown with entry_page for landing pages, exit_link for outbound clicks, get_hostnames for multi-domain sites. It also tells the agent how to narrow results with filter_utm_campaign / filter_referrer. Both when-to-use and when-to-use-something-else 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 a safe read operation, but the description adds important behavioral context: point-in-time scope, no date/filter/pagination arguments, polling rate limit of once per 5 seconds, and authentication requirements (websiteId or domain with a workspace token).

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

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

The description is front-loaded with the core purpose, then efficiently covers constraints, alternatives, return path, polling limit, and auth. Every sentence adds distinct value with no wasted wording.

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

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

With annotations covering safety, full schema coverage, and an output schema available, the description supplies all remaining operational context an agent needs: scope, alternatives, polling rate, and auth requirements.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description still adds useful semantics by stating that the tool takes no date, filter, or pagination arguments and clarifying the websiteId/domain token dependency, which goes slightly beyond the schema text.

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

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

States a specific verb and resource (count active visitors), defines the time window (last 5 minutes), and distinguishes the result as point-in-time with no history. It also names sibling tools for different needs, so an agent can disambiguate immediately.

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

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

Explicitly says when to use alternatives: get_timeseries with interval hour for recent trends, and get_realtime_map when location is needed. It also provides a clear polling constraint, making intended usage unambiguous.

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

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

Annotations already declare readOnlyHint, destructiveHint false, and openWorld false, so safety is covered. The description adds real behavioral context beyond annotations: recognized sites collapse under a source name (Google, ChatGPT, Reddit) while others show as domains, rows carry value/visitors/revenue/percentage with pagination.total, limit defaults to 100 (max 1000), dates default to 30 days, and it requires websiteId or domain with a workspace token.

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

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

Front-loaded with the core purpose, then routing guidance, then defaults and auth requirements. Dense but every clause carries information; only the row-shape detail slightly overlaps the output schema.

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

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

For a 28-parameter read tool with an output schema, the description covers purpose, sibling routing, defaults, auth requirements, and row contents. Nothing an agent needs to invoke 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%, so the baseline is 3, and the description exceeds it by confirming that all filter_* arguments apply, spelling out default values for limit and the date window, and clarifying the semantics of filter_referrer (source name vs domain). With 28 parameters this is meaningful added meaning beyond the schema.

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

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

States a specific verb and resource (get referrers) plus sort order (ranked by visitors, descending) and scope (external sites sending traffic in the date range). It further distinguishes itself from get_channels, get_campaigns, and get_breakdown by name, so an agent can route correctly without opening schemas.

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

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

Explicitly names the alternatives and the exact condition that selects each: get_channels for GA4-style channel grouping, get_campaigns or get_breakdown with dimension utm_source for UTM-tagged traffic. This is a textbook when-to-use-this-vs-that statement.

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/destructive/openWorld, so safety is covered. The description adds real behavioral context beyond that: returned columns (value, visitors, revenue, percentage), pagination.total, limit default/max, 30-day date default, and the auth prerequisite (websiteId or domain with a workspace token). Return-shape detail partially overlaps the output schema, keeping this just short of 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?

Four tight sentences, front-loaded with what it returns and where it sits in the hierarchy, then defaults, then auth. No filler; each clause 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?

For a 28-parameter tool with full schema coverage, an output schema, and annotations covering safety, the description supplies the missing pieces: sibling positioning, auth requirement, pagination semantics, and default windows. Nothing essential for correct invocation 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 100% and each filter_* parameter is documented in the schema (including operator syntax). The description only restates a few defaults (limit 100/1000, last 30 days) and the blanket 'all filter_* arguments apply', adding little beyond the schema.

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

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

States a specific verb and resource (visitors grouped by region/state), the ranking (by visitors descending), and the date-range scope. It explicitly positions itself in the geographic hierarchy between get_countries and get_cities, so an agent can distinguish it from siblings immediately.

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 when-to-use routing: combine with filter_country to list one country's regions, and pass filter_region to other tools to scope them. Names the alternatives (get_countries, get_cities) with their relative granularity.

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, destructiveHint=false and openWorldHint=false. The description adds real behavioral context beyond that: default date range (last 30 days), default interval (day), an auth requirement (websiteId or domain with a workspace token), and a performance warning about hourly buckets over a year producing thousands of points. It omits pagination interaction details, which is why it is 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?

Front-loaded with the core purpose and return shape, then guidance, then defaults, then auth. Every sentence carries distinct information and none 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 an output schema present, the description needn't document return values, and it nonetheless summarizes the point structure. For a 29-parameter read tool it covers routing, defaults, interval/range trade-offs and auth — 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 description coverage is 100%, so the schema already documents all 29 parameters including defaults, enums and filter operators. The description restates date/interval defaults but adds no format or syntax 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 ('Get the same metrics as get_overview bucketed by hour, day, week, or month') and enumerates the returned fields. It explicitly distinguishes itself from get_overview and get_* breakdown tools, so an agent can route 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?

Names the alternatives and the conditions that select them: 'use get_overview for one total and a get_* breakdown tool for a split by dimension rather than time.' It also gives practical guidance on matching interval to range and notes the defaults.

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 readOnly/no-destructive safety, but the description goes well beyond them: profile is null for anonymous visitors, each list is capped at the 100 most recent items, unknown/foreign ids fail with 'Visitor not found', and workspace-or-domain auth is required. Only the timeline ordering and cap nuance are covered; return shape is delegated to the output schema, which is appropriate.

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 paragraph that is front-loaded with the resource description before constraints. Every sentence carries information (privacy, nullability, caps, errors, auth), though the volume of clauses makes it heavier than an ideal short brief.

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 4-param read tool with an output schema, the description covers purpose, privacy obligations, edge cases (anonymous visitors, 100-item caps, not-found errors), auth prerequisites, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely non-redundant semantics: visitorId is the record ID from get_realtime_map or the dashboard view and explicitly NOT the _fs_vid cookie value, plus the websiteId-or-domain token requirement. That disambiguates the most error-prone parameter beyond the schema text.

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

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

Specific verb+resource (one visitor's full profile) followed by an enumerated inventory of what the profile contains: geo/device/browser, acquisition, activity, revenue, identified profile, merged timeline. The closing contrast with the aggregate get_* siblings makes it unmistakably distinct from get_overview, get_breakdown, etc.

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

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

Explicit when-to-use and when-not: 'call it only when asked about a specific visitor', 'surface the minimum needed', and 'Use the aggregate get_* tools for questions about many visitors.' The privacy constraint plus the named alternative leaves nothing to inference.

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

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

Annotations already declare a safe read, but the description adds substantial context beyond them: deduplication across sessions, default severity ranking, suspended issues being hidden rather than deleted, a free-trial cap of 10 issues, and the auth requirement (websiteId or domain with a workspace token). This is exactly the behavioral detail annotations cannot convey.

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

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

Front-loaded with the core purpose and routing to get_issue before the finer details of counts, trial limits, and pagination. Dense but nearly every clause carries actionable information; slightly long with some redundancy between the response-field listing and the existing output schema.

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

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

Covers what the tool returns (row fields, site-wide counts, pagination.total), how records can disappear, trial limitations, and default/max limits. Even though an output schema exists, the added context about suspended issues and trial truncation makes the description fully sufficient 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?

Schema coverage is already 100%, so the baseline is 3, but the description reinforces key semantics: limit defaults to 100 with a 1000 max, recency means 'last seen', and status omission covers open/in_progress/resolved while suspended is opt-in. It doesn't add format or syntax beyond the schema, so not a 5.

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

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

States a specific verb and resource ('List issues the AI found while analyzing session recordings') and immediately enumerates the resource's content (bugs, broken flows, UX problems) with dedup and severity ranking. It is clearly distinguishable from siblings like list_websites and get_issue.

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

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

Explicitly positions itself as the entry point ('Start here for what is broken') and names the follow-up tool with its purpose ('then call get_issue with an id for occurrences, steps to replicate, and comments'). It also explains the suspended-status edge case so an agent can interpret a missing issue correctly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false. The description adds valuable behavioral context: workspace token returns every website, website key returns only its own, and omitting both identifiers fails with a specific error. However, it also says 'Takes no parameters,' which inaccurately describes the tool's behavior relative 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?

Information is front-loaded with the core purpose and token behavior, and the failure condition is clearly stated. The only wasted and harmful sentence is 'Takes no parameters,' which is both unnecessary and incorrect.

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

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

An output schema exists, so return values need not be explained, yet the description still lists them. It covers token types, call ordering, dependency requirements, and failure conditions well. The only meaningful gap is the inaccurate parameter statement that conflicts with the schema.

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

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

Schema description coverage is 100% for the optional workspaceId parameter, so the baseline would be 3. But the description states 'Takes no parameters,' which directly contradicts the schema and could mislead an agent into omitting workspaceId, causing calls to default to the wrong workspace.

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', defines scope by token type, and lists returned fields. It distinguishes itself from get_metadata by naming the alternative when the website is already known.

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

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

Explicitly says to call this first with a workspace token, explains that every other tool needs websiteId or domain from this list, and gives the exact failure message when both are omitted. It also names get_metadata as the alternative for known-website settings.

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

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

Beyond the readOnly/destructive/openWorld annotations, the description discloses auth-scoped behavior: a flow_ws_ token lists only its own workspace, a flow_ token fails here with a 400, and omitting workspaceId silently changes what other tools target. Those are non-obvious behavioral traits that annotations do not cover.

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

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

Front-loaded with the purpose, then routing, then edge cases. Every sentence carries information, though the enumeration of return fields is partly redundant given the output schema exists.

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 zero-arg, multi-tenant discovery tool this covers purpose, routing, token/scope edge cases, and error behavior. An output schema exists, so the return-shape sentence is a bonus rather than a necessity, and nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with 'Takes no arguments', and the semantics it does explain (workspaceId consumed by other tools) are about other tools rather than this one's inputs.

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 the workspaces this sign-in can act in') plus scope ('across every organization the user belongs to'), which clearly distinguishes it from sibling list_websites and the metric getters.

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 explicit trigger conditions ('when the user names a workspace, client or organization, or when data they expect is missing'), the downstream action ('pass the matching id as workspaceId to every other tool'), and the fallback semantics when workspaceId is omitted (tools act in the 'current' workspace). This is genuine 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 only declare the safety profile (not read-only, not destructive, closed-world). The description adds behavior beyond them: auto-creation on first use, append semantics with the explicit warning that repeating counts the goal twice, visitor attribution behavior, and the auth requirement (websiteId or domain with a workspace token). That is exactly the value structured fields don't carry.

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

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

Front-loaded with the core action, then behaviors, alternatives, undo path, and auth. Sentences are dense but each carries distinct information — no restatement of the title 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?

An output schema exists so return values need not be described. For a 6-param mutation with nested metadata, the description covers auto-creation, append/idempotency risk, attribution, alternatives, and auth — everything an agent needs 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 coverage is 100%, so the baseline is 3. The description nonetheless adds interpretation beyond the schema for visitorUid (what it is, and the consequence of omitting it: anonymous completion) and reinforces the name/websiteId/domain auth relationship, though name constraints are largely restated from 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 verb and resource: 'Record one completion of a custom goal.' It names the distinct sibling for adjacent work ('Use track_payment for revenue') and the inverse tool ('Undo with delete_goals'), so an agent can tell it apart from the other track_* tool without opening schemas.

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

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

Explicit when/when-not/alternatives: no setup call needed since the goal is created on first use, use track_payment for revenue, undo via delete_goals, pass visitorUid to attribute vs omit for anonymous. Every routing decision is stated, not inferred.

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 cover the safety profile (readOnlyHint=false, destructiveHint=true), and the description goes well beyond them: it states no money moves, that repeated transactionIds are rejected rather than deduplicated, that isRefund overwrites an existing record, that a payment auto-creates a goal, and that unmatched attribution falls back to Unknown. This is exactly the mutation semantics an agent needs before calling.

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?

Dense but front-loaded, leading with what the tool is not (never charges, moves money, refunds) before edge cases. Every sentence carries usable information, though the single block paragraph could be broken up for scanability.

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 14-parameter mutation tool with an output schema present, the description covers the risky behaviors, attribution fallback, goal side effect, and identifier prerequisites. Nothing an agent needs to invoke it safely 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 the baseline is 3, but the description adds real semantic detail the schema lacks: the rejected-not-deduplicated behavior of transactionId, the overwrite semantics of isRefund, the free_trial goal on zero amount, and the attribution lookup order. Some phrasing (websiteId/domain requirement) restates schema, keeping it from a 5.

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

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

Opens with a specific verb+resource ('Record an analytics payment') and immediately scopes it against siblings by naming track_goal as the no-revenue alternative. An agent can distinguish this from delete_payments, get_overview, etc. 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 explicit when-not guidance ('Skip it when the site's provider is tracked automatically') and a named alternative for the adjacent case ('use track_goal for conversions without revenue'). Prerequisites (websiteId or domain with a workspace token) are also stated.

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