QuerySail: Google Analytics

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

With readOnlyHint, idempotentHint and destructiveHint already declaring the safety profile, the description goes further: default window when no dates are given (last 28 days ending yesterday), that filters apply to both periods symmetrically, that the work is done in one Google request, and that results are observational rather than causal. That last caveat materially changes how an agent should relay results to a user.

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?

Sentences are ordered by decision value: trigger first, mechanism second, output third, defaults fourth, caveat last. No sentence is redundant with another and none restates structured fields unnecessarily; even 'in one Google request' conveys a cost trait.

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 12-parameter read-only tool with full schema coverage and an existing output schema, the description covers the remaining gaps: defaults, filter scoping, ranking behavior, and result interpretation limits. Return-format detail is minimal because the output schema owns it, which is the right division.

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 still adds semantics the schema does not: the default current period (last 28 days ending yesterday), the shared filter scope across both periods, and that movers are 'ranked by change in one metric' (clarifying rank_by). It stops short of describing the compare_to/custom date interplay beyond labeling.

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

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

The description opens with a concrete use trigger and states the verb+resource precisely: compares one property's metrics between a current and a comparison period. The period-comparison framing inherently separates it from run_report, which handles single-period reporting, so an agent can select between them without opening schemas.

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

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

It gives explicit when-to-use triggers ('what changed between two periods', 'why traffic or conversions went up or down', 'which channels... gained or lost') and a clear limitation ('Changes are observed differences and do not identify causes'). What it lacks is an explicit named alternative (e.g. run_report for a single-period snapshot), so usage context is clear but not fully routed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the trailing "Read-only" is redundant restatement. The description does add that results include custom definitions and key events, which is useful content context, but says nothing about pagination or result caps despite a limit 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?

Two sentences, purpose front-loaded ahead of the filtering details, with no wasted clauses. The closing "Read-only" overlaps the annotations and could be dropped, but the overall structure is efficient and scannable.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. With 100% schema coverage, 1 required parameter and the description confirming the discovery purpose, an agent has what it needs; only explicit sibling routing is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description goes beyond the schema by specifying that the search term is matched against the API name, display name and category — detail the schema omits. It also confirms the kind and custom-definition filters, adding a modest amount of meaning over the structured fields.

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

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

States a specific verb and resource: find the exact API names of dimensions and metrics a property can report on, and enumerates what is included (custom dimensions, custom metrics, key events). It does not explicitly differentiate itself from siblings like run_report or list_properties, relying on the agent to infer that this is the discovery step.

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 to find the exact API names" implies the discovery-before-reporting workflow, and the filter options suggest refinement scenarios. However, no when-not-to-use guidance or named alternatives are provided, so the agent must infer the relationship to run_report and compare_report on its own.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description partly echoes that ('Read-only. Does not change anything'). It earns credit for disclosing traits annotations cannot: returned fields (property ID, display name, account, visible Google accounts), deduplication of properties visible to multiple connections, and the GA4-only filter.

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 routing condition, then the return shape, then caveats. Efficient overall, but the final two sentences ('Read-only. Does not change anything in Google Analytics.') restate the annotations and could be trimmed.

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

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

An output schema exists, so return values need not beSpecified; the description nonetheless previews them helpfully. With safety covered by annotations and both params documented in the schema, nothing an agent needs in order to select or call this tool 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% with only two optional params, so the schema fully documents cursor and connection_id. The description adds no additional semantics about when or how to supply them, which is the baseline-3 case 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 a specific verb and resource ('List Google Analytics properties') and immediately narrows scope: GA4 only, UA excluded, one entry per property. An agent can distinguish this from the report-oriented siblings (run_report, compare_report) without opening any schema.

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

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

Gives explicit trigger conditions: when the user asks which GA sites/apps they can access, or needs the exact property_id for another call. It also states an exclusion (Universal Analytics not included). It does not name a sibling or alternative to route to, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds real behavioral context the annotations cannot: realtime figures are preliminary, never cached, standard properties cover 30 minutes versus 60 for GA4 360. Those freshness and coverage constraints directly affect how an agent should interpret results.

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 dense paragraph rather than a list, but each clause earns its place: trigger, window, dimensions, metrics, tier differences, freshness, and safety. The trigger is front-loaded so the first sentence carries the routing decision.

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 8-parameter tool with nested filters, an output schema is present so return values need not be explained, and the schema covers most parameters. The description supplies the realtime-specific context (window length, preliminary data, default metric) and is close to complete, only omitting guidance on filter/metric combinations that the schema partly covers.

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 88%, so the schema already documents filters, metrics, dimensions, row_limit and minutes_ago in detail. The description restates the default metric and a few dimension names ('unifiedScreenName', event name) that are already in the schema, adding little beyond the baseline.

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

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

States a specific verb and resource ('Run a Google Analytics realtime report') and immediately pins the scope to 'right now: active users in the last 30 minutes'. That realtime framing is exactly what distinguishes it from the sibling run_report, so an agent can choose correctly 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?

Gives a concrete trigger: 'Use this when the user asks what is happening on their site or app right now'. It implies the split from historical reporting but never names run_report as the alternative or states the when-not condition explicitly, 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?

Beyond the readOnly/idempotent annotations, it discloses thresholding of small values, sampling of large reports, the property-time-zone date semantics, rate metrics being fractions, and the fact that figures are observed not causal. It also documents pagination via cursor and the 100-row ceiling, which are genuine operational traits rather than restatements of structured data.

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

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

Purpose is front-loaded in the first clause, followed by scope, defaults, paging, and caveats in a logical order. It is dense and information-rich rather than padded, though the single long sentence stretches readability and a few clauses (rates as fractions) border on redundant for an experienced agent.

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 11 parameters, nested filter/order_by objects, and an output schema already covering return shape, the description still supplies the missing context an agent needs: defaults, time-zone semantics, pagination mechanics, filter combination via AND, and data-quality caveats. Nothing material to a correct invocation is absent.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds default behavior not present in the schema: omitting metrics yields activeUsers/sessions/screenPageViews, and omitting dates yields the last 28 days ending yesterday. It also restates the 100-row/default-20 limit, which the schema already carries, so the gain is real but modest.

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

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

The description opens with a specific verb and resource ('retrieve Google Analytics 4 data for one property') and enumerates the metric and dimension families it can return. It is clearly a reporting tool, but it never names or contrasts itself with siblings such as run_realtime_report or compare_report, leaving the agent to infer the boundary from the names alone.

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 rather than prescribed: the agent learns what happens with no metrics or no dates, plus a concrete filter example ('sessions from Organic Search to pages starting with /blog/'). There is no explicit when-not guidance and no routing to the realtime or comparison siblings, so the agent must infer when this tool is the wrong choice.

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