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 declare a non-destructive, idempotent, open-world mutation. The description adds no further behavioral context such as what exactly is created, permissions required, side effects on the timeline, or how expectedRevision affects the write. It does not contradict annotations, but it does not enrich them either.

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

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

The description is a single front-loaded sentence with no filler. However, it is too sparse for a 12-parameter mutation tool with low schema coverage, so its brevity becomes under-specification rather than effective conciseness.

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 12-parameter tool with 25% schema coverage, existing annotations, and an output schema, this description is incomplete. It gives the purpose but omits the parameter meanings and usage context needed to invoke the 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?

With only 25% schema description coverage, the description must compensate for 9 undocumented parameters. It indirectly touches on timelineItemId (optional attachment) and includeSfx (paired with sound), but ignores name, easing, preset, intensity, layerIndex, durationSeconds, and expectedRevision.

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

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

The description states a specific verb and resource: 'Add a timed transition effect.' It distinguishes itself from timeline siblings like add_text_overlay or timeline_audio_add by resource type, though it does not explicitly name an alternative. Clarity is high but lacks sibling routing.

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

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

There is no when-to-use or when-not-to-use guidance. The phrase 'optionally attached to one timeline item and paired with sound' implies the tool can be used standalone or attached, but this is context about parameters, not selection guidance versus 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 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?

Annotations already disclose idempotentHint=true and destructiveHint=false; the description adds the upsert-like 'create or update' behavior and the fact that the character is reference-based. It does not disclose important operational constraints such as consent or rights gates, but those are documented in the schema properties, so the additional behavioral gap is moderate.

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

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

One tight sentence that front-loads the operation, the resource kind, and the use case; no filler or restatement of the title. It earns its place, even though it sacrifices 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?

Although an output schema exists, the tool has 14 parameters and a very low schema description coverage. The description leaves critical invocation questions open—how updates are keyed (characterId vs idempotencyKey), what reference assets are required, and which consent flags must be set. This is not complete enough for a complex write 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 description coverage is only 21%, so the description should compensate for the many undocumented parameters. It does not: no mention of idempotencyKey, characterId as the update selector, referenceAssetIds/primaryReferenceAssetId, voice fields, or storyFacts. The only hint is 'reference-based,' which weakly maps to the reference asset 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?

States a specific verb ('Create or update') and resource ('reference-based character'), and adds the purpose context 'for repeatable faceless story generation.' This is enough to distinguish it from sibling read tools like characters_get/characters_list and from story-generation tools, even though it does not name a sibling explicitly.

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

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

Provides a clear context by describing the intended use case—reusable characters for faceless story generation—but does not articulate exclusions or point to alternatives such as characters_list or generation_faceless_create. The agent can infer when to use it but is not explicitly steered away from sibling tools.

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

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

The description adds minimal behavioral context beyond the annotations. 'Inspect' aligns with readOnlyHint=true and destructiveHint=false. The mention of 'ordered reference-image set' hints at the output structure, but no further details about auth, rate limits, or idempotency are provided. 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?

A single sentence of 14 words that is front-loaded and efficient. However, it is slightly terse and could be more explicit about the core resource (e.g., 'Reusable character' is a domain term that may not be universally understood). Still, it earns its place without excess.

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 simple nature of the tool (read a single character), the presence of annotations and an output schema, the description is mostly complete. It clarifies the use case and the ordered reference-image set. However, it does not explicitly state that the characterId is required or that the operation is read-only, though these are inferred from context 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 description does not mention any parameters. Schema coverage is 50% (workspaceId has a description in the schema, but characterId does not). The tool description could have explained what characterId represents, but it fails to compensate for the undocumented parameter, leaving a gap.

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

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

The description specifies the verb 'Inspect' (read-only) and the resource 'one reusable character and its ordered reference-image set', with a clear scope ('before planning a story'). This distinguishes it from siblings like 'characters_list' (list all) and 'characters_apply' (apply a character).

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

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

The description provides a clear context for when to use this tool ('before planning a story'), but does not explicitly mention when not to use it or alternatives such as 'characters_list' for browsing. The sibling list implies the differentiation, but the description could be more direct.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe, repeatable read operation. Description adds the term 'bounded' which hints at scope but doesn't explain what 'bounded' means (e.g., workspace-scoped, project-scoped) nor mention pagination behavior that offset/limit implies. No contradiction with annotations.

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

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

Single sentence, 14 words, zero waste. Each part ('List', 'bounded reusable characters', metadata details) serves a clear purpose. Front-loaded with the action and resource.

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 low parameter description coverage, the output schema exists and parameter names are clear. The description lacks a note about workspace scoping or archived behavior, but for a simple list tool with rich annotations and output schema, it is largely complete. Could mention that workspaceId is optional and defaults to user's default.

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 4 parameters but description coverage is only 25%—it does not mention or elaborate on any parameter. However, the output schema exists and parameters like limit/offset/workspaceId/includeArchived are self-explanatory from names and schema defaults. Baseline 3 is appropriate since description adds no value beyond schema, but schema names provide adequate context.

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 states specific verb ('List'), resource ('bounded reusable characters'), and included data ('identity, voice, facts, and image-reference metadata'). It clearly distinguishes this tool from sibling tools like characters_get or characters_apply by framing it as a list operation. However, it doesn't explicitly differentiate from other list tools in the sibling set.

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?

Implied usage is listing characters, but no explicit guidance on when to use this vs alternatives like characters_get (for a single character) or characters_apply (for applying characters). No exclusion criteria or context about filtering, pagination, or prerequisites beyond schema-bound parameters.

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?

The description discloses that it creates a 'private' batch and supports certain URL sources, which is useful. But it does not mention side effects (it triggers a creation job), batch/asynchronous behavior, the need for rights confirmation for external media, or any downstream consequences. With no annotations provided, the description carries a heavier burden and falls short.

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 no filler. The key purpose and source types are front-loaded, making the description easy to scan.

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

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

This is a complex creation tool with 10 parameters, including idempotency and rights confirmation, yet the description does not explain the overall workflow, what a 'batch' means, or external-URL requirements. An agent would need to read every parameter description to understand important constraints like confirmRightsToMedia. The short description leaves key operational context unstated.

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 already documents each parameter thoroughly (e.g., confirmRightsToMedia, idempotencyKey, assetId/url mutual exclusion). The description adds only the supported URL types and 'batch' context, which partially repeats schema information. This matches 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 names a specific action ('Create a private BlitzReels clip batch') and identifies two input sources ('existing asset' or 'user-provided video URL'), which is clear and specific. However, no sibling tool names are provided, so it cannot differentiate from related tools like clip_batches_create or media_import_url.

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 the general scenario (create clips from an asset or URL) but no explicit guidance on when to choose this tool over alternatives, no prerequisites (e.g., rights confirmation for external URLs), and no mention of intended workflow. Without sibling context, an agent is left to infer usage from the parameter names.

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 annotations indicate this is a mutating, non-idempotent operation, and the description reinforces this with verbs like 'regenerate' and 'promote,' but it does not disclose side effects, prerequisites, or reversibility. For example, 'promote an accepted delivery export' implies a state change but no details are given about what is affected or whether confirmation is needed.

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 packs many operations into a comma-separated list, making it somewhat run-on but still efficient in length. It is front-loaded with 'List or inspect clips' but the long list of loosely related actions reduces clarity and structure.

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 30 parameters, 7 enums, and an output schema, the description provides only a high-level operation list. It lacks critical contextual details such as parameter dependencies, operation-specific behaviors, or typical use cases, making it incomplete for an agent to reliably invoke the 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?

With 30 parameters and only 17% schema description coverage, the description carries a heavy responsibility to explain parameters, but it names none of them. It does not map operations to required fields (e.g., which params are needed for 'repair' vs 'export') nor explain enums like selectionMode or layoutMode.

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 enumerates the tool's operations with action verbs (list, inspect, regenerate, repair, start export, promote, inspect, apply), making its broad purpose evident. It distinguishes from siblings like clips_get or exports_start by covering a wider range of clip management actions, though the list-like structure prevents a single focused purpose from being stated.

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

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

No guidance is provided on when to use clips_manage versus sibling tools such as clips_get, clips_create, or exports_start. The description only lists operations without explaining which to choose for a given scenario or when a more specific sibling tool would be preferable.

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?

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false). The description adds genuinely useful behavior beyond them: it consumes AI credits and returns an asynchronous job to be polled. It does not quantify cost or say how long the job runs, keeping it short of a 5.

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

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

Two tight sentences with zero waste: the pipeline scope is front-loaded, and the cost/polling consequence follows immediately. 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?

An output schema exists, so return-value detail is not required, and the description still flags the credit spend and the polling handoff to generation_jobs_get. For a heavy 18-parameter generator, this is nearly complete, with only the absence of sibling routing leaving a small gap.

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

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

Schema description coverage is 100%, so all 18 parameters are already documented in the schema; baseline is 3. The description's mention of optional voiceover, captions, music and sound loosely maps to the boolean toggles but adds no syntax, defaults, or enum guidance 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?

Specific verb+resource: 'Turn a script into a full faceless video project' with an enumerated pipeline (scene plan, visuals, voiceover, captions, music, sound). This scope implicitly separates it from single-asset siblings like generation_video_create or generation_voiceover_create, though no sibling is named explicitly.

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

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

The description says it 'returns a job to poll with generation_jobs_get', which implies the async usage pattern. However, it never states when to choose this full-pipeline tool over generation_video_create, generation_plan_brief, or the per-asset generators, so selection among siblings is left to inference.

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 communicate idempotency and non-destructiveness, and the description adds meaningful behavioral context: it spends AI credits and returns an asynchronous job to poll. This reveals cost and job-based execution, which are not visible from the annotations alone. No contradiction with annotations.

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

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

Two sentences with no filler. The primary action is front-loaded, followed immediately by the most important operational facts (credit cost and job polling). Every word earns its place.

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

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

The rich input schema and annotations already cover parameters, idempotency, and non-destructive behavior. The description supplies the missing operational facts—credit spending and polling the returned job—which are exactly what an agent needs to invoke and follow up correctly. The output schema covers return details, so nothing critical is missing.

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

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

Schema description coverage is 100%, with each parameter already well-documented (model defaults, prompt length limits, resolution behavior, aspect ratio, etc.). The description adds no extra parameter-level detail, 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 uses a specific action ('Queue') and a clear resource ('AI image generation into the BlitzReels media library'), and it distinguishes this tool from sibling generation tools like generation_video_create or generation_music_create. It also includes the key outcome—returns a job to poll—so an agent understands exactly what this tool produces.

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

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

The description clearly frames this as the image-generation entry point and tells the agent to follow up with generation_jobs_get, which implies the async usage flow. However, it does not explicitly state when to use this tool over the other generation_* siblings or when not to use it, so the routing guidance is implicit rather than explicit.

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

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

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine value beyond them by disclosing the shape of returned data: video duration is an enum per model (durations_seconds), not a min-max range — a trait an agent would otherwise guess wrong.

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, both front-loaded: the first states the purpose, the second immediately delivers the non-obvious durations_seconds caveat. No filler.

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

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

An output schema exists, so return values needn't be described in full, yet the description includes the one detail most likely to cause misuse (duration enum vs range). For a single-enum-param read tool, nothing an agent needs to call it correctly is missing.

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

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

There is only one parameter (kind), and schema description coverage is 100% with a full enum of allowed kinds. The description adds no meaning to the 'kind' parameter itself, so the baseline 3 applies; the durations_seconds note pertains to output, not this parameter.

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

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

States a specific verb (List) and resource (models, defaults, limits, credit costs) scoped to 'one generation kind before queueing it'. An agent can distinguish it from the generation_*_create siblings, which consume the options this tool returns.

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

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

The phrase 'before queueing it' clearly signals this is a pre-flight/discovery call that precedes a generation create. It does not explicitly name the alternative tools (generation_image_create, generation_video_create, etc.), but the sequencing intent is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds behavioral context by specifying what the brief contains and its role in the authoring workflow, going beyond the annotations. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main purpose, and contains no filler. Every sentence earns its place, making it highly concise and 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?

Given the presence of an output schema, detailed annotations, and 5 optional parameters, the description is sufficient. It explains the tool's purpose, what the brief contains, and the expected next step (validate), making it contextually 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 80%, and the parameter descriptions are detailed (e.g., genre, videoModelId). The tool description does not add extra meaning to parameters beyond what the schema already provides, 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 uses a specific verb+resource ('Fetch the authoring brief') and clearly lists the brief's contents (prompting grammar, capability constraints, locked style contract, plan JSON schema). It distinguishes this tool from the sibling generation_plan_validate by stating the workflow: author the plan from the brief, then validate.

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 usage context: this tool provides the brief for authoring a plan, and the next step is validation with generation_plan_validate. It implies when to use it (before authoring) but does not explicitly state exclusions or alternatives beyond the validate sibling, 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 read-only, idempotent, and non-destructive behavior. The description adds context about return behavior ('Returns directive errors to fix and revalidate') and establishes this tool as a gate for execution. This goes beyond annotations without conflicting with 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?

Two sentences with no redundant wording. The purpose is front-loaded, and the second sentence efficiently conveys return behavior and the validity constraint.

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 single well-documented parameter, output schema, and clear annotations, the description sufficiently covers purpose, usage context, and return behavior. It 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?

The schema provides a full description for the 'plan' parameter, referencing generation_plan_brief's planJsonSchema. The tool description adds no additional parameter-specific semantics, but with 100% schema coverage, a 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 tool's function: validating a generation plan against the schema and model capabilities. It uses a specific verb ('validate') and resource ('generation plan'), and the phrase 'before execution' distinguishes it from planning or execution tools like generation_plan_brief.

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: after authoring a plan and before execution. It does not explicitly name alternatives or exclusions, but the context is clear enough from 'self-authored' and 'only a valid plan is executable.'

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?

Annotations already declare write, idempotent, non-destructive, closed-world. The description adds two things annotations cannot convey: it consumes AI credits, and it is asynchronous — it returns a job rather than a finished asset, to be polled with generation_jobs_get. That async/cost behavior is exactly the context an agent needs before calling.

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 waste. The queueing action and input modes come first, then the cost and async follow-up, so the most decision-relevant facts are 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?

For an 18-parameter, credit-spending, async generation tool it covers the essential non-schema facts: cost, async polling, and the two input shapes. Output schema exists so return values needn't be enumerated, but a hint that model/options must be validated via generation_options_list is only in the schema, not the 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 100%, so the baseline is 3 — the schema already documents model, duration, reference arrays, asset IDs, and their per-model constraints in detail. The description adds only a high-level encapsulation of the two input modes (prompt / image asset) and no syntax or format detail 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?

States a specific verb and resource ("Queue an AI video generation into the BlitzReels media library") and names both input modes (prompt or existing image asset). The word "video" distinguishes it cleanly from generation_image_create, generation_music_create, and generation_voiceover_create without needing to inspect them.

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

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

It gives the two valid entry paths (text prompt vs. existing image asset) and names the follow-up tool, generation_jobs_get. It stops short of explicitly stating when to prefer this over the sibling generation tools or generation_faceless_create, so routing guidance is clear but not complete.

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 significant behavioral context beyond what annotations provide: the operation 'Spends AI credits' (a cost consequence), is queued asynchronously rather than executing synchronously, and 'returns a job to poll' — all unstated in the annotations. The annotations cover idempotency and non-read-only status, and the description is fully consistent with them, while enriching the agent's understanding of 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?

Two sentences with zero waste. The action and resource are front-loaded in the first sentence, and the second sentence delivers the two highest-stakes facts — cost and async polling — that an agent must know before invoking. 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?

With an output schema present to document the job return shape, 100% schema coverage, and annotations covering idempotency/safety, the description covers the remaining essentials for an async queue tool: what is produced, where it lands, that it costs credits, and how to follow up (poll with generation_jobs_get). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters well, including the voiceId catalog lookup (generation_options_list with kind voiceover), speed range, voiceStyle enum, and idempotencyKey semantics. The description adds minimal parameter-level meaning beyond confirming 'text' is the read-aloud script via the 'text-to-speech' phrasing. Baseline 3 is appropriate since the schema carries 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?

Uses a specific verb ('Queue') and names a precise resource ('text-to-speech voiceover into the BlitzReels media library'). The async nature ('returns a job to poll') clearly distinguishes this from synchronous siblings, and the 'text-to-speech voiceover' scoping separates it from the generation_music_create, generation_sound_create, generation_video_create, and generation_faceless_create siblings without needing to open any schema.

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

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

The description establishes clear context for when to use this tool: when a voiceover is needed and the caller expects an async queued job. The explicit pointer to generation_jobs_get gives the follow-up workflow, and the TTS scoping implicitly routes the agent away from the music/sound/video/image generator siblings. It stops short of explicitly enumerating when-not-to-use conditions, so it doesn't reach 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?

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description reinforces 'without creating media' and adds the input constraint that the URL must be public, but it does not go beyond annotations to disclose failure modes, rights-confirmation effects, or provider-specific behavior. This is adequate but not especially 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 with no filler. Every clause earns its place: the source ('user-provided public'), the supported link types ('social-video or Google Drive URL'), the behavior ('return available import metadata'), and the key non-effect ('without creating media').

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 strong annotations, a 100%-covered input schema, and an output schema present, the description covers the core task well and reinforces the critical read-only distinction. It could be more complete by explicitly separating itself from media_import_scan_page or explaining what confirmRightsToMedia actually changes in the response, but those are minor gaps given the surrounding structured context.

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

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

Schema description coverage is 100%, so the schema already documents both 'url' and 'confirmRightsToMedia'. The description mostly restates the schema's URL domain (public, social video or Google Drive) and adds no new meaning about URL formats, required confirmation semantics, or edge cases. It does not elevate above 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 uses a specific verb ('Inspect') with a clear resource ('a user-provided public social-video or Google Drive URL') and a clear outcome ('return available import metadata'). The phrase 'without creating media' distinguishes it from import-oriented siblings like media_import_url, making the tool's role as a read-only preflight step evident.

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 the tool: when a user provides a public URL and you need import metadata without creating media. It does not explicitly name alternatives or state when not to use it, so it stops short of full routing guidance, but the use case is unambiguous.

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

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

Annotations already disclose read-only, idempotent, and non-destructive behavior. The description adds meaningful context by explicitly stating no media is created and that the target must be a user-controlled public page, reinforcing the safety and authorization expectations beyond the structured fields.

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

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

The description is a single, directly relevant sentence with no filler. The primary action, target, outcome, and non-destructive nature are all front-loaded and economically expressed.

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, combined with strong annotations and a fully documented schema, covers what the tool does and its key constraints. The presence of an output schema means return value details are not required here. A small gap is the lack of explicit guidance on when to use this tool versus its import-related siblings.

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 are already well described in the input schema, so the description carries little additional parameter burden. It does not add extra semantics beyond what the schema provides, which matches the baseline expectation 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 states a specific action ('Scan a user-controlled public page') and outcome ('return an importable video URL found on it'), with a clear non-creation qualifier. It does not explicitly distinguish itself from sibling tools like media_import_inspect or media_import_url, but its page-scanning purpose is clear.

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

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

The description provides context that the page must be user-controlled and public, which implies an authorization condition, and 'without creating media' signals a non-destructive inspection use case. However, it does not explicitly state when to prefer this tool over the related media_import_inspect or media_import_url tools, nor does it describe when not to use it.

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

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

Annotations already indicate this is a mutating, non-idempotent operation, and the description's 'Import' wording is consistent with that. It adds helpful context about the destination and accepted media types, but it does not disclose behavioral nuances like network download behavior, validation failures, dedupe-by-hash semantics, or the rights confirmation requirement.

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, efficiently structured sentence that front-loads the action, resource type, source, and destination. There is no filler, and every phrase contributes to the agent's understanding.

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

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

With rich schema descriptions, clear annotations, and an output schema present, the description provides enough context for an agent to call the tool correctly. It could be more complete by giving explicit routing guidance versus upload/inspect siblings, but that gap does not block correct invocation.

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

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

The input schema provides 100% coverage for all six parameters, so the description does not need to restate parameter details. The description adds no new parameter-level semantics beyond the schema, but the baseline of 3 applies because the structured schema already carries that 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 identifies a specific verb ('Import'), a clear resource (video, audio, or image from a direct URL), and a destination ('private BlitzReels media library'). This distinguishes it from sibling tools such as media_upload_file and media_import_inspect without requiring an agent to inspect schemas.

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 'user-provided direct URL' implies the intended use case: importing remote media into the library. However, the description never explicitly names alternatives or states when not to use this tool, such as for local file uploads or pre-import URL inspection, so usage guidance is only implied.

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

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

Annotations already declare 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?

Annotations already cover the safety profile (non-destructive, idempotent, closed-world), and the description adds genuinely new behavior: it consumes AI credits and returns a new pending media asset requiring polling. Those are the two things an agent most needs to know before invoking an async, credit-spending job.

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

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

Three short sentences, front-loaded with the action, then prerequisite, then side effects and next step. No filler or repetition.

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 an existing output schema, the description still conveys the async contract (pending asset + polling), the credit cost, and the required prerequisite call. An agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so every parameter including assetId, targetResolution, projectId, workspaceId, and idempotencyKey is already documented with format and defaults. The description only restates the resolution options, adding no meaning beyond the schema. 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?

States a specific verb (upscale), the single resource affected (one stored video asset), the provider, and the two valid outputs (1080p/4k). It is clearly distinguishable from media_upscale_estimate, which it explicitly defers to.

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

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

Gives an explicit prerequisite ('Call media_upscale_estimate first') and a follow-up path (poll with media_assets_get). It doesn't spell out when NOT to use it, but the sequencing guidance is strong 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?

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description reinforces this with valuable context: 'Does not spend credits or queue a job,' which tells the agent the side-effect profile. It does not add rate limits, auth requirements, or latency expectations, so it falls slightly short of a 5.

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

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

Three tight sentences with zero waste. The purpose is front-loaded, the behavioral constraint follows, and the routing instruction comes last.

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?

Complete for a read-only estimation tool. The description establishes purpose, side-effect profile, and sibling relationship; the schema and annotations cover parameters and safety. With an output schema present, no return-value 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?

Schema coverage is 100%, so all four parameters are fully documented in the schema, including the enum for targetResolution. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 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?

States a specific verb+resource: 'Estimate ByteDance upscale eligibility and credits for one stored video.' Explicitly distinguishes from the sibling media_upscale by noting it 'does not spend credits or queue a job' and instructs calling it 'before media_upscale.'

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 sequencing guidance: 'Call this before media_upscale' names the alternative and the condition that selects it. The agent knows exactly when to use this tool versus the actual upscale tool, with no exclusions left to inference.

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?

Annotations already mark readOnlyHint=false, so the write nature is disclosed. The description adds that the project is 'private', a useful behavioral detail, but does not mention authentication, default workspace resolution, or any side effects beyond the creation itself.

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

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

One clean sentence delivers the core intent without waste. It front-loads the action and object, though given the 7-parameter surface, the description is relatively thin if not actively concise.

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 schema and output schema cover the parameter and return details. However, the description omits usage guidance (when to use vs alternatives) and does not clarify operational defaults or consequences like default workspace or private visibility, which would help an agent invoke it confidently.

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

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

Schema description coverage is 100%, so all 7 parameters are already documented in the schema. The description adds no additional meaning or constraints about parameters (e.g., default aspectRatio, frameRate behavior) beyond what the schema 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 states a specific action ('Create') and a specific resource ('new private BlitzReels video project'), which clearly identifies it as a creation tool for projects. It distinguishes from sibling read/list tools like projects_get and projects_list, though it doesn't explicitly name any alternative as another option.

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 is given on when to use this tool versus alternatives such as workflow_runs_create or clips_create. There is no mention of prerequisites, idempotency usage, or scenarios where this should be preferred over other create 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 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.