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

Adds substantial context beyond the annotations: zero credit cost, the demo/sample-data behavior with the demo: true marker and result note, and the full auth path (OAuth host prompt or 'Authorization: Bearer acd_live_…' key with a URL). Those are exactly the behavioral facts an agent needs before calling and that readOnlyHint/idempotentHint cannot convey.

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?

Front-loads purpose and returned fields, then cost, demo caveat, and auth in a logical order with no filler sentences. The auth block is dense but every clause (scheme, header format, key URL) is actionable, so it earns its space.

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 read-only search tool with an output schema, the description covers the remaining gaps: cost, sample-data semantics and marking, and authentication. Nothing an agent needs to call it correctly is missing.

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% and both enums (platform, sort) already document their defaults and meaning, so the schema does the heavy lifting. The description adds only the platform framing ('on Meta or TikTok') and no detail on keyword syntax, sort, or limit beyond what is already structured.

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?

States a specific verb and resource ('Search live competitor ads by keyword') and names the platforms (Meta, TikTok) plus the fields each ad returns (advertiser, copy, hook, CTA, media, run time). It is clearly distinguishable from generation/canvas siblings, though it never names its natural counterpart save_competitor_ad.

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?

Gives clear operating context: keyword search over live ads, no credit cost, and the explicit fallback rule that when live data is unavailable rows are samples marked demo: true. It stops short of naming alternatives or stating when another sibling (e.g. save_competitor_ad) should be chosen instead.

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