ga4_run_report

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds valuable non-obvious behavioral context: 400 errors mean incompatible metric/dimension pairs, dimension_filter and order_by require GA4 object dicts, and reports are generated in the property's timezone. This is precisely the kind of information an agent needs to interpret results correctly.

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?

Six sentences each carry distinct, necessary information: purpose, API-name caveat, compatibility error semantics, object formats, date formats, and timezone behavior. The description is front-loaded with the purpose and contains 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?

The description covers the main non-obvious failure modes and formatting requirements, and the output schema means return values need no explanation. It could be more complete by addressing pagination and property_id selection, but these are minor given the schema defaults and the presence of an output 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?

With zero schema description coverage, the description compensates well by explaining GA4 API-name conventions, listing valid metric and dimension examples, specifying date formats, and clarifying filter/order_by object formats. It does not mention the limit or property_id parameters, but those are either self-evident or have schema defaults, so the compensation is strong but not 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 opening sentence uses a specific verb ('Run') and resource ('GA4 report'), explicitly names the underlying runReport method, and the word 'arbitrary' distinguishes it from more targeted sibling tools like ga4_landing_pages. An agent can immediately tell what this tool does and roughly how it differs from specialized report tools.

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

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

The description clearly frames this as the general-purpose/custom GA4 reporting tool, and the timezone note contrasts it with Search Console tools. It does not explicitly name sibling alternatives or provide a 'when not to use' statement, so it stops short of full routing guidance.

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