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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses the output shape, pagination mechanics, default and allowed limits, ordering, cost ('Free'), and error conditions ('422 for a bad run_id or cursor'). This is exceptional transparency.

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 dense but every sentence contributes: what is listed, how it is ordered, scoping, pagination, output shape, reference endpoint, cost, and errors. It is front-loaded with the core purpose and contains no filler.

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 list-with-pagination tool, the description covers everything needed to invoke it correctly: limit range, cursor continuation, run_id filtering, response shape, error handling, and cost. The output schema exists, but the description adds the operational context an agent needs.

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 description coverage is low (25%), so the description must compensate. It adds meaningful semantics for run_id and cursor, and the limit behavior is also referenced. The api_key parameter is not described, but it is self-explanatory and nullable, so the gap is minor.

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 names the specific resource ('hooks you kept with keep_hook'), the operation (list), the ordering ('newest decision first'), and the scoping options ('across all runs or within one run_id'). It clearly distinguishes itself from sibling tools like find_hooks or get_hook by focusing specifically on kept hooks.

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 makes the usage context clear: list kept hooks either globally or scoped to a run_id, with pagination via cursor. It does not explicitly name alternatives or state when not to use this tool, but the scoping and pagination details give strong practical guidance.

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