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

Description adds significant behavioral context beyond annotations: evaluation on MCP session connect, no background push, threshold semantics (absolute vs percentage), and one-alert-per-call limitation. Annotations (readOnlyHint false, destructiveHint false, idempotentHint true) are consistent and not contradicted.

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?

Concise yet comprehensive. Front-loaded with purpose, then examples, then limitations. No wasted sentences; every part serves a purpose.

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 all necessary aspects: what the tool does, parameters, examples, limitations, and behavioral traits. Output schema exists, so return details are covered elsewhere. No obvious gaps for an alert creation tool.

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

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

With 100% schema coverage, baseline is 3, but description adds substantial value: explains metric units (bounce_rate as 0-100, avg_duration in seconds), condition interpretations, threshold meaning for each condition, period defaults, and pathname scoping. Examples map conditions to concrete scenarios.

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?

Description clearly states it creates a metric alert with specific condition, metric, and threshold. It distinguishes from siblings by focusing on creation and explains the alert behavior (session-based evaluation). Examples reinforce the purpose.

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?

Provides use cases and examples, plus limitations on evaluation timing and lack of push notifications. However, it does not explicitly contrast with other alert tools (e.g., when to use alerts.list vs create) or specify when not to use this 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 indicate destructiveHint=true and idempotentHint=true. Description adds irreversible nature, no soft-delete, need to confirm intent, and 404 behavior. Adds significant context beyond 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?

Well-structured: front-loads main action, then prerequisites, examples, limitations. Every sentence adds value without 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?

With output schema present, description covers prerequisites, side effects, error cases, and usage examples. Complete for a delete tool.

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

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

Schema has 100% coverage. Description adds that alert_id must be UUID from alerts.list (not metric name) and project_id can be omitted if single project. Provides extra clarity beyond 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?

Clearly states 'Delete an alert by its id' with specific verb and resource. Distinguishes from siblings by referencing alerts.list as prerequisite and mentioning siblings like alerts.create and alerts.list.

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

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

Explicitly tells when to use (after alerts.list) and when to confirm intent. Provides examples for different use cases. Mentions limitations and error handling (404).

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

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

Beyond the readOnlyHint annotation, the description discloses specific return fields, empty array behavior, omission of alert state, and lack of pagination. No contradictions 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 concise and front-loaded with purpose. A few extra details could be trimmed, but overall it is efficient.

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 simple single-parameter tool with readOnly annotation and output schema, the description covers return values, limitations, and usage examples thoroughly.

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% with detailed project_id description. The description adds context on when project_id is required and how to retrieve it via projects.list, providing 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?

The description clearly states the verb 'list' and resource 'alerts' with scope 'for a project'. It lists the returned fields, distinguishing it from sibling tools like alerts.create and alerts.delete.

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 explicitly advises using this tool before alerts.delete to find IDs, and to show active monitors. Examples are provided, though it does not explicitly state 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?

The description discloses key behavioral traits: order matters (first is primary), duplicates are deduplicated, retention windows are uniform across cohorts, and sample-size caveats apply. Annotations indicate readOnlyHint=true, aligning with the read-only nature of comparing cohorts. No contradiction.

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 thorough and well-structured, starting with purpose, then use cases, examples, and limitations. While it is somewhat lengthy, every sentence is informative and earns its place. A slightly more concise summary could improve readability, but it remains effective.

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 availability of an output schema, the description does not need to detail return values. It covers all necessary aspects: when to use, parameter semantics, ordering, limitations, and examples. The tool is complex but the description is complete for an agent to invoke 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?

Input schema coverage is 100%, and the description adds significant value beyond schema definitions. It explains the 'names' parameter with comma-separated format and ordering, 'periods' with reference to cohorts.retention, and 'project_id' with conditional usage guidance. Examples illustrate parameter combinations.

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

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

The description clearly states the tool's purpose: 'Compare 2–10 saved cohorts side-by-side on retention.' It identifies the specific verb (compare), resource (saved cohorts), and aspect (retention), distinguishing it from siblings like cohorts.retention (single cohort) and traffic.compare (traffic).

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 usage contexts are provided via examples and use cases (e.g., 'did April 14 signups retain better than April 7'). Limitations (max 10 cohorts, same windows, sample-size caveats, multiple-comparisons risk) and ordering behavior are clearly stated, guiding the agent on when and how to use this tool versus 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?

The description discloses that membership is recomputed at query time, cohort definitions are immutable after creation, and duplicate names return 409. It also notes the Pro plan requirement. These go beyond the annotations, which only indicate non-read-only, non-destructive, and non-idempotent.

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

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

The description is well-structured with sections, examples, and limitations, but it is somewhat lengthy. All content is valuable, but could be slightly more concise without losing information.

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

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

Despite the complexity of nested definitions and multiple parameters, the description covers creation behavior, error handling, naming rules, and pairing with other tools. Presence of an output schema reduces need for return value details, but the description still provides sufficient context for correct usage.

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 description adds value beyond the schema by providing concrete examples of definition objects, explaining period formats (ISO range vs preset), and describing filter property/value usage. This supplements the 100% schema description coverage with practical usage context.

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

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

The description clearly states the tool creates and persists a named cohort, specifying the event-based definition structure. It distinguishes from siblings like cohorts.compare and cohorts.list by explaining that this tool is for creation, and it pairs with other 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?

The description explicitly states when to use the tool (to define a cohort for later queries), provides limitations (only event-based, no behavior cohorts), and gives examples. It also advises using events.property_values to discover filter values, and mentions naming constraints and duplicate handling.

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 indicate destructiveHint=true and idempotentHint=true. The description adds that only the cohort definition row is removed (not event data) and that the operation is irreversible, providing further behavioral context beyond 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 brief (4 sentences) and well-structured, starting with the main purpose, then stating irreversibility, followed by an example and limitations. Every sentence is informative with no unnecessary words.

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

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

For a simple delete tool with an output schema and comprehensive annotations, the description covers all necessary aspects: purpose, irreversibility, error condition (404), and preparation steps (capture definition from cohorts.list). It is complete for its complexity.

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

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

The input schema covers both parameters fully (100% schema description coverage). The description adds value by mentioning the name parameter explicitly and giving an example for project_id, but the schema already includes detailed descriptions for both parameters, so the additional contribution is limited.

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 'Delete a saved cohort by name,' clearly specifying the action (delete) and the resource (saved cohort) with an identifier (name). It distinguishes from sibling tools like cohorts.create and cohorts.list.

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 explicitly advises that deletion is irreversible and the agent should confirm intent with the user before calling. It also mentions the 404 response and suggests capturing the definition from cohorts.list first if needed, providing clear guidance on when and how to use the 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 declare readOnlyHint=true, and the description adds important behavioral detail: 'size is recomputed at fetch time' and the moving nature for time-based cohorts. No contradictions.

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 paragraphs with examples and a limitation note. Every sentence is purposeful; no redundancy or fluff.

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 simple list operation and presence of an output schema (not shown), the description covers what is returned, the optional parameter behavior, and a key limitation. No significant gaps.

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

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

Schema covers both parameters (project_id, name) with good descriptions. Description adds value by explaining the effect of providing 'name' vs not and giving concrete examples, but schema already provides baseline meaning.

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?

Description clearly states 'List saved cohorts' and distinguishes two modes: with 'name' returns one cohort with size, without returns all with definitions. It explicitly positions the tool as a prerequisite for 'retention' and 'compare', differentiating from 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?

Explicitly says 'Use to discover cohort handles before calling retention or compare' and provides examples for when to include or omit 'name'. Does not explicitly exclude other uses, but context is clear enough.

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 declare readOnlyHint=true, and the description adds important behavioral details: retention measures any non-pageview-end event, numerator is per-day, cohort size is denominator, and limitations on custom metrics. 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 reasonably concise and well-structured with examples and limitations. It is front-loaded with the main purpose. Each sentence adds value, though it is slightly long but not excessively so.

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 complexity of retention analysis, the description is thorough: it covers usage, examples, limitations, and sibling tools. The output schema exists, so return values are not required. No gaps identified.

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 value by explaining the period format (<n>d or <n>w), default, and examples of usage. It clarifies the meaning of retention windows beyond the schema.

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

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

The description clearly states the tool computes a retention curve for a saved cohort, specifying the verb 'compute' and resource 'cohort'. It differentiates from siblings by mentioning cohorts.compare for comparisons and cohorts.list 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?

The description explicitly says when to use the tool (e.g., answer 'did this cohort stick around?') and provides examples. It also flags that cohorts.compare is for comparisons. However, it does not include negative guidance or explicit exclusions.

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

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

Annotations only provide readOnlyHint=true. Description adds key behavioral details: keyword-only matching (no semantic search), scoring (title matches rank higher), limitations (hand-maintained index, updates only on redeploy), and error handling (empty array). Provides substantial value beyond 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?

Well-structured with main info front-loaded. Examples and limitations at end. Slightly lengthy but every sentence is meaningful.

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 it's a search tool with output schema (not shown), description explains return format (ranked entries with url, title, description), limitations, and behavior details. Complete for an agent to decide and invoke 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 covers both parameters with 100% description coverage. Description adds useful semantics: query should be keywords (not full sentences), examples for typical use cases, limit default and max. Adds moderate value beyond 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?

Clearly states the tool searches the Clamp documentation index for setup, SDK, MCP, concepts, and skills pages. Differentiates from sibling tools (analytics, alerts, etc.) by specifying it's for 'how to' questions rather than data queries.

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 'Use when the user asks how to do something... rather than what their data shows.' Provides concrete examples. Lacks specific exclusions for data questions beyond mentioning analytics tools, but it's clear enough.

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?

Adds behavioral context beyond annotations: returns only earlier events, default limit 20 max 100, session scoping caveat. Annotations only provide readOnlyHint=true, and description does not contradict.

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?

Description is well-organized with examples, limitations, and paired tools. Each sentence serves a clear purpose. Front-loaded with core functionality.

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?

Fully covers all aspects: parameters, outputs (event rows with name/url/pathname/referrer), limitations, use cases. Output schema exists, so return value explanation is sufficient. No gaps.

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

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

Schema coverage is 100%, but description adds real meaning: explains where to get anonymous_id (from errors.list), timestamp format, limit default and max usage. Examples reinforce 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 states 'Breadcrumbs leading to one error: events from the same session before the error timestamp'. It distinguishes itself from siblings like errors.list and users.journey by specifying its unique role.

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 examples show when to use (e.g., 'what did this user do right before the error') and when not to ('use users.journey for per-event context'). Limitations are clearly stated (single session scope, timestamp alignment).

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?

Discloses behavioral traits beyond annotations: describes the grouping logic, exclusion of null-fingerprint events, default sort and limit, and the nature of the view. Annotations only indicate read-only, which this description supports without contradiction.

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?

Well-structured: starts with core purpose, then describes each output field, provides concrete examples, and ends with limitations and sibling references. Every sentence adds value without 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?

Given the presence of an output schema (context signals), the description focuses on purpose and usage, adequately covering the output fields (count, users_affected, etc.) and pairing with other tools. No gaps for a triage-view tool.

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

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

Despite 100% schema coverage, the description adds value with usage examples for each parameter. However, it contains a contradiction: says 'Default limit 50, max 200' while schema says limit 1-50, default 10. This inaccuracy reduces reliability.

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

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

The description clearly states it aggregates errors by fingerprint with counts and timestamps, and explicitly calls it 'the triage view'. It distinguishes itself from sibling tools like errors.list (individual occurrences) and errors.timeline (rate charting).

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?

Provides explicit examples of when to use the tool with different parameters (e.g., 'what's broken right now' → period='today', sort_by='count'). Also mentions limitations (only fingerprintable errors) and pairs with specific siblings for drill-down or correlation.

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?

Discloses behavioral traits beyond readOnlyHint: returns newest-first, default limit, max limit, no source-map resolution, how errors are captured and grouped (fingerprint). The description adds value that annotations alone do not capture.

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 well-structured: first sentence core purpose, second paragraph ingest details, third paragraph examples, fourth limitations and paired tools. Every sentence adds value despite length. Front-loaded with essential 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?

Given the tool's complexity (10 parameters, rich output, many siblings), the description covers return structure, filtering, limitations, and pairing with alternatives. Output schema exists, so return values are not required to be repeated. The description is complete and actionable.

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?

Input schema has 100% description coverage, so baseline is 3. The description adds value by providing usage patterns (e.g., period='today', browser='Safari') and clarifying the fingerprint parameter (16-char hex from errors.groups). This extra context raises the score above baseline.

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

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

The description clearly states the tool lists recent error events with full context, one row per occurrence, newest-first. It distinguishes itself from sibling tools (errors.groups for aggregates, errors.context for breadcrumbs) and specifies the exact shape of each row (error details plus standard event context).

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

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

Provides explicit guidelines: examples of queries (by period, message, browser, fingerprint, handled flag), limitations (max rows, no source-map resolution), and clear when-to-use alternatives (e.g., errors.groups for aggregate counts, errors.context for breadcrumbs). Pairs with sibling tools are explicitly stated.

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

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

Annotations declare readOnlyHint=true, and the description adds behavioral context: sparse series with omitted zero buckets, ISO timestamp format, and automatic interval defaults. 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 well-structured with a clear opening, examples, and pairing suggestions. Though lengthy, each section adds value. Could be slightly trimmed, but overall effective.

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

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

Given the output schema existence (though not shown), the description sufficiently explains return format and sparse series behavior. It covers all needed context for an agent to use the tool effectively.

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

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

With 100% schema coverage, baseline is 3. The description provides additional context beyond schema, such as default behavior for interval and period, and examples mapping natural language queries to parameters, improving usability.

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

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

The description clearly states the tool's function as returning error counts over time bucketed hourly or daily, and distinguishes it from siblings by mentioning optional fingerprint scoping and pairing with related tools like errors.groups and traffic.timeseries.

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

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

It provides explicit use cases (spot regressions, post-deploy spikes) and explains when to override defaults. While it doesn't explicitly state when not to use, it lists alternative tools for comparison, giving implicit 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 indicate readOnlyHint=true. The description adds extensive behavioral details: excluded events, dead-event signal with compare, type handling and silent misses if value_type wrong, max limit, and more. No contradictions.

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?

Description is lengthy but well-structured with paragraphs, examples, and bullet points. Front-loaded core purpose. Each part adds value given the tool's complexity. Could be slightly more concise, but earns its length.

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 26 parameters and an output schema, the description is very complete: covers all behaviors, filtering options, compare mode, type handling, limitations, and examples. Return values are implied; output schema exists so not needed. Highly informative.

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 significant value through examples, interaction explanations (e.g., compare only works without name/group_by), and practical context (e.g., event names case-sensitive, property keys max 128 chars). Slightly above baseline but not a full 5 as schema already describes each parameter well.

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

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

The description clearly states it lists custom events, explicitly excludes $-prefixed system and revenue events, and distinguishes from revenue.* tools. It covers behavior with and without name filter, making the purpose very specific.

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?

Provides explicit guidance: when to use (custom events), when to use alternatives (revenue.sum for billing), limitations (one property/value pair, group_by only with name filter), and examples for various use cases.

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

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

The description fully discloses behavioral traits beyond annotations. It explains the response shape, including the array of typed observations to detect type drift. It mentions limitations: 'returns keys + types only, no property values' and that occurrences are row-level. It also clarifies the default exclusion of $-prefixed system events and how to include them. No contradiction with annotations (readOnlyHint=true).

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 well-structured with a clear purpose, examples, a response shape block, and usage guidance. It front-loads the main purpose and uses bullet points for examples. However, it is somewhat lengthy and could be more concise by reducing the detailed list of system events.

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 tool's complexity and the presence of an output schema (implied by context signals), the description is complete. It covers the tool's purpose, usage, response shape, limitations, and pairing with siblings. It leaves no significant gaps for an agent to understand how to select and invoke the tool.

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

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

Although schema description coverage is 100%, the description adds significant meaning beyond the schema. For period, it gives examples of valid values and defaults. For include_pageviews, it lists the specific events included. For project_id, it explains when it's required and how to discover project IDs. This adds context that the schema does not provide.

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

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

The description clearly states the tool's function: 'Return what's actually firing into ingest as a structured signature, for diffing against the project's authored event-schema.yaml.' It specifies the verb (return), the resource (firing events), and the purpose (diffing). It distinguishes itself from sibling tools by mentioning that it excludes system events and that it is observation-based, not declaration-based.

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 provides explicit guidance on when to use the tool: 'Use it to compare declared vs reality' with concrete examples such as 'what events are firing in production' and 'did the spec drift this week.' It also explains when to use parameters (e.g., 'include the SDK's automatic events too' for include_pageviews) and how to set period. Additionally, it pairs the tool with siblings and the local event-schema.yaml.

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

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

Annotations declare readOnlyHint, and description adds behavior: only string properties, non-string returns empty array, results capped at limit, events without property skipped. No contradiction.

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, followed by examples and limitations. Every sentence earns its place. Concise yet comprehensive, no unnecessary text.

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

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

For a 5-parameter tool with output schema, the description covers return shape (via example), use cases, limitations, and pairing with siblings. All critical context for correct invocation is provided.

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

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

Schema coverage is 100%; description adds value with examples (event='signup', property='plan'), period format details, limit defaults, and behavior for invalid property type. Each parameter's role and constraints are well explained.

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

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

The description clearly states the tool returns top distinct values for a string-typed property on an event, ranked by count. It differentiates from siblings by referencing events.observed_schema for property discovery and traffic.breakdown for country data, and pairs with cohorts.create.

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: to understand value space before filtering (cohort definitions, segment filters). Provides examples and limitations (string only, capped results, omitted events). Also suggests alternative pattern with other 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?

Discloses behavioral traits beyond annotations: funnel saved and re-evaluable, per-session evaluation, immutable definitions (delete and re-create), step order importance, name uniqueness, and step DSL constraints. 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?

Long but well-structured: core purpose first, then step format, examples, limitations. Every sentence adds value, though could be slightly more concise given the complexity.

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 all essential aspects: step format, examples, limitations, error cases (duplicate name), and return values (step counts, conversion rates). Despite no output schema shown, description adequately describes behavior.

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%, but description adds extensive meaning: steps DSL with predicate types, examples, and limitations; name charset and collision info; project_id multi-project handling. Goes far beyond schema.

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

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

The description clearly states the tool creates and immediately evaluates a conversion funnel, explains what a funnel measures, and returns step-by-step counts and conversion rates. It distinguishes from siblings like funnels.list (re-evaluation) with specific verb and resource.

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?

Provides explicit when-to-use guidance, including handling duplicate names (409 error, suggests delete or new name), contrasts with funnels.list, and includes limitations (2-10 steps, char limits, step order, pageview exact match).

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?

Adds context beyond annotations: describes irreversibility, that only definition is removed (not events), and that definition isn't returned before deletion. No contradiction.

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?

Well-structured with main action first, then warnings, alternatives, examples, and limitations. Slightly lengthy but all sentences add value.

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 key aspects: purpose, irreversibility, editing pattern, error behavior, and prerequisites. Output schema exists but not described, which is acceptable.

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 description adds examples and clarifies project_id requirements. The name parameter is straightforward, but the extra context enhances usefulness.

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

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

The description clearly states 'Delete a saved funnel by name' with specific verb and resource. It distinguishes from siblings by explaining the editing workflow (delete+create).

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 advises confirming with user before calling, describes when to use (delete) and not (edit via delete+create), provides examples, and notes limitations (irreversible, 404).

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

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

Beyond the readOnlyHint annotation, the description adds that the funnel is re-evaluated against current data, returns step-by-step counts and conversion rates, cohort filters are session-level and not retroactive, and funnel definitions are immutable. No contradictions 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 well-structured: a concise core explanation, followed by practical examples, and then limitations. Every sentence adds useful information without 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?

Given the complexity (19 optional parameters), the description covers primary use cases, provides examples for common patterns, and notes limitations. The output schema exists to document return values, so the description is sufficiently complete for usage.

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 value by explaining how cohort filters work in combination, providing example parameter values, and stating defaults (e.g., period defaults to '30d'). This enriches the semantic understanding beyond the param 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?

The description clearly states it retrieves and re-evaluates funnels, distinguishes between listing all (no 'name') and getting a specific one (with 'name'), and contrasts with funnels.create for re-evaluation. It differentiates from sibling tools like funnels.create and funnels.delete.

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?

Provides explicit examples for common scenarios (list all, specific funnel with period, segment filters, comparing segments). Mentions when to call without name first to avoid 404, and implies when to use funnels.create instead for new funnels.

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

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

Goes beyond the readOnlyHint annotation by detailing behavior: null values for avg_engagement_seconds, SDK requirements for sections, 400 error without pathname, and the definition of bounce_rate and scroll metrics. No contradictions 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?

Well-structured with bullet points for each view, followed by examples. Every sentence is informative, no padding. Front-loaded with the core purpose.

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 complexity (20 parameters, output schema exists), the description fully explains the tool's purpose, three modes, and key behavioral quirks. An agent can confidently select and invoke this tool with the provided information.

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 covers all 20 parameters with 100% coverage, so the description focuses on the view parameter's impact, which is the key differentiator. Adds examples and limitations that clarify parameter usage beyond the schema alone.

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

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

The description clearly states it returns per-page metrics with three distinct detail levels: summary, engagement, and sections. Each level is defined with specific returned fields and use cases, distinguishing this tool from siblings like traffic.overview or sessions.paths.

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?

Provides explicit guidance on when to use each view, with examples like 'top pages this week' for summary and 'which pages bounce hardest' for engagement. Explains limitations and prerequisites, but lacks explicit instructions on when to avoid this tool in favor of 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 provide readOnlyHint=true, but description adds valuable context: returns empty array if org-scoped with no projects, and clarifies plan field is billing plan not permission. 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?

Description is concise yet comprehensive: single paragraph split into purpose, usage guidance, examples, and limitations. No fluff, every sentence adds value.

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 zero parameters and existence of output schema, description covers return fields, use cases, and edge cases (empty array, plan interpretation). Complete for a listing tool.

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

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

No parameters exist in input schema, so baseline is 4. Description adds no parameter information but none is needed; the tool is simple with no configuration.

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

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

The description clearly states the tool lists all accessible Clamp projects with id, name, and plan. It uniquely identifies the tool's purpose among siblings by specifying that it's for listing projects, contrasting with other tools like alerts, cohorts, 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?

Explicitly states when to use (e.g., user asks 'which sites do you see', need project_id) and when not needed (most tools auto-resolve for single-project). Includes concrete examples like 'which sites are tracked' and before drilling into specific project data.

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

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

Beyond the readOnlyHint annotation, the description details the MRR-on-MRR math, how mature_size works, and event requirements (e.g., $ prefix). No contradictions.

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?

Well-structured: purpose first, then math, then examples, then limitations. Every sentence adds value, and the description is front-loaded.

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

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

For a complex tool without an output schema provided, the description fully explains output concepts (retention_rate, mature_size, NRR) and how to interpret results. Covers limitations and edge cases.

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?

Defaults for cohort_event and windows are explained, and the $ prefix for events is highlighted. However, cohort_filter_property and cohort_filter_value are not described; schema coverage is only 17%.

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

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

The description clearly states the tool computes cohort revenue retention, anchoring at first cohort event and reporting user and dollar retention per window. It distinguishes itself from sibling 'cohorts.retention' by focusing on revenue metrics.

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?

Provides concrete examples of queries and mentions limitations (e.g., re-subscribers). Lacks explicit comparison to sibling tools like 'revenue.sum' but gives good context.

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?

Discloses key behaviors beyond readOnlyHint: never mixes currencies, attribution model differences, first-touch limitations, ad-blocker loss for client-only revenue. 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?

Description is long but well-organized into sections (core, attribution, examples, limitations). Front-loaded with purpose. A minor condensation could be beneficial, but every sentence earns its place.

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

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

Given 23 optional parameters, existence of output schema, and the complexity of revenue attribution, the description covers usage patterns, edge cases, and limitations comprehensively for an AI agent.

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% with clear descriptions. The description adds significant value: explains attribution models in detail, provides practical examples, clarifies default behaviors (no group_by gives total per currency, property omitted sums all Money properties).

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

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

The description clearly states the tool sums revenue from Money-typed event properties, returns per-currency totals, and optionally groups by a traffic dimension. It distinguishes from sibling tools (e.g., traffic.breakdown, funnels) by focusing on revenue summation.

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?

Provides explicit when-to-use (sum revenue) and when-not (events without Money property contribute zero). Includes examples and limitations (first-touch only supports acquisition dimensions, small-sample sensitivity). Does not explicitly name alternative tools but the context signals and sibling list provide differentiation.

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?

Discloses all return fields in detail, limitations (MRR requires mrr_delta, customer counting caveat), and is consistent with readOnlyHint=true annotation. No contradiction.

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?

Well-structured with clear opening, bulleted returns, examples, and limitations. Slightly long but every section serves a purpose. Front-loaded with the core purpose.

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?

Completely covers the tool's behavior with detailed return fields, usage examples, limitations, and alternatives. With 18 parameters and rich output, the description is exhaustive and actionable.

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 does not add new meaning to parameters beyond schema; it references parameters in examples but does not elaborate on individual parameter semantics.

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

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

The description clearly states the tool returns a revenue dashboard with specific KPIs, and distinguishes from siblings like revenue.sum and revenue.retention by stating when to use those instead.

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?

Provides explicit when-to-use guidance ('Use this for 'how's revenue doing?' questions') and multiple examples for different use cases (MRR, plan breakdown, etc.). Also recommends alternative tools for per-channel revenue or cohort retention.

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 indicate readOnlyHint=true. Description adds behavioral context: join nature, attribution constraints, default conversion event, and URL path matching. No contradictions.

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?

Description is thorough but well-structured: starts with core purpose, then details, examples, and limitations. Every sentence adds value.

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 complexity of joining two data sources, description covers purpose, usage, parameters, examples, and limitations. Output schema exists, so return values are not needed.

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 covers 100% of parameters. Description adds meaning: explains default conversion_event and project_id requirement when multiple projects. Period and limit are also clarified.

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?

Clearly states it joins Search Console metrics with Clamp's organic_sessions and conversions to answer which search traffic converts. Distinct from siblings like search.queries.

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 (e.g., 'which search pages convert') and provides examples. Also notes limitations like page-level only and URL path matching.

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, ensuring safety. The description adds useful behavioral context: data lags ~2 days, synced daily, and requires a connected Search Console property (returns empty list if none). This goes beyond what annotations provide.

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?

Well-structured, front-loaded with core definition, then use cases, examples, and limitations. Every sentence adds value, no fluff.

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 presence of an output schema (not shown but exists), return values are covered. The description covers purpose, limitations, prerequisites, and alternatives to other tools. Complete for the complexity.

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?

Input schema has 100% description coverage, but the description adds practical usage context (e.g., period examples, hint to call projects.list for project_id, default limit). This adds value beyond the schema.

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

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

The description clearly states it returns Google Search Console query metrics (clicks, impressions, CTR, position) for search terms that drove clicks. It explicitly distinguishes from sibling tool 'search.landing_pages' by noting that the latter covers post-click activity.

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?

Provides explicit when-to-use examples ('what are we ranking for', 'which queries drive the most clicks', 'where do we sit on [term]') and includes limitations (only queries with at least one click, no zero-click impressions). Also directs to a sibling tool for post-click data.

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

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

The description goes beyond the readOnlyHint annotation by detailing that the tool is aggregate-only, returns no per-user traces, no full pageview chains, and includes potential null durations for sessions without a pageview_end beacon. This adds important behavioral context.

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 concise and front-loaded with the main purpose. It uses examples effectively. However, it is a single paragraph without clear section breaks, which could be improved for scanning. Still, it is well-structured overall.

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

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

The description covers the return fields (top pairs, sessions count, avg pages, avg duration, bounce flag), limitations, and parameter guidance. With an output schema present and 100% parameter coverage, the description sufficiently completes the context for an agent.

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

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

The input schema has 100% coverage with descriptions for all 20 parameters. The tool description adds minimal extra value by showing examples and explaining min_pages behavior, but it largely repeats or implies what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool aggregates entry_page to exit_page session pairs and returns top pairs with metrics. It specifies the resource (sessions.paths) and the verb (aggregate). It distinguishes itself from siblings like events.list and users.journey.

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 provides explicit examples of when to use (e.g., 'what do visitors do after landing on /pricing') and when not to (e.g., 'use events.list for granular event analysis'). It also gives usage tips like setting min_pages=2 to exclude bounces.

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

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

The description adds significant context beyond the readOnlyHint annotation: it explains sorting by visitors descending, limit cap, joined columns for certain dimensions, and the raw format of the name column. It fully discloses behavior without contradiction.

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 structured with a clear summary, detailed dimension explanation, result format, examples, and limitations. Every sentence adds value, no 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?

Given the full schema coverage, readOnly annotation, and the description covering output shape, limitations, and examples, the tool definition is complete. The lack of an output schema is mitigated by the description specifying return fields.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by grouping dimensions by category (page paths, traffic sources, geography, etc.) and providing example usage. It clarifies the effect of the limit parameter and the extra columns returned for specific dimensions.

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

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

The description clearly states the tool aggregates visitors and pageviews grouped by a single dimension. It provides numerous examples covering all dimension categories, and the purpose is distinct from sibling tools like traffic.timeseries and traffic.compare.

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 explicitly mentions when to use alternatives: for custom event breakdowns use events.list with group_by, and for per-page time-on-page use pages.engagement. It implies usage context but could more directly contrast with traffic.overview or traffic.live.

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 indicate readOnlyHint=true, and description adds that percentage delta normalizes by ratio for unequal period lengths. No contradictions. Adds useful behavioral nuance.

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 concise paragraphs: purpose, examples, limitations. Front-loaded with key information. No extraneous text.

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 output schema present, description need not explain return values. Covers usage, examples, limitations, and parameter formats, fully adequate for a tool with 20 parameters.

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 covers 100% of parameters with descriptions. Description adds value with examples for metric, pathname, and period format, clarifying usage beyond 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?

Description clearly states it compares one metric across two periods, returning period values, delta, and percentage delta. It distinguishes from sibling 'traffic.overview' by noting that overview always includes the previous period.

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 specifies when to use: month-over-month, before-vs-after-launch, week comparison. Also states limitations (one metric per call, relative phrases not parsed) and suggests 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 indicate readOnlyHint=true. Description adds critical behavioral context: ingestion lag ~30s, approximate nature, visitor count definition as unique anonymous_ids, and limitations, which goes beyond annotation info.

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?

Description is brief yet comprehensive, with clear structure: purpose, use cases, examples, limitations. Every sentence adds value without 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?

Given the tool's simplicity (2 parameters, output schema present, annotations provided), the description covers all necessary aspects: purpose, when to use, tech details, and parameter usage. No gaps remain.

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% with detailed descriptions. Description adds value through examples (window_minutes defaults and max) and context for project_id usage, though it does not repeat schema details.

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?

Description clearly states the tool shows active visitors and top metrics within a time window, using specific verbs 'See' and 'Returns'. It distinguishes from siblings like traffic.overview by specifying real-time vs historical.

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 use cases are provided (incidents, launches) with example queries. Also states when not to use it (for historical questions, use traffic.overview), guiding appropriate tool selection.

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

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

Discloses key behaviors: always returns a comparison block with deltas, lists derived metric limitations (bounce_rate/avg_duration null for SDK<0.3), and specifies custom date range format and max range (365 days). Adds value beyond readOnlyHint= true annotation.

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?

Description is front-loaded with core snapshot characteristics followed by usage guidance, examples, and limitations. Concise enough; no filler. Could be slightly shortened but still well-structured.

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 18 optional parameters and an existing output schema, the description covers purpose, comparison behavior, limitations, and usage context thoroughly. It compensates for complexity without overwhelming detail.

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?

Input schema has 100% description coverage with detailed parameter definitions. The tool description adds minor contextual examples (e.g., period mappings) but does not heavily extend schema details. 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?

Clearly states it provides a high-level snapshot of traffic metrics (pageviews, visitors, sessions, bounce rate, session duration) and a comparison block. Unambiguously distinguishes itself from sibling tools like traffic.breakdown by positioning as the first call before drilling.

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 instructs to use this as the first call when the user asks 'how is the site doing', before diving into channels, pages, or funnels. Provides concrete examples mapping user queries to period values, offering clear decision support.

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 indicate readOnlyHint=true, which matches read-only behavior. Description adds critical behavioral details: automatic granularity based on period length, mutual exclusivity of metric and event, zero vs. skipped missing dates, and server-side truncation warnings.

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?

Well-structured with a clear initial statement followed by examples and limitations. The examples are particularly helpful but slightly increase length. Could be tightened slightly, but the content is valuable.

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 23 optional parameters, 100% schema coverage, and an output schema, the description is complete. It covers all major behaviors, limitations, and edge cases (e.g., mutual exclusivity, granularity override, zero counts). No apparent gaps.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds value by explaining parameter interactions (e.g., metric vs. event), selection patterns, and providing examples that illustrate parameter usage in context.

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

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

The description clearly states it returns traffic metrics over time as date buckets, with the output format [{ date, count }]. It distinguishes from sibling tools like traffic.overview (overview vs. time series) and traffic.live (live vs. historical).

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?

Provides explicit examples for different use cases (pageviews, visitors, bounce rate, custom events) and explains the mutual exclusivity of metric and event. Also details behavior of automatic granularity and limitations (e.g., metric vs. event exclusivity, truncation for long periods).

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 provide readOnlyHint=true. The description adds rich behavioral context: 365-day lookback default, session collapse with fields, is_first_touch flag, and limitations like requiring anonymous_id.

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

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

Well-structured: output description first, then use cases, examples, limitations, and pairing. Every sentence adds value with no 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?

Given high schema coverage, presence of output schema, and detailed description covering input, output, use cases, limitations, and cross-tool pairing, the description is fully complete for agent usage.

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 descriptions cover all 4 parameters (100% coverage). The description adds value by explaining the anonymous_id source (SDK getAnonymousId) and the period default's significance for first-touch meaning.

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

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

The description clearly states it provides 'chronological session history for a single visitor (anonymous_id)', specifying the verb (chronological session history), resource (single visitor), and scope. It differentiates from sibling tools like revenue.sum by focusing on individual-level analysis.

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 (multi-touch attribution, debugging) and when not to (aggregate queries). Provides alternative tool (revenue.sum with attribution_model) and warns against looping over thousands of users.

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