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

The description extensively discloses behavior: it compares independent breakdowns with canonical totals, uses exact reconciliation for eventCount and HLL++ tolerance for sessions, and renders an Unverified card on persistent mismatches. It also specifies output format and data accuracy contract. Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description complements these with rich context, though it adds details beyond annotations. One minor gap: it doesn't explicitly state potential side effects like rate limits or timeout, but the annotations cover safety aspects.

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 packs a lot of crucial information in a structured way: it starts with the core purpose, then details reconciliation logic, input parameters, output expectations, and integrity rules. Each sentence is purposeful. Could be slightly tightened but given the complexity (reconciliation, tolerance, data accuracy contract), the length is justified. It's well-front-loaded with the primary function.

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 (live data fetch, reconciliation, integrity receipt, explicit output requirements), the description is comprehensive. It covers what the tool does, how to use it, what the output contains, and the behavioral contract. The output schema exists (though not provided in the prompt), which reduces the need to describe return values. The description also handles edge cases (persistent mismatches) and provides clear instructions. It fully equips an agent to invoke 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?

Schema description coverage is 80% for parameters, and the description adds semantics for all but the `property_id` which is explained in schema pattern. It explains that `metric` can be sessions or eventCount, that `event_name` is only valid with eventCount, and default date formats (30daysAgo, today). It also states property_id is required. This adds meaning beyond schema by indicating usage context (defaults and relationships). Minor deduction: it doesn't describe the exact format for date values beyond the schema's 'YYYY-MM-DD, today, yesterday, or NdaysAgo', but that is already in 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 clearly states it fetches live GA4 data and returns a CorpusIQ PNG recap with text, values, reconciliation status, and integrity receipt. It distinguishes itself from siblings like ga4_connector, chart_render, and get_my_youtube_analytics by specifying the reconciliation methodology and output format. The verb 'Fetch' and resource 'Google Analytics 4 data' are specific and differentiated.

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 explicitly explains when to use this tool (for GA4 data with reconciliation) and provides detailed instructions on how to present results (always end with 'Powered by CorpusIQ'), and what not to do (do not invent metrics, do not hide mismatches). It also lists valid parameter values and their defaults, giving clear contextual guidance. It contrasts with sibling tools like `ga4_connector` implicitly by focusing on the evidence-backed recap format.

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