wafle_ads_propose_pause_underperformers

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

Annotations already mark the tool as readOnly and idempotent. The description adds behavioral context with 'This tool NEVER mutates' and explains the recommendation logic (distance below threshold, Learning Phase status, trend vs previous period). It also discloses that output is shaped for direct pasting into follow-up tool calls, which is valuable for the agent's decision-making.

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 two well-structured paragraphs. The first sentence states purpose and scope; the second clarifies the non-mutating nature and execution path; the third explains the recommendation logic. Every sentence earns its place with no redundancy or fluff.

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?

With no output schema, the description must explain returns. It states the tool returns a list of adsets with recommendations and ids for follow-up, and explains the recommendation basis. While it doesn't enumerate every return field, its focus on LLM-friendly output and integration with sibling execution tools makes the description sufficiently complete for the tool's proposing role.

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 coverage is 100%, so the baseline is 3. The description enhances parameter understanding by integrating `threshold_roas`, `min_spend_cents`, and `range` into the tool's core filtering logic, showing how they combine to trigger recommendations. It does not add new parameter-level details, but the contextual integration adds meaningful value.

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 'READ-ONLY proposer' and clearly states it returns a list of adsets filtered by ROAS and spend criteria, with per-item recommendations. It distinguishes itself from execution tools by naming `wafle_ads_campaign_pause`, `wafle_ads_bulk_pause`, and `wafle_ads_campaign_update_budget` as the required follow-up actions.

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 explicitly says 'This tool NEVER mutates' and instructs that to execute, the caller must call the named execution tools with the returned ids. This provides clear when-to-use guidance and explicitly names alternatives, telling the agent the exact sequence of tool invocation.

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