FrameThrower

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

Annotations already declare readOnly and openWorld, and the description adds real context: the conditional researched profile only appears for certain kinds, and the breakdown includes awards by show, tones/genres, and best/most recent work. It omits failure behavior for unknown names and any pagination or cost characteristics.

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?

It is a single sprawling sentence with em-dash and parenthetical stacking, which makes it hard to scan, though nearly every clause carries real information. It lacks a leading verb-based statement of what the tool does.

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 carries the burden of describing returns and does so thoroughly, including the conditional profile block. The remaining gap is input semantics — how `name` should be supplied and what happens when a name doesn't resolve.

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 50% — `kind` has a description but `name` does not. The description loafs in a parallel kind list ('brand, director, agency, production company, DP, editor or composer') that diverges from the enum (omits edit_house, post, music, sound, vfx; 'composer' is not an enum value), and says nothing about name matching semantics such as exact vs fuzzy.

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 ('track record ... in FrameThrower's ads library') and enumerates what the profile contains, so an agent knows it aggregates people/company history. It does not, however, distinguish itself from commercials_stats or search_commercials, which plausibly return overlapping data.

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 statement of when to call this versus the sibling tools (stats, search, find_by_craft). The only conditional guidance is buried mid-sentence ('for directors / agencies / production companies with a public page'), which describes output behavior rather than tool selection.

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 and openWorldHint=true, so the description adds useful behavioral context by explaining that the tool counts and ranks commercials with breakdowns by dimension. It still does not explain the exact return format, ranking metric, or how limit affects results, leaving some operational details implicit.

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 action ('Count and rank the ads library') and follows with a compact enumeration of dimensions plus one concrete example. Every sentence contributes to understanding how to use the tool.

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 26-parameter aggregation tool with no output schema, the description is adequate: it explains the central concept, identifies the required fields dimension, and demonstrates a realistic filtered query. It still leaves some gaps around output structure and ranking behavior, but the combination of schema descriptions and this narrative is sufficient for common calls.

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?

With 65% schema description coverage across 26 parameters, the description adds meaningful semantics for the key fields parameter by framing its values as breakdown dimensions. The worked example also clarifies how award_show, industry, and year_min combine in practice, though several parameters such as limit and min_award are left to 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 uses a specific verb and resource: 'Count and rank the ads library'. It immediately clarifies that this is an aggregation tool rather than a search or record-retrieval tool, which distinguishes it from siblings like search_commercials and get_commercial.

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 example query ('which agencies won the most Cannes Lions for car ads since 2015') clearly illustrates the intended aggregation use case and maps it to parameters. However, it does not explicitly state when not to use this tool or name alternatives such as search_commercials.

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 description adds behavioral context beyond the annotations by stating that filters can be combined to narrow results, implying an AND-like filtering behavior. It does not contradict the readOnlyHint or openWorldHint annotations, and the read-only nature is already covered by 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 concise, consisting of two short sentences that immediately state the tool's purpose and usage. It is well-structured and front-loads the key information without unnecessary fluff.

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?

Although the tool has nine optional parameters and no output schema, the description lacks important context such as how parameters combine (AND/OR), the meaning of the 'limit' parameter, or any edge cases. It mentions 'combine to narrow' but does not specify semantics, and does not address paging or result ordering, leaving some gaps for a complex search tool.

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 description lists all nine parameters by name, covering even those without explicit schema descriptions (e.g., director, year_min, year_max). It clarifies they are optional and combinable, but does not provide detailed per-parameter semantics beyond the names and a few schema examples. This partially compensates for the 44% schema coverage.

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 clearly states the tool's purpose: finding frames by specific cinematography craft attributes, listing examples like lens character, shot size, and director. It distinguishes itself from siblings by focusing on craft attributes and explicitly mentions refining a search, which differentiates it from general search_frames and similarity-based find_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?

It provides guidance on when to use the tool ('to refine a search precisely') and notes that all parameters are optional and combinable to narrow results. However, it does not explicitly mention when not to use it or contrast with siblings, leaving some inference to the agent.

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 declare readOnlyHint=true and openWorldHint=true, which cover safety and open-world expectations. The description adds context on the input ('from a prior result') but doesn't disclose details like how similarity is computed or result ordering, though given the annotations the description does not contradict them and provides some added value.

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 sentences with no fluff. It front-loads the core purpose and then gives a concrete use case. Every word 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?

The tool is simple (2 params, no output schema) and the annotations provide some context, so the description is adequate. However, it lacks details on the output format (e.g., a list of frames) or how the 'similarity' is determined, which could be useful for an agent but is not strictly required.

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 0% and there are only two simple parameters (frameId and limit). The description does not elaborate on the semantics of these parameters beyond what schema provides (string id, number limit with bounds), but with such simple parameters the baseline of 3 is reasonable.

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 the tool finds frames similar to a given frame id and the use case of pulling more references, which clearly distinguishes it from siblings like search_frames or get_frame_details. However, it could be more explicit about the 'visually/semantically' modes but it is still 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?

The description gives a usage hint ('from a prior result', 'shortlisted') but does not explicitly state when NOT to use it or mention alternatives. It implies the tool is for extending a set of references, which is somewhat useful but could be more directive.

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 and openWorldHint=true, and the description adds real value by itemizing exactly what payload comes back (credits by role, awards, craft numbers, script timings, shot list) since there is no output schema. It omits the credit cost of clips: true (8 vs 2), though the schema parameter description covers that.

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 front-loaded sentence that opens with the resource and scope, then enumerates fields. The dense mid-sentence list of credits and craft metrics is long but every item conveys distinct content an agent could not get from the schema.

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 carries the full burden of describing the return value and does so thoroughly, and all three parameters are documented at 100% coverage in the schema. Minor gap: the clips credit cost and pagination/size expectations are not mentioned in the description itself.

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% and the schema already explains id format (AD-0505), the clips cost tradeoff, and the default for shots. The description only restates clips behavior ('with clips: true, each shot's clip too'), adding nothing the schema does not already say.

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 definition gives a specific verb+resource ('The full breakdown of one commercial by id') and then enumerates the returned content, so its role as the single-record detail tool is unmistakable versus the search_* siblings. It stops short of explicitly naming any sibling tool, so the distinction is inferred from content breadth rather than stated.

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?

Usage is only implied: the phrase 'full breakdown of one commercial by id' signals the drill-down case after a search, and 'with clips: true, each shot's clip too' hints at the optional branch. Nothing states when to prefer this over commercials_profile or find_similar, and there are no exclusions or prerequisites.

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 and openWorldHint=true. The description adds value beyond that by detailing the returned artifacts and noting the depth map is 'precomputed and free,' which informs cost/effort expectations. No contradiction with 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?

Two tightly written sentences with no filler. The verb and resource are front-loaded, and the second sentence adds a practical use case without redundancy.

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 single-parameter read-only tool with no output schema, the description is complete: it enumerates the returned data, clarifies the input, and gives a use case. The annotations cover safety, and no additional context seems necessary 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?

With 0% schema description coverage, the description carries the parameter-semantics burden. It clarifies that frameId identifies a single frame and that the depth map belongs to 'this frame,' but it does not explain where a valid frameId comes from or any format constraints. The guidance is adequate but minimal.

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 ('Get') and resource ('full metadata + preview thumbnail + full-resolution image URL + depth map URL + link') for a single frame id. This clearly differentiates from sibling search/find tools by focusing on a single existing frame rather than retrieval or discovery.

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 explicit context: 'use it when the user is generating images and needs the composition or camera geometry of this frame.' It does not explicitly mention when not to use it or name sibling alternatives, 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real value beyond that by disclosing the default result ordering (award winners first when no query) and the per-result payload (brand, title, year, credits, best award, logline, still, watch link). It doesn't mention pagination limits or result-count caps, 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?

Three sentences, front-loaded with the verb and the resource, then the query examples, then the return payload — a sensible order. The long enumeration of filterable facts is dense but each item is load-bearing for a 28-param tool; only the parenthetical examples could be trimmed.

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 does the work by listing the fields returned per spot, which is exactly what an agent needs to decide whether to call it. Combined with the default-sort rule and query semantics, the definition is nearly self-sufficient; the missing piece is any statement about pagination/limit behavior for a tool that returns a list.

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?

With 28 params at 64% schema coverage, the description compensates by enumerating most filter dimensions (brand, director, agency, production, DP, editor, award show/level, year, industry, market, tone, genre, structure, season) and by explaining the most important one — 'query' as the plain-language idea/story, with worked examples. It leaves music, format, celebrity, duration bounds, person, sort and limit/offset to the schema, so coverage is good but not complete.

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 (Find) plus a precisely scoped resource — 'whole COMMERCIALS (TV / online spots)' — which implicitly separates it from the sibling shot-level tools like search_commercial_shots and search_frames. It also explains the two access modes (idea/story query vs. structured facts), so an agent knows exactly what this tool returns.

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 concrete example queries and an explicit behavioral rule for the alternative mode: 'Without a query it lists matching spots, award winners first.' That clarifies query-vs-filter usage well. It stops short of naming sibling tools (e.g., directing shot-level searches to search_commercial_shots), so routing is implied by the 'whole commercials' framing rather than stated.

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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description adds genuinely useful behavior the annotations don't: what each hit contains (still, tags, deep link to the exact moment) and an explicit cost delta (8 credits with clips vs 2 without), which matters for a paid, open-world search.

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 sentences, front-loaded with the purpose and examples before the output description. The long parenthetical tag list is dense but each item corresponds to a real filter param, so it earns its space; the only mild redundancy is restating what a shot result 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?

For a 29-param open-world search with no output schema, the description explains the return shape (still, tags, exact-moment link, optional clip) and cost, which is the critical missing piece. It stops short of saying whether query and filters combine as AND, how results are ranked, or the default limit.

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 69%, so the schema does much of the work, but the description adds meaning beyond it: the query should read as a description of one frame, the tag taxonomy (size, angle, setting, time of day, lighting, mood, people, product/logo) maps the filter params into groups, and clips carries its cost tradeoff.

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?

Opens with a specific verb and resource ('Find individual SHOTS inside commercials') and immediately scopes it to frame content with three concrete query examples. It also makes clear the result unit is a shot, not a commercial, which separates it from search_commercials even though the call accepts commercial-level filters.

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 frame-description framing implies when to reach for it, and it gives one real usage rule ('Ask [for clips] only when the user wants to see the shots move'). But it never names an alternative or an exclusion, despite siblings like search_frames, similar_commercial_shots and search_commercials that an agent must choose between.

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 flag readOnlyHint and openWorldHint, so the safety profile is covered; the description goes further by enumerating the actual return payload — film/credits metadata, preview thumbnail, full-resolution URL, greyscale depth map with matching dimensions, and a viewer link. It adds real consumption guidance (which URL for decks, which for depth ControlNet) that annotations cannot express. Minor gap: nothing about result caps, ranking, or pagination 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?

A single front-loaded sentence that leads with the search action and then spends its remaining length on payload details an agent genuinely needs. It is dense but not padded; the parenthetical about depth maps is long yet earns its place by telling the agent how to consume the output.

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 carries the return-value burden and does so thoroughly, covering every artifact returned and its intended downstream use. Annotations handle the read-only/open-world profile, leaving only pagination, result caps, and ranking transparency as unaddressed details.

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%: query and enhance are documented in the schema, and the description's 'by concept, mood, color, composition, or scene' loosely reinforces what query accepts. The limit parameter (1–40) is undocumented in both places and the description does not compensate, so performance sits at the baseline rather than above it.

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 (search) and resource (FrameThrower cinematography reference library) plus the searchable dimensions: concept, mood, color, composition, scene. An agent can distinguish it from search_commercials / search_commercial_shots because the resource is explicitly 'frames', though the description never names a sibling to sharpen that contrast.

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?

Usage is implied rather than stated: you search for visual references, and the description advises using the full-resolution URL for decks/documents and the depth map for ControlNet pipelines. There is no explicit when-to-use-this-vs-find_by_craft-or-find_similar guidance, so the agent must infer tool selection from names alone.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description adds useful semantics — the story/look distinction and that filters compose with similarity — but says nothing about what comes back, whether the source commercial is excluded, or how results are ranked/capped (limit max 20). It also doesn't warn that this is a search over an open corpus that may return few or no matches.

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 sentences, densely packed, with the core operation front-loaded and the story/look gloss and filter hint following. No filler, no repetition of the title.

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 10 parameters and no output schema, the description should say at least roughly what a result set looks like (commercial records? ranked list?) and whether the seed commercial is included. It also omits the default for 'limit'. The available budget is small and mostly well spent, but a similarity tool that returns none of this leaves a real gap.

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 70%, so many parameters are already documented. The description still adds real meaning beyond the schema: it explains what 'story' and 'look' actually compute over (tropes and tone vs. light, framing, palette), which the bare enum values 'story'/'look' do not convey, and it signals that the remaining filter parameters mirror search_commercials' filter set.

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 operation (find commercials similar to a given one) and defines the two axes precisely: STORY (idea, tropes, tone) versus LOOK (light, framing, palette). That is far more than a restatement of the name. It falls short of 5 because it never differentiates itself from the near-duplicate sibling find_similar, leaving the agent to guess which of the two to pick.

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 implies usage through 'Accepts the same filters as search_commercials to narrow (e.g. only award winners, only another brand)', which shows a realistic narrowing scenario. However, there is no explicit statement of when to choose this over find_similar or similar_commercial_shots, and no exclusions. Usage is inferable but not prescribed.

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 establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that the filters act as optional steering alongside the seed ids, which is useful. It does not mention credit cost of the base call, default limit, or that clips raises cost, though the schema covers the clip cost.

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, front-loaded with the core action and then the refine-loop rationale. No filler; only mild loss from the quoted example phrase eating space that could note the return shape.

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 21-param similarity search with no output schema, the description conveys the seed-plus-steering model an agent needs to call it plausibly. Still missing the interaction between shot_ids and the 20 optional filters, and any hint of result shape or default limit.

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 57%, so the schema handles roughly half the 21 parameters. The description adds the key semantic point that the tag/filter params steer similarity rather than hard-restrict, which is beyond what the schema says. It leaves ambiguous whether filters combine with shot_ids or override them.

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: returns shots similar to given shot_ids. The 'refine loop: more like #2' framing makes the operation concrete. It does not name the nearest sibling (find_similar, search_commercial_shots) to disambiguate, 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?

'from earlier results or a shot list' implies the tool depends on a prior search, and 'refine loop' hints at iterative use. But there is no explicit when-not-to-use guidance or comparison to find_similar / search_commercial_shots, which sit right next to it in the list.

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