Agent Analytics

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the account-wide scoping constraint; it says nothing about what 'Filtered' means, whether results are aggregated per project, or how limit/period shape the output.

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

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

A single short sentence with no waste, and the scope qualifier is front-loaded. It is a verbless fragment rather than a sentence, which slightly reduces immediate parseability but costs no 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?

There is no output schema, so the description bears the burden of describing what is returned — bot traffic metrics, aggregation level, units, or per-project breakdown — and it does none of that. For an analytics endpoint whose whole value is the returned data, this is a substantial gap.

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

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

Schema description coverage is 100%, with both limit ('Max projects to include') and period ('Comparison period') documented and an enum on period. The description adds no additional meaning about these parameters, so the baseline 3 applies.

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

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

The description names a specific resource (automated/bot traffic) and a scope (all active projects in the account), which implicitly separates it from the single-site bot_traffic_overview and from all_sites_overview. However, it never names or contrasts with a sibling, and the fragment lacks a verb, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no reference to any alternative such as bot_traffic_overview for a single project. The agent must infer the usage context entirely from the name and the 'all active projects' scope phrase.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the returned content (totals, active project count, daily trend, top projects), which partially compensates for the absent output schema, but it says nothing about freshness, caching, or cost of the aggregation.

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 that states scope first and then lists the returned metrics. Every clause earns its place with no repetition or filler.

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

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

For a read-only aggregate with no output schema, enumerating the returned metrics plus the account-wide scope gives the agent enough to call it correctly; parameters are fully covered by the schema. It only lacks guidance on selecting this over the many analytics_* siblings.

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 both parameters (limit, period) are already fully documented with defaults, bounds, and an enum. The description only hints at the top-projects output that 'limit' governs and says nothing about 'period', so it adds no real meaning beyond the schema — the baseline 3 applies.

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

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

The description names the resource (account-wide project summary) and enumerates the concrete outputs: total events, active project count, daily trend, top projects. The phrase 'across all projects in your account' implicitly distinguishes it from project-scoped siblings like analytics_overview, but no sibling is named, 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?

Usage is implied by the scope phrase 'across all projects in your account,' which suggests this is the account-wide roll-up rather than a single-project view. However, there is no explicit when-to-use/when-not guidance and no alternative tool is named, leaving the agent to infer the boundary against analytics_overview and all_sites_bot_traffic.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about the anonymous-preview data restriction, but says nothing about result ordering, truncation, or aggregation behavior beyond the one-line ranking note.

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

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

Two compact sentences with the core purpose front-loaded and the environment limitation second. No wasted prose, though the parenthetical example list is slightly redundant with the schema's property description.

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 aggregation tool with no output schema, the description conveys what is returned well enough to call it safely, and the anonymous-preview caveat is important. It is nevertheless thin on return shape and ranking/pagination behavior for a tool whose whole value is the ranking output.

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

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

Schema description coverage is 100%, so all five parameters (days, event, limit, project, property) are already documented with types, ranges, and defaults. The description's example property keys (pages, referrers, UTM sources) loosely map to the 'property' param but add no syntax or semantics beyond the schema.

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

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

States a specific verb+resource: it returns top property values ranked by count, with concrete examples (pages, referrers, UTM sources). It is clear what the tool computes, though it does not explicitly distinguish itself from overlapping siblings like analytics_pages or properties.

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?

Adds a real usage condition: anonymous preview is restricted to synthetic read-only data and sign-in is required for real projects. However, it offers no guidance on when to prefer this over analytics_pages, analytics_paths, or properties, so selection among siblings is left to inference.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it specifies the return contents (per-step user counts, conversion rates, average time between steps) and discloses the anonymous-preview data limitation, which the annotations do not convey.

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

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

Three tight sentences: purpose first, then return contents, then access constraints. No filler, and the most important information (what it does) is front-loaded. Slightly dense but nothing wasted.

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

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

With no output schema, the description usefully summarizes the return shape (per-step counts, conversion rates, timing) and flags the anonymous-data limitation. Combined with 100% schema coverage, an agent has enough to invoke it correctly, though the funnel-vs-alternative decision remains implicit.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including defaults, ranges, and the enum. The description adds only the illustrative event-chain example, which loosely maps to the 'steps' parameter, so baseline 3 is appropriate.

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

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

States a specific analysis verb and resource: 'track where users drop off across a sequence of events', with a concrete example chain (page_view → signup → purchase). This clearly separates it from siblings like analytics_paths or analytics_retention conceptually, 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?

Provides useful auth/scope guidance ('Anonymous preview is limited to agentanalytics-demo synthetic read-only data; sign in for your own projects'), which tells the agent about data availability. However, it gives no guidance on when to choose a funnel versus paths, retention, or breakdown for a related question.

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

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

Annotations already establish readOnly/destructive/openWorld, so the bar is lower, and the description adds real value on top: times are in UTC, and the anonymous preview is restricted to synthetic read-only agentanalytics-demo data with sign-in required for real projects. It does not say anything about result size, sampling or refresh cadence, which would complete the picture.

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, purpose front-loaded, no filler. The second sentence runs the access caveat and the sign-in instruction together without clear punctuation, slightly hurting readability but not 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 no output schema, the description usefully sketches the return shape (day-of-week × hour grid with peak detection) and covers access scoping for the single required parameter. Reasonably complete for a read-only single-argument analytics call, though it omits any note on grid axes labeling or value units.

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?

One parameter with 100% schema description coverage ("Project name"), so the schema carries the semantics. The description adds no meaning about the project argument or its expected format, which is the baseline-3 case when schema coverage is complete.

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

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

The description names a specific, distinctive resource: a day-of-week × hour traffic grid with peak detection. That shape is unique among siblings like analytics_overview, analytics_breakdown or analytics_sessions, so an agent can differentiate it in practice, though no sibling is named explicitly and there is no leading verb ("Get"/"Return").

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 choose this over analytics_breakdown, analytics_overview or other time/path analytics tools. The only selection-adjacent content is the anonymous-preview/sign-in note, which is about data access rather than tool 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: anonymous access is restricted to synthetic read-only demo data and authentication is required for real projects — an auth/scope disclosure the annotations do not convey.

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

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

Front-loaded with the core capability in the first clause, followed by the access caveat. Two clauses, no filler, though the parenthetical metric list and the access note make the single sentence somewhat dense.

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

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

With no output schema, the description does carry return-value burden, and listing the metrics (events, users, bounce rate, session duration) and the trend/comparison shape gives an agent a reasonable picture of the output. It stops short of describing the response structure or how the comparison is rendered.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (period with enum and default, project name). The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific analysis type ('period-over-period comparison with trend') and enumerates the metrics it covers (events, users, bounce rate, session duration). It does not explicitly distinguish itself from siblings like analytics_overview or analytics_breakdown, so an agent must infer the difference from the metric 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 gives a prerequisite/context note (anonymous preview is limited to synthetic demo data; sign in for your own projects) but never states when to choose this tool over analytics_overview, analytics_breakdown, or the other analytics siblings. Usage is implied by the comparison framing rather than explained.

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 tool read-only, non-destructive, and closed-world. The description adds valuable context beyond those annotations by explaining the anonymous-preview data limitation and the sign-in requirement. It does not cover rate limits or response shape, so it is not a 5.

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

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

Two sentences, front-loaded with the tool's purpose and no filler. A missing period between 'session' and 'Anonymous' makes the second sentence run on slightly, but overall it is appropriately sized and 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 the rich schema and read-only annotations, the description supplies the key metrics and the anonymous-preview caveat. No output schema exists, but naming bounce rate, avg duration, and events per session gives enough return-value context. More detail on the entry/exit distinction or result shape would make it complete.

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

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

Schema description coverage is 100%, so the type, limit, and project parameters are already documented. The description mentions entry/exit page stats, which loosely aligns with the type enum, but adds no new semantic detail such as allowed values or defaults. Baseline 3 applies.

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

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

The description names the specific resource and metrics: 'Entry/exit page stats with bounce rate, avg duration, events per session.' An agent can tell what data this returns. It does not explicitly distinguish itself from siblings like analytics_overview or analytics_paths, so it falls short of a 5.

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

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

It provides useful setup context: the anonymous preview is limited to synthetic demo data and signing in is required for real projects. However, it says nothing about when to choose this tool over alternatives such as analytics_overview, analytics_breakdown, or analytics_paths.

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. The description adds genuinely useful context beyond that: it accepts empty input, existing plan and access checks are retained for queries, and anonymous preview is restricted to a synthetic read-only demo dataset requiring sign-in for real projects.

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

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

Four short sentences, front-loaded with the usage trigger, with no filler. Slightly dense with the auth/dataset caveats stacked at the end, but every sentence carries 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?

For a zero-parameter UI-opening tool with full annotation coverage and no output schema, the description covers trigger, input expectation, and access/auth behavior. It does not clarify what the tool returns or whether the panel must be opened before querying, which would be the last missing piece.

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

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

The tool takes zero parameters, so the baseline is 4, and the description correctly states that it accepts empty input, which keeps the agent from hunting for required arguments.

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 action on a specific resource: opening a compact project/view picker to explore a project's analytics alongside the conversation. It is clear what the tool does, but it never names or contrasts itself with the many sibling analytics_* tools, so an agent must infer that this is the interactive panel rather than a data query.

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

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

"Use this when you want to explore an authorized project's analytics beside the conversation" gives a clear trigger condition, and the sign-in note implies the boundary for anonymous use. However, no alternative tools are named for agents who want raw data instead of the panel, so the routing guidance is contextual rather than explicit.

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 and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the analysis is 'bounded,' terminates at goal/drop-off/truncation, and the anonymous preview is restricted to synthetic read-only demo data with sign-in required for real projects — useful auth and data-scope disclosure.

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, front-loaded with the core purpose before the usage hint and the environment/auth caveat. Little waste, though the preview/auth sentence could be slightly tighter.

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 analysis tool with full schema coverage and no output schema, the description covers scope, termination behavior, and auth/data limitations adequately. It stops short of clarifying return structure or how results relate to sibling funnel/retention tools, but nothing critical to invocation is missing.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema. The description's mention of 'bounded' and 'truncation' loosely relates to max_steps and candidate_session_cap but adds no format or syntax detail. 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 gives a specific verb and resource: 'bounded session path analysis from entry pages to goal, drop-off, or truncation.' It clearly states the analysis type, though it does not explicitly distinguish itself from siblings like analytics_pages or analytics_sessions, which also deal with page/session behavior.

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 says it is 'useful for connecting page behavior to funnels, retention, and experiments,' which implies a usage context but never states when to prefer this tool over the named siblings (analytics_funnel, analytics_retention) or any when-not conditions. Usage is implied rather than directed.

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, closed-world safety, so the description adds meaningful extra context: default retention semantics, the mode switch, and that anonymous access is confined to synthetic read-only demo data with sign-in required for real projects. It omits output shape and performance notes, but adds real value beyond the annotations.

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

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

Three short sentences, front-loaded with the core purpose, then default behavior, then the auth/preview caveat. Every sentence carries information; no filler.

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

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

With no output schema, the description does not need to explain return values, and annotations cover the safety profile. It addresses defaults, mode switching, and access constraints, leaving only minor gaps such as pagination or result formatting for a 5-param read 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 coverage is 100%, including descriptions for event, period, cohorts, project, and returning_event, so the schema carries the parameter burden. The description only reinforces the event parameter's mode-switching effect, adding marginal value above the schema, which is the expected baseline of 3.

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

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

States a specific verb and resource ('Cohort retention analysis — track what % of users return over time'), which clearly distinguishes it from siblings like analytics_funnel, analytics_breakdown, or analytics_paths. An agent can identify the analysis type without opening the schema.

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

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

Explains the default mode (session-based retention) and the condition that switches behavior ('Pass event to switch to event-based retention'), plus the anonymous-preview restriction. It does not name an alternative sibling to use instead when retention isn't the right analysis, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a genuine access constraint (anonymous preview limited to demo synthetic read-only data, sign in for real projects), which is useful, but says nothing about the return shape or bucketing behavior beyond a one-line summary.

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

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

It is short and front-loads the purpose, but the missing punctuation between 'median bucket' and 'Anonymous preview' runs two unrelated ideas together, making it read as one garbled sentence. It is compact yet structurally sloppy.

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 low-complexity read tool with one required parameter and no output schema, the description conveys only a rough sense of the return (histogram, engaged percentage, median bucket). It does not explain the shape of the result or how this report relates to the similarly named sibling, so it is only minimally adequate.

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

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

There is a single 'project' parameter with 100% schema description coverage, so the schema carries the parameter semantics. The description adds no syntax, format, or scoping detail for the project argument, so the baseline of 3 applies.

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

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

The description states a concrete output: a session duration histogram showing engaged percentage and median bucket. It's clear what data the agent gets, but it never distinguishes itself from the similarly named sibling 'sessions' or from analytics_overview, leaving selection ambiguous.

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 indication of when to use this tool versus alternatives such as 'sessions' or 'analytics_overview'. The only condition mentioned is the anonymous-preview/sign-in limitation, which is an access note rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by listing the returned content categories, but says nothing about rate limits, auth, or aggregation behavior.

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

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

A single compact sentence with the resource and content scope front-loaded and no filler. It is a noun phrase rather than a full verb statement, which is slightly less informative but not wasteful.

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

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

With no output schema, the description usefully enumerates the returned content (automated requests, dropped events, categories, top actors), which is the key thing the agent cannot learn from structured fields. Only the missing period-selection guidance keeps it from being fully complete.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description's mention of 'top actors' loosely corresponds to the limit parameter, but adds no syntax or semantics beyond what the schema provides.

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

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

States a specific resource (automated traffic) scoped to 'a single project', with an enumeration of what it covers: automated requests, dropped events, categories, top actors. The 'single project' scoping implicitly differentiates it from the sibling all_sites_bot_traffic, though the sibling is not named.

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

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

Usage is only implied by the 'single project' scope, which suggests it as the per-project counterpart to all_sites_bot_traffic. There is no explicit when-to-use, prerequisites, or named alternative, so an agent must infer the routing decision.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not mention required inputs, whether variants/weights must be balanced, or what happens on duplicate names. With annotations present the bar is lower, but there is still zero added 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 single sentence is front-loaded and wastes no words, but for a mutation tool with four required parameters it is under-specified rather than truly concise. Brevity here comes at the cost of useful context.

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?

This is a write operation with four required parameters, no output schema, and no annotations detail beyond the safety hints. The description says nothing about required fields, weight defaults, or the returned experiment identifier, leaving real gaps for an agent invoking 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?

Schema description coverage is 100%, so all five parameters (including the required project, name, variants, goal_event) are documented in the schema with examples for weights and variants. The description adds no syntax, defaults, or constraint information beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Create' + 'A/B experiment'), which is unambiguous. It does not differentiate from siblings such as create_project or update_experiment, but the verb+resource pairing is distinctive enough to identify the operation.

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 (e.g., update_experiment for existing experiments). The agent must infer everything 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely non-derivable behavior: idempotency on duplicate names and the shape of what comes back (tracking snippet, API example). It does not disclose auth requirements or side effects on existing projects beyond the idempotent case.

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

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

Three short sentences, front-loaded with the core action and followed by the two facts an agent most needs (return payload and idempotency). No filler or restatement of the name.

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

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

With no output schema, the description usefully names the return payload and the idempotency behavior, which covers the main gaps for a 2-param creation tool. Minor omissions remain around auth/permission needs and what happens to non-name fields on a name collision.

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 both parameters (name format constraints, allowed_origins default '*') are fully documented in the schema itself. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the work.

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

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

The description states a specific verb+resource ('Create a new Agent Analytics project') and adds the return payload, making the operation unambiguous against siblings like list_projects or get_project_context. It stops short of explicitly naming which sibling to use instead when a project already exists.

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

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

Usage is only implied — an agent can infer this is the setup step before experiments or tracking, but there is no explicit when-to-use, no prerequisites (e.g. auth/account requirements), and no routing to alternatives such as list_projects for existing projects.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is carried by structured data. The description adds nothing about irreversibility, whether deletion is soft or permanent, or required permissions — the exact context a destructive operation needs.

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

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

It is a single short phrase with zero padding, so there is no wasted text. However, this brevity comes from under-specification rather than disciplined conciseness, so it cannot score above the minimum viable level.

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

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

For an irreversible destructive operation with no output schema, the description should at minimum state that the deletion is permanent and what happens to the referenced experiment. The annotations cover the destructive flag, but the description leaves the agent without operational context.

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

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

Schema description coverage is 100% with a single well-documented 'id' parameter ('Experiment ID'), so the schema already does the full job. The description contributes no additional parameter meaning, which is acceptable at the baseline 3.

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

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

The description 'Delete an experiment' is a near-verbatim restatement of the tool name delete_experiment, adding no distinguishing information. It is a verb+resource, but the agent learns nothing it did not already know from the name itself.

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 mention of related siblings such as get_experiment or update_experiment that an agent might reasonably reach for first. Nothing tells the agent under what conditions deletion is appropriate.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond that: anonymous access is restricted to agentanalytics-demo synthetic read-only data, and signing in is required for real projects. That is a meaningful auth/data-scoping disclosure, though it says nothing about pagination or result size.

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

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

The purpose is front-loaded, but the description is a run-on with no separator between the functional sentence and the preview/auth note ("...with results Anonymous preview..."), which reads as two sentences accidentally concatenated. Size is small, but the structure cost is real.

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

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

For a one-parameter getter with no output schema, the definition covers the operation and the environment limitation. The absence of an output schema means return values need not be described, though "with results" is only a hint about what comes back. Adequate for the tool's 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?

Single required parameter with 100% schema description coverage, so the schema already documents "id". The description adds nothing about id format or where to obtain it (e.g., from list_experiments). Baseline 3 is appropriate.

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

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

States a clear verb+resource pair ("Get experiment details with results") that separates it from create_experiment, update_experiment, delete_experiment, and list_experiments by implying a single-item detail fetch. It does not explicitly name a sibling or contrast scope, so it stops short of a 5.

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

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

There is no guidance on when to call this versus list_experiments or get_project_context. The only conditional information is an environment/auth caveat about the anonymous preview, which is not usage routing. An agent must infer that a single id yields one experiment.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — the anonymous preview is restricted to agentanalytics-demo synthetic read-only data — but says nothing about size, caching, or how often the 'self-improving' context refreshes.

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, no filler, and the payload list is front-loaded before the access caveat. The colon-separated inventory is dense but readable; nothing obviously wastes 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?

For a single-parameter read tool with no output schema and annotations covering the safety profile, the description covers what is returned and who can call it. Return shape details are modestly under-described, but the conceptual contents (goals, glossary, date annotations) are listed.

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

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

Only one parameter exists and schema coverage is 100% ('Project name or ID'), so the schema fully documents it. The description adds no format hints such as whether the project value is a slug, UUID, or display name, which would be the only meaningful contribution here.

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

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

The description names a specific verb and resource ('Get ... project context') and enumerates the payload — goals, activation events, event-name glossary, date annotations. It is clearly distinct from sibling mutators like set_project_context, though it never explicitly contrasts itself with list_projects or the analytics_* readers.

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

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

Usage is only implied: the clause about interpreting analytics results hints you fetch this before running analytics queries, but no explicit when-to-use, when-not-to-use, or named alternative is given. The sign-in note is access guidance rather than selection 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuine value beyond that by disclosing the auth/preview constraint: anonymous access is restricted to synthetic read-only demo data and requires sign-in for real projects. It stops short of describing pagination or result size limits for a list operation.

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 purpose is front-loaded in the first clause, which is good, but the second clause is spliced onto it without punctuation ('for a project Anonymous preview is limited to...'), creating an ambiguous run-on. The content is short but structurally sloppy.

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 one-parameter list tool with annotations covering safety and no output schema, the description covers purpose and the notable access restriction. It is nearly complete; only listing behavior (ordering, pagination, empty results) is unaddressed.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema fully documents 'project'. The description's phrase 'for a project' merely echoes that parameter without adding format, default, or lookup guidance. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (A/B experiments) scoped to a project, so the agent knows exactly what it returns. It does not, however, distinguish itself from siblings like get_experiment, list_projects, or the other experiment CRUD 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 statement of when to use this tool versus get_experiment (single experiment) or the analytics_* siblings. The only contextual clause is about anonymous preview limits, which is auth context rather than usage routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the anonymous-preview response is limited to synthetic read-only demo data, which tells the agent what it will actually receive before authenticating.

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 purpose is front-loaded, but the two clauses run together without punctuation ('projects Anonymous preview...'), making the auth caveat read as a continuation of the object rather than a separate sentence. The content earns its place; the formatting does not.

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 list tool with no output schema, the description covers purpose, auth behavior, and result limitations. It omits what a project record contains, but the agent needs nothing further to invoke the call correctly.

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

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

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. The description correctly implies the call is parameterless and scoping is determined by authentication state rather than arguments, which is the relevant semantic point.

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

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

States a specific verb and resource ('List all your Agent Analytics projects'), so the agent knows exactly what comes back. It does not distinguish itself from the sibling create_project or explain the difference between this and project-scoped tools, but the core purpose is unambiguous.

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

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

It gives conditional context — anonymous preview yields only the agentanalytics-demo synthetic read-only dataset, and signing in is required for real projects — which is genuinely useful for deciding whether the call is worth making. However, it never states when to call this versus create_project or the project-scoped analytics tools, so usage 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: the data comes from an in-memory ring buffer and issues no D1 query, which tells the agent the call is cheap, non-persistent, and bounded in history. It stops short of stating retention limits or latency figures.

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

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

Two sentences, both front-loaded: the payload is listed first, then the implementation detail that determines cost. No filler, no restatement of the tool name.

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

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

There is no output schema, but the description compensates by enumerating the returned fields, which is the most important missing piece for this tool. Combined with annotations covering the safety profile and a fully documented schema, an agent has nearly everything needed; only retention/refresh semantics of the ring buffer are unstated.

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

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

Schema description coverage is 100% — both 'window' (10-300s, default 60) and 'project' are documented inline. The description adds no further parameter meaning (e.g. how 'window' interacts with the 'events per minute' figure), so the baseline of 3 applies.

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

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

Names a specific artifact ('Real-time snapshot') and enumerates exactly what it contains: active visitors, sessions, events per minute, top pages, recent events. That is far more specific than sibling names like analytics_overview or sessions, though it never explicitly contrasts itself with those 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?

Usage is only implied: the word 'Real-time' plus the 'no D1 query' note signal that this is for live monitoring rather than historical analysis, but there is no explicit when-to-use/when-not statement and no named alternative (e.g. analytics_overview, query).

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

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

Annotations already declare readOnlyHint/destructiveHint=false and openWorldHint=false, but the description adds genuinely new operational context: anonymous preview is restricted to agentanalytics-demo synthetic read-only data and real data requires signing in. That is exactly the kind of auth/scope detail annotations do not carry. It does not disclose return shape or whether 'recent' is bounded by the days parameter.

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

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

It is short, but the two clauses are run together without punctuation ('...recent events Anonymous preview...'), creating a readability defect, and the auth sentence sits after the core purpose rather than being framed as a separate note. Size is appropriate; structure is sloppy.

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

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

For a 2-parameter tool with no output schema and full schema coverage, the description adequately states what is returned (event names and property keys) and flags the data-access restriction. It omits any relationship to properties_received or the fact that results are scoped by the days window, which an agent choosing between the two would need.

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 'days' (lookback window) and 'project' are already fully documented in the schema. The description adds nothing about parameter semantics beyond 'recent events', so the baseline 3 applies.

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

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

The first clause gives a specific verb and resource: 'Discover event names and property keys from recent events.' An agent can tell this is a discovery/metadata tool. However, it never differentiates itself from the near-identical sibling properties_received, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus query, properties_received, or the other analytics siblings. The auth note ('sign in for your own projects') describes a constraint, not a usage condition, so the agent is left to infer applicability from the purpose sentence alone.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description does add real value beyond them by disclosing the sampling behavior and the auth/scope constraint ('Anonymous preview is limited to agentanalytics-demo synthetic read-only data; sign in for your own projects'), which tells the agent when results will be demo data rather than real data. It still says nothing about pagination, limits, or the shape of the returned keys.

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

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

It is short, but the two ideas are run together without punctuation ('...recent events Anonymous preview is limited to...'), which hurts readability and makes the disclaimer read as part of the functional clause. The functional statement is front-loaded, which is the right ordering.

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

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

With no output schema, the description is the only place that can explain the return shape (keys grouped per event name) and it does not. It also omits any differentiation from the sibling 'properties', leaving an agent unable to choose between the two from the definition alone.

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 'since', 'sample' and 'project' are already fully documented in the schema. The phrase 'sampled from recent events' loosely echoes the 'sample' and 'since' parameters but adds no syntax, default, or interaction detail beyond the schema. Baseline 3 applies.

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

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

The fragment 'Property keys by event name, sampled from recent events' communicates the resource returned but supplies no verb and no scope, so it is closer to a label than a stated purpose. A sibling tool literally named 'properties' exists, and nothing here distinguishes the two, which is exactly the differentiation the description should have provided.

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

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

There is no when-to-use guidance at all: no condition, no prerequisite, and no mention of the closely named sibling 'properties' or any alternative such as 'query' or 'analytics_breakdown'. The agent must infer usage entirely from the 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?

With annotations already declaring readOnlyHint=true, openWorldHint=false, and destructiveHint=false, the description adds substantial behavioral context. It explains the privacy-first email lookup, states that raw email is sent only in the authenticated HTTPS POST body and not stored in event rows or profile traits, notes that invalid filter fields fail loudly, and details count_mode fallback semantics. These are meaningful operational traits beyond the annotations.

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

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

The description is long but front-loaded: it begins with purpose and usage guidance, then examples, then parameter and behavioral details. For an 11-parameter analytics query tool with no output schema, most of the length earns its place, though some parameter details are repeated from the schema and the phrase 'the most powerful endpoint' is subjective. It is comprehensive but not maximally tight.

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, the 11-parameter schema, and the absence of an output schema, the description is complete enough for an agent to call it correctly. It covers purpose, usage context, examples, filter syntax, field naming rules, privacy behavior, grouping, metrics, and count modes. Nothing critical appears to be missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds useful meaning beyond the schema. It lists filter operators and filterable fields, clarifies that event properties must be queried as properties.referrer, properties.utm_source, etc., and provides concrete examples showing how filters, group_by, metrics, and date_from combine. Some parameter details are duplicated by the schema, but the examples and closed-list clarification add real value.

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

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

The description states a specific verb and resource: 'Run a flexible ad-hoc analytics query' with custom metrics, filters, grouping, date ranges, and email lookup. It also distinguishes this tool from siblings by calling it 'the most powerful endpoint' and saying to use it 'when other tools don't answer the question.' An agent can immediately understand what this tool does and how it differs from the surrounding analytics tools.

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

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

It gives clear usage context: use this when other tools don't answer the question, and it provides concrete example questions. However, it does not name specific sibling alternatives or explicit when-not scenarios beyond the general 'other tools' framing. The guidance is clear but not maximally explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful access context — anonymous preview is restricted to synthetic read-only demo data and requires sign-in for real projects — but says nothing about ordering, pagination behavior, or what a session record contains.

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

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

It is short and front-loads the purpose, but the two sentences run together without punctuation ("records Anonymous preview..."), which slightly obscures the boundary between function and access note. No wasted marketing language, though.

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 list tool with no output schema and annotations covering safety, the description covers access scope but omits the return shape and ordering. An agent could call it correctly, but not predict what it gets back or how it relates to analytics_sessions.

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 limit, since, and project are already documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, which matches the baseline for a fully-covered schema.

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

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

The description states a specific verb and resource ("List individual session records"), which is clear on its own. However, it never differentiates itself from the sibling tool analytics_sessions, leaving the agent to guess whether "individual session records" means raw sessions versus an aggregated session metric.

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 analytics_sessions or analytics_overview, and no stated prerequisites or exclusions. The second sentence addresses authentication scope, not usage selection, so the agent gets no routing help.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the replace semantics are partly covered. The description still adds real value beyond the annotations: the 512KB cap on the encoded request body and the read-first/merge workflow, which tells the agent this is a whole-context overwrite rather than an incremental append. It does not detail the response or failure behavior.

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

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

Front-loaded with the core action and constraint, then the operational workflow, then the inclusion/exclusion guidance. Information-dense with essentially no filler, though the middle sentence packs several clauses into a run-on that could be broken up for readability.

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

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

For a destructive write tool with no output schema, the description covers the safety profile (via annotations), the size limit, the read-merge-save workflow, and detailed content inclusion/exclusion rules. An agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the semantic intent of the fields - what qualifies as 'durable product truth' for goals, activation events, glossary entries, and annotations, and which events are meaningful for annotations. This adds interpretation the schema 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?

States a specific verb ('set or replace') and resource ('compact project context'), and the instruction to 'read existing context first' implicitly distinguishes it from the read counterpart get_project_context. An agent can identify both what it does and how it differs from the sibling read tool.

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

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

Gives explicit when-to-use guidance (save only durable product truth tied to goals, activation events, glossary, date annotations; use annotations for landing page/pricing/onboarding/feature/release/experiment changes) and explicit when-not (no git commit logs, noisy edits, PII, secrets, or long release notes). It also prescribes a read-merge-save workflow. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds nothing beyond that — it does not say that completing likely finalizes results, that changes may be irreversible, or whether a winner must be supplied. The status labels it lists (pause/resume/complete) don't even match the schema enum (active/paused/completed), a small inconsistency.

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

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

A single short sentence with the core operation front-loaded and zero filler. It is efficient, though so terse that it omits useful context rather than trimming fat.

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 small 3-parameter mutation with full schema coverage and destructive annotations, the essentials are arguably covered, but an agent completing an experiment needs to know that 'winner' matters in that case and whether the change is reversible — neither is addressed.

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 both required parameters and the optional 'winner' are already documented; baseline 3 applies. The description's parenthetical loosely hints at status values but uses different wording than the enum and never mentions 'winner' or when it is needed.

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 (Update) and resource (experiment) plus the field being changed (status), with the possible transitions named. It does not, however, distinguish itself from siblings like delete_experiment or the create/get experiment tools, so an agent still has to 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?

There is no indication of when to choose this over delete_experiment, create_experiment, or get_experiment, nor any prerequisites (permissions, whether a completed experiment can be reopened). The parenthetical enumerates actions but gives no routing guidance.

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