Mine customer angles

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the mutation/external-read profile is known. The description then adds genuinely useful context the annotations cannot: credit spend on reads and model tokens, hard input limits (300 reviews / 2,000 chars / 40,000 total) that are refused at no cost, and the side effect that brandId silently switches the key's active profile like use_brand. That side-effect disclosure is the standout — it is the kind of destructive-adjacent behavior an agent must know. It stops short of describing retry/failure behavior beyond the size refusal or how long a run takes, so 3 rather than 4.

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-loaded correctly — the verb, data sources, and return shape come first, with alternatives and limits after. Every section carries information, but the dense ALL-CAPS emphasis and repeated format enumerations ('one per line, numbered, blank-line separated...') make it longer than it needs to be; it reads as one packed paragraph rather than structured segments.

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 carries the return-value burden and does so: it names the angle tags, quote count, score breakdown, hook field, and the `next` object containing exact plan_variations/generate_image arguments. Combined with credit, limit, and profile-switching disclosure, an agent has everything needed to call it correctly and chain it forward.

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, and the description still adds meaning: accepted review-block formats beyond the enum-less schema text, that reviewsUrl can be a plain file path on a local CLI, and that useOwnReviewsOnly carries a real cost difference (no search credits). It duplicates some schema wording (upload_file provenance, CSV review column) rather than adding to it, which keeps it at 4.

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+resource ('Mine ad ANGLES from real customer language') and then details exactly what the output contains: ranked angle bank, taxonomy tags, 2-5 verbatim quotes, 0-100 score with breakdown, ready-to-run hook. It is unambiguously distinct from sibling competitor_teardown and from search_* tools that only gather raw data.

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?

Explicitly routes the agent away from this tool ('To tear down a COMPETITOR use competitor_teardown instead') and gives condition-based guidance for its own variants: brandId to target another profile, useOwnReviewsOnly:true to skip public search, and the review-volume limits that force batching. The when-to-use and when-not-to-use cases are both covered.

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