This is not longer maintained - use the official one
Ask your Google Analytics 4 property how the site is doing: traffic, pages, events, audit.
Scored across 12 tools
Most tools have clearly distinct purposes, and descriptions explicitly separate close pairs like list_referrers vs list_traffic_sources and list_pages vs search_pages. A few pairs remain adjacent enough that an agent could initially hesitate, but the descriptions resolve the confusion.
The majority of tools follow a readable verb_noun or list_noun/search_noun pattern: list_countries, list_events, search_pages, audit_site, configure_site. live_visitors and site_status deviate, but the overall convention is still predictable.
Twelve tools is well-scoped for GA4 read/reporting, setup, audit, and realtime needs. Each tool occupies a clear slot, and there is no obvious padding or missing essential category.
The surface covers setup, auditing, overview metrics, dimensions, events, pages, referrers, traffic sources, search, and realtime visitors. Minor gaps exist around managing the saved default property, updating/deleting properties, or configuring key events, but core analytic workflows are covered.
How the property is measuring, rather than what it measured. Sixteen checks: whether anything is marked as a key event and whether those events ever fire, whether outcomes are arriving unmarked, whether the stream is measuring what it was told to and recording what it measures, whether purchases carry their revenue, whether page views are counted twice, whether the site or a payment page is crediting itself with conversions, whether an event stopped firing between one window and the one before, whether the tag is firing on a development machine. Each finding is graded and carries what it means, and some carry a fix naming the one thing that would repair them — craft audit --fix is what applies those, and this tool never does. Run this before trusting the numbers from any other tool, and whenever a number looks wrong — most numbers that look wrong are being measured wrong.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context beyond them, disclosing that findings are graded, that some carry a `fix` field, and crucially that this tool never applies fixes ('craft audit --fix is what applies those, and this tool never does'). With no output schema present, this return-shape disclosure carries real weight.
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 key differentiator ('how the property is measuring, rather than what it measured') is front-loaded, and every sentence contributes. The long repetitive 'whether...whether...' enumeration of checks is informative but slightly bloated, keeping it from a 5.
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 two-parameter, zero-required audit tool with minimal annotations and no output schema, the description supplies everything needed: what is checked, what the output looks like (graded findings with optional fixes), that fixes are not applied here, and when to run it. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the 'days' lookback window and the omit-to-use-default behavior for 'property,' so the schema fully documents both parameters. The description adds nothing about parameter syntax or semantics, which is the expected baseline 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?
The description states a specific verb+resource ('audit' the measurement of a property) and immediately distinguishes itself from the reporting siblings by framing it as 'how the property is measuring, rather than what it measured.' The enumeration of sixteen concrete check categories makes the scope unmistakable versus list_events, list_pages, live_visitors, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use guidance: 'Run this before trusting the numbers from any other tool, and whenever a number looks wrong.' That implicitly excludes using it as a reporting tool, but no sibling is named as an explicit alternative for the reporting case, keeping it just 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.
Set up GA4 for a domain the account does not measure yet: creates the property and its web data stream and returns the gtag.js snippet to paste into the site's . Re-running for a domain that already has a stream returns that tag instead of creating a second property. This is the one tool that writes to the Analytics account — and it still never changes which property is the saved default.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain to set up, e.g. example.com. A pasted URL is trimmed to its host; ports, paths and emails are refused. | |
| account | No | The GA4 account to create the property under, by numeric id or display name. Only needed when the login can see more than one. | |
| currency | No | ISO 4217 reporting currency for the new property. | USD |
| timezone | No | IANA time zone for the new property, e.g. Europe/London. Otherwise the machine's own is used, and the answer says when it fell back to UTC. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and openWorldHint=true; the description goes well beyond that by disclosing the two created resources, the returned snippet, idempotent re-run behavior that avoids a second property, and an explicit side-effect boundary ('still never changes which property is the saved default'). For a mutating tool with no output schema, that is rich 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?
Three sentences, all load-bearing: the first covers the create-and-return action, the second the idempotency rule, the third the mutation-scope boundary. The most important facts are front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations carrying behavioral detail, the description still covers what is created, what is returned (the gtag.js snippet), re-run semantics, and the boundary of what is not modified. An agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents domain, account, currency, and timezone, and the description adds no syntax or format detail beyond it. It only implies the domain parameter's role through the setup narrative, which lands at the baseline for a fully-documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('creates the property and its web data stream'), and names the concrete artifact returned ('the gtag.js snippet to paste into the site's <head>'). This clearly separates it from the read-only siblings like list_properties and site_status without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition ('a domain the account does not measure yet') and explains the re-run case, so the agent knows when the tool is idempotent rather than duplicative. It also flags that this is the only writing tool among the siblings, which is a strong routing signal, though it never names a specific alternative tool to use instead when the domain is already measured.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Countries the period's users came from, ranked by users.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral fact — output is ranked by users — but says nothing about the default window, row cap, or that the period is bounded by the 'days' parameter ending yesterday.
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 resource front-loaded and no filler. Its brevity, however, shades into under-specification rather than tight economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return shape; it tells the agent the rows are countries ranked by users but not what columns come back. Combined with no usage context, the definition is only minimally sufficient for a GA4 reporting 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 100%, so 'days', 'limit', and 'property' are fully documented in the schema. The description adds no parameter-level meaning beyond that, making the baseline 3 correct rather than a deficiency.
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 the resource (countries) and the ordering behavior (ranked by users), which lets an agent distinguish it from list_pages, list_referrers, and list_traffic_sources at a glance. It never uses an explicit verb like 'list' or 'return', and 'the period's users' is vague, but the resource + ranking is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no mention of any sibling or alternative, despite ten siblings including several other list_* traffic breakdowns. The agent must infer that this is the country-dimension slice of a traffic report.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Events over the period, ranked by count, with the per-day total for this period and the one before it so a rise or fall is visible.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavioural detail beyond that: results are count-ranked and include per-day totals for both the current and preceding period, which is exactly the return-shape context an agent needs given there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the rationale clause 'so a rise or fall is visible' justifies the comparison behaviour rather than padding. It is slightly run-on but every clause 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?
With no output schema, the description does useful work describing the ranked plus two-period per-day return content, and defaults are covered in the schema. But for a tool sitting next to search_events it omits the routing information that would make selection unambiguous, leaving a real 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 each of days, limit and property fully documented in the schema, so the description is not required to compensate. It adds nothing about parameter meaning or interaction (e.g. how days relates to the comparison period), making the baseline 3 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 resource (events) and an explicit ordering (ranked by count over a period), plus the per-day comparison framing. It is clear what the tool returns, but it never distinguishes itself from the sibling search_events or list_pages, so an agent must guess which of the two event tools 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?
There is no when-to-use guidance and no mention of alternatives such as search_events, which is the obvious near-neighbour. The phrase 'ranked by count' hints at a top-N summary use case, but the agent is left to infer that this is the non-search, aggregate view.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most-visited pages over the period, ranked by page views.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful context that results are ranked by page views and scoped to a period, but it does not mention pagination, return format, auth requirements, or rate limits.
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 waste. The ranking criterion and time scope are stated immediately, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with full schema coverage, annotations, and no required parameters, the description is nearly complete. It states the ranking metric and period scope, though it does not describe the returned page fields or the default 7-day window (the latter is covered by the schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no parameter syntax, format, or default details beyond what the structured schema provides; a 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 resource ('pages'), a ranking criterion ('ranked by page views'), and a time scope ('over the period'). An agent can tell it returns top pages rather than events or countries, but it does not explicitly differentiate itself from the sibling 'search_pages'.
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 only states what the tool returns; it gives no when-to-use guidance, no prerequisites, and no comparison to alternatives like 'search_pages' or the other list_* tools. An agent must infer usage from the name and title alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every GA4 property the signed-in account can read, and which one is the saved default. Read-only: this cannot change the default.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real context beyond that: it discloses the result scope (all readable properties, not just one) and that the response flags the saved default, and it reinforces that the default is not mutable here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the scope and the default-marker fact front-loaded before the read-only caveat. Every clause 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?
With no output schema, the description must convey the return, and it does so at a summary level (all readable properties plus the default). It stops short of describing result shape or fields, but for a no-arg list tool with annotations covering behavior, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. Nothing in the description misrepresents the argument surface.
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 ('Every GA4 property the signed-in account can read') plus an extra output fact (which one is the saved default). No sibling in the list enumerates properties, so an agent can distinguish it immediately from configure_site or the list_* 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?
The scope clause ('every property the signed-in account can read') tells the agent when this tool returns the whole set rather than a filtered view. The trailing 'this cannot change the default' implicitly routes mutation intent elsewhere (configure_site), but no alternative is named explicitly, 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.
The URLs that sent traffic, ranked by sessions. Use this for "who is linking to us"; use list_traffic_sources for the channel breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context that results are ranked by sessions, but says nothing about row limits per call, empty-result behavior, or attribution caveats. Adequate but not rich for a query tool with only annotation-level coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste: the resource and ranking are front-loaded, and the routing hint follows immediately. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All parameters are optional with defaults, so an agent can call this with no arguments, and the description covers what the tool returns and when to prefer it. There is no output schema, but for a simple ranked list the semantics are self-evident; only a note on default window or result shape would fully close the 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% and each of the three parameters carries its own description and default, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond it, making the baseline 3 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 resource (the URLs that sent traffic) plus the ordering (ranked by sessions), so the agent immediately knows what comes back. It also explicitly distinguishes itself from list_traffic_sources, which prevents confusion with the channel-breakdown sibling.
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 selection rule: 'who is linking to us' routes here, while 'channel breakdown' routes to list_traffic_sources. The alternative and the condition that selects it are both named, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where traffic arrives from, as GA4's source / medium pairs (google / organic, (direct) / (none), …), ranked by sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful value semantics about what the rows look like (source / medium pairs, ranked by sessions, with examples), but says nothing about freshness, pagination, or coverage that isn't already in the schema's days description.
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 leads with the resource and ranking, then supplies concrete example values to make the output format unambiguous. No wasted clauses, though the conversational 'Where traffic arrives from' opener is slightly indirect.
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 three-parameter read with no required inputs and no output schema, the description adequately conveys the return content and ordering, which is what an agent most needs. The remaining gap is disambiguation from overlapping list_* siblings, which is a moderate omission rather than a blocker.
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 days, limit, and property each documented in the schema itself. 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?
The description names a specific resource (traffic sources), states the exact data shape GA4 source/medium pairs with concrete examples, and states the ranking metric (sessions). It does not explicitly differentiate itself from close siblings like list_referrers or list_countries, 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 mention of alternatives (list_referrers in particular overlaps conceptually), and no prerequisites or exclusions. The agent must infer from the returned content alone that this is for top-of-funnel source analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who is on the site right now — active users in the last 30 minutes, broken down by country. Realtime, so it ignores the days window entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description adds genuinely useful behavioral detail: the fixed 30-minute activity window, the country breakdown, and the fact that the `days` parameter is inert for this 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?
Two short sentences, zero waste, and the defining constraint (realtime / 30 minutes) is front-loaded before the caveat.
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?
No output schema, but the description states the return dimension (breakdown by country) and the temporal scope, which is sufficient for an agent to invoke it correctly. Only slight gap is the absence of any mention of the optional `property` default behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single `property` parameter, so the schema already carries that meaning; baseline 3 applies. The description adds no parameter syntax or default details of its own.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope: active users in the last 30 minutes, broken down by country. This clearly distinguishes it from the list_* snapshot siblings, which report historical aggregates rather than a realtime view.
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 word 'Realtime' and the note that it 'ignores the `days` window entirely' tell the agent when this tool is the right choice versus the windowed list tools. It does not explicitly name an alternative or a when-not condition, 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.
Events whose name contains a substring, ranked by count — "signup", "purchase", "click".
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| query | Yes | Substring to match against the event name, case-insensitive. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds one genuine behavioral fact — results are ranked by count — which is not in the annotations or schema. It says nothing about how the count is computed, whether results are truncated, or how ranking interacts with the days window.
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 short sentence with the core behavior front-loaded and no filler. The dash-clause of examples is slightly telegraphic but earns its place by showing the substring format.
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 4-parameter read tool with full schema coverage and no output schema, the description is minimally adequate. It omits what 'ranked by count' means (event count over the window) and gives no hint of the return shape or pagination behavior, which an agent must infer from limit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (days, limit, query, property) are already documented with semantics and constraints. The description's example substrings (
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 (searching events) plus the matching rule (name contains a substring) and the ordering (ranked by count), with illustrative query values. It is clearly distinguishable from list_events, though it never names that sibling 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?
Usage is implied by 'whose name contains a substring' — the agent can infer this is for substring lookup rather than enumeration. There is no when-to-use statement, no mention of list_events as the broader alternative, and no note about when a default property is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pages whose path contains a substring, ranked by page views — "/blog", "pricing", a slug you half remember.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| limit | No | How many rows to return. | |
| query | Yes | Substring to match against the page path, case-insensitive. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and openWorldHint, so safety is covered. The description adds a real behavioral trait beyond that: results are ranked by page views, which tells the agent how to interpret ordering. It doesn't cover pagination or result-size behavior, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence: resource and matching semantics come first, ordering second, examples last. 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 usefully discloses that results are ranked, and the schema supplies the time window and limit defaults. An agent has enough to call it correctly, though a note on empty results or the default 7-day window being only from the schema would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description's concrete examples ("/blog", "pricing") clarify what the query parameter accepts — substrings of the path rather than full URLs — which the schema alone states more abstractly.
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 (pages) and the matching rule (path contains a substring) plus the ordering (ranked by page views), which is more than a tautology. It doesn't explicitly differentiate from siblings like list_pages or search_events, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "a slug you half remember" implies the use case — fuzzy/partial lookup when you don't know the exact path — but there's no explicit statement of when to prefer this over list_pages or how it differs from search_events. Usage is inferred, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How the site is doing: users, sessions, page views, key events, bounce rate and average session duration for the period, each against the equivalent period before it, plus the daily user series and any milestones the numbers crossed. Start here for "how are we doing".
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days to look back, ending yesterday. | |
| property | No | Numeric GA4 property id. Omit to use the saved default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=true, so safety and live-data behavior are covered structurally. The description adds non-obvious behavior: every metric is compared against the equivalent preceding period, and milestones are surfaced — traits an agent could not infer from 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?
Front-loaded with the payload contents and closed with a short routing cue; the metric list is dense but earns its place because no output schema exists. Slightly long single sentence, but 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 usefully enumerates the returned metrics, comparison basis, daily series and milestones, and annotations cover the safety profile, so an agent can call it correctly. It omits any note on data freshness, pagination, or response shape beyond the metric names.
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?
Both parameters are fully documented in the schema (100% coverage), including the days default/max and the property default behavior, so the schema carries the load. The description only alludes to "the period" without adding syntax, format, or default semantics beyond what the schema states.
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 enumerates exactly what the tool returns (users, sessions, page views, key events, bounce rate, avg session duration, with period-over-period comparison, daily series and milestones), so an agent knows precisely what this resource is. It does not, however, name any sibling tool directly, so differentiation from list_pages/list_events is inferred 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?
"Start here for 'how are we doing'" gives clear positive guidance about when this tool is the right entry point, which is meaningful for an overview tool sitting beside many narrower list_* tools. It stops short of naming alternatives or stating when not to use it (e.g. for per-page or per-event breakdowns).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
audit_siteconfigure_sitelist_countrieslist_eventslist_pageslist_propertieslist_referrerslist_traffic_sourceslive_visitorssearch_eventssearch_pagessite_statusRun Google Ads, Meta Ads, GA4 and Search Console from chat: read, audit and launch campaigns.
Connect Google Analytics to ChatGPT. Query GA4 data in plain English and get instant insights.
Privacy-first web analytics. Query pageviews, referrers, trends, and AI insights.
Add one secure layer between your agents and this server.
