performance_report

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

With no annotations, the description takes on the full burden of disclosing behavior. It reveals that numbers come back as typed (floats/ints, percentages as plain numbers), that TimePeriod is auto-dropped for Summary aggregation, and that predefined_time is ignored when start_date/end_date are given. It does not mention whether the operation is read-only or side-effect-free, but the word 'pull' strongly implies no mutation, and the disclosed quirks are valuable.

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 well-structured with a clear opening and a bulleted list of arguments. Each line is purposeful and compact, avoiding redundancy. It front-loads the main purpose and the most important behavioral note about typed numbers. No wasted words.

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 tool with 9 parameters and no annotational safety signals, the description covers a wide range of context: parameter meanings, value restrictions, behavioral quirks, and output formatting. Although an output schema exists, the description still clarifies how values are returned, which is helpful. The only minor omission is max_rows, but the rest is sufficiently complete for an agent to use it effectively.

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%, so the description must compensate. It thoroughly explains each parameter: account_id, report_type with an enumerated list and per-item meaning, predefined_time with a complete list, start_date/end_date format and requirement, aggregation with enumeration and a behavioral note, campaign_ids, and columns. It misses max_rows, but that parameter is self-explanatory in the schema with a default. The description provides far more than the schema does.

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 'Pull a performance report,' a clear verb+resource statement. It further distinguishes report types (search_term, keyword, ad_group, ad, geographic) and explains their specific purposes, which helps differentiate from sibling tools like list_keywords or list_ads.

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 gives useful context for choosing report_type (e.g., 'search_term = actual user search queries (best for finding waste + new keywords)') but does not explicitly state when to use this tool over simpler list tools like list_keywords or compare_periods. Usage guidance is implied rather than explicit about alternatives or exclusions.

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