find

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

With no annotations, the description carries the full burden and delivers: the ranking tiers used, the fact that the first result line explains which tiers answered and which could not, find_index's hard boundary (no transcription, no network), the diversity score returned by find_to_timeline, and the expected_sha256 refuse-on-mismatch guard on filepath actions. It stops short of naming permission or write side effects beyond the reel.

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 block is dense but every sentence carries information, and it is front-loaded with the core purpose. The trailing 'Actions: find_index, find_shots, find_to_timeline.' merely restates the schema enum, and the single-paragraph form makes three distinct operations harder to scan than bullets would.

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 high-complexity dispatcher with three sub-operations, nested args, and no output schema or annotations, the description covers each action's parameters and observable behavior well. Remaining gaps are minor: return shapes are not described (acceptable given no output schema) and find_shots' write side effects on filepath inputs are only implied.

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?

The schema's args object is free-form, so the description is the only place that enumerates the real per-action parameters and defaults (limit=10, visual=false, clip_name?, captions=true, backend, min_source_separation=1, output_path?) and defines expected_sha256's semantics. This adds substantial meaning the schema cannot provide.

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?

Each action is given a concrete verb+resource: find_shots is 'natural-language shot search', find_index 'warms scenes and captions', find_to_timeline 'assembles the hits into a _found selects reel'. An agent can tell the three operations apart. It never contrasts itself with siblings like index, transcript, or scenes, so it falls short of a 5.

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 implies a workflow (index warms caches, shots searches, to_timeline builds a reel) and notes that find_index 'never transcribes or goes online', which constrains when it is useful. But there is no explicit 'use X when Y' or stated exclusion relative to the sibling tools; usage must be inferred.

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