Stockfilm — Authentic Vintage Footage

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

Annotations already cover readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds useful behavioral context by stating the tool auto-assembles and returns an ordered list with durations, which is not present in the annotations. There is no contradiction with 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 short sentences with no filler. It front-loads the action, then states output and use case, and every sentence adds useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With complete parameter descriptions, read-only/open-world annotations, and a clear statement of the return value, an agent has enough to call the tool correctly. A concrete output example or mention of edge cases would improve completeness, but they are not essential for this 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?

All five parameters have schema descriptions, including pace ranges, year filters, and target_seconds bounds, so the schema carries most of the semantic weight. The description's mention of 'based on a description' and 'timed sequence' lightly reinforces the query and timing parameters but adds no new detail 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?

The description names a specific verb and resource: 'Auto-assemble a timed sequence of vintage clips into a video timeline based on a description.' It also states the core deliverable, an ordered clip list with durations. This clearly distinguishes it from sibling tools like search_vintage_footage or license_clip.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Great for creating edit lists or storyboards' gives a clear intended use case. It does not explicitly mention when not to use the tool or name alternative tools, but the edit-list/storyboard context is enough to guide selection among the provided siblings.

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 safety profile is covered. The description adds the behavioral context that this is a pre-licensing eligibility check and that AI training requires a separate written agreement (in the schema). It doesn't describe what happens when a clip is ineligible or whether it returns a simple boolean vs. detailed rights information, but the annotations carry the main safety burden.

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 states the tool's purpose and key use cases with zero waste. 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 read-only, idempotent check tool with 100% schema coverage and no output schema, the description is nearly complete. It could mention what the response looks like (e.g., eligible/not eligible) or what happens for ineligible clips, but the annotations and schema cover the essential safety and parameter context.

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 both parameters. The description adds the intended-use examples (commercial, editorial, broadcast) which align with the schema's enum-like list, but doesn't add meaning beyond what the schema provides. 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?

The description uses a specific verb ('Verify') with a clear resource ('a clip') and a clear condition ('eligible for a given intended use'), and it names example use cases (commercial, editorial, broadcast) that distinguish it from siblings like license_clip or get_clip_details. It clearly states the tool's role in the licensing workflow.

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 when to use this tool: before licensing, to verify eligibility for a specific intended use. It doesn't explicitly name alternatives or exclusions, but the context of 'before licensing' and the sibling list (license_clip, get_clip_details) makes the usage context clear. It could be stronger with an explicit 'use this instead of X when...' statement.

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 idempotentHint/openWorldHint, description discloses real behavior: external Stripe payment, idempotent reuse ('Repeating the same quote reuses its order'), and the caution 'Creating checkout is not proof of purchase.' 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?

Four sentences, zero filler; the critical precondition is first, then return values and caveats. 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 two-parameter mutation tool with no output schema, description covers preconditions, return shape, idempotency, payment security, and status caveat. It equips an agent to call correctly and avoid common mistakes.

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 covers 100% of parameters with detailed descriptions, so baseline 3 applies. Description reinforces quote context and reuse but adds no new parameter-level syntax or formatting.

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?

Description opens with 'Create or resume Stripe hosted checkout for a quoted 4K license', a specific verb and resource, and adds return value ('checkout URL and private order token') that separates it from retrieval/quote siblings.

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?

Explicit precondition: 'Call ONLY after the user explicitly approves...' and 'never collect card details in chat' clarifies when not to proceed. However it doesn't name sibling alternatives like get_4k_order or quote_4k_license, so exclusions remain implicit.

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, covering safety. The description adds that it returns clips from the Stockfilm archive, giving context on the data source. However, it does not disclose behavior like result ordering, pagination, or error handling, which is acceptable given the read-only nature and existing 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 a single sentence that front-loads the main action ('Find visually similar vintage clips') and provides the key input. It has no redundant filler and is easy to parse.

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 with two parameters and no output schema. The description explains the purpose and the return type (clips with similar visual content). It does not mention the limit parameter or any limitations, but the schema covers that. Overall, it is sufficiently complete 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?

The schema documents both parameters (clip_id and limit) with descriptions, so the schema already provides full meaning. The description adds nothing beyond restating that a clip ID is needed, so it does not improve 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 clearly states the verb 'find' and the resource 'visually similar vintage clips' based on a clip ID. It distinguishes itself from search_vintage_footage by specifying similarity-based retrieval rather than keyword search, 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?

The description implies the tool is used when you have a clip ID and want similar content, but it does not explicitly state when to prefer this over search_vintage_footage or other siblings. There are no exclusions or alternative routing given, so the agent must infer the appropriate context from the tool's purpose 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?

Even with annotations present, the description adds substantial behavior beyond them: the Stripe payment-verification side effect, the fact that it may activate an already-paid license, the polling rate limit, and the confidentiality requirement for the token and download URL. None of this contradicts the annotations (readOnlyHint=false, idempotentHint=true).

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 main purpose is front-loaded in the first sentence, and each subsequent sentence adds a distinct operational rule (prerequisite, activation side effect, completion criterion, retry condition, polling limit, privacy). Given the behavioral complexity, the length is fully justified with no filler.

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 1-parameter tool with no output schema, the description covers the critical operational facts: what is retrieved, the completion condition, the retry condition, and the rate limit. The only gap is the precise response shape and failure-mode handling, which would normally come from 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%, so the baseline is 3. The description restates that order_token comes from create_4k_checkout and must be kept private, but the schema already says both of these things. No additional meaning is added beyond the schema for the single parameter.

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: verify a 4K order's payment with Stripe and retrieve the license, receipt, and private master download. It clearly differentiates from siblings — it references create_4k_checkout as its prerequisite and is distinct from quote_4k_license and license_clip, which handle quoting and licensing rather than post-payment fulfillment.

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?

Explicit when-to-use and when-not-to-use guidance is given: requires the token from create_4k_checkout, retry later if delivery_status is preparing, never claim completion until purchase_completed is true, and poll no faster than once every 10 seconds. This fully equips an agent to sequence the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safe read-only nature is clear. The description adds the set of returned fields but no additional behavioral caveats, which is acceptable given the strong 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?

One focused sentence with the action and resource front-loaded, followed by a compact list of returned fields. There is no repetition or filler.

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?

This is a simple single-parameter, read-only retrieval tool. The description, schema, and annotations together fully cover what an agent needs to invoke it correctly: what it does, what it returns, and that it is safe and idempotent.

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 fully documents the single clip_id parameter. The description adds no parameter-specific detail beyond indicating the target is a specific Stockfilm clip, which does not exceed the schema baseline.

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: 'Get full details for a specific Stockfilm clip' and enumerates concrete fields (description, year shot, location, price, resolution, thumbnail URL, preview URL). This clearly differentiates it from siblings like check_clip_rights or search_vintage_footage.

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 schema parameter description says clip_id is 'The clip ID from search results,' which implicitly tells the agent to call this after searching. However, the description itself gives no explicit when-to-use or when-not-to-use guidance, nor does it name 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 establish read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by stating that the user is not charged, no license is issued, and payment is not processed. The 4K masters vs. 144p x402 detail provides additional product context 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?

Four sentences, each serving a purpose: stating the core function, adding product context, advising pre-purchase review, and clarifying non-action. The 4K/144p detail is slightly peripheral to invoking the tool, but the description remains tight and 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?

Given the low complexity, complete schema for the single parameter, and strong annotations, the description covers the essential purpose and behavioral boundaries. It does not specify the exact return shape, but the absence of an output schema and the simplicity of the tool make this a minor 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?

The single parameter clip_id is already fully described in the schema as 'The clip ID to license,' so schema description coverage is 100%. The description mentions 'eligible clips' but does not add substantial meaning about the parameter's format or validation requirements 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 opens with a specific verb and resource: 'Get licensing options for a clip.' It also clarifies the tool does not issue a license or process payment, which helps define its scope. It does not explicitly contrast itself with sibling tools like check_clip_rights, so it falls just short of full differentiation.

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 clearly frames this as a no-charge, no-commitment lookup and tells the user to review availability, exact price, and terms on the clip page before purchase. This gives clear context for when to use the tool, though it does not explicitly name alternatives or state when not 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?

The description adds important behavioral context beyond the annotations: it does not charge the user, verifies resolution and licensing availability, requires showing the full quote before checkout approval, and excludes AI training. No contradiction exists with the annotations; the readOnlyHint false is consistent with a tool that creates or processes a quote.

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 five concise sentences, front-loaded with the primary action and followed by essential behavioral and workflow constraints. Every sentence adds useful information: eligibility, verification, required inputs, no charge, checkout approval, and AI training exclusion.

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 there is no output schema, the description adequately covers what the tool returns and does: a complete quote with terms. It also informs the agent about required inputs, the non-charging behavior, and the proper sequence before checkout, making it sufficiently complete for a tool of this complexity.

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 high at 80%, so the schema already documents term, territory, usage_scope, and customer_email. The description adds process guidance to 'ask for the buyer email and desired use, territory, and term,' but it does not clarify the undocumented clip_id parameter or provide format/constraint details beyond what the schema already says.

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: 'Quote an eligible, unwatermarked 4K master using the website's direct license pricing.' It also clarifies the scope by noting verification of resolution and licensing availability, and explicitly distinguishes itself from charging/checkout actions by saying 'Does not charge the user' and 'before requesting checkout approval.'

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 a clear workflow: ask for buyer email and desired use/territory/term, verify eligibility, show the quote, then request checkout approval. It implies the next step is a separate checkout tool, but it does not explicitly name alternatives like license_clip or create_4k_checkout, nor does it state when-not-to-use this tool.

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, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by specifying return contents (metadata, pricing, thumbnails, licensing info) and the authenticity guarantee ('real 8mm/Super 8 film — no AI-generated content').

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 deliver the core action, resource, temporal scope, return fields, and a key content guarantee with no filler. The most important identifying 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 covers return content. All five parameters are documented in the schema, annotations cover side effects, and the description supplies the essential domain context. Nothing an agent needs to call this tool 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 coverage is 100%, and parameter descriptions are already detailed. The description adds value by framing the default era (1930s-1980s), which helps agents interpret year_from/year_to filters and the scope of the query parameter.

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 ('Search') and identifies a distinct resource: Stockfilm's archive of vintage home movie clips from the 1930s-1980s. It clearly distinguishes itself from siblings like get_clip_details or license_clip by stating what the search 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?

The description implies usage by framing this as the archive search entry point, but it does not explicitly state when to use this tool versus siblings like find_similar_footage or check_clip_rights. No exclusions or alternative routing are provided.

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