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

Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true), and the description goes further by disclosing the data flow: question text, schema, project ID, and dates may be sent to a configured AI provider, and the question is persisted to project history. It also adds a useful privacy advisory (avoid sensitive question text). This is solid added context beyond structured fields.

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, then mechanism, then the privacy constraint and parameter note. Sentences are dense but each adds distinct information with no filler; slightly wordier than strictly necessary.

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

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

An output schema exists, so return values need no explanation. The description covers purpose, execution paths, fallback behavior, privacy, and the one non-obvious parameter, which is sufficient for a two-parameter question tool.

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

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

Schema description coverage is 0%, so the description carries the burden. It usefully explains days (default window 1..366, overridable by recognized date phrases), but says nothing about the question parameter beyond the general purpose, leaving half the parameters implicit.

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

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

The description names a specific verb and resource (answer a natural-language analytics question, store its text in project history), which is clearly distinct from metric-reporting siblings like query_metrics and run_query. It does not explicitly name or route against those siblings, so it falls short of full sibling differentiation.

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

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

It implies when the tool applies (natural-language questions, with a deterministic planner for common ones and an explicit fallback for unsupported ones), but never states when to prefer it over siblings such as run_query or query_metrics. Usage context is implied rather than guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds nothing behavioral beyond the dimension list: no ordering (presumably top-N by count), no pagination, no statement about what the default 30-day window does.

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

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

A single front-loaded sentence with the dimension enumeration inline and no filler. It is efficient, though so terse it reads as a fragment rather than a complete task statement.

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 output schema exists, so return-value explanation is not required. Still, for a 3-parameter analytics tool with zero schema coverage and many sibling tools, the definition omits time-window and limit semantics and any routing guidance.

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

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

Schema coverage is 0%, so the description carries the burden. It usefully enumerates valid dimension values (which the schema lacks as an enum), but says nothing about days (time window) or limit (top-N count), leaving two of three parameters undocumented.

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

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

States a clear resource and action: returns top values for a dimension, and enumerates the valid dimensions. However, it does not distinguish itself from the sibling list_dimension_values, leaving real ambiguity about which to pick.

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

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

No when-to-use guidance, no exclusions, no named alternatives. With siblings like list_dimension_values, query_metrics, and compare, the agent gets no signal about when this tool is the right choice.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world call, so safety is covered elsewhere. The description adds genuinely new behavioral context: that observed changes are descriptive (not causal attributions) and that a null percent change means a zero baseline — an edge case an agent would otherwise misinterpret.

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

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

Two short sentences, no filler, with the core comparison scope front-loaded and the edge-case caveat following. Every sentence carries information.

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

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

An output schema exists, so return values need not be explained, and the analysis intent is stated. However, the lone input parameter is undocumented, the phrase 'changes are descriptive' is cryptic without further explanation, and there is no routing guidance among the many sibling report tools.

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

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

The single parameter 'days' has 0% schema description coverage and is never mentioned in the description. 'Equal-length previous period' hints that a window exists, but the unit, default of 30 and the current-vs-previous relationship are left entirely for the agent to guess, which is a real gap for a one-parameter tool.

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

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

The description names a specific verb (compare) and the concrete resources it compares — traffic, custom events and revenue — against an equal-length previous period. That is enough for an agent to know what the tool returns, but it never distinguishes itself from overlapping siblings like investigate_change, detect_anomalies or breakdown.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative is named despite several siblings (breakdown, investigate_change, detect_anomalies) that could plausibly serve similar 'compare a period' needs. The agent must infer placement purely from the tool name.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely valuable interpretive context: these are screening signals rather than significance tests, telling the agent how to treat and communicate results. It doesn't disclose the lookback window or return specifics, but the caveat is the important disclosure for a detection tool.

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

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

A single front-loaded sentence with minimal waste. It is somewhat telegraphic and relies on stacked parentheticals ('screening signals, not significance tests' and 'robust historical scores'), which slightly hurts parseability but keeps it compact.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. What's missing is any explanation of the sole parameter's time-window semantics and how spikes/dips are reported relative to sibling tools. Adequate but with a clear gap for a tool whose only knob is undocumented.

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 schema has 0% description coverage on the single 'days' parameter, so the description must carry meaning. It only implies a historical lookback ('historical scores') without stating that 'days' controls the window or what happens at the default of 30. The parameter's role is left for the agent to guess.

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

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

The description states a specific outcome: detecting unusual spikes/dips in pageviews and revenue using robust historical scores, which goes beyond restating the tool name. It clarifies the statistical character (screening signals, not significance tests). However, it never names or distinguishes itself against siblings like investigate_change or compare, so an agent must infer the boundary.

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 phrase 'screening signals, not significance tests' implies a triage/first-pass use case, which is useful context, but the description gives no explicit when-to-use guidance nor names any alternative. The distinction from investigate_change (root-cause) or compare is left entirely to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuine domain behavior beyond that: funnels are resolved by name or id, steps must be completed in order, and a visitor's segment is taken from their entry-step event. The entry-step attribution rule is non-obvious and valuable; only return shape and any pagination/limits are absent, and an output schema exists anyway.

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

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

Three sentences, front-loaded with the core purpose, then the matching rule, then the optional segment behavior. No filler, no repetition of the tool name, and each sentence adds distinct 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 an output schema exists, the description need not explain return values, and it provides the funnel-resolution rule and segment semantics that the schema omits entirely. It is close to complete for calling the tool, with the only soft spot being no explanation of the 'days' window or guidance on when to prefer this report over sibling reporting tools.

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

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

Schema description coverage is 0%, so the description carries the full burden for three parameters. It explains 'funnel' (match by name or id) and 'segment_by' thoroughly, including concrete examples and the entry-step attribution semantics, which goes well beyond the bare schema. Only 'days' (default 30) is left unaddressed, which is a small but real gap.

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

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

The description opens with a precise verb+resource: 'Conversion report for a funnel (match by name or id).' An agent can immediately tell this produces funnel conversion output, distinct from siblings like retention_report, goal_report, and breakdown. It stops short of naming a sibling to route against, so it earns a 4 rather than a 5.

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

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

It gives conditional guidance for one parameter ('Pass segment_by ... to compare conversion per segment'), which is real when-to-use advice. However, it never says when to choose funnel_report over siblings such as breakdown, compare, or retention_report, and no prerequisites or exclusions are stated. Usage is implied rather than framed against alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds two facts beyond them: the resource is 'immutable' (a property of the stored record, not this call) and the review note is 'separate' from the investigation, which hints at the payload's structure. With an output schema present, no further return detail is required.

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

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

One sentence, front-loaded with the verb and primary resource, no filler or redundancy. Every clause adds 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?

A low-complexity read tool with an output schema, so return values need no explanation. It is adequate overall, but the completely undocumented identifier parameter and lack of any usage context leave visible 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 0% and the single required parameter, investigation_id, is never described. 'Saved investigation' loosely implies what the ID points to, but no format, source, or example is given, so the description fails to compensate for the coverage gap.

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

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

States a specific verb ('Read') and resource ('saved investigation') plus an extra artifact ('human review note'). It is distinguishable from list_investigations by 'saved investigation' (singular fetch), though it never explicitly names the sibling it is not.

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

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

No when-to-use guidance, no prerequisites, and no routing to list_investigations or investigate_change. The purpose implies retrieval of an existing record but gives the agent no criteria for choosing this over the listing sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the fixed 30-minute window, which is real behavioral context, but says nothing about data freshness or update cadence for a 'live' endpoint.

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

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

A single tight sentence that front-loads the resource and lists the concrete contents with zero filler. Every clause earns its place.

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

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

With no parameters, full annotation coverage, and an output schema handling return values, the description only needed to establish scope and content — which it does. A note on freshness or supported granularity would complete it.

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

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

This tool takes zero parameters, so the baseline expectation is a 4. The schema is empty and the description correctly implies a no-argument call, adding nothing misleading.

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

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

States a specific resource (live activity) and enumerates the exact metrics returned — visitors, pageviews, top pages — plus the 30-minute scope. It is clearly distinguishable from the metrics-querying siblings like query_metrics or list_metrics, though it never names an alternative explicitly.

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

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

There is no when-to-use directive and no mention of alternative tools for historical or custom-range data. The 'last 30 minutes' phrasing implies a realtime use case, but the agent must infer when this beats query_metrics.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description goes beyond that by flagging what the report surfaces — denominator, repeated occurrences, missing identity — which is useful data-quality context an agent would not get from the schema.

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

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

Two tight sentences with no filler, and the operational rule about the time window is placed last where it is easy to act on. The opening metric clause is dense and slightly hard to parse, which costs it a point.

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

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

An output schema exists, so return values need not be described, and the windowing behavior is stated. What remains thin is the core semantic — what a 'period conversion' actually counts and how it differs from the funnel report — which an agent needs in order to pick this tool confidently.

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

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

Schema description coverage is 0%, so the description carries the burden. It does explain the date_from/date_to pairing versus days (the highest-risk ambiguity, since days defaults to 30), but goal_id's meaning and accepted format are never clarified, leaving one of four parameters purely name-dependent.

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?

It names the resource (a goal) and the metric it computes (unique visitors who had a pageview and then the goal), which is more than a restatement of the name. But 'Period conversion' is unexplained jargon and the description never distinguishes this from adjacent reporting siblings like funnel_report or retention_report.

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

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

It gives a concrete selection rule for the date parameters (use date_from/date_to together for an exact window, otherwise days governs). It offers no guidance on when to reach for goal_report versus funnel_report or compare, so sibling choice is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds the diagnostic insight that 'missing collection limits interpretation,' telling the agent how to reason about the output rather than just that the call is safe.

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

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

Two sentences, zero filler, with the scope (what is checked) front-loaded before the activation condition. Every clause earns its place.

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

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

An output schema exists, so return values need not be described. The description covers what is checked and when to run it; the only minor gap is guidance on what to do after discovering missing coverage.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly introduces no spurious argument concepts.

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

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

States a specific verb and resource: 'Check collection coverage and recency' for four named data domains (pageviews, custom events, funnels, revenue). This clearly separates it from data-returning siblings like query_metrics or breakdown, though it never names an alternative tool explicitly.

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

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

Gives an explicit trigger: 'Run this when results are empty or unexpected,' which is exactly the condition an agent needs to activate it. It does not state when not to use it or name the sibling to prefer under normal conditions, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: what the output contains (equal-duration comparison, additive source/device/browser/path changes, coverage, timeline notes, caveats, next checks) and the important epistemic caveat that it 'describes associations, not causes.'

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 tight sentences, front-loaded with the core action and no filler. Slightly jargon-dense phrasing ('additive source/device/browser/path changes') partly offsets the otherwise efficient structure.

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

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

An output schema exists so return-value detail is optional, and the description still usefully previews return contents. With 6 parameters at 0% schema coverage, the undocumented filters argument is the main remaining hole; otherwise the agent has enough to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does for metric, event_name, and the date_from/date_to vs days relationship. It says nothing about the filters parameter (field/value structure, limit of 30 values) or how days defaults when dates are supplied, leaving meaningful gaps.

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

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

States a specific verb+resource ('Investigate changes in pageviews, events, or event_count') and scopes which metrics are supported plus the event_name prerequisite. An agent can distinguish it from siblings like compare or breakdown, though it never names an alternative explicitly.

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

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

Gives conditional guidance for one parameter set ('Use date_from/date_to together... otherwise days determines it'), which is useful. However there is no when-to-use versus when-not, and no routing to alternatives such as compare or detect_anomalies for related questions.

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

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

Annotations already declare a safe read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds that it returns the *actual* observed values rather than a theoretical list, which is useful, but says nothing about the time window, result caps, or pagination.

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

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

A single tight sentence with the core behavior front-loaded and examples in parentheses. No filler.

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

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

With an output schema present, return values need not be described, and the annotations carry the safety profile. The description is nearly sufficient for a 2-param discovery tool, though the time-window semantics of 'days' remain unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate. It gives meaning to 'dimension' via concrete examples, but the 'days' parameter (time window, default 30) is never explained, leaving half the parameters undocumented.

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

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

States a specific verb ('discover which values') and resource ('a dimension'), with concrete examples ('real page paths, real UTM sources') that make the output shape clear. It is distinguishable from list_metrics in spirit, though it never names a sibling to sharpen the contrast.

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

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

The examples imply the use case (figuring out which concrete values exist before querying), but there is no explicit when-to-use, no exclusions, and no pointer to alternatives like breakdown or query_metrics. Usage is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description contributes the useful fact that goals are custom-event based, named, and ID-bearing (implying it is a discovery/ID-resolution step), but says nothing about scope, filtering, or whether the list is paginated.

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

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

A single front-loaded sentence with zero filler; the resource and the payload (names and IDs) come first.

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

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

With an output schema present, return values need not be explained, and a zero-parameter list tool needs little else. The only missing piece is how this list relates to goal_report, which would help an agent route 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?

The tool takes zero parameters, so per the rubric the baseline is 4 and there is no schema detail the description could usefully add.

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

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

States a specific verb (Discover) and resource (named custom-event conversion goals) plus what is returned (their IDs), so the agent knows exactly what this tool yields. It does not differentiate itself from the sibling goal_report or explain the relationship to it, which keeps it at a 4 rather than a 5.

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

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

There is no guidance on when to call this versus goal_report or the other reporting siblings, and no stated prerequisites. 'Discover' implies lookup-before-use, but that inference is left entirely to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so safety is covered. The description adds useful behavioral context with 'Recent' (temporal scope) and 'human review status,' but does not cover auth needs, pagination, limits, or ordering.

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 definition is a single, front-loaded sentence with no filler. Every word contributes to identifying the resource and the key returned attributes.

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, rich annotations, and an output schema, the description need not explain return structure or safety. It provides enough context to understand the listing scope, though it could be more complete by clarifying how it relates to get_investigation.

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

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

The tool takes zero parameters, and the rule states that zero parameters yields a baseline of 4. The description appropriately does not invent parameter details because there are none to document.

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

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

The description names a specific resource ('saved evidence records') and the returned fields ('IDs and human review status'), which lets an agent identify this as a listing tool for investigations. It does not explicitly distinguish itself from siblings like get_investigation or investigate_change, so it falls short of a 5.

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

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

There is no guidance on when to use this tool instead of get_investigation or other sibling tools. The description only states what the records are, leaving context and alternatives entirely to inference.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint false, closed-world), so the description doesn't need to restate safety. It adds nothing about scope, size, or refresh behavior, but an output schema exists and carries the return-value burden.

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

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

Two short sentences, front-loaded with the resource and immediately followed by the usage cue. No filler or redundancy.

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

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

For a zero-parameter discovery tool with full annotations and an output schema, the description supplies enough to select and call it. The only arguable gap is not naming the sibling query tools it precedes.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema coverage is 100% and no enums or nested objects exist.

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

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

The description states a specific resource ('available metrics and dimensions') and frames the tool as a catalog, which is distinct from the querying siblings like query_metrics. It never names those siblings, so the differentiation is implied rather than explicit.

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

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

'Start here to discover what you can query' gives a clear when-to-use cue that positions this as an entry point ahead of the query tools. It doesn't name an alternative tool or state any exclusions, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and non-open-world, so the safety profile is covered. The description adds 'Newest first,' which is a genuinely useful ordering behavior not present in structured fields. It still omits pagination, result limits, and whether all history is returned, leaving gaps beyond the annotation baseline.

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 terse clauses with no filler, and the ordering note ('Newest first') is placed at the end where it reads as an operational detail. It is a fragment rather than a full sentence, which slightly undercuts polish but wastes no space.

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

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

An output schema exists, so return-value structure needn't be explained, and annotations cover safety. For a simple no-param list tool this is nearly complete, but the description omits any mention of result volume, pagination, or time bounding, which an agent may need before invoking.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Per the rubric, a 0-parameter tool has a baseline of 4; the description does not degrade this.

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

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

The description identifies the resource (timeline annotations) and clarifies exactly what a note contains: launches, deploys, campaigns logged by the founder or an agent. This distinguishes it from sibling list tools like list_metrics or list_goals. However, the verb is implicit – it never states it 'lists' or 'returns' notes, relying on the tool name to supply that.

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

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

There is no guidance on when to use this tool versus alternatives such as get_investigation or ask. No exclusions, prerequisites, or context signals are given. The agent must infer usage purely from the name and content type.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds the report's contents but nothing behavioral beyond that — no pagination, refresh cadence, or auth requirements — so it is adequate but not rich.

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

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

One sentence, front-loaded with the resource and immediately followed by the returned fields. No filler or redundancy.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The only real gap is the unexplained 'days' parameter, which leaves the agent guessing at the default lookback semantics.

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

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

Schema coverage is 0% and the single 'days' parameter (default 30) is never mentioned in the description. Because coverage is below 50%, the description was expected to compensate for the undocumented window parameter and does not.

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

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

The description names a specific resource (this MCP server's agent usage) and enumerates the content returned: tool-call counts, error rates, recent questions. That is far more concrete than a tautology, but it never differentiates itself from the many metrics-oriented siblings such as list_metrics or query_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?

There is no statement of when to reach for this tool versus the sibling analytics tools, and no prerequisites or exclusions. The agent must infer from the name alone that this reports on MCP/agent traffic rather than product metrics.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that, such as whether results are cached, how the range is interpreted, or how missing data is handled. It also doesn't contradict the annotations.

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

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

Two terse sentences with the core purpose front-loaded and zero filler. It is arguably over-compressed into fragments, but nothing is wasted and scanning is trivial.

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

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

An output schema exists, so return format need not be explained, and annotations cover the safety profile. Still, the minimal text leaves usage routing and the days parameter's semantics unaddressed, making the definition only adequate for a multi-parameter analytics tool.

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

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

Schema description coverage is 0% and the schema defines no enum constraints, so the inline lists 'visitors|pageviews|sessions|events|revenue' and 'day|hour' are genuinely additive value over the schema. However, the 'days' parameter is completely unexplained — its unit, default of 30, and allowed range are left entirely undocumented, so compensation is only partial.

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

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

The phrase 'Time series for a metric' identifies the resource and the output shape, but the verb is only implied and there is no differentiation from siblings such as get_realtime, breakdown, compare, or list_metrics. An agent can guess it queries metric data, but nothing in the text distinguishes this tool's role from the many other report 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite a crowded sibling list containing several overlapping reporting tools. The agent gets no help deciding between query_metrics, get_realtime, breakdown, or compare.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real behavioral context: incomplete cohort cells are null, the cohort definition is fixed to first observation, and identities/acquisition history affect accuracy. It omits pagination/volume expectations but the output schema covers return shape.

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

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

Three compact sentences with no filler: report definition first, then the accuracy/null caveat, then parameter interaction. Every sentence carries information an agent needs.

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

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

For a read-only report with an output schema, the description supplies the cohort definition, the fixed 0..12 week horizon, null handling, accuracy caveats, and window semantics. The main gap is the absence of any routing guidance relative to the many sibling report tools.

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 0% schema description coverage, the description must carry parameter meaning, and it does: event_name's limited scope (returning activity, not cohort definition), and the mutual-exclusion rule between date_from/date_to and days. It leaves the date string format and the days default semantics only implicitly defined, so it is strong but not exhaustive.

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

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

The description names the specific artifact produced: weekly first-observed visitor cohorts over weeks 0..12, which an agent can identify as a retention/cohort report distinct from funnel_report or breakdown by subject matter. It lacks an explicit action verb and makes no direct sibling comparison, so it stops short of 5.

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

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

It clarifies parameter interaction (event_name restricts returning activity only; date_from/date_to together vs days alone), which is genuinely useful usage context. However, it gives no guidance on when to choose retention_report over sibling reports like funnel_report or compare, so selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds no behavioral context beyond the metric list — nothing about the time window semantics, aggregation behavior, or auth requirements. It neither contradicts nor enriches the annotations.

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

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

A single front-loaded sentence fragment with no filler — it is efficiently sized. It is a noun phrase rather than a sentence, which slightly undercuts clarity, but there is no wasted verbiage.

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

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

An output schema exists, so enumerating return values is largely redundant rather than additive. Given that, the description should carry the usage and parameter guidance, which it omits entirely: no time-range explanation for 'days', no sibling disambiguation. For a metrics tool among heavy metric siblings, it is under-described.

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

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

Schema description coverage is 0% and the single parameter 'days' (default 30) is never mentioned in the description. With low coverage, the description is expected to compensate, but it instead says nothing about the time window, its default, or allowable ranges. The parameter's meaning is left entirely to the bare schema.

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

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

The description names the resource and enumerates its outputs (revenue total, transactions, revenue-per-visitor, traffic-source breakdown), so an agent can infer it returns revenue attribution metrics. However, there is no verb (compute/return/report) and no differentiation from siblings like breakdown or query_metrics, which likely also produce metric aggregations. Purpose is implied rather than stated.

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

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

The description offers no when-to-use guidance, no exclusions, and no routing to alternatives. With siblings such as breakdown, query_metrics, compare, and goal_report that plausibly overlap with revenue analysis, the agent has nothing to disambiguate when this tool is the right pick.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely behavioral detail beyond the schema: filters are ANDed while values within a filter are ORed. It also notes the response includes resolved plan and caveats, though the output schema already covers that.

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

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

Front-loads purpose, then fields, then filter semantics, then a concrete example. Dense but every element is functional; slightly repetitive in listing filter fields also found in the example/schema, but not wasteful 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?

Covers the nested plan fields, cross-field dependencies, filter combination logic, and a worked example, which is substantial for a complex tool. An output schema exists so return values need not be spelled out, but default-value behavior on omitted fields is left to the schema.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it enumerates all plan fields, explains allowed values per field, states the cross-field constraint that event_name is required for event_count and dimension is for breakdown, gives date format (ISO UTC), limit range, and filter shape. This adds meaning the schema alone does not convey.

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

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

States a specific verb (Execute) and resource (typed analytics plan), and the phrase 'without AI or SQL' distinguishes it from the sibling 'ask' tool that presumably handles natural-language queries. It is clear what the tool does, though it doesn't name the alternative explicitly.

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

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

'Without AI or SQL' implies when this deterministic structured path is preferred over an NL/SQL path, but there is no explicit statement of when to use it versus siblings like query_metrics, breakdown, or ask. Usage is inferred rather than stated.

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