Suggest hook texts

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: 'Costs no credits' (economic behavior affecting agent decisions), the 150-char output limit, and the fact that multiple suggestions are returned ('Pick one'). This goes beyond what the schema or annotations state.

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?

Three tightly packed sentences with zero filler. The definition is front-loaded, the usage guidance and downstream chaining follow logically, and the credit-cost note is a single useful clause at the end. Every sentence earns its place.

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 low-complexity tool (1 optional param, no required fields, no output schema), the description covers the essentials: what it does, how to tailor it, output constraint, downstream consumer, and cost. The main gap is the exact response format (e.g., an array of candidate strings), though 'Pick one' implies multiple suggestions and the 150-char limit constrains the format sufficiently.

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 the schema already explains the context parameter well. The description adds value by stating the parameter's functional purpose — passing context produces 'tailored hooks' — which explains why the agent should bother supplying it. This is a meaningful addition over the schema's neutral 'Describe the app' phrasing.

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 specific verb ('Get'), resource ('AI-suggested hook texts'), and defines what a hook is ('the short attention-grabbing line burned over a UGC ad'). It also disambiguates the potentially misleading 'list_' name by clarifying this is a suggestion/generation tool, not a retrieval of stored hooks, and even maps it to the CLI equivalent 'clipugc hooks suggest'.

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 gives clear context for when to use the tool (when a hook text is needed for a UGC ad), how to tailor results (pass app context), and what to do with the output (pass it as hook to merge_ad). It lacks explicit when-not-to-use or alternative tool exclusions, but the chaining instruction makes its role in the workflow unambiguous.

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