The hook + setting libraries, and which hooks are working

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

The description goes beyond the readOnlyHint annotation by explaining dynamic behavior: verdict suppression below 5 measured posts with reason, no cross-channel comparison, and treatment of never-tried hooks as observation not advice. It also explains why hooks are marked unusable (on-screen-text hooks incompatible with authentic renders). These are valuable behavioral details not conveyed by annotations alone.

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 a single long paragraph but is dense and front-loaded with the core purpose. Each sentence adds meaningful content (what it returns, when to call it, limitations, behavior). It could be broken into more readable bullets, but it is not wastefully verbose relative to the complexity it explains.

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 lookup tool with 4 optional parameters and no output schema, the description fully covers what an agent needs: what it returns (menu, settings, traction), how the verdicts are gated, which params affect what, and its place in the ad-planning workflow. Nothing essential 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 descriptions cover all 4 parameters, so baseline is 3. The prose adds context: tier changes the 'FINISH of the room' and authentic flag makes on-screen-text hooks 'unusable with the reason.' This clarifies the interaction between parameters and the tool's output, going beyond the schema. Slight deduction for not elaborating the category parameter more explicitly, but it's adequately covered.

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 states a precise purpose: a curated menu of visual scroll-stop hooks and settings, with measured traction, that plan_ad and render_ad accept. It names the consumers and differentiates itself from other tools by being a deliberate selection aid rather than an improvisation tool. It is clear what the tool does and its scope is explicit.

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 explicitly states when to call it: 'before planning an ad' and 'after publishing,' giving concrete usage timing. It also lists three things it will not do (no recommendation from thin data, no cross-channel comparison, never-tried hooks reported as fact not advice), which effectively tells the agent what not to expect and when to avoid using it. This is excellent guidance.

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