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

Beyond the annotations (write, idempotent, open-world), the description discloses the output container and codec, the destination directory, and the sidecar provenance file, plus that 3 check frames are returned. It does not mention failure modes (e.g., download errors, invalid time ranges) or that audio is stripped/handled, but the added context is substantial.

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?

Two dense sentences with zero filler, front-loading the core action and slice definition, then the output artifact and idempotency behavior.

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?

With an output schema present, the description needn't detail the returned frames, and it already covers output format, location, and idempotent repeat behavior. Missing pieces are prerequisites and the semantics of the optional audio/brief/label parameters.

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 only 43%, yet the description only clarifies start_s and duration_s semantics (the slice definition) and hints at identifier/file via 'remote archive.org video'. Optional parameters audio, brief, and label are not explained in the description, so it only partly compensates for the coverage gap.

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?

States a specific verb (cut), the resource (a remote archive.org video), the exact time slice derived from start_s and duration_s, and the output artifact (verified H.264 MP4 under BROLL_HOME/clips plus a provenance JSON). This is clearly distinguishable from search_footage, inspect_item, and get_provenance.

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?

Conveys implied usage (produce a clip after locating footage) and explicitly notes that repeating the same cut returns the existing clip. However, it never states when to prefer this over siblings like inspect_item or search_footage, nor any preconditions such as inspecting the item first.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior — results come from local records, no archive.org round-trip, and the identifier mode also returns clips already cut from the item. Cursor/pagination behavior is not disclosed, which is the remaining behavioral gap.

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?

A single sentence plus one short constraint clause, with the clip vs item distinction front-loaded and zero filler. Every phrase adds information.

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?

With an output schema present, return values need not be explained, and the two access modes plus the offline-only constraint are covered. The only missing piece an agent needs is how cursor-based pagination works, which is absent from both description and schema.

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 0%, so the description must carry parameter meaning: it does explain clip_id and identifier semantics and their oneOf exclusivity, but the third parameter (cursor) is never mentioned anywhere, leaving pagination undocumented. Two of three parameters are covered, so it compensates only partially.

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?

Names a specific verb ('Read') and resource ('provenance record') and splits the tool into two clearly described modes keyed on clip_id vs identifier. It does not explicitly differentiate itself from the sibling inspect_item, whose item-level scope could be confused with the 'license/source record of an item' mode here.

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?

Gives a clear selection rule between the two call modes (clip-level provenance vs item license plus derived clips) and states a hard scope limit: local records only, never contacts archive.org. It stops short of naming when to prefer a sibling tool such as inspect_item or search_footage instead.

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

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

The annotations already establish read-only and open-world behavior, and the description adds meaningful context: paged scene results with keyframes, shotlist excerpt and license, or a paged clip list with thumbnails. It also discloses the follow-up pattern needed when an item contains many clips. It does not cover auth, rate limits, or failure behavior, but it adds solid operational detail beyond the annotations.

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 two tight sentences with no wasted language, and it front-loads the overall purpose before branching into the two item shapes. The conditional follow-up instruction is embedded without clutter.

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 five-parameter read-only inspection tool with an output schema and existing annotations, the description covers the main item shapes and follow-up behavior well. The remaining gap is paging parameter semantics, but the presence of an output schema and schema-defined defaults/maximums makes the definition largely 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 description coverage is low at 40%, so the description needs to compensate. It explains file usage and implies paging for both modes, but cursor, page_size, and window semantics are left mostly to the schema, with cursor and page_size lacking textual descriptions in both places.

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 action and resource: showing what is inside an archive.org item. It clearly distinguishes the two inspection modes (single video scenes vs. many separate clips), but it does not differentiate itself from siblings such as search_footage or extract_clip.

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 useful conditional guidance for the two internal modes, including calling again with file=<name> when an item has many separate clips. However, it does not say when to use inspect_item instead of the sibling tools, so alternative routing remains implied rather than explicit.

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

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

Annotations already declare readOnly and openWorld, but the description adds real context: results are capped at 5, ranked, and annotated with license, collection tier and match rationale. It also discloses that text matching happens remotely on archive.org while ranking is local, which matters for latency and failure expectations. Pagination mechanics are mentioned but not detailed.

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 short sentences, each load-bearing: output shape first, pagination second, execution model third. No filler and well front-loaded.

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?

With an output schema present, the description need not enumerate return fields, yet it usefully summarizes them, and it covers the remote-search/local-rank split that an agent should know before calling. Minor gap: no guidance on how many results to expect per page or what an empty result means.

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 67% and the schema already documents brief, cursor and the filter semantics (license modes, tier meaning). The only added meaning is tying the cursor parameter to the next_cursor output, which is a modest but genuine clarification. Baseline 3 is appropriate since the schema carries most of the weight.

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?

States a specific verb and resource: turning a written shot brief into ranked archive.org video items, capped at 5. That is clearly distinguishable from siblings like inspect_item, extract_clip and get_provenance, which act on items rather than search for them.

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 phrase 'turn a written shot brief into...' establishes the entry condition clearly, and 'Page with next_cursor' signals the follow-up call. It does not explicitly say when not to use it or when to switch to inspect_item, so it stops short of full routing guidance.

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