footage.cool: 4K Drone & Aerial Stock Footage

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond this: it does not render video or license anything, and it returns an edit decision list with preview URLs. This helps the agent set expectations about side effects and output without contradicting 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 three sentences with no fluff: the first front-loads the core planning action, the second describes the output, and the third lists exclusions. Every sentence earns its place, and key differentiators are prominently stated.

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 8 parameters and no output schema, the description provides solid context: it explains the high-level purpose, the nature of the return value (EDL with preview URLs), and what the tool does not do. It misses some detail about how ordering or cost totals are computed, but the core information needed to invoke it correctly is present.

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 already describes all 8 parameters with 100% coverage, including pace ranges, query examples, and defaults. The description's references to 'description', 'chosen pace', and 'shoots and locations' map to existing parameters but add no new semantic detail. Baseline 3 is appropriate given the schema handles parameter documentation.

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 function: 'Plan a timed edit from a description' and details what it does (picks/orders clips, sets cut lengths, totals license cost, returns an EDL with preview URLs). It also explicitly differentiates from render/license tools by stating what it does not do, which helps distinguish it from siblings like license_clip and render-related tools.

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 provides clear context for when to use the tool: when you have a text description and need a timed rough-cut plan. It also offers exclusions ('does not render video or license anything') that tell the agent situations where this tool is not appropriate. However, it does not explicitly name alternative tools, 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, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by stating it reports chain of title, people/property flags, and release policy, and explicitly disclaims legal advice. It doesn't describe any side effects, but for a read-only tool this is sufficient.

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 concise sentences: purpose and tiers first, output details second, disclaimer third. No redundant phrasing or filler. Every sentence earns its place, and key information is 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 no output schema, the description adequately describes what the tool returns (chain of title, flags, release policy). It also clarifies its non-authoritative nature. For a read-only check tool with fully documented parameters, this is complete enough for an agent to invoke 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 description coverage is 100%, so the baseline is 3. The description repeats the list of intended uses from the schema but adds no new meaning beyond that. The schema already explains the default and the AI data license note, so the description doesn't materially enhance parameter understanding.

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 a clear verb ('Screen') and resource ('a clip'), and states exactly what it does: checks license coverage and which tier fits. It also distinguishes itself from siblings like license_clip (which actually licenses) by focusing on the screening aspect. The listed use tiers and output (chain of title, flags, release policy) make its purpose unmistakable.

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 clear context for when to use this tool: to screen license coverage before an intended use. It does not explicitly name alternatives or exclusion conditions, but the phrasing 'Catalog screening, not legal advice' implies a pre-license check use case. Given the sibling list, an agent can infer this is the read-only precursor to license_clip, though explicit when-not guidance is absent.

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 provide idempotentHint=true and destructiveHint=false; the description expands on this by explaining that calling again returns the same checkout, that it returns a checkout URL and private order token, and that it is not proof of purchase. It also discloses the security-sensitive nature of the token.

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 compact and front-loaded: it states purpose first, then prerequisites, then return info, then caveats. Every sentence adds value with no redundancy, making it easy for an agent to parse quickly.

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?

Given the tool's complexity (checkout creation, idempotency, security), the description covers all key aspects: when to call, what it returns, idempotent behavior, and a caution about card details. It also ties the token source to quote_4k_license, which is a sibling, providing enough context without an output 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% with descriptive parameter comments. The description adds extra context beyond the schema: it emphasizes that quote_token is private and should never appear in public links or logs, and reinforces the 'confirmed' flag as the gate for user approval. This adds meaningful security and usage nuance.

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 clear verb ('Create or resume') and a specific resource ('Stripe hosted checkout for a quote'), and it distinguishes itself from siblings like quote_4k_license and license_clip by focusing on the checkout step. The scope and outcome are unambiguous.

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 states the precondition: call ONLY after user approves the quoted clip, master, license, price, and terms. It also warns against collecting card details in chat and notes that creating checkout is not proof of purchase, giving clear boundaries and safety rules.

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, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, non-mutating read. The description adds value by disclosing that results are 'spread across different shoots so the results are not near-duplicates,' which is a behavioral guarantee beyond the annotations. It also lists the specific similarity dimensions. However, it doesn't mention any rate limits, authentication, or edge cases, so it's not exhaustive, but with the annotations covering safety, a 4 is appropriate.

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 one tightly-worded sentence that packs the core purpose and criteria, followed by a short clause on use cases. No filler or redundant information. It is front-loaded with the main action, making it easy to parse quickly. 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?

For a simple list-returning tool with no output schema, the description covers the essential aspects: what it does, how similarity is determined, and that it avoids near-duplicates. It doesn't specify the return format (e.g., whether it returns clip IDs or full metadata), but the tool name and context imply a list of clips. Combined with annotations that establish safety, this is adequately complete for an agent to invoke correctly, though a note on the result structure would push it to 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?

Schema description coverage is 100%: limit is described as 'Number of results, 1 to 24 (default 8)' and clip_id as 'Clip to find similar footage for (clip_id from search_footage).' The tool description adds no extra meaning beyond the schema—it doesn't elaborate on parameter behavior or formats. Since the schema already documents both parameters thoroughly, the baseline of 3 is correct; the description does not need to compensate.

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 verb 'find' and the resource 'clips similar to a given clip', then specifies the similarity criteria (shared subjects, scene, location, shot year) and the deduplication behavior. It differentiates itself from search_footage (which searches by explicit criteria) and get_clip_details (which returns a single clip) by focusing on similarity to an existing clip. This gives a precise and unambiguous purpose.

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 includes explicit use cases: 'offer alternatives or to keep a sequence consistent.' It implies the tool is appropriate when you have an existing clip and want related footage, but it does not explicitly state when NOT to use it or name alternative tools. The context is clear enough for an agent to select it appropriately among siblings like search_footage, though a direct comparison would have made it fully 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?

Beyond annotations, the description reveals Stripe verification behavior, the exact returned artifacts, the purchase_completed flag requirement, a polling rate limit, and privacy obligations. This substantially exceeds what idempotentHint and destructiveHint imply, and there is no contradiction.

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?

Four tight sentences that front-load purpose and return values, then deliver operational guardrails. Each sentence adds essential guidance with no filler or redundant detail beyond the critical privacy reminder.

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 tool with no output schema, the description sufficiently covers prerequisites, expected return content, a boolean completion gate, rate limiting, and privacy. An agent has everything needed to decide when to call it and interpret the result.

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 documents order_token as private and returned by create_4k_checkout. The description reinforces this but does not add new parameter-level semantics beyond the schema's text, so the high-coverage baseline applies.

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?

Clearly identifies a specific action ('Check a 4K order after checkout') and enumerates concrete outcomes: active license, receipt, certificate link, and download link. It is distinct from sibling checkout/quotation tools because it is explicitly positioned as the post-checkout follow-up to create_4k_checkout.

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 contextual conditions: call after checkout, requires the token from create_4k_checkout, and must not be polled faster than every 10 seconds. It lacks an explicit list of alternatives or when-not-to-use scenarios, but the context is unambiguous.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds functional context by specifying the kind of data returned (counts by various dimensions and pricing) and its role in discovering valid category values. This enriches the agent's understanding beyond the annotations without contradicting them.

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 exactly two sentences, front-loaded with the core content (what the overview includes) and then the usage guidance. Every word earns its place; there is no redundancy or filler. The structure makes it easy for an agent to quickly parse both the tool's function and its recommended use.

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 zero-parameter, read-only overview tool with no output schema, the description is complete. It tells the agent what data to expect (counts by categories and pricing), how to use it (to discover valid category values), and connects it to related tools. Nothing an agent needs to call it correctly 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?

The tool has zero parameters, so the baseline score is 4 per the rubric. The description correctly notes that it is an overview tool with no inputs; it does not need to explain parameter semantics. The description's mention of what it returns is sufficient for a no-input tool.

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 explicitly states the resource and scope: 'Overview of what footage.cool's library covers: clip counts by shot year, scene category, subject, and location (grouped by region), people versus no-people counts, and pricing.' It also differentiates from siblings by positioning itself as a discovery tool for valid category values used by search_footage and build_rough_cut. This makes the tool's role unmistakable.

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 provides explicit usage direction: 'Use it to see what exists and to find valid category values for search_footage and build_rough_cut.' This tells the agent exactly when to call this tool and ties it to specific sibling tools, leaving no ambiguity about its purpose relative to alternatives.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by listing the exact content of the response (e.g., 4K master verification status, licensing options), which helps the agent understand what data to expect. It does not introduce side effects or contradict annotations, so this is a strong addition beyond the structured metadata.

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 sentence that front-loads the main action ('Get full details for one footage.cool clip') followed by an efficient enumeration of the returned fields. It is slightly long but each item adds clarity about the tool's output, so no sentence is wasted. It strikes a good balance between completeness and brevity.

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 only one parameter and no output schema, the description carries the burden of explaining the return value. It lists all major fields (description, tags, location, shot year, duration, people, release notice, collection, thumbnail, watermarked preview, clip page, 4K master status, licensing options) making the expected output clear. It omits error handling details, but for a simple read operation this is not critical.

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 input schema provides a thorough description for clip_id, explaining it can be a numeric or filename-style id from search_footage, and that a URL also works. Since schema coverage is 100%, the description does not need to add further meaning. It does not offer additional semantics, matching the baseline of 3.

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 ('Get') and resource ('full details for one footage.cool clip') and enumerates the exact fields returned (description, tags, location, etc.). This makes the tool's purpose unambiguous and clearly distinguishes it from sibling tools like search_footage (which returns lists) and license_clip (which performs licensing actions). The scope is precise: a single clip's detailed record.

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 usage when detailed information about a specific clip is needed, but it does not explicitly state when to avoid this tool or mention alternatives. For example, it doesn't say 'for licensing, use license_clip' or 'for rights, use check_clip_rights'. The guidance is inferred from the wording rather than stated, which is adequate but not 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?

Beyond the readOnlyHint annotation, the description discloses that no charge occurs, no license is issued, and the Exclusive option requires email quoting. These are behavioral traits (side-effect-free and transactional boundaries) that are valuable for an agent.

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-load the primary purpose and pricing, then clarify limitations and alternative. No wasted words; every clause adds decision-relevant 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 single-parameter, read-only tool with no output schema, the description covers purpose, price ranges, behavioral guarantees, and alternative tool. Nothing an agent needs to invoke it correctly 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 already documents clip_id with 100% coverage, including accepted formats and sources. The description adds no additional parameter-level details, matching the baseline of 3 for full 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?

States a specific action (get), resource (licensing options and prices for a clip), and explicitly disambiguates from quote_4k_license by noting that tool starts a purchase. Lists concrete licensing tiers and prices, leaving no ambiguity about what is retrieved.

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 states when not to use this tool ('This tool never issues a license or takes payment') and points to the alternative quote_4k_license for purchases. This provides clear routing guidance for an agent deciding between tools.

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 substantial behavioral detail beyond annotations: it does not charge anything, returns a 30-minute quote token, verifies the master file and reports resolution/codec, and excludes AI training. These are critical operational details not covered by annotations, with no contradictions.

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 and well-structured, front-loading the primary purpose in the first sentence. Each subsequent sentence adds distinct value—verification, pricing, token validity, usage instructions—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 tool with no output schema, the description explains what it returns (a token, resolution/codec info) and the full process (ask user, show quote). It covers all essential aspects an agent needs to invoke it correctly, including the 30-minute validity and no-charge behavior.

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 all parameters are already well-documented. The description reinforces the requirement to ask for customer_email and license_type but does not add new semantic meaning beyond the schema, meeting the baseline for high 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 quotes a license for a 4K master, and distinguishes it from siblings like create_4k_checkout by emphasizing it is a quote that does not charge. It also specifies verification, pricing, and a token, making its purpose unambiguous.

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 explicit step-by-step usage instructions: ask for buyer email and license type first, never invent an email, and show the full quote before checkout. However, it does not explicitly contrast with sibling tools like license_clip or create_4k_checkout, leaving some inference about when to use it.

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, idempotent, and non-destructive. The description adds meaningful behavioral context: natural-language query understanding (synonyms, typos), the returned data types (metadata, thumbnail and watermarked preview URLs, page links, prices), and the guarantee that footage is real, not AI-generated. This goes beyond annotations without contradicting them.

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, front-loaded with the core action. The geographic and temporal details are relevant to search scoping, and the query-capability and return-value sentences earn their place. It is informative without being verbose, though the location list could be trimmed without losing essential meaning.

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?

Given 11 parameters, no output schema, and rich annotations, the description provides a solid overview of the tool's purpose, query behavior, and return contents. It does not explain pagination or sorting, but those are documented in the input schema. It gives an agent enough context to invoke the tool correctly for a search task.

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 baseline is 3. The description mentions query flexibility and synonyms, which aligns with the `query` parameter, but it does not add parameter-specific semantics beyond what the schema already describes (e.g., 'Places and years in the query become filters'). The schema carries the full parameter load.

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 'Search footage.cool's library' – a specific verb and resource – and details the collection's content, scope, and provenance. This clearly distinguishes it from sibling tools like get_catalog_overview, get_clip_details, or license_clip, which perform different operations.

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 usage as the search tool and gives querying tips ('Understands place names, years, synonyms...'), but it never explicitly states when not to use it or names alternatives such as get_catalog_overview for category browsing or find_similar_footage for similarity. No when/when-not guidance is provided.

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