Instavar Video Templates and Studio

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses the account-linking requirement, that it consumes plan usage, that the result is 'a queued job, not a finished video', and that it does not publish. The requestId retry contract ('preserve when retrying, including after a timeout; new UUID for changed content') meaningfully elaborates the idempotent hint.

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 core action and the confirmation prerequisite are front-loaded in the first sentence, and every sentence carries a rule rather than filler. The cost is that the remainder is an unstructured run of imperatives with no grouping by parameter or workflow stage, which makes it harder to scan for a 250-word description.

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 22-param creation tool with no output schema, the description covers the things an agent cannot infer from the schema: prerequisites, billing/account implications, the queued-job return semantics, non-publication, and retry identity rules. Combined with the highly self-describing schema (enums, const values, inline descriptions on confirmed/requestId/automaticBroll/workspaceId), the definition is complete enough to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 27% across 22 params, so the description has to compensate, and it does for the highest-risk fields: script must hold exact spoken words and never filmmaking directions, prohibitedChanges must stay separate from visible copy, generated motion shots capped at 15 seconds, aspectRatio must be preserved. However, large parameter groups (visualDirection, directions, audioLayers, assetSlots, steps, workspaceId) get no semantic treatment, so it only partly closes the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ('Create a private hosted video') plus the triggering condition ('after the user confirms the complete brief and plan usage'). It also actively disambiguates from siblings: 'This is the hosted brief contract, not VideoSpec or paired-announcement source' and 'Does not publish' separate it from scaffold_video_spec, prepare_announcement and any publish flow.

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 guidance is present throughout: confirmation and account linking are prerequisites, automaticBroll must stay off unless the user explicitly requests footage, narrationMode goes off for silent videos, publishTarget is a layout hint rather than a publish action. It even supplies an alternative-selection rule ('not VideoSpec or paired-announcement source') and retry guidance ('new UUID for changed content').

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, destructiveHint=false and openWorldHint=false, so the agent knows this is a safe local read. The description adds that the output is advisory ('a safe next step'), reinforcing non-mutation, but it does not disclose the classification categories or whether it can definitively resolve the error.

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 sentence, front-loaded with the verb and resource, zero filler. Nothing roundabout or restated from 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?

For a one-parameter, read-only tool with no output schema, the description covers the input domain but leaves the return value underspecified ('a safe next step' — a category label, a string, a fix instruction?). Since there is no output schema, the description should at least sketch what comes back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description is the only source of meaning, and it does clarify that errorText should be a local validation or render error rather than, say, a network failure. It says nothing about format expectations (raw stack trace vs. message) or the 10,000-character cap beyond what the schema encodes.

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 ('classify') and a specific resource ('a local validation or render error') plus an outcome ('a safe next step'), which clearly distinguishes it from the scaffolding/listing siblings. It does not explicitly name which sibling to use for non-local errors, but the domain is 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 phrase 'local validation or render error' implies the triggering situation is 'you have an error string', but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., get_render_instructions or get_video_render_status) for cases this tool doesn't cover.

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 behavior beyond the annotations: it returns a Studio approval link, this call does not save copy or start a render, the signed-in user must approve in Studio, approval consumes rerender credits and revokes existing review links, previous run records are retained, publishing is excluded, and requestId must be preserved for unchanged retries. This is exactly the context an agent needs before invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first sentence establishes purpose and scope, followed by the approval workflow and side-effect warnings. Every sentence carries operational value, and no important warning is buried.

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 complex approval workflow with no output schema, the description is strong: it explains the return artifact, approval consequences, credit consumption, link revocation, record retention, and reretry behavior. The main remaining gap is that it does not clarify how omitted editable fields are handled or what the required confirmed parameter signifies.

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 names the editable copy fields (title, script, caption) and explains requestId must be preserved for unchanged retries, which adds meaning beyond the schema. But schema description coverage is only 14%, and the description does not explain jobId, the required confirmed boolean, or whether omitted copy fields are preserved or cleared.

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: prepare exact title, script, or caption changes for an existing private video. It also distinguishes this edit workflow from creation and publishing by saying 'existing private video' and 'Does not publish.' An agent can identify the operation without opening the schema.

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

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

The context is clear: use this for copy changes on an existing private video, and note that it only prepares an approval link rather than saving copy or rendering. However, it does not explicitly name alternatives such as create_video_brief or review_video_project, 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 readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: that public access metadata in the response does not prove session authentication, which is exactly the kind of interpretation caveat an agent cannot infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with the imperative 'Call first' front-loaded, then the payload, then the authentication caveat and fallback. Every sentence carries distinct information and there is 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 zero-parameter, annotation-covered, no-output-schema tool, the description covers the essentials: what it returns, when to call it, and how to interpret an ambiguous auth signal. A brief note on the response shape would close the remaining gap, but it is not blocking.

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 takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter guidance is needed or missing.

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 verb 'Reports' plus the resource 'public planning features and optional account features' tells an agent what comes back, and the description explicitly points at list_video_projects as the sibling for the private-read case. The phrase 'capabilities' is broad and the split between public and account features is only loosely sketched, but the tool's identity is clear.

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

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

'Call first' is an unambiguous sequencing directive that no sibling description could supply. It also names list_video_projects with the specific condition that selects it (verifying private read access). What it lacks is an explicit 'do not use this for X' exclusion, keeping it at 4 rather than 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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the return value is a JSON Schema, but it does not describe schema versioning, content scope, or how the schema relates to downstream carousel authoring tools. No annotation 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?

The description is a single front-loaded sentence with no wasted words. It directly states the return value and resource scope.

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 schema-retrieval tool with annotations covering safety and no output schema, the description is mostly complete: it states that a JSON Schema for carousel decks is returned. It could be slightly stronger by clarifying how this schema is used with scaffold_carousel_deck or listing templates, but that is 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?

This tool has zero parameters, so the baseline is 4. The empty input schema is appropriate, and no additional parameter guidance is needed.

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: return the JSON Schema for Instavar carousel decks. It distinguishes the resource from the sibling get_video_schema by specifying carousel decks rather than video. It does not explicitly contrast with other carousel-related siblings like list_carousel_templates or scaffold_carousel_deck.

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 for retrieving the carousel deck schema, likely before scaffolding or validating a deck, but it does not explicitly state when to use it versus get_video_schema, get_template, or scaffold_carousel_deck. There are no exclusions or alternative-routing instructions.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description usefully adds that the return value is guidance for the assistant to apply rather than generated copy or saved feedback. That is real behavioral information, especially since there is no output schema. The omit-guideId-to-list behavior is also disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the when-to-use trigger, then the return-nature caveat, then the parameter behavior. No filler and nothing repeated from the schema or annotations.

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 a single optional enum parameter, no output schema and read-only annotations, the description covers trigger, return nature and the listing mode well. The only mild gap is any hint about the shape or volume of the returned guidance, which matters for an agent planning its next step, but that is a minor omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the param burden, and it largely does: its four listed activities correspond in order to the enum values visual-copy, carousel-stories, visual-design and human-review. It also explains that guideId is optional via 'Omit guideId to list guides.' It never names the enum values literally, so the mapping requires a small inference.

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 ('Read') plus a specific resource ('practical guidance') and enumerates the four guidance domains, which map to the four enum values. It also clarifies what the tool does NOT return ('not generated copy or saved feedback'), which separates it from the creation/review siblings. It stops short of naming a specific sibling tool it might be confused with, such as get_example or get_template.

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?

'Read practical guidance before drafting ... copy, choosing carousel stories, designing visuals or recording human feedback' gives explicit trigger conditions tied to four concrete tasks. It also gives a mode-selection rule: 'Omit guideId to list guides.' It does not state when NOT to use it or name an alternative tool, so it falls 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 destructiveHint=false, so the safety profile is covered. The description adds that the return is a 'valid starter example' (i.e., usable as-is rather than a partial sketch), but says nothing about format, size, or whether the example is minimal or complete — context that would matter when handing it to a downstream spec edit.

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 tight sentence with the deliverable front-loaded and zero filler. It is efficient, though on the sparse side for a tool with five siblings and an unlabeled enum.

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 one-parameter, read-only tool with no output schema, the description is adequate on the surface but omits two things an agent needs: what the example actually contains (spec object vs. prose) and how it relates to get_template/get_video_schema. With no output schema, the return shape falls entirely on the description and goes unexplained.

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 the enum values (qa-ad, proof-walkthrough, finance-brief, etc.) carry no per-value explanation anywhere. The description's phrase 'one template family' does clarify that templateId selects a family rather than an instance, which is real added meaning over the raw enum, but the individual families remain undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: returns a valid starter example for one template family. It is clearly not a schema/exercise tool like get_video_schema or scaffold_video_spec, but it never explicitly contrasts itself with the closest siblings (get_template, get_video_schema), so the boundary is inferable 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?

No when-to-use, when-not-to-use, or alternative named, despite five sibling tools (get_template, get_video_schema, get_carousel_schema, scaffold_video_spec, prepare_video_template) that overlap conceptually. The agent must guess whether to call this before or instead of a schema 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds the content scope of the returned workflow, but it does not describe output format, response shape, or any client-specific behavior beyond 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 front-loaded sentence with no filler, and the list of workflow phases is easy to scan. It is appropriately concise, though its terseness leaves important parameter context unaddressed elsewhere.

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 read-only tool with one optional enum parameter and no output schema, the description covers the general return content but omits the meaning and effect of the client parameter. An agent can infer the broad purpose but lacks enough context to choose the client value confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description never mentions the single optional client parameter. The enum values codex, claude-code, and manual are left unexplained, so the description does not compensate for the schema coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns a workflow covering clone, install, validate, preview, and render steps. This is clear enough for an agent to understand the tool's function, though it does not explicitly differentiate itself from sibling guidance tools such as get_creative_guide or get_example.

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 no explicit when-to-use guidance, exclusions, or alternatives. It implies usage for obtaining local render workflow instructions but does not say when this is preferable to related tools or how the client parameter affects the choice.

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 (readOnly, non-destructive, closed world), so the description's real contribution is disclosing the shape of the returned content. With no output schema, naming the four returned fields is meaningful added context; it stops short of covering invalid-id behavior or error responses.

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 listing the returned facets with zero filler. Nothing could be cut without losing information.

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

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

For a one-parameter read tool with annotations and no output schema, describing the returned fields is the key missing piece, and it is present. Minor gaps remain around error handling and how to discover valid ids, but nothing critical blocks correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the single templateId param has no documentation anywhere. The enum self-documents the five valid values, and 'one template' hints that the id selects a template, but the description adds no detail about what the id means or where to obtain 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?

Names a specific verb and resource ('Get one template') and enumerates the payload it returns (purpose, aspect ratios, scene kinds, example identifier). This clearly separates it from list_templates, though no sibling is named explicitly.

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 singular 'one template' plus a required templateId suggests this is the detail lookup after browsing ids. It never says when to prefer this over list_templates or get_example, and gives no 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 cover the safe, idempotent read profile, and the description adds genuinely new context: the render is 'private', the response includes error and recovery information, and non-terminal states must not be read as success. It does not say how long a render typically takes or whether repeated polling is rate-limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what is checked and what comes back, then follows with the state and resubmission cautions. Every sentence carries an instruction, though the phrase 'errors and recovery guidance' is slightly loose about what the tool actually returns.

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 admirably covers return content (URL, errors, recovery hints) and terminal-state distinctions for a two-parameter read tool. It falls short only on polling/timeout expectations and on directing the agent to the error-diagnosis sibling.

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%: workspaceId is thoroughly documented in the schema, but jobId has no description at all. The line 'Keep workspaceId from creation' reinforces the schema's requirement to reuse the creation workspace, and the phrasing implies jobId comes from the creation call, but neither parameter's syntax or sourcing is spelled out beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check the requested private render') plus what it returns: output URL, errors, and recovery guidance. It names review_video_project as the playback path, but does not mention the sibling diagnose_render_error, which is the obvious next step on failure, leaving that boundary implicit.

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

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

Gives clear operational rules: keep workspaceId from creation, treat queued/rendering as not complete, and do not auto-resubmit on failure. What is missing is routing to the appropriate recovery tool (diagnose_render_error) once an error is seen, and any guidance on polling cadence or when to stop checking.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the returned schema is the 'published' one for version 1.0, implying a static reference document, but says nothing about response shape (raw schema vs. wrapper), caching, or whether other versions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no preamble and no waste. Every word (verb, 'published', 'VideoSpec', '1.0') carries 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 zero-parameter, annotation-covered reference fetch, the description is nearly complete: it names the artifact and its version, which is what the agent needs before calling. With no output schema present, a brief note on what the response contains (the schema object itself) would close the remaining 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 tool takes zero parameters and the input schema is an empty object, so there is no parameter semantics to explain — baseline 4 applies. The pinned '1.0' in the description usefully confirms version selection is not a 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?

States a specific verb ('Return') and resource ('the published JSON Schema for VideoSpec'), with the version pinned to 1.0. It is clearly separable from get_carousel_schema by resource, though it never names the adjacent tools (scaffold_video_spec, get_creative_guide) that an agent might confuse it with.

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: you call it when you need to know the VideoSpec shape, presumably before writing or scaffolding a spec. There is no explicit 'use this when' or 'use X instead when' statement, and no mention of how it relates to scaffold_video_spec or get_capabilities.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful constraint that templates are account-free, but says nothing about result volume, ordering, or whether it includes non-editorial templates.

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 with no filler. It is a bit too compressed, since 'story structures' is left undefined and could be clarified in the same breath.

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 zero-parameter list tool with strong annotations, this is nearly sufficient, but with no output schema the description should say what a returned template looks like (id, name, structure) so the agent knows what it will receive.

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 takes zero parameters, so the schema leaves nothing to explain; baseline 4 applies. The description correctly implies no filtering inputs are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('List') plus resource ('carousel templates'), with qualifying adjectives 'account-free' and 'editorial' that narrow the scope. However, it never distinguishes this from the close siblings list_templates and get_template, leaving the agent to guess whether those cover carousels too.

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 use this versus list_templates, get_template, get_carousel_schema, or scaffold_carousel_deck. The 'account-free' qualifier hints at a use case but no condition for selection or exclusion is given.

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 the tool as read-only, closed-world, and non-destructive, so the safety profile is covered. The description adds that only 'published' families are listed and that filtering is optional, which is useful context, but it does not disclose ordering, pagination, or return granularity.

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 with no filler. The listing scope comes first and the optional filter is mentioned second, so every part 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 read-only listing tool with one optional enum parameter and annotations covering safety, the description is nearly complete. It could say more about what each returned template family contains, but the core selection and invocation information 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?

Schema description coverage is 0%, so the description must carry semantic weight. It clarifies that 'aspect' means output aspect ratio and is optional, which is helpful, but it does not explain the allowed enum values or formatting beyond what the schema already shows.

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 gives a specific verb (list) and resource (published Remotion template families), making it distinguishable from get_template and list_carousel_templates by scope and content type. It does not explicitly name a sibling alternative, but the resource itself is clear enough for an agent to select it.

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 'optionally filter by output aspect ratio' implies when the single parameter is useful, but there is no explicit when-to-use guidance, when-not-to-use guidance, or comparison to sibling listing tools. Usage is implied rather than spelled out.

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 read-only/idempotent/non-destructive profile, yet the description adds real context beyond them: the resolved workspace is returned in accountContext, billing details are permission-gated on billing.read, and recorded credits are a read-only snapshot rather than a reservation or render guarantee. The billing.draftCreditCheck shortfall flow is arguably downstream workflow rather than this tool's own behavior, which keeps it from a 5.

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 scoping sentence is well front-loaded, but the description then runs into multi-sentence billing-draft workflow policy (shortfall handling, linking to billing, not requesting creation confirmation) that reads as process boilerplate for a simple list call. Roughly half the text does not help an agent decide to call or correctly invoke this 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 two-parameter read with no required inputs and no output schema, the description does well: it names what comes back (accountContext, permission-gated billing), states the account-linking precondition, and warns against stale inference. The missing piece is any hint of the shape/fields of a project entry and the effect of `limit` on recency, which matters given there is no 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 50%: workspaceId carries a long, thorough schema description, so the description's added note ('do not infer current workspace from an older job') is supplementary rather than compensating. The `limit` parameter is undocumented in both schema and description, yet it defines what 'recent' means (default 10, max 20) — a genuine gap the description could have closed.

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+resource+scope: 'List recent private Instavar video projects after the user links their account.' An agent immediately knows this is a read of the user's own recent projects, not a template or schema listing. The billing/credit guidance that follows dilutes the front-loaded clarity slightly, keeping it at 4 rather than 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?

Gives an explicit routing rule to a named sibling: 'Use this before review_video_project when the user has not supplied a project ID,' plus a negative instruction not to infer workspace or allowance from an older job. It stops short of stating when NOT to call this (e.g., when a project ID is already known) but the alternative is clearly implied.

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

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

Annotations already declare readOnly/destructive=false, but the description adds crucial context beyond them: it returns source files for local rendering, the project document is caller-held and must be kept for later calls, it must not be described as a hosted saved project, and non-copy edits cannot be preserved across a switch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and alternative, and every sentence encodes a rule rather than filler. It is dense and somewhat run-on with many clauses packed together, which slightly reduces readability.

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 5-param nested-object tool with no output schema, the description covers the caller-held lifecycle, framework selection, revision checking, edit ordering, and the return of source files — everything an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are documented structurally. The description still adds meaning beyond the schema: framework omission/'no-preference' semantics, expectedRevision checking the supplied document rather than a server version, and the ordering rule for edits.

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 specific verbs (prepare, continue, edit, switch) plus the resource (announcement-card-v1 template / caller-held project). Explicitly distinguishes itself from prepare_video_template, which it names as the tool for VideoSpec templates in either framework.

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

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

Gives explicit routing rules: use this for paired announcement-card-v1 or HyperFrames announcement requests, use prepare_video_template for VideoSpec. Adds decision guidance — never infer framework from creative wording, omit framework unless explicitly chosen, ask the user on needs-selection, apply edits before switching.

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 mark it read-only/non-destructive; the description adds the crucial clarification that despite 'switch framework' wording it returns local source and does not render, save or upload, and that the project is caller-held rather than a hosted saved project. It also discloses rejection behavior ('a rejected field is unsupported in both frameworks'), which the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then usage rules, then the iteration loop, then the non-goals. Dense and nearly waste-free, though the framework-inference warnings are repeated in spirit across two sentences.

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

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

With no output schema and nested project/spec objects, the description supplies the needed context: what is returned (local source and commands), what is not (render/save/upload), and how to iterate. It doesn't describe the shape of the returned source/commands, which is a minor remaining 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 100%, so baseline is 3; the description adds meaning beyond the schema by explaining the framework field's intent (never infer from creative wording, omit unless the user chose, ask on needs-selection) and the spec/project relationship. It does not explain the mutual exclusivity of spec vs project explicitly, leaving a small gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource pair: validate one VideoSpec against the paired template contract and return local source for a chosen framework, or switch an existing project's framework. It is clearly distinguishable from siblings like scaffold_video_spec or get_template, and even names the input artifact (VideoSpec) that selects it.

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 routing rules: 'For a VideoSpec template in Remotion or HyperFrames, use prepare_video_template with the VideoSpec', plus when not to infer a framework, when to omit it, and to ask the user on needs-selection. It also prescribes the follow-up loop (edit project.spec, call again to regenerate or switch).

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 destructiveHint=false; the description reinforces this with an explicit negative list of side effects (no image generation, no project save, no render, no publish). That is genuinely useful disambiguation beyond the annotations, though it says nothing about cost, latency, or result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with purpose, then the templateId rule, then the scope boundaries. Every sentence carries distinct information with 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?

The description covers purpose, the key templateId branch, and non-goals, and sketchily characterizes the output ('three-beat visual proposal and recommended template'). But for a 7-parameter tool with a nested object and no output schema, the undocumented parameters leave a meaningful gap before an agent can call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 7 parameters including a nested acceptedDesign object, yet the description only explains templateId. It gives no meaning for brief, title, body, cta, aspect, or the required sub-fields of acceptedDesign (style, durationSeconds, audio, illustration, exclusions).

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 concrete verb and resource: 'Turn an ordinary video request into a three-beat visual proposal and recommended template.' The closing negations ('does not generate images, save a project, render, or publish') carve out scope against render/publish siblings, though no sibling is named explicitly.

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

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

Gives explicit conditional guidance for templateId: pass it to preserve an accepted template when changing only the aspect, omit it for a new direction. It also signals via exclusions that rendering/publishing belong to other tools, but never names the alternative tool to call.

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, destructiveHint=false, and the description's negative list reinforces that profile while adding the account-linking prerequisite and the private-visibility constraint. Beyond that it says nothing about what the review session does or returns, so it adds moderate value over structured fields only.

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, no filler, and the positive scope statement is front-loaded ahead of the exclusion list.

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 rich annotations, a fully documented two-parameter schema, and an output schema, the description covers the prerequisites and scope boundaries an agent needs. The only gap is that "focused review" is not further characterized, though the output schema can fill that in.

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 the workspaceId description already carries detailed resolution rules, so the description adds nothing about parameters and needs to add nothing. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Open a focused review of one private Instavar video") and immediately excludes adjacent capabilities (edit, render, approve, publish), which cleanly separates it from siblings like edit_video_brief and get_video_render_status.

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

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

Gives a clear precondition ("after account linking") and explicit when-not-to-use coverage via the negative list. It stops short of naming a specific alternative sibling for the excluded operations, so it lands at 4 rather than 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 only say readOnly/non-destructive/closed-world; the description adds real behavioral context by clarifying that 'build' means producing an in-memory scaffold and that no persistence, rendering, or publishing occurs, and that output is deterministic. It still omits what the returned deck looks like and whether validation errors are thrown for over-length copy.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, the primary purpose front-loaded and the scoping caveat immediately after. Nothing redundant or padded.

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 8 undocumented parameters, no output schema, and four required fields, the description is too thin — it never says what the scaffold contains or how the agent should use it downstream. The safety profile is covered by annotations, but the functional contract is not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 8 parameters, including two enums and four required fields, and the description names none of them. 'Accepted copy' loosely gestures at hook/points/payoff but gives no guidance on length caps, point-count limits, or aspect ratios, leaving the schema to carry the entire burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Build a deterministic editorial carousel deck') plus its input source ('accepted copy'), which is materially more precise than the title. It does not name a sibling tool it should be preferred over, so an agent must infer placement relative to get_carousel_schema or scaffold_video_spec.

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 negative scoping ('does not render, save, or publish it') effectively excludes whole categories of misuse and implies this is a pre-render step. However, it never names the alternative to use for rendering/publishing, nor states the prerequisite tool that produces 'accepted copy' — the agent must infer the workflow position.

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=false, and destructiveHint=false, so safety is covered. The description adds that output is deterministic and that it neither writes files nor generates creative copy, but it does not describe what the returned skeleton contains or how the nested acceptedDesign object is used.

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 filler and is front-loaded with the core action. The second sentence adds a useful scope exclusion without redundant restatement.

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 has a complex nested input schema and no output schema, so the description should explain the returned skeleton and key parameter roles. It only states that a deterministic skeleton is returned and that file writing and creative-copy generation are excluded, leaving major behavioral and structural details undocumented.

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 only 13%, with just the brief parameter carrying a description. The tool accepts 8 parameters, including a required templateId enum and a nested acceptedDesign object with multiple required fields, yet the description provides no parameter-level meaning or usage guidance.

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: it returns a deterministic VideoSpec skeleton. It also excludes creative-copy generation and file writing, which clarifies scope. However, it does not distinguish this tool from siblings such as create_video_brief, propose_video_storyboard, get_video_schema, or scaffold_carousel_deck.

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 negative boundary: it does not generate creative copy or write files. It gives no positive guidance on when to use this tool instead of alternatives like create_video_brief, edit_video_brief, get_video_schema, or propose_video_storyboard. The agent must infer the intended usage from the tool name alone.

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