Refs

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

With no annotations, the description carries the full burden and largely succeeds: it discloses the 2-credit cost, the mandatory prior measurement step with a concrete download URL and command, and the exact return shape (score /100, checks table, numbered frame-level fixes, then JSON). It never explicitly states that the tool is side-effect-free, which is the one gap given zero annotation coverage.

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?

Front-loaded with purpose, then prerequisites, returns, and cost in a logical order; every sentence carries information. It is dense and embeds a shell one-liner and a credit cost, which makes it heavier than ideal, but nothing is redundant.

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?

No output schema exists, so the description must describe returns — and it does (score out of 100, checks table, numbered fix list, JSON). Combined with prerequisite steps, cost, and platform-specific loudness targeting, an agent has everything needed to invoke it correctly.

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 the baseline is 3; the description adds value beyond the schema by explaining how to obtain the `render` payload (the curl-and-unzip starter kit plus measure.mjs) and by clarifying that fix frames are expressed at the render's own frame rate. It does not elaborate on `id` beyond what the schema already documents.

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 — checking a rendered video against the reference's measured timeline — and enumerates exactly what it evaluates (cut timing, pace, brightness, motion, loudness, format). An agent can distinguish it from siblings like get_frames, plan_video, or storyboard without opening any schema.

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?

Opens with the triggering condition ("After rendering a video from a reference") and prescribes the prerequisite workflow of measuring the render first. It also tells the agent how to iterate (fix, re-measure, check again). It lacks explicit when-not-to-use or a named alternative tool, so not quite a 5.

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?

With no annotations, the description carries the behavioral burden and discloses that output defaults to Markdown and that format "json" returns a single object with plates, toolkit, recipe, and measured timeline. It does not state permissions, rate limits, or error behavior, but for a read-style retrieval tool it covers the key output-shape behavior.

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 front-loaded with the core purpose and then covers format and the get_frames alternative. The component list is long but each item earns its place by clarifying what the blueprint contains.

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?

No output schema exists, so the description must explain return values, which it does by listing blueprint contents and describing the JSON object. It is complete enough for invocation, with only minor gaps around include_recipe and operational constraints.

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 parameter meanings are already well documented. The description reinforces accepted id forms and the Markdown/json output distinction but adds little beyond the schema and omits include_recipe.

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 a specific resource and verb: the full reverse-engineered blueprint of one video, and enumerates its contents. It also distinguishes itself from get_frames, so an agent can tell which retrieval tool to choose.

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 explicitly routes frame-viewing to get_frames and explains accepted identifier forms, giving clear usage context. It does not cover when to prefer other sibling tools such as storyboard or plan_video, so it is strong but not exhaustive.

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?

No annotations are provided, so the description must carry behavioral disclosure. It says 'Private to you' and enumerates the returned data, but does not explicitly state read-only/no-side-effect behavior, permission requirements beyond privacy, or failure behavior for invalid ids.

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 three sentences, but the first is a long parenthetical catalog of brand-kit dimensions. It is information-dense and mostly front-loaded; trimming would improve scanability, though the detail 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 retrieval tool with full schema coverage and no output schema, it explains the returned brand kit and film summaries, the privacy scope, and how to use returned film ids. No critical calling information is missing.

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 100%, so the schema already documents id, limit, context, and llm_model. The description adds no meaningful parameter semantics beyond the return id format and downstream usage, so the baseline of 3 is appropriate.

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 specifies the resource (a brand import), the returned bundle (brand kit rules plus film blueprint summaries and film ids), and points to get_blueprint/get_frames. It distinguishes this from plan_video, but does not explicitly contrast with list_brands as the discovery tool.

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: use the returned film ids with get_blueprint/get_frames, and call plan_video(brief, brand: id) to make a new film in this style. It lacks an explicit when-not-to-use or a direct alternative for listing brands, though the schema notes list_brands for the id.

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?

With no annotations the description carries the full burden, and it discloses what is returned as well as access scope ('anyone's shared collection, or your own private one') and the special 'favourites' input. It omits auth/permission specifics for private collections and any rate-limit or pagination notes.

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?

Front-loaded with the core output statement, then input forms, then downstream usage. Sentences are dense but each earns its place; the chained references to plan_video/get_blueprint add mild length but useful routing.

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?

No output schema, so the description's enumeration of card contents is valuable and largely compensates. Combined with the id-format and downstream guidance, an agent has enough to call it correctly, though permission behavior for private collections is left implicit.

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 the schema already documents id formats and the limit default. The description reinforces the id variants (collection id, refs.video/c/… link, 'favourites') but adds no syntax beyond the schema and never mentions limit.

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+resource ('Every film in a Refs collection as search cards') and enumerates the returned fields (REF id, link, length, aspect, metrics, why it works). This clearly separates it from list_collections (which lists collections) and get_blueprint (one film in depth).

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?

Explicitly routes downstream: use returned cards with plan_video(brief, reference_ids), up to 5, or get_blueprint for a single film. It doesn't name list_collections as the way to discover ids or state exclusions, so it falls just short of a full when/when-not treatment.

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?

With no annotations, the description bears the full behavioral burden. It usefully discloses the return format (markdown) and the sections included, but says nothing about read-only nature, authentication needs, rate limits, or what happens when the id is unknown or the formula does not exist.

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?

One compact sentence front-loads the key noun phrase ('The full cross-video formula for one format') and follows with a tight colon list of returned sections. There is no filler, repetition, or buried 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?

For a tool with no output schema, the description must explain returns, and it partially does by listing the markdown sections. However, with no annotations and an undocumented id parameter, it omits id requirements and error behavior, leaving meaningful gaps for correct invocation.

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%; context and llm_model are documented directly in the schema, while the required id parameter has no schema description. The description only implies that id selects 'one format' without specifying its format or source, so it adds little beyond the schema.

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 resource ('the full cross-video formula for one format') and enumerates the returned content (structure, timing ranges, top-performer patterns, mistakes, template prompt), so the agent knows exactly what it retrieves. It does not explicitly differentiate from the sibling list_formulas or state a retrieval verb, but the purpose is clear.

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?

There is no guidance on when to use this tool versus list_formulas or other getter siblings, no prerequisites (such as that the id likely comes from list_formulas), and no exclusions. The only usage signal is the implicit 'for one format' scope.

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?

With no annotations, the description carries the full burden and does well: it enumerates what each sheet contains (hook = first 3s at 0.25s steps, shots = one frame per shot, timeline = whole film at fixed steps, transitions = every frame around each cut) and notes each image is captioned. It doesn't address cost, size, or auth characteristics of an image-returning operation, which is the remaining 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?

Purpose is front-loaded in the opening clause before the sheet breakdown, and the dense parentheticals are informative rather than filler. It runs slightly long with stacked clauses about the transitions sheet, but 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 4-param tool with no output schema, the description supplies the return format (labelled frame sheets as images, each followed by a caption) and the sheet semantics, which is what an agent most needs. It omits any note on the two analytics-only params, but those are already fully documented in the 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the enum description only states the default while the prose defines what each sheet actually contains (hook/shots/timeline/transitions semantics) and clarifies the id domain by linking it to get_blueprint.

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+resource: retrieves one video's labelled frame sheets as images, clarifying this is visual reference rather than text. It actively distinguishes itself from the sibling get_blueprint by noting it accepts the same ids while returning visual sheets, so an agent can tell the two apart without opening a schema.

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?

Provides clear usage context via "so you can see the reference instead of guessing from text" and gives a conditional directive for the transitions sheet ("for timing transitions to the frame... ask for 'transitions' separately"). It lacks explicit when-not guidance or naming of alternatives beyond the id-compatibility nod to get_blueprint, so it stops short of a 5.

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?

No annotations exist, so the description carries the load; it discloses privacy ("Private to you") and the contents of each entry, which is useful. It does not state ordering, pagination, or whether an empty list is possible, and read-only behavior is only implied by the verb "list".

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 compact sentences with the resource and return contents front-loaded, followed by the routing hint. No filler or repetition.

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 no output schema, the description usefully specifies the shape of the result (each account with progress and film count) and the privacy scope. Minor gaps around ordering and pagination keep it from a 5.

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 two schema parameters are analytics-only boilerplate (context, llm_model) and are fully documented at 100% coverage, so there is no domain parameter for the description to explain. Nothing is missing, but the description adds no value over the schema here.

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?

Specific verb and resource: it lists the user's brand imports on refs.video/saved, describing exactly what each entry contains (X account, progress, film count). It also distinguishes itself from the sibling get_brand by assigning that tool a different job (brand kit and films).

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?

Routes the agent explicitly: pass an id or handle to get_brand to get the brand kit and every film, which is a clear alternative-selection rule. What's missing is a direct statement of when to call this tool itself (e.g. to discover which brands were imported), though that is strongly implied.

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?

No annotations are provided, so the description carries the full burden. It does useful work by disclosing the return content (ids and film counts), which matters because there is no output schema, but it never states the read-only nature, auth requirements, or pagination/ordering behavior.

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 tight sentences with no filler, front-loaded with the resource definition and followed by the sibling routing. Every clause 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?

With no output schema and no annotations, the description supplies the essential missing pieces: what the list contains and what the ids are for. Only minor gaps remain, such as ordering, pagination, and auth expectations.

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?

Both parameters (context, llm_model) are fully documented in the schema at 100% coverage, and the description adds nothing about them. Baseline 3 applies since the schema does all the work and these are analytics-only fields.

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 (list) and resource (your collections and favourites on refs.video), and immediately defines the resource for the reader as 'named sets of films you saved'. It also distinguishes itself from get_collection by describing what it returns (ids and film counts) versus what get_collection does (reads the films).

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?

Explicitly routes the agent: 'Pass an id to get_collection to read the films and use them as references,' which names the alternative and the condition that selects it. It does not state any when-not-to-use condition, but the escalation path is clear enough to call correctly.

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?

With no annotations, the description carries the full burden, and it does disclose the returned shape (ids, titles, summaries, source films), which is real value since no output schema exists. It says nothing about pagination, result caps, ordering, or read-only safety, leaving meaningful behavioral gaps for a no-annotation tool.

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 tight sentences with the resource definition and examples front-loaded and the navigation hint at the end where it is most useful. No filler or restatement of the tool name.

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 three-parameter list tool with no output schema, the description covers the essentials: what is listed, what fields come back, and where to go for detail. It omits collection size, pagination, and ordering behavior, which an agent would still have to discover empirically.

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%: the two analytics parameters are fully documented in-schema and the enum's allowed values are visible, so the schema does most of the work. The description only loosely gestures at the category filter via 'one format' and never explains what the enum values mean, adding little beyond structured data.

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 ('list_formulas') and immediately defines what a formula is with two concrete examples ('the silent UI workflow', 'the delayed hardware reveal'). It also names the complementary sibling get_formula, so an agent can separate browsing from fetching a single item.

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 closing clause 'fetch one with get_formula' clearly establishes the browse-then-detail workflow and routes the agent away from this tool when it wants a single formula. There is no explicit statement of when listing is preferable (e.g. discovery vs. filtered lookup), which keeps it short of a 5.

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?

With no annotations, the description carries the full burden, and it does substantial work: it enumerates the returned artifacts per reference and describes the storyboard-before-build sequencing that governs behavior. It is thin on operational traits such as side effects (does it persist a plan or canvas?), permissions, or failure modes.

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?

Nearly all content is substantive, but it is delivered as a single run-on paragraph with heavy comma chaining, forcing the agent to parse inputs, returns, and workflow out of one block. Splitting the return description from the workflow would make it scannable without losing 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?

No output schema exists, and the description compensates by detailing returned plates, recipe prompts, formulas, and multi-reference mixing rules, which is enough for an agent to call it correctly. Minor gaps remain around side effects and whether the call creates any persistent artifact.

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 the baseline is 3, but the description adds real meaning: it decomposes the brief (product, audience, length, platform), expands reference id forms (REF ids, links, ids, brand:<import>:<film>), and explains that brand injects a house-style constraint and can substitute for references.

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 ('plan a video from references') and immediately explains what planning yields (plates carrying timing/look, recipe prompt, best-matching formula). It explicitly segments itself from the sibling get_blueprint ('For every plate of one film, use get_blueprint'), so an agent can route correctly without reading schemas.

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 concrete use conditions (1-5 references, optionally a brand for house style; optional references when a brand is named), names the alternative tool for the adjacent case, and lays out the downstream sequence: draft storyboard, check with the storyboard tool, lay out as a Claude Design canvas, user picks a direction, then write the build prompt.

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?

With no annotations, the description carries the burden and does meaningful work: it discloses the return shape (compact cards enumerating REF id, link, thumb, length, aspect, views, measured metrics, and rationale) and notes the library is pre-dissected. It omits auth/rate-limit behavior and the partial-match fallback detail (which lives in the schema), so not fully complete.

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 dense paragraph that front-loads what the library is and what results contain before the call-to-action routing. Every clause carries information; it is slightly long but nothing is redundant boilerplate.

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 13-param tool with no output schema, the description compensates well by enumerating the returned card fields and the metrics available. It does not explain the ordering/pagination mechanics, but those are covered by schema descriptions, so an agent has enough to call it correctly.

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 77% with 13 params, so the schema already documents most fields including enums and defaults. The description adds only that a REF id or link can be passed via a ref, and does not enrich the meaning of brand, category, made_with, or the seconds filters beyond the schema. Baseline 3 is appropriate.

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+resource (search a curated video library) and pins the scope with concrete content types and counts (4,000+ dissected top-performing videos). It also names the downstream siblings (get_blueprint, plan_video), so an agent can distinguish this discovery tool from the retrieval/planning tools without opening their schemas.

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 explicit when-to-use context ('find references before making a video') and names the follow-on alternatives to pass a ref into. It stops short of stating when NOT to use it (e.g. use get_collection for curated sets), so it is clear context rather than full when/when-not routing.

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?

With no annotations the description carries the full burden, and it does so well: it discloses the two output branches (ok:false lists what to fix; ok:true gives canvas/text-board layout instructions), that it returns each REF's real still, and even the Pro/free tier note. It omits permissions, rate limits, and error conditions, so it is not exhaustive.

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?

Front-loaded with the moment of use, and nearly every clause adds actionable detail rather than restating the name. It is a dense wall of text with several run-on sentences that could be broken into a when-to-use line, an input-shape line, and an output-behavior line, so it is not maximally scannable.

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 very complex nested-schema tool with no output schema and no annotations, the description covers the workflow, both return branches, the direction-count logic, and layer conventions. The main omission is any guidance on the top-level technical params (aspect, bpm, fps, length_s) that shape the call.

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 (30%), so the description must compensate; it does so strongly for `directions`, enumerating per-direction contents (logline, references with one job each, palette, type, sound, style frames, 3-30 panels with in/out seconds, shot size, camera move, transitions, layers) and the 'real' flag semantics. However, top-level parameters like bpm, fps, aspect, and length_s get no mention, leaving a real 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?

The description states a specific verb and resource ('storyboard the film', 'checks the timing and the REF ids') and explicitly names the sibling it consumes from and differentiates against ('the storyboard you drafted from plan_video'). An agent can tell this apart from plan_video and the other siblings without opening the schema.

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 and workflow position ('Before anything is built', feed in the plan_video output, 1 direction for a fixed brief vs 2-4 when open) and an explicit retry rule ('fix it and call again') plus a post-condition ('Let the user pick a direction before you write any build prompt'). It stops short of explicitly contrasting similarly-named siblings such as check_render, so it is not a full when/when-not guide.

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