wafle_ads_breakdown_by_creative

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

Beyond the annotations (readOnlyHint, idempotentHint), the description powerfully discloses behavioral details: the ROAS is derived from CAPI server-side truth rather than Meta pixel, the `winner` flag logic (top quartile ROAS AND spend above floor), and the default significance floor of 5,000 cents. This enriches the agent's understanding of how results are computed and interpreted, far exceeding the annotation safety hints.

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 compact yet thorough: the first sentence captures the core purpose and return metrics; the second adds the unique data-source qualification; the second paragraph gives the use case, default sort, and winner-flag algorithm. Every sentence earns its place with no filler or repetition.

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?

There is no output schema, so the description must explain what the tool returns and key behaviors—it does both thoroughly, covering metrics, ROAS source, winner flag, and significance threshold. For a read-only breakdown tool with 5 parameters, this fully equips an agent to understand the tool's purpose, output, and parameter implications.

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?

The input schema already covers most parameters (80% description coverage). The description adds meaning by explaining the significance floor (min_spend_cents default) and the default sort behavior, while the winner-flag explanation ties parameters to output semantics. This goes beyond the schema's dry descriptions and justifies a score above the baseline 3.

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+resource ('Per-creative performance breakdown') and states exact metrics returned (spend, impressions, clicks, conversions, ROAS, CPA). It also distinguishes itself from siblings by clarifying scope (campaign or account-wide) and its unique CAPI cross-tabbing, making it unmistakable from tools like wafle_ads_performance_summary.

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 provides an explicit use case: 'Use when you need to find the *one* creative carrying a campaign vs the ones bleeding spend.' While it doesn't name alternative tools or state when-not-to-use, the scenario is clear and the differentiator (CAPI truth, winner flag) guides selection.

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