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

Goes well past the annotations, which only declare a safe read. It discloses the authorization model, that inclusive calendar dates use the property timezone rather than UTC, that ordering is stabilized by dimension tie-breaks, that pagination is offset/limit based, that the comparison block is a separate live call, that conversion events are provider-configured and not proven orders, that ChatGPT referrals are folded into source/medium, and that missing/sampled/thresholded data is surfaced rather than silently dropped. The negative scope ('no legacy tokens, arbitrary endpoints or writes') further constrains 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 prerequisites, and the remaining sentences are dense but each carries a distinct constraint. The 'shared API/MCP handler' phrase and the trailing POST endpoint path are internal detail that consumes space without helping an agent decide or invoke.

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 9-parameter nested-schema tool with no output schema, the description covers operational semantics thoroughly but never indicates the shape of what comes back (rows keyed by dimensions/metrics, how comparison results are attached) and never says how to discover a connectionId, despite list_marketing_connections existing among siblings. Adequate to call correctly in broad strokes, incomplete for interpreting results.

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

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

Schema description coverage is 0% across 9 parameters including nested dateRange, comparison, filters and orderBy, so the description carries the full burden. It does add meaning for dimensions/metrics/filters, offset/limit pagination, the comparison block and dateRange timezone semantics, but connectionId (how to obtain a valid one), the orderBy direction, and the meaning of enum values like keyEvents versus eventCount are left to the schema's bare enums.

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: read a tenant-bound GA4 property, with the scope (single selected connection) made explicit. It is distinguishable from sibling performance tools such as get_search_performance or get_advertising_performance, but the opening phrase 'through the shared API/MCP handler' adds internal plumbing rather than disambiguation, and no sibling is 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?

Gives concrete preconditions (analytics:read plus Marketing module read access plus an active verified provider connection) and a boundary condition: organic query data requires Search Console, so this tool is not the answer for query-level organic reporting. It stops short of naming an alternative tool or saying when not to call it (e.g. for non-GA4 sources).

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