bi_list_clips

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

Annotations only state readOnlyHint=true and a title; the description adds meaningful behavior: server-side search, tiles returning one entry per day, default limit of 50, and date parsing flexibility. It even discloses the UI3 v91 bug fix context. The crossover alert-side behavior is unusually transparent about a surprising response shape, though it doesn't enumerate all response fields beyond the listed ones. Since annotations are minimal, this description carries the behavioral burden well.

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 dense paragraph with no wasted words; it front-loads the core purpose and required parameter. The crossover note and UI3 v91 mention are relevant but add length; still, each sentence serves a purpose. It could be improved with slight formatting breaks, but it is efficiently packed.

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 tool with 8 parameters and no output schema, the description covers the main parameters, their formats, and response-shape caveats. No output schema exists, so the description should explain what is returned; it does list returned clip fields and flags the alert crossover fields, but does not specify pagination or how limit interacts with tiles beyond the default. Given readOnlyHint annotation and the extensive parameter coverage, this is nearly complete.

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 a baseline of 3 applies. The description adds meaning beyond the schema by explaining why tiles is useful for calendar views, clarifying that the crossover view values return alert items with an 'msec' field that means alert length, and explaining server-side memo substring search. It also emphasizes that camera is required and 'Index' means all. However, some schema descriptions already cover the same semantics, so the added value is moderate, not exceptional.

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 opens with a clear verb-resource pair: 'Recent recorded clips for a camera: path, duration, resolution, flags, memo.' It explicitly contrasts with bi_list_alerts, noting that clips include continuous recordings while alerts are AI/motion events. This distinguishes it well from the sibling that appears most similar.

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 directly says it is 'Complementary to bi_list_alerts' and explains the difference. It also provides a crossover warning explaining that alert-side view values return alert items, a subtle but critical usage detail. Required camera parameter and optional view/date/search/tiles/limit semantics are all covered, including date format alternatives and relative shorthand.

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