BlitzReels Video Editor

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

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds that the overlay is 'editable' and placed at an exact time/layer, but does not discuss retry semantics, expectedRevision behavior, or effects of defaults. Adds some context beyond annotations but not deeply.

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, focused sentence with no wasted words. It front-loads the core action and object, then adds placement details, achieving high clarity in minimal space.

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 parameters and an output schema, the description is serviceable but sparse. It does not mention required idempotencyKey, default duration of 4 seconds, or revision handling. It is adequate for basic selection but not fully complete for correct invocation without deeper schema inspection.

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 38%, so the description should compensate for undocumented parameters. It only hints at startSeconds and layerIndex via 'exact time and layer' and implies text content, but says nothing about durationSeconds, name, expectedRevision, or idempotencyKey semantics. This leaves most parameters underexplained.

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 a specific verb ('Add') and resource ('editable text overlay') with precise placement ('at an exact time and layer'). This distinguishes it from sibling tools like add_transition or timeline_media_add, which handle different timeline additions.

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: it is for adding an editable text overlay to a project timeline. It does not explicitly enumerate exclusions or alternatives, but the specificity makes the intended use obvious relative to siblings. Lacks explicit 'when not to use' guidance.

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 indicate a mutating, non-destructive, idempotent operation. The description adds useful behavioral context: it is 'timed,' can be attached to one timeline item, and can include sound. It does not disclose versioning behavior or effects on existing timeline items, but with annotations present, this partial transparency is reasonable.

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 efficiently conveys the core purpose and optional behaviors.

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?

Despite the presence of an output schema, this is a complex 12-parameter tool with low schema coverage. The one-line description fails to explain the semantics of presets, easing, intensity, or the optional attachment behavior, leaving significant gaps for an agent to use 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 only 25% (3 of 12 parameters documented), so the description must compensate. It only hints at timelineItemId ('attached to one timeline item') and includeSfx ('paired with sound'), leaving many critical parameters like easing, preset, intensity, layerIndex, durationSeconds, and expectedRevision unexplained.

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 adds a timed transition effect, optionally attached to one timeline item and paired with sound. This specific verb+resource+scope distinguishes it from sibling tools like add_text_overlay or timeline_audio_add.

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 that this is for adding transition effects in a timeline context, with optional attachment to a timeline item and sound. However, it does not explicitly state when not to use it or mention alternatives, 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 indicate idempotent=true, readOnly=false, and destructive=false. The description adds valuable behavioral context: the operation is transactional and limited to 100 items. It does not contradict the annotations and provides insight beyond the structured hints.

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, tightly packed sentence. It front-loads the verb, specifies the supported fields, and includes the critical constraints (up to 100 items, one transaction) without any wasted words.

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 rich schema (100% coverage) and the presence of an output schema, the description is sufficient for understanding the core operation. It captures the essential batch and transactional behavior. A minor gap is not explicitly directing users to the singular update_timeline_clip for single updates, but that is more of a usage guideline than a completeness issue.

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 every parameter already has a description. The phrase 'timing, trim, layer, or state' adds semantic grouping to the fields, but it does not provide new syntax or details beyond what the schema already documents. This is the baseline for high schema coverage.

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

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

The description clearly states the action ('Update'), the resource ('timeline items'), and the scope ('up to 100 ... in one sequence transaction'). It explicitly lists the kinds of updates (timing, trim, layer, state), which distinguishes it from singular siblings like update_timeline_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 description gives clear context for use: it is for batch updating up to 100 items atomically ('one sequence transaction'). It does not explicitly name an alternative for single-item updates, but the batch limit and transactional phrasing imply the appropriate use case.

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, covering the safety profile. The description adds that it includes both built-in looks and saved themes, which is useful context, but does not disclose additional behaviors like pagination or ordering. This is adequate given the annotations, but not overly rich.

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 that directly states the action and scope. No redundant words or filler, making it highly concise and well-structured.

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 operation, the description, combined with comprehensive annotations and a full output schema, provides complete context. There are no missing details about return values or safety, and the tool's simplicity means no additional context is needed.

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 three parameters have full descriptions in the input schema, achieving 100% schema coverage. The description itself does not add parameter-level meaning, but the schema is sufficient, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists built-in caption looks and saved caption themes for a workspace, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on caption themes, which is unique among the provided 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 implies usage as a simple listing tool, but provides no explicit guidance on when to use it versus alternatives or when not to use it. Since no alternative theme-listing tools exist among siblings, this is acceptable but not explicitly stated.

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

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

The description goes well beyond the annotations (which already indicate destructive and idempotent). It discloses that dry-run is the default, real deletion requires confirmation and a retention choice, workspace delete permission is needed, and an idempotency key is required. This fully informs the agent of conditions and side effects.

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, well-structured sentence that efficiently conveys purpose, default behavior, and prerequisites. Every phrase adds value without wordiness.

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 the core behavior and preconditions for this destructive, idempotent tool with 6 parameters. Given that the output schema exists (so return format is already specified), the description provides sufficient context for the agent to understand the tool's workflow, though it does not elaborate on what the dry-run preview returns.

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

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

With only 33% schema description coverage, the description must compensate for the lack of parameter details. It does add semantic value by referencing dry-run, confirmation, retention choice, workspace permission, and idempotency key. However, it does not explain the precise conditions for each parameter (e.g., dryRun must be false, confirmDelete must be true, or the meaning of retention enum values), leaving some ambiguity for the agent.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Preview or delete a terminal clip batch.' It distinguishes itself from sibling tools like delete_timeline_items by focusing on clip batches, and the dual preview/delete nature is explicit.

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 this tool: for previewing or deleting a terminal clip batch. It implies that real deletion requires explicit confirmation and permissions, giving the agent actionable guidance. It doesn't explicitly name alternatives, but the resource type is distinct enough from 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 disclose that this is a non-read-only, non-idempotent mutation. The description adds 'from an existing video asset or an import URL' and lists supported URL platforms, but this information is largely repeated in the url parameter schema. It does not provide additional behavioral details such as potential long-running processing or asynchronous batch creation, which would be valuable beyond 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 two sentences, front-loaded with the primary purpose, and the second sentence efficiently expands on supported input sources. Every word earns its place with no redundancy 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?

With 8 parameters fully documented in the schema and an output schema present, the description is sufficiently complete for initial understanding. It covers the two input modes (asset or URL) and supported platforms. It omits details like asynchronous behavior, but these are likely captured in the output schema or annotations, so it remains adequate.

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 covers 100% of parameters with detailed descriptions, including the exact supported URL types. The tool description's second sentence merely echoes the url param description, adding no new parameter meaning. The first sentence summarizes assetId/url but does not enrich what the schema already provides.

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 creates a BlitzReels clip batch from an existing asset or an import URL. This specific verb+resource combination distinguishes it from sibling tools like clips_get and clips_manage, and the supported URL list adds further precision.

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 conveys the context for use: you have an existing video asset or a URL to import and want a clip batch. However, it does not explicitly mention alternatives or when not to use this tool, such as pointing to media_import_url for import-only scenarios or clips_manage for bulk editing.

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, so the safety profile is covered. The description adds valuable behavioral context by enumerating the specific output fields (status, clips, counts, links), which goes beyond the generic annotations. This merits a 4.

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 action and lists key outputs in a compact manner. No unnecessary information or filler, earning a 5.

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 getter with an output schema and strong annotations, the description is complete. It clearly states the purpose and return contents, with no missing critical context. The tool's simplicity and structured data make this comprehensive without needing extra detail.

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%, with both parameters (batchId, workspaceId) fully described including UUID format and default behavior. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate as the schema does the heavy lifting.

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 'Get' and names the resource 'BlitzReels clip batch', listing the exact outputs: status, generated clips, render counts, download links. This clearly distinguishes it from siblings like clips_create or clips_manage, which handle creation or broader management.

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 after creating a batch (e.g., via clips_create) by stating it retrieves batch data. It gives clear context for when to use it, though it does not explicitly name alternatives or exclusions. Given the tool's name and sibling context, this is sufficient for a 4.

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 annotation set is limited (readOnlyHint false, destructiveHint false, etc.). The description adds one behavioral detail: caption defects return warnings and do not disable rendering. This is useful but does not disclose side effects of repair/reselect/export operations or any required permissions.

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, efficiently lists operations. The first sentence is dense but comprehensive at a high level. It is front-loaded with the tool's main actions and the second sentence adds an important behavioral caveat.

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 high complexity (7 operations, 24 parameters, low schema description coverage), the description is too brief. It does not cover per-operation parameter requirements, output expectations, or side effects. The presence of an output schema helps, but the tool's complexity demands more 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 coverage is only 17% (only a few UUID fields described). The description gives high-level operation hints (e.g., 'reselect an exact range or suggestion' implies time range/suggestion parameters, 'start export' implies format/resolution) but fails to explain many parameters (timelineItemId, coverFrameSeconds, min/maxDuration, clearWordOverrides, etc.) and does not provide syntax or constraints. This is a significant gap for a 24-parameter 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 enumerates specific operations (list, inspect, reselect, repair, export, list caption words, set caption look), making the tool's purpose clear. However, it does not explicitly distinguish from sibling tools like clips_get or exports_start, which may overlap.

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 guidance on when to use this tool vs alternatives. It does not mention that exports should use exports_start, or that getting a single clip should use clips_get. The description simply lists capabilities without contextual recommendations.

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 well-covered. The description adds the factual content (clipping/caption defaults) but does not disclose additional behavioral traits such as return format, pagination, or whether presets include custom user-defined ones.

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, focused sentence that immediately states the action and object. It contains no redundant phrases or filler, making it highly concise and well-structured.

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 an output schema present and comprehensive annotations, the description is largely complete for a simple list tool. However, it could provide slightly more contextual value by hinting at how these presets are used (e.g., 'These presets can be applied when creating clip batches'), which would help new users understand the workflow.

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 schema coverage is trivially 100% and the description has no parameter burden. A baseline score of 4 is appropriate since there is nothing to explain.

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 action ('List') and resource ('available clip batch presets'), and specifies the included information ('clipping/caption defaults'). This distinguishes it from sibling tools like captions_themes_list and clips_get, which serve different purposes.

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 usage is implied by the tool's name and description—if you need to list presets, this is the tool—but there is no explicit guidance on when to use it versus alternatives, nor any mention of prerequisites or follow-up actions. The description could benefit from noting that these presets are for use with clip batch creation.

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?

Adds information about the preview mode and optional caption removal beyond the annotations, which already indicate destructive behavior. Still, it doesn't explain the dryRun/confirmDelete workflow or other behavioral nuances, so only partially transparent.

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 redundant filler. Efficiently conveys the core functionality and primary option.

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?

Despite having annotations and an output schema, the description omits essential workflow details for a destructive tool—such as how preview (dryRun) and confirmDelete interact, the purpose of idempotencyKey, and revision handling. This is a significant gap for safe usage.

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 adds meaning to timelineItemIds (up to 100) and removeAssociatedCaptions (linked captions), but schema coverage is only 29%, leaving many parameters (dryRun, confirmDelete, idempotencyKey, expectedRevision) unaddressed. The description does not compensate enough for the low 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?

Clearly states it previews or deletes timeline items and optionally removes linked captions. The verb 'delete' and resource 'timeline items' are specific, though it doesn't explicitly distinguish from sibling 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 phrase 'Preview or delete' implies a safe preview mode before deletion, providing some usage context. However, there's no explicit guidance on when to use this tool versus alternatives, nor on when to choose preview vs actual deletion.

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, covering the safety profile. The description adds valuable behavioral context beyond annotations: render status/progress and the presence of signed download URLs on completed exports. This informs the agent about the data shape and what to expect, without contradicting 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 two concise sentences with no filler. It front-loads the primary action and then adds the key differentiator (single export via exportId). 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?

Given the tool's low complexity, rich annotations, complete parameter schemas, and presence of an output schema, the description is sufficiently complete. It covers what the tool does, the main data included (status/progress, signed URLs), and the single-record mode. No additional context is necessary.

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%, with each parameter clearly explained. The description adds no new information about parameters beyond saying 'Pass exportId,' which the schema already documents. This meets the baseline of 3 when the schema carries the parameter-semantics 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?

The description clearly states the tool's purpose: 'List exports with render status and progress.' It also distinguishes two modes — listing all exports vs. returning one by exportId — which separates this from sibling tools like exports_start. The verb 'List' and resource 'exports' are specific and 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 provides clear usage context: it lists exports with status/progress and notes that completed exports include signed download URLs. It also instructs when to pass exportId to retrieve a single export. While it does not explicitly name alternatives or exclusions, the single-vs-list distinction serves as effective usage guidance.

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 useful behavioral context beyond annotations: the tool returns export and job IDs and can be polled via exports_list, implying an asynchronous operation. Annotations already indicate it is not read-only or idempotent, and the description does not contradict them. It could mention side effects (e.g., rendering costs or project state changes), but the polling hint covers the main follow-up behavior.

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

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

Two tight sentences. The first states exactly what the tool does; the second explains the return value and the follow-up polling mechanism. No wasted words, and the most important 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?

The tool has 5 parameters, an output schema, and is a side-effecting operation. The description covers the key flow (start export, get IDs, poll with exports_list) and leverages the complete schema. It could be slightly more thorough about asynchronous behavior or failure modes, but the essential context is present, especially given the rich schema and 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 description coverage is 100%, with clear descriptions for all parameters including enums and defaults. The description itself adds no parameter-specific detail, but given complete schema coverage, no additional compensation is needed. 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 ('Render/export') and names the exact resource ('BlitzReels video project after timeline edits'). It also states the return value (export and job IDs) and references the sibling tool exports_list for polling, which clearly distinguishes it from 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 gives clear contextual guidance: use after timeline edits, and poll results with exports_list. It does not explicitly state exclusions or alternative tools for this action, but the reference to exports_list implies the workflow and the timing is reasonably clear.

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 discloses important behavioral traits beyond the annotations: it 'spends AI credits' (cost implication) and 'returns a job to poll' (asynchronous operation). It also clarifies the extent of creation (full project with scene plan, visuals, etc.). Annotations already indicate a non-read-only, non-destructive operation, and the description is consistent, adding valuable context without 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 two sentences, front-loaded with the primary purpose. The second sentence adds critical workflow and cost information. Every word earns its place; no redundancy 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?

Given the tool's complexity (15 params, 1 required, output schema present), the description provides essential workflow context: it creates a full project, spends credits, and returns a pollable job. The rich input schema covers parameter details, and the output schema covers return values, so the description is complete for the agent to understand what this tool does and how to use it.

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 each parameter already has a clear description. The tool description lists high-level components (voiceover, captions, music, sound) that map to parameters, but does not add new meaning beyond the schema. Thus, 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 clearly identifies the tool's purpose: 'Turn a script into a full faceless video project' with a specific verb, resource, and outcome. It distinguishes itself from siblings by emphasizing the full-project scope (scene plan, visuals, voiceover, captions, music, sound) and the async job return, which is not covered by individual generation 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 implies usage context: it is the all-in-one faceless video creation tool, as opposed to more granular siblings like generation_video_create or generation_image_create. It also provides a key next step: 'returns a job to poll with generation_jobs_get.' However, it does not explicitly state when to prefer this tool over alternatives or mention exclusions, 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 cover important aspects (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds critical behavioral context: it spends AI credits and returns a job to poll, indicating a cost and asynchronous execution. This goes beyond the annotations and helps set expectations for side effects and workflow.

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. The first sentence establishes the core action, and the second covers cost and output behavior. Every word contributes value, making it highly efficient and 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?

Given the tool's complexity (7 params, async job flow, credits) and the rich schema plus annotations, the description provides the essential context: queuing, credit cost, and polling via generation_jobs_get. It does not explain the output schema, but that is already provided in the output schema, so the description is sufficiently complete.

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%, with each parameter having a clear description (e.g., 'What the image should show', 'Output aspect ratio', 'Image model. Call generation_options_list for costs.'). The tool description itself does not add additional parameter-specific details, so it stays at the baseline 3 for well-covered schemas.

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: "Queue an AI image generation into the BlitzReels media library." It uses a specific verb (queue), identifies the resource (AI image generation), and differentiates it from sibling generation tools (video, music, sound) by specifying "image." The mention of returning a job to poll also clarifies its role in the async 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 gives clear context for when to use this tool: to generate an image and enqueue it. It also hints at the follow-up action via 'returns a job to poll with generation_jobs_get.' However, it does not explicitly mention when not to use it or name alternatives (e.g., generation_video_create for videos), so it falls short of the highest bar.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the state constraint (queued or running) and the credit-saving rationale, which is useful. However, it does not disclose what happens on cancel (e.g., whether credits are refunded or if cancellation is irreversible), but the output schema may cover return values.

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 that conveys the core purpose and key scope without any fluff. Every word earns its place, making it highly concise and well-structured.

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 cancellation tool with good schema coverage, annotations, and an output schema, the description is nearly complete. It specifies the applicable states and the rationale, though it could explicitly mention side effects or edge cases (e.g., cancelling an already-finished job). Minor gap, but overall adequate.

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 both parameters (jobId and workspaceId) have detailed descriptions in the schema. The tool description adds no additional parameter-level information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Cancel') with a clear resource ('generation job') and adds meaningful scope ('queued or running generation before it finishes spending credits'). This clearly distinguishes it from sibling tools like generation_jobs_get and the various generation creation 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 implies when to use the tool: when a generation job is queued or running and you want to avoid spending credits. It specifies the applicable states ('queued or running') but does not explicitly name alternatives or exclusions, though the scope is clear enough.

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 operation read-only and idempotent. The description adds value by revealing that completed jobs include a media asset ID and download URL, and by implying incomplete jobs do not. This is useful behavioral context beyond the annotation flags.

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

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

Two sentences, front-loaded with the primary purpose. Every phrase earns its place; no fluff or repetition of schema/annotations. Very concise and effective.

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 an output schema present and strong annotations, the description need not explain every return field. It explains the key distinction between completed and non-completed jobs, which complements the structured data. Slightly missing polling guidance or error-state info, but not critical for a simple read operation.

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% for both parameters, so the schema fully documents their meaning. The description does not add any additional insight into parameter semantics, warranting the baseline score 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 clearly states the tool checks a generation job and specifies what completed jobs return (media asset ID and download URL). It distinguishes from sibling generation creation/cancel tools, though the phrase 'queued generation' is slightly ambiguous about whether it handles all job states.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention that it should be used after a generation_*_create call or contrast with generation_jobs_cancel. Usage context is only implied by the presence of sibling tools and the parameter schema.

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 valuable behavioral context by disclosing that the operation spends AI credits and returns a job to poll via generation_jobs_get. This goes beyond the annotations, which only indicate idempotency and non-destructiveness.

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-loading the core purpose and adding only essential behavioral context. No wasted words.

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 schema covers all parameters and an output schema exists, the description sufficiently conveys the operation's purpose, cost, and async workflow. It 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?

All 5 parameters are fully described in the input schema (100% coverage), so the description does not need to explain them. The description does not add additional parameter-level meaning, staying at the 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 clearly states the tool's function with a specific verb ('Queue') and resource ('background music track into the BlitzReels media library'), distinguishing it from sibling generation tools by specifying background music.

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 background music and mentions the asynchronous job pattern and AI credit cost, but it does not explicitly contrast with alternative generation tools such as generation_sound_create or generation_voiceover_create.

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 idempotentHint=true, covering safety. The description adds useful context about what information is returned (models, defaults, limits, credit costs), which goes beyond annotations and helps the agent understand the tool's behavior.

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

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

A single, well-structured sentence that front-loads the action and resource, then adds a contextual purpose. No redundant wording.

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 a simple one-parameter tool, full schema coverage, and an output schema, the description is complete enough for an agent to understand the tool's purpose and invoke it correctly. The phrase 'before queueing it' provides the necessary workflow 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 coverage is 100% for the single 'kind' parameter, with an enum and description. The phrase 'one generation kind' reinforces the parameter's role but adds no extra syntax or format details beyond what the schema already states.

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 ('List') and names the exact resource ('models, defaults, limits, and credit costs') for a given generation kind. The phrase 'before queueing it' differentiates it from the sibling generation creation tools that actually queue jobs.

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 indicates when to use this tool: 'before queueing it' a generation. This implies it should be called prior to the generation_*_create tools, but it does not explicitly name alternatives or exclusion cases.

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?

Goes well beyond annotations by revealing the asynchronous nature ('Queue'), the cost implication ('Spends AI credits'), and the return of a job to poll with generation_jobs_get. Annotations only cover read-only/idempotent/destructive hints, so this adds substantial behavioral context.

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 concise sentences with the core purpose front-loaded. Every word earns its place, and the job-polling hint is included without unnecessary detail.

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 full schema coverage and an output schema, the description fills the remaining gaps: async job model, credit cost, and media library destination. This is complete for the tool's 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 coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds no param-specific meaning, but the schema already handles 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?

Clearly states it queues a sound effect into the BlitzReels media library, distinguishing it from sibling generation tools for music, image, video, and voiceover. Also mentions returning a job to poll, which clarifies its role.

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 context: use for sound effects, spends AI credits, returns a job for polling. It doesn't explicitly name alternatives, but the sound-effect scope and job-based workflow make the usage 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?

Beyond the annotations, the description discloses that the operation spends AI credits and is asynchronous ('Queue... returns a job to poll'). These are important behavioral traits not captured by readOnly/idempotent/destructive hints, and they help the agent set expectations for cost and follow-up.

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. The first sentence front-loads the action and scope; the second covers cost and the polling workflow. Every clause contributes value.

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 15-parameter tool with an output schema, the description provides the essential workflow overview: queue from prompt/image, spend credits, poll with generation_jobs_get. Model-specific limitations are documented in the schema, so the description doesn't need to repeat them. It's slightly brief but adequate given the schema coverage.

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 15 parameters have schema descriptions (100% coverage), so the schema carries the heavy lifting. The main description only hints at prompt vs sourceAssetId for input modes, adding minimal extra meaning beyond the schema. Baseline of 3 is appropriate given the rich schema.

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

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

The description uses the specific verb 'Queue' and names the resource 'AI video generation', further scoped to the BlitzReels media library and input modes (prompt or image asset). It clearly distinguishes from sibling generation tools by its focus on video and the polling follow-up with generation_jobs_get.

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 states it generates video from a prompt or image asset and returns a job to poll, giving clear usage context. It doesn't explicitly name alternatives like generation_image_create for still images, but the video-specific focus makes the tool's role clear. The cost warning ('spends AI credits') is a useful consideration.

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 indicate readOnlyHint=false and idempotentHint=true. The description adds valuable behavioral context: 'Spends AI credits' discloses cost, and 'returns a job to poll' discloses asynchronous behavior. This goes beyond the structured fields 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 two sentences, front-loaded with the core purpose, and every word adds value. It avoids redundancy and is perfectly sized for an agent to quickly parse and understand the tool's function.

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 is complete for the tool's complexity. It conveys the essence (queue voiceover), the cost implication, the async pattern, and the necessary next step (poll with generation_jobs_get). With an output schema present, there is no need to describe return values, and the description covers all critical 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 baseline is 3. The description does not add parameter-level meaning beyond what the schema already provides; it mentions 'text-to-speech voiceover' which relates to the 'text' parameter, but does not elaborate on other fields. This is acceptable given 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?

The description clearly states the action ('Queue a text-to-speech voiceover into the BlitzReels media library') with a specific verb and resource. It distinguishes this from sibling generation tools by specifying 'text-to-speech voiceover', and even notes the async nature with 'returns a job to poll with generation_jobs_get'.

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 implicit usage context by mentioning it 'Spends AI credits' (a cost/prerequisite) and directs the user to a sibling tool for follow-up ('returns a job to poll with generation_jobs_get'). While it does not explicitly list when to use this over alternatives, the context is clear and actionable.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds meaningful behavioral context by specifying the type of data returned (metadata, processing state) and explicitly stating what is not returned (transcript segments). This goes 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 a single, well-structured sentence that front-loads the verb and object, includes a necessary exclusion clause, and contains zero filler. Every word contributes to understanding the tool's purpose.

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 get-by-id tool with one parameter, a rich output schema, and strong annotations, the description is complete. It explains what the tool returns (metadata and processing state), what it excludes (transcript segments), and the tool is simple enough that no further context is needed.

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 provides 100% coverage for the single parameter, describing it as 'Media asset UUID. UUID string.' The description reinforces the parameter's role by saying 'one media-library asset', but it does not add additional semantic 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 states exactly what the tool does: 'Get metadata and processing state for one media-library asset'. It clearly identifies the verb (get), resource (media-library asset), and scope (one). The exclusion clause 'without returning transcript segments' also distinguishes it from sibling tools like media_transcript_get.

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: when you need metadata and processing state for a single asset. The phrase 'without returning transcript segments' provides guidance that this is not the tool for transcript retrieval, effectively directing users to a sibling tool. It does not explicitly name alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds valuable context beyond annotations by specifying the output as a bounded JPEG and the conditional behavior for images vs videos (stored visual vs thumbnail). This clarifies what the agent can expect from 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?

Two concise sentences, each adding value. The first sentence states the action and result; the second clarifies behavior for different asset types. No wasted words, and the most important 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?

The tool is simple, has full schema coverage, an output schema, and safety annotations. The description covers the key behavioral distinction (image vs video) and clearly communicates the return format. Nothing critical is missing for the agent to select and invoke this tool 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 parameters are well-documented in the schema. The description mentions 'bounded' which relates to maxDimension, but doesn't add new parameter-specific meaning beyond what the schema already provides. Baseline 3 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?

The description clearly states the tool's function: 'Return one bounded JPEG as MCP image content for visual inspection.' It specifies the verb (return), the resource (media asset), the output format (JPEG), and the purpose (visual inspection). It also distinguishes itself from siblings by noting the difference between image and video behavior.

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 usage is implied by the phrase 'for visual inspection' and the tool name, but there is no explicit comparison to alternatives or guidance on when not to use it. No exclusions or alternative tool references are provided, so it falls short of a clear contextual distinction.

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=false, destructiveHint=false, and idempotentHint=true. The description accurately describes the write behavior but adds no extra context beyond what the annotations imply (e.g., side effects, reversibility, idempotency details). 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?

The description is exceptionally concise: one sentence lists the actions, followed by the required at-least-one condition. It is front-loaded, contains no fluff, and 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 6-parameter tool with an output schema and clear annotations, the description is nearly complete. It covers the tool's purpose and the key usage constraint. It implicitly conveys partial update semantics but could be slightly more explicit about that. Overall, sufficient for agent invocation.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description adds the critical constraint that at least one of name, description, folderId, or allowUsingAsBroll must be provided, which is not enforced in the schema. This adds meaningful guidance beyond the schema's field descriptions.

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 updates a single media asset with specific actions: rename, edit description, move to folder, or change B-roll eligibility. It is unambiguous and differentiates from read-only sibling tools like media_assets_get or media_assets_preview.

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 this tool (updating a media asset) but does not explicitly mention alternatives or when not to use it. The instruction to provide at least one of the updatable fields is a constraint, not a comparison to 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?

The description adds 'retry-safe mutation receipt' which aligns with the idempotentHint annotation, providing a bit more nuance. However, it does not disclose other behavioral aspects beyond what annotations already indicate, and the annotations already cover the safety profile.

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 that conveys the primary action and result. It is concise without any redundant words, earning the highest score.

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 complete schema coverage and existence of an output schema, the description is sufficient. It states the core action and the return of a receipt, providing all necessary context for an AI agent to understand the tool's purpose and outcome.

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 six parameters are fully described in the schema with 100% coverage. The description itself adds no additional parameter semantics or relationships, so the schema does the heavy lifting. A 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 clearly states the specific action ('Create') and resource ('media-library folder'), and mentions the return of a mutation receipt. This distinguishes it from siblings like media_folders_list, and the scope ('one folder') is explicitly defined.

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 its usage context: when you need to create a media folder. However, it does not explicitly name alternatives (e.g., media_folders_list for listing) or provide when-not-to-use guidance, so there is clear context but no exclusions.

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 read-only/idempotent/non-destructive behavior, and the description adds useful behavioral context: it returns only one level of folders and direct (non-recursive) asset counts. This clarifies scope and return semantics beyond the structured 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 that fully conveys the tool's purpose and key scoping behavior. No filler or 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?

Given the tool's moderate complexity, the description covers the essential scope and return value, and the output schema and annotations fill remaining gaps (pagination, safety). No critical missing details for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning to the parameters; 'bounded level' implicitly relates to parentFolderId but does not explain parameter syntax or behavior 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 uses a specific verb ('List') with a clear resource ('media-library folders') and scopes the action ('one bounded level', 'direct asset counts'). This distinguishes it from sibling tools like media_folders_create (create) and media_list (likely asset-level listing).

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 context by noting 'one bounded level' (i.e., not recursive), but it does not explicitly state when to prefer this over alternatives or provide exclusions. The parentFolderId parameter further hints at hierarchy traversal, but no explicit guidance 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds context about what the tool returns (title, duration, qualities, audio tracks) and expands the supported URL types beyond the schema, but does not delve into edge cases or error scenarios. Since annotations carry the safety burden, this extra behavior context earns a 4.

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, front-loads the core purpose and return values, and then provides usage differentiation. Every sentence serves a distinct purpose with no waste. It is concise and well-structured.

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 parameter, a rich annotation set (readOnly, openWorld, idempotent, non-destructive), and an output schema present, the description is fully adequate. It states what the tool does, when to use it, and when to use the sibling tool. The output schema covers return values, so no further explanation is needed.

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 has 100% description coverage for the single 'url' parameter, which already mentions social video links and Google Drive file links. The description contributes additional meaning by adding 'direct video file URL' as a supported type, which is not in the schema. It also frames the parameter's purpose ('Check whether a video URL can be imported') so the agent understands the URL's role.

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: 'Check whether a video URL can be imported and return its title, duration, qualities, and audio tracks.' It uses a specific verb ('inspect') and resource ('video URL'), and distinguishes itself from sibling tool media_import_scan_page by specifying the exact scope of URLs it handles.

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 usage guidance is provided: 'Use for a social video link, a Google Drive file link, or a direct video file URL.' It also names the alternative tool with a clear condition: 'Use media_import_scan_page instead when the URL is a web page that only embeds a video.' This is excellent differentiation.

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 the key behavior of extracting an importable video URL from the page, which is more than just a repeat of annotations. However, it does not mention edge cases like 'no video found' or any network fetching requirements, so it's not a full 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 description is only two sentences, with the first sentence front-loading the purpose and the second sentence providing essential usage guidance. No filler or 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 a single read-only parameter, no mutation risk, and an output schema, the description covers the core purpose, usage restrictions, and alternatives. It is sufficiently complete for an AI to invoke it correctly in most scenarios.

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 provides 100% parameter coverage with a description for the 'url' field. The description adds a crucial semantic clarification: pass a page URL, not a direct video URL, and directs direct-URL cases to media_import_inspect. This meaningfully narrows the schema's broader phrasing and prevents misuse.

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 action ('Scan a web page') and the result ('return the importable video URL found inside it'). It also distinguishes itself from the sibling media_import_inspect by noting that inspect handles social, Google Drive, and direct video URLs.

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 explicitly states when to use this tool ('Use only when the URL is a page rather than a video') and explicitly names the alternative (media_import_inspect) along with what that tool already handles. This gives the AI clear decision guidance.

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=false and destructiveHint=false, so the mutation profile is clear. The description adds that this is a network fetch operation ('direct URL') but does not disclose potential failure modes, URL format restrictions, or effects of contentHashSha256 deduplication. It provides some value beyond annotations but lacks rich behavioral context.

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, well-formed sentence that leads with the primary verb and immediately conveys the core function. No filler or redundancy, making it efficiently parseable for an agent.

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 core function is clear, and the schema plus annotations cover parameters and safety. However, the absence of usage guidance and behavioral caveats (e.g., URL reachability, media format support) leaves gaps for an agent deciding between URL import and other media ingestion methods. Adequate but not complete.

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%, with each parameter (url, name, projectId, workspaceId, contentHashSha256) already described meaningfully. The tool description adds no extra parameter semantics, so the baseline of 3 is appropriate.

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

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

The description specifies a clear action ('Import'), resource type ('video, audio, or image'), source ('direct URL'), and destination ('BlitzReels media library'). This unambiguously distinguishes it from sibling tools like media_upload_file (local upload) and media_import_inspect (inspection).

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 no guidance on when to use this tool versus alternatives such as media_upload_file or media_import_scan_page. It does not mention prerequisites, URL accessibility requirements, or exclusions, leaving the agent without context for tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal extra behavioral context beyond scope ('user's library'), but does not disclose pagination, ordering, or default workspace behavior beyond what schema already provides.

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 directly states the tool's purpose without redundancy or filler. It is front-loaded and every word contributes 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?

For a simple filtered-list tool, the description is sufficient when combined with complete schema documentation, strong annotations, and an output schema. There are no complex behaviors or hidden side effects to explain.

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% with each parameter documented (limit, offset, assetType, workspaceId). The description adds no new parameter nuance beyond mentioning media types, which duplicates the assetType enum. Baseline 3 is appropriate because the schema carries the semantic 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 uses a specific verb ('List') and resource ('media files in user's library'), and clarifies scope with media types ('videos, audio, images'). This clearly distinguishes it from siblings like media_assets_get (singular asset retrieval) and media_folders_list (folders).

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 implicitly establishes usage context: use this tool to list media assets in the user's library. It doesn't explicitly name alternatives or exclusions, but the purpose is clear enough and no conflicting sibling offers the same list functionality with these filters.

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 safety profile is clear. The description adds 'bounded window' to indicate pagination/limiting behavior, which is useful context 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 a single, well-structured sentence with no wasted words. It front-loads the action and clearly states the two output forms, making it 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?

With a 4-parameter schema fully described, an output schema present, and annotations covering safety, the description provides adequate context. It might slightly under-explain the three modes, but the schema's mode enum descriptions fill that gap sufficiently.

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 has 100% parameter description coverage, including mode, limit, offset, and assetId. The description's reference to 'summary metadata or bounded window' loosely maps to mode but adds no concrete parameter details beyond what the schema already specifies.

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 gets transcript summary metadata or a bounded window of transcription segments for a video asset, using a specific verb ('Get') and identifying the resource and scope. This distinguishes it from sibling media tools, none of which handle transcripts.

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 implies this is the tool for retrieving transcript data from a video asset, with no sibling transcript tools offering an alternative. It does not explicitly state when not to use it, but the clarity of purpose and lack of transcript siblings provide sufficient usage guidance.

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 no safety hints (readOnly=false, destructive=false, idempotent=false), so the description carries the burden. It only says 'import' and does not disclose behavioral details like whether the file is copied or moved, whether any processing occurs, or whether permissions are needed. The source and types are stated, but these align more with purpose than with behavior.

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

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

The description is two clearly written sentences. The first sentence front-loads the action and target, and the second provides the exact use cases. No filler or 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?

The tool has an output schema and a moderately complex nested input, but the description leaves gaps: it doesn't mention how this differs from media_upload_start/finish, whether import is one-step, or any preconditions. It covers the main use scenarios but could be more complete regarding alternatives and side effects.

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 each parameter already has descriptions in the schema. The description adds context that the file must come from ChatGPT, which clarifies the 'file' parameter's origin, but it doesn't add much for name, projectId, or workspaceId beyond what the schema provides. This matches the baseline 3 for high schema coverage.

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

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

The description states 'Import a video, audio, or image file from ChatGPT into the BlitzReels media library.' This is a specific verb ('import') with a clear resource and target, and it distinguishes from sibling tools like media_import_url and media_upload_start by emphasizing the source is ChatGPT-attached/generated files.

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 explicitly tells when to use this tool: for files the user attached or picked, and for ChatGPT-generated images the user wants to keep, animate, or edit. This provides clear context, though it doesn't explicitly name alternatives or exclusions (e.g., when to use media_import_url instead).

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 no safety hints (all false), so the description must carry the full burden. It only says 'Complete the upload process' without disclosing side effects, such as asset creation, validation, or potential errors. This is nearly a tautology of the tool name.

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 concise sentence with no redundant words, front-loading the action and context. It is appropriately short, though it could have included more behavioral context without becoming verbose.

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 captures the essential step and references the presigned URL flow, and an output schema exists. However, it omits details about required preconditions (e.g., calling media_upload_start), validation, and what 'completing' entails, making it minimally adequate for a 7-parameter tool.

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

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

The input schema covers all 7 parameters with rich descriptions (100% coverage), including formats, constraints, and optionality. The tool description adds no parametric detail, but the schema alone provides sufficient semantics, justifying the baseline score 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 specifically states the action 'Complete' and the resource 'upload process,' with the context 'after uploading to a presigned URL.' This clearly identifies the tool's role in the upload workflow and distinguishes it from siblings like media_upload_start and media_upload_file.

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 'after uploading to a presigned URL' provides clear sequencing and prerequisite guidance. However, it does not explicitly mention alternatives or when not to use this tool, leaving some room for ambiguity.

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 only says 'get a presigned URL' and gives no insight into side effects such as creating an upload session, URL expiration, or the need to call media_upload_finish afterwards. Annotations are all false, providing no safety profile, so the description carries the burden and fails to disclose the state-changing nature of initiating an upload.

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 sentence that is front-loaded with the core action and includes a high-value qualifier. No filler or redundancy; the title and description align well.

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?

Despite having an output schema, the description does not explain the expected workflow: how to use the returned presigned URL, whether to follow up with media_upload_finish, or why this differs from media_upload_file. This is a meaningful gap for an upload-start tool, making the description incomplete.

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 parameters are already fully documented. The description adds no additional parameter semantics beyond implying 'large files', earning the baseline score 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 uses a specific verb and resource: 'Get a presigned URL for direct file upload', which clearly states the tool's function. The parenthetical 'for large files' distinguishes it from sibling upload tools like media_upload_file.

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 'for large files' provides clear context for when to use this tool, implying it is intended for direct/large uploads. However, it does not explicitly name alternatives or establish exclusion criteria (e.g., 'for small files use media_upload_file').

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?

Description states the direct effect (volume set to zero) and is consistent with annotations (idempotent, not destructive). It adds little beyond the tool name, but annotations carry the safety profile; no contradiction or extra context like reversibility.

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?

Single sentence, densely packed, no filler. Front-loaded with the primary action and target.

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, has an output schema, and rich annotations. The description adequately identifies the single clip target; missing only explicit alternative guidance, but overall the context is sufficient for calling it.

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 projectId, idempotencyKey, and expectedRevision. Description clarifies timelineItemId as the target media item, compensating for the missing schema description. No additional syntax or relation to the optional expectedRevision is provided.

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 uses a specific verb ('Set') and precise resource ('one timeline media item's volume to zero'). It clearly distinguishes from sibling tools like timeline_audio_add or batch_update_timeline_clips by targeting a single clip's audio.

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 'one timeline media item' implies single-item usage, but the description does not explicitly state when to choose this over update_timeline_clip or batch_update_timeline_clips, nor any exclusions.

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 the useful detail that new projects are 'private', which is not disclosed in the annotations. However, it doesn't elaborate on the implications of privacy, permissions, or any side effects (e.g., timeline creation). Annotations already mark it as a non-read, non-destructive operation, so the description adds some but not rich context.

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, concise sentence that clearly conveys the essential purpose without filler. 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?

Given that the input schema fully documents parameters and an output schema exists, the description adequately covers the essential context. The 'private' attribute adds meaningful behavioral detail. The description is complete enough for an agent to select and invoke the tool, though it could optionally mention what a created project includes.

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%, with clear documentation for all six parameters, including defaults and enums. The tool description itself contributes no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Create') and the resource ('a new private BlitzReels video project'). It is specific and distinguishes this tool from siblings that create other entities (clips, media, workflows) or read/inspect projects.

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 for creating new projects, which is a clear context. It doesn't explicitly state when not to use it or mention alternatives, but given the sibling set, no direct alternative for creating projects exists, so the context is sufficient.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by naming what details are included (timeline summary, clips, captions), which goes beyond the annotations. It does not mention error handling or permissions, but these are less critical given the safety hints.

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, concise sentence that front-loads the action and resource and lists included content. There is no redundant wording 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?

For a simple read operation with one well-documented parameter and an output schema, the description is sufficiently complete. It even previews the return content, making the tool's purpose and result clear without needing to reference the 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?

The schema already provides 100% description coverage for the single parameter, including type and format. The tool description does not add any additional meaning beyond what the schema states, so baseline 3 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?

The description clearly states the action ('Get details'), the resource ('one BlitzReels project'), and specifies key content ('timeline summary, clips, and captions'). This distinguishes it from list-style siblings like projects_list and from clip-specific 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 purpose is clear enough that usage is implied: use when needing details for a single project. However, there is no explicit guidance contrasting with projects_list or projects_inspect, so the agent must infer when this is the right choice among similar 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not burdened with safety disclosure. It adds the 'bounded' trait and lists content types, but does not describe pagination defaults, mode behavior, or other operational details beyond what the schema already provides.

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 entire description is a single, compact sentence that front-loads the core action ('Read bounded project context') and then efficiently enumerates the major content categories. No redundant words 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?

Given the high parameter count (11) and the presence of a full output schema, the description provides a sufficient high-level overview without needing to explain return values or parameter syntax. It could have mentioned the default mode or the purpose of the 'mode' parameter, but that is covered in the schema, so the description remains adequately complete.

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 itself does not add parameter-specific meaning; it only states what content is included. All 11 parameters are fully documented in the schema, so no compensation 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 uses a specific verb ('Read') and identifies the exact resource ('bounded project context for editing') with a clear list of included content (timeline items, media assets, transcripts, captions, and stable IDs). This clearly distinguishes it from sibling tools like projects_get or media_transcript_get by emphasizing the consolidated yet bounded nature.

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 during editing workflows by stating 'for editing', but it does not explicitly mention when to use this tool versus alternatives such as projects_get, media_assets_get, or media_transcript_get. There are no exclusions or explicit alternative references, leaving the decision to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds no further behavioral context (e.g., pagination behavior, default workspace handling) beyond what the schema and annotations provide, so it neither contradicts nor significantly enhances transparency.

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 that names the action and resource, then lists the key output attributes. No unnecessary words or redundancy are present.

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 list tool with a comprehensive schema and output schema, the description covers the essential purpose. It does not mention pagination or default filtering, but those are defined in the schema, so the context is adequately complete for the tool's 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 100%, so the schema documents all five parameters with defaults and constraints. The description does not add parameter-specific meaning beyond what the schema already states, leaving the schema to carry the burden fully.

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 ('List') and resource ('BlitzReels projects'), and further clarifies the scope ('user's') and output fields (status, duration, basic metadata). This clearly distinguishes it from sibling tools like projects_get (single project) and projects_create (creation).

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 for listing multiple projects, which gives clear context for when to use it compared to single-project retrieval tools, but it does not explicitly mention exclusions or alternatives. For a straightforward list operation, this level of guidance is sufficient.

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 show this is a write operation (readOnlyHint=false), and the description confirms a mutation ('Place onto... timeline'). The description adds the prerequisite of a prior upload, which is useful, but it does not disclose other behavioral traits like validation of audio type, error cases, or reversibility. With minimal annotation detail, the description carries some burden but leaves gaps.

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 long, front-loaded with the core action and resource, and every word provides value. It does not waste space with redundant 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?

Given the tool's complexity (8 params, output schema exists), the description covers the primary use case, prerequisite, and audio-specific scope. It does not explain nuances like the required durationSeconds condition, but those are in the schema. It is adequately complete for an agent to decide when to use it.

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 documented. The description adds context that the asset must be an uploaded audio asset and that placement occurs at a timestamp, which reinforces but does not extend parameter meaning. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Place'), the resource ('uploaded audio asset'), and the destination ('actual BlitzReels project timeline at a timestamp'). It distinguishes this tool from siblings by specifically mentioning audio (voiceover, music), which separates it from timeline_media_add.

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 explicitly says 'Use after media_upload_file' and specifies the user intent ('add voiceover, music, or audio to a video'). This gives clear context for when to use the tool, but it does not mention when not to use it or explicitly 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the operation types (trim/extend/split), which is useful but does not disclose behaviors like revision-based concurrency or potential side effects beyond what annotations already indicate.

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 concise sentences that are front-loaded with the most important information. Every word contributes, with no redundant or vague phrasing.

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 complexity of the schema (nested operation union) and the presence of an output schema, the description is minimally adequate. It covers the core behavior but omits important context, such as the need for expectedRevision for optimistic concurrency and how this tool relates to timeline_edit_preview (apply vs preview).

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 50%, with projectId and expectedRevision described. The tool description adds meaning by naming the two operations (trim/extend and split), which helps interpret the 'operation' union parameter. However, it does not explain parameters like trimStartDeltaSeconds, splitAtSeconds, or idempotencyKey, leaving gaps.

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 with specific verbs and resources: 'Trim or extend one timeline item' and 'Split one timeline item at an exact sequence position.' It distinguishes two operation types and explicitly targets a single timeline item, making it easy to differentiate from 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?

The description provides clear context on when to use the tool: when you need to trim, extend, or split a single timeline item. However, it does not explicitly mention alternatives or exclusions (e.g., batch edits or previewing), 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 description's 'without mutation' is consistent but not novel. However, it does add behavior beyond annotations by specifying that the preview covers trim/extend and split operations, which are concrete, non-obvious capabilities. No contradiction exists.

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 short sentences, front-loaded with the critical 'without mutation' qualifier. Every phrase adds value—the first sentence establishes the read-only nature, the second enumerates supported operations. No wasted words.

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 moderate complexity (two operation variants), the presence of a detailed schema with oneOf, an output schema, and annotations covering safety, the description is sufficiently complete. It captures the essential behavioral contract (preview-only) and lists all supported operations; any remaining details are handled by the schema and annotations.

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 provides descriptions for projectId and expectedRevision, but the operation parameter has no description and is expressed as a oneOf with const values. The description's enumeration of 'trim or extend' and 'split' maps to the two operation variants, but it does not clarify parameter semantics like 'expectedRevision' or delta meanings beyond what the schema names imply. With 67% schema coverage, the description gives partial compensation.

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 'Preview without mutation,' using a specific verb and resource that immediately distinguishes it from the sibling 'timeline_edit_apply.' It then enumerates the exact operations ('Trim or extend one timeline item,' 'Split one timeline item at an exact sequence position'), making the tool's scope 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?

'Preview without mutation' clearly signals that this tool is for pre-flight checks rather than actual edits, and the sibling 'timeline_edit_apply' implies the alternative. However, it never explicitly states 'use this instead of timeline_edit_apply when you want to verify without persisting changes,' so it falls short of a fully explicit when/when-not directive.

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

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

Annotations already signal readOnlyHint=false, and the description reinforces the mutating nature by saying 'Place' onto the 'actual' timeline. It adds useful workflow context ('Use after media_upload_file') and media-type nuance, but it does not disclose side effects on existing timeline items or layer conflicts beyond what the schema already implies.

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 very concise: two sentences, front-loaded with the action and object, and every phrase adds value. The second sentence provides essential usage context without waste.

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 a 9-parameter schema that is fully described and an output schema, the description does not need to repeat internals. It covers core purpose and usage enough for an agent to select the tool, though it could mention layer/positioning semantics if the schema were less rich. Overall, it is sufficiently complete for the tool's 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 100%, with detailed descriptions for every parameter, including enums and defaults. The description adds no additional parameter guidance, so the baseline score of 3 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?

The description opens with a specific verb ('Place'), a resource ('actual BlitzReels project timeline'), and object ('uploaded image or video asset'), clearly indicating what the tool does. It distinguishes from siblings like media_upload_file and timeline_audio_add by specifying B-roll/static image/visual media and 'actual' timeline.

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

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

It explicitly states when to use: after media_upload_file and when the user wants to add B-roll, a static image, or visual media. It gives a clear workflow but does not explicitly name alternative tools or provide when-not-to-use guidance, 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=false, idempotentHint=true, and destructiveHint=false. The description adds the constraint about providing at least one field, but no additional behavioral traits like return formats or revision checking. It is consistent with annotations but does not go beyond 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 two sentences, front-loaded with the core purpose and followed by a necessary usage constraint. Every word earns its place, and it is appropriately compact for the tool's complexity.

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 11-parameter schema and output schema presence, the description covers the key functional fields and distinguishes from similar tools. It omits explicit guidance on when to use this tool versus batch_update_timeline_clips, but the 'one' qualifier mitigates this. Overall, it is sufficiently complete for a concise tool description.

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 27%, but the description names several updatable fields (start, duration, trim, layer, ignored state, blurred background), providing some semantic guidance. It does not elaborate on parameter-specific details like the meaning of trimStart vs trimEnd or expectedRevision, leaving a gap for 8 undocumented parameters.

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 action ('Update') and the resource ('one timeline item'), and lists specific attributes ('start, duration, trim, layer, ignored state, or blurred background'). It distinguishes from the sibling 'batch_update_timeline_clips' by emphasizing 'one' timeline item.

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

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

The description implies usage for single-item updates by saying 'one timeline item' and provides a key prerequisite: 'Provide at least one field to update besides timelineItemId.' It does not explicitly name alternatives or exclusions, but the sibling tool name suggests batch usage, making the context clear.

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?

All annotations are negated hints (readOnly=false, destructive=false), so the description carries the burden of behavioral disclosure. It only adds the ambiguous term 'interactive' without explaining lifecycle, blocking behavior, or prerequisites, which is insufficient for a create operation.

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 10-word sentence that is front-loaded with the verb and contains zero filler. It communicates the core action efficiently 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?

The output schema and parameter descriptions cover return values and inputs well. However, the description fails to explain the 'interactive run' concept and its relationship to workflow_runs_execute_step, which is essential context for a moderately complex tool with nested object inputs.

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 clear per-parameter descriptions, so the baseline applies. The tool description mentions 'workflow and optional inputs' but adds no semantics beyond what the schema already documents.

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

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

The description uses a specific verb ('Create') and resource ('interactive workflow run'), which clearly distinguishes it from siblings like workflow_runs_get and workflow_runs_execute_step. However, the term 'interactive' is not elaborated, leaving some ambiguity about what makes this run type distinct.

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 no guidance on when to use this tool versus alternatives such as workflow_runs_execute_step, nor does it explain when an interactive run is appropriate. No exclusions or alternative tools are mentioned.

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