Clipwave

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds minimal context by noting it returns a 'status/result,' hinting at the return content. It doesn't contradict the annotation (Get aligns with readOnlyHint). It adds little beyond the annotation but is consistent.

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, front-loaded sentence with no wasted words. It is efficient and immediately states the purpose. However, the brevity partly reflects under-specification rather than deliberate conciseness, which keeps it from 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?

With no output schema, the description should explain what 'status' and 'result' actually look like — e.g., possible statuses (queued, running, completed, failed) and how to interpret them for polling. It provides none of this. For a polling tool, the agent lacks the information needed to know when a job finishes or what constitutes success.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented job_id parameter. It does not mention job_id at all — neither its meaning nor where to obtain it (presumably from a generation call's response). With a single required parameter and zero schema documentation, this is a clear gap.

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

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

The description states a clear verb+resource combination: 'Get the status/result of a generation job.' It is specific about what the tool does. It doesn't explicitly differentiate from siblings, but none of the sibling tools (video_editor_*, media_forge_generate) directly offer job-status retrieval, so it is reasonably distinct by nature.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that it should be called after media_forge_generate to poll for completion, nor how statuses should be interpreted (e.g., when a job is finished). No exclusions or alternative references are 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 include readOnlyHint: true, so the agent already knows this is a safe read operation. The description adds valuable detail about the return content: per-model capability flags, exact IDs, durations, aspect ratios, and image model specifics. This goes beyond the annotation without contradicting it.

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 moderately long but every sentence adds value. It front-loads the core purpose, then details the output structure, then provides usage directives. The use of dashes and line breaks aids readability. It could be slightly more concise, but it is well-structured and not bloated.

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 parameterless tool with no output schema, this description is exceptionally complete. It tells the agent what it will receive (model capabilities, IDs, etc.), how to use it (pass exact IDs to media_forge_generate), and when to use alternative tools. Nothing an agent needs to call this correctly is missing.

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

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

The tool has zero parameters, so the schema covers 100% trivially. The description doesn't need to explain any parameters, and the baseline for 0 params is 4. The description's focus on output and usage 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 verb 'List' and the resource 'ALL Media Forge models', and specifies exactly what it returns (capabilities, IDs, durations, aspect ratios per model type). It also differentiates from sibling video_editor_* tools by explicitly saying to use them for reference-image + dialogue scenarios.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS call this and pass an exact id... to media_forge_generate' and never hand-build a model_id. It also states when not to use it: 'For reference-image + dialogue together, use the video_editor_* tools instead.' This is crystal 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 only provide destructiveHint=false distance, while the description discloses crucial async behavior (returns job_id), polling requirements, in-memory job volatility, redeploy dropping jobs, and resubmission guidance. This goes well beyond the structured annotations and materially helps an agent avoid failed calls.

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 dense but every sentence earns its place: the core action and async workflow are front-loaded, and the later sentences address model selection, job lifecycle, and sibling routing. It is appropriately sized for the complexity.

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

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

For an async, broad-catalog media generation tool with no output schema and minimal annotations, the description covers everything an agent needs: how to submit, which model id to pass, how to poll, what to read from the result, error modes, and when to defer to another tool set. 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 coverage is only partial, but the description meaningfully enriches parameters: it clarifies the i2v_id/t2v_id distinction, explains how image_url, image_urls, and reference_urls are treated for image/reference models, and notes that image_url switches to image-to-video for video generation. This adds critical semantics not obvious from 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 states a specific verb and resource: 'Generate media with ANY Media Forge model' and explicitly differentiates itself from the video_editor_* workflow tools. The scope is unambiguous and clearly distinct from sibling generation/list/poll 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?

It gives explicit when-to-use instructions: call list_models FIRST, pass an exact id, and choose i2v_id when supplying image_url versus t2v_id otherwise. It also names the alternative sibling workflow ('For reference + spoken dialogue, prefer the video_editor_* tools'), providing clear routing 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 only provide a title and destructiveHint=false, so the description carries most of the behavioral burden. It discloses deterministic behavior, track inference rules, image still behavior, default position, and that it returns clip_id. It does not explicitly mention auth or side effects, but the tool is non-destructive and the behavior is well covered. The description adds substantial value beyond the annotations, so a 4 is appropriate.

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

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

The description is a single, dense paragraph that front-loads the core purpose and key behavioral rules. Every sentence earns its place: it gives the action, the deterministic alternative, track inference, position default, and return value. No fluff 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?

Given the tool's moderate complexity (6 parameters, 2 required) and lacking output schema, the description covers all necessary aspects for correct invocation: what it does, how to use it, parameter defaults, and return value. Sibling tools like 'remove_clip' and 'reorder_clip' are distinct, and the integration with the timeline is clear. 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 coverage is low (17%), so the description must compensate, and it does. It explains the semantics of 'track' (which values map to which tracks), 'position' (default append, 0-based index), 'duration_sec' (only for image stills, default 1), and the role of asset_id and project_id. This adds meaning beyond the schema's bare parameter names.

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: to place an existing LIBRARY asset onto a video's timeline by id. It distinguishes itself from the sibling 'video_editor_instruct' by explicitly saying to use this instead of asking instruct to 'add a clip'. The verb 'place' and resource 'asset onto timeline' 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 explicit guidance on when to use this tool: when you have a library asset id and want to add it to the timeline. It also tells the agent to prefer this over 'instruct' for deterministic behavior. It explains track inference, position default, and image duration default, giving clear usage context without needing to inspect the 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?

Beyond the destructiveHint=false annotation, the description adds behavioral details: the asset is persistent and reusable, and importing it consumes no credits. It also explicitly requires that the URL be external and public. It does not describe validation failures or response shape, but for a simple import tool this is adequate.

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

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

A single, front-loaded sentence that states the action, object, purpose, and cost implication without filler. Every clause 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 three-parameter import tool with no output schema, the description covers the core behavior, the reason to use it, and a key operational detail (no credits). The main gaps are return behavior and the optional name parameter, which are minor for this tool.

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

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

With 0% schema description coverage, the description partially compensates by identifying url as an external public media URL and project_id as the target project. However, the optional name parameter is left undocumented, and there is no explicit mapping between the prose and each schema field.

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

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

The description opens with a specific verb and resource: 'Import an external public image/video/audio URL into a project' as a persistent reference asset. It clearly distinguishes this tool from siblings like upload_file or add_clip by framing it as a reusable reference for later generations, not as a media upload or timeline operation.

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 a clear usage context: bring an external public URL into a project so it can later be used as image_url / reference_image_urls. It does not explicitly name exclusions or alternative tools, but the stated use case is specific enough to guide an agent's selection.

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

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

Annotations provide only destructiveHint=false, so the description is responsible for additional behavioral context. It adds the return value 'Returns project_id,' which is a useful behavioral disclosure not present in the schema. However, it does not mention side effects (e.g., whether a project is persisted, whether it can be modified later, or any rate limits). This falls short of rich behavioral transparency, but the return-value note earns a middle score.

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

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

The description is very short, but this is under-specification rather than appropriate conciseness. It front-loads the action correctly, but with three parameters and zero schema descriptions, a single sentence is not appropriately sized. The lack of parameter guidance and usage context makes the brevity counterproductive, so it does not earn credit for efficiency.

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 3-parameter tool with no schema descriptions, no output schema, and only a bare annotations object, the description is incomplete. It explains the basic action and return value but lacks parameter semantics, usage conditions, and any indication of the project's lifecycle or integration with sibling tools. An agent would be uncertain about how to correctly invoke the tool with meaningful inputs.

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

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

Schema description coverage is 0%, so the description must compensate for explaining what parameters do. It does not mention 'name', 'description', or 'aspect_ratio' at all. The enum for aspect_ratio is visible in the schema, but the meaning of valid values (e.g., whether they define the canvas or output format) and any default behavior are omitted. This is a significant gap for a tool with three potentially optional parameters.

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

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

The description states a specific verb and resource: 'Create an AI Studio video project.' This clearly differentiates from siblings like video_editor_create_video (creating a video) and video_editor_add_clip (adding content). The resource 'video project' is distinct and the concise phrasing leaves no ambiguity about the tool's core action.

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 this tool versus alternatives. There are no context cues, prerequisites, or exclusions, such as 'use this before adding clips' or 'for an existing project, use video_editor_add_clip instead.' An agent must infer the appropriate usage solely from the tool name, which is insufficient for correct selection among 21 siblings.

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

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

Annotations only provide destructiveHint=falsehol; the description adds useful context that the operation reuses the project's shared media library and returns a video_id for downstream use. However, it does not disclose other operational details such as auth requirements, default behavior, or failure modes, and annotations do not cover those.

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 the primary action and distinguishing claim front-loaded. The second sentence adds return-value and next-step information without 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 3-param tool with no output schema, the description covers the essential invocation path: existing project, return artifact, and downstream instructions. It could mention defaults for optional parameters or side effects on the media library, but the core call is sufficiently complete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It clarifies project_id's role as an existing project and mentions video_id, but name and aspect_ratio are left entirely to the schema with no additional semantic guidance.

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

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

States a specific verb 'create', a clear object 'NEW video', and the scope 'inside an existing project'. The explicit note that no new project is needed distinguishes it from video_editor_create_project without requiring schema inspection.

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

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

Makes the prerequisite explicit ('existing project') and instructs the caller to pass the resulting video_id to instruct/export, which provides downstream routing. It does not explicitly list when to prefer an alternative like create_project, so exclusions are implied rather than stated.

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

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

The description adds that it returns video_url, which is useful behavioral context beyond the annotations. However, annotations only include destructiveHint=false, so the description carries significant burden; it does not disclose potential asynchronous execution (sibling job_status suggests this may exist), rate limits, or prerequisites, leaving gaps.

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

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

Two concise sentences with zero fluff. The main action is front-loaded, and the optional parameter behavior is stated efficiently. Every sentence earns its place.

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

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

Given no output schema, the return value note is helpful, but the description omits the fit parameter meaning, does not mention whether the export is synchronous or async (despite job_status existing), and lacks preconditions. For a tool with 3 parameters and one enum, this is not fully 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?

With schema description coverage at 0%, the description must compensate. It only explains video_id, not project_id or fit (the enum). This partial coverage adds some meaning but leaves the fit parameter and required project_id semantics undocumented.

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

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

The description uses a specific verb ('Stitch') and resource ('video's timeline into one MP4') while specifying features like transitions, audio mix, and burned-in captions. It also clarifies the optional video_id behavior, making it clearly distinct from sibling video_editor_export_captions.

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 guidance for the video_id parameter ('Pass video_id to export a specific video; omit to export the project's main video'), which is helpful context. However, it does not explicitly mention alternatives like video_editor_export_captions or state when not to use this tool, so it lacks explicit exclusions.

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

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

The annotations already declare readOnlyHint=true, and the description adds that the operation returns serialized text, which is useful. However, it does not disclose behaviors such as required project context, how video_id relates to project_id, or likely file naming/encoding details. With annotations covering the read-only safety profile, this is adequate but not 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 compact two-sentence definition with no filler. It front-loads the core action and output format, then adds the return value in a separate short sentence. Every word contributes.

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 no output schemahare, 0% schema description coverage, and no usage/exclusion guidance. An agent still cannot confidently infer whether video_id is optional, why project_id alone is required, or what 'serialized text' precisely looks like. The description is too thin for the tool's parameter ambiguity.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions SRT and VTT, which maps to the format enum, but it adds no meaningful explanation for the required project_id parameter or how video_id relates to it. The phrase 'a video's caption rows' weakly implies video_id, but the parameter roles remain underspecified.

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

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

The description names a specific verb ('Export'), resource ('a video's caption rows'), and concrete output ('a subtitle file (SRT or VTT)'). It also states the return behavior ('Returns the serialized text'), making the tool's purpose unmistakable and distinguishably different from sibling tools like video_editor_export and video_editor_upload_captions.

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 clearly implies when to use the tool: whenever caption rows need to be exported as an SRT or VTT subtitle file. However, it gives no explicit guidance about when not to use it or how it compares to related siblings such as video_editor_export or video_editor_upload_captions.

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 readOnlyHint=true, and the description aligns with that. It adds behavioral context by explaining the nature of the content ('persistent notes... style, characters, do/donts') and that it is read-only. This goes beyond the annotation without contradicting it, though it does not discuss errors or edge cases.

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

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

The description is two sentences with no filler. The primary purpose is front-loaded, and the optional parameter guidance is appended directly. Every word earns its place.

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

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

For a simple read-only tool with two parameters and no output schema, the description covers the main usage and parameter semantics adequately. It does not mention return format, but that is not required given the tool's simplicity and the absence of an output schema. Edge cases (e.g., missing context) are not discussed, but they are not essential for calling 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 0% schema description coverage, the description carries the burden for parameters. It explains that project_id identifies the project and video_id is optional for a specific video's context. This adds meaning beyond the bare type/name in the schema, though it does not provide format or example values.

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 ('Read') and resource ('creative context/brief for a project and optionally a specific video'), and clarifies the purpose ('persistent notes that steer the editor agent'). It clearly distinguishes from siblings like video_editor_set_context by emphasizing the read operation and what content is retrieved.

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

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

The description tells when to include video_id ('Pass video_id for that video's context too') and implies the primary use case is retrieving the creative brief. However, it does not explicitly mention alternatives (e.g., video_editor_set_context for updates) or when not to use this tool, leaving some inference to the agent.

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

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

Annotations already mark readOnlyHint=true, and the description adds meaningful behavioral details beyond that: it returns only structure/ids, provides scoped_video_id to identify the owning timeline, notes asset/clip ids live in the `id` field, and states URLs are absolute. This is useful context for interpreting the response even without an output schema. Minor gaps remain around pagination or error behavior, but they are not critical for a read-only getter.

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 no filler. The core scope is front-loaded, the critical alternative is named immediately, and the parameter guidance and return-field notes each earn their place. Nothing redundant.

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

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

For a read-only state tool with no output schema, the description covers enough: what is returned, how video_id scoping affects results, how to identify the owning timeline, and where to find IDs/URLs. It doesn't exhaustively describe all asset fields, but it gives an agent a safe mental model and points to the right sibling for deeper timeline data.

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

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

Schema description coverage is 0%, so the description carries the burden. It thoroughly explains video_id semantics, including recommended usage and the main-video fallback. project_id is required and inferable from 'Get a project's videos'; the description does not spell out its format or type, but the name and context make it clear. This is adequate compensation for a sparse 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 names a specific verb and resource combination: 'Get a project's videos, shared library assets, and a video's timeline clips.' It also directly differentiates this tool from video_editor_get_timeline by clarifying it returns structure/ids only, not durations/positions, so an agent can distinguish siblings without inspecting their 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?

It explicitly tells when to use the alternative (durations & positions go to video_editor_get_timeline) and gives concrete condition-based guidance for the optional video_id parameter: pass it to scope clips (recommended since clips are per-video), omit to use the main video. This removes ambiguity about invocation.

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

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

Beyond the readOnlyHint annotation, the description details the precise return structure (clips per track, captions, total duration) and confirms 'Free, read-only.' It adds substantive behavioral context about what the agent will receive, going beyond the annotation.

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 efficiently packed: it lists output fields first, then gives usage context, and ends with a behavioral note. No redundancy, and the critical info 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?

Given it's a read-only tool with no output schema, the description fully explains what is returned, when to use it, and how to proceed after. It covers all necessary details for 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 schema has 0% description coverage for parameters, and the description does not clarify the roles of video_id and project_id. It only says 'Read the FULL timeline of a video' without explaining which identifier is required or how they relate. This fails to compensate for the lack of schema documentation.

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

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

The description uses a specific verb ('Read') and resource ('FULL timeline'), enumerates the exact fields returned (clip_id, asset_id, duration_sec, etc.), and explicitly contrasts with get_state, making it unambiguous and distinct from siblings.

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

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

It states when to use this tool ('before editing') and explicitly names the alternative ('get_state does not include durations'), giving the agent a clear decision rule and post-use guidance ('Reference clips by clip_id afterwards').

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 set destructiveHint: true, so the description adds value by disclosing the RUN mode, the ability to generate assets, and the return field names. It does not contradict annotations and provides context beyond the safety flag.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. It includes usage and return info without wasted words, though it could benefit from clearer parameter coverage.

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 destructive, multi-purpose tool with four parameters and no output schema, the description is incomplete. It fails to explain project_id and image_urls, does not define what constitutes a valid instruction, and only lists return field names without 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 0%, so the description must compensate. It explains video_id (target a specific video or omit for main video) and implicitly describes instruction, but completely omits project_id and image_urls, leaving them unexplained.

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

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

The description clearly states the verb ('Send ONE instruction') and resource ('editor agent'), with examples of what it may do (generate media, add to timeline, subtitles). It distinguishes itself as a general instruction tool among specific siblings like video_editor_add_clip, though it doesn't name an explicit alternative.

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 ('Call repeatedly to build the video') and explains video_id targeting, but it doesn't explicitly state when to use this tool versus the specific sibling tools (e.g., add_clip, set_transition). No exclusions or conditions are provided.

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, so the read-only safety profile is covered. The description adds scoping context ('the user's' projects) but does not disclose additional behavioral concerns such as authentication needs or response behavior. This is acceptable but not a major value-add beyond the annotation.

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 contains no filler and states the core function directly. For a zero-parameter read-only tool, this is an appropriately concise definition.

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 low-complexity with no parameters and read-only annotations, so the description is nearly sufficient. The main gap is the missing relationship to video_editor_list_videos; the description does not clarify what distinguishes an 'AI Studio project' from a video, leaving slight potential for misuse.

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 zero parameters and 100% schema description coverage. With no parameters to document, the description adds appropriate context by specifying which projects are listed; there is nothing left unexplained.

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

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

The description states a clear action and resource: 'List the user's AI Studio projects.' It distinguishes from the sibling video_editor_list_videos by naming projects as the target, though the title's 'List video projects' phrasing creates minor ambiguity about whether video projects and AI Studio projects are the same entity.

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 for when to use this tool versus alternatives such as video_editor_list_videos or video_editor_get_state. The description does not state exclusions or conditions, so an agent must infer which listing tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful domain context beyond that: a project holds N videos that share the same media library, and this tool returns identifiers targeted by other operations. This goes beyond the annotation without contradicting it.

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

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

Two sentences, no filler. The first sentence states the action and resource; the second adds the key domain fact and downstream use. Every word earns its place.

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

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

For a simple read-only list operation with one required parameter and no output schema, the description supplies enough: what is listed, the project relationship, and how the returned video_id will be used. It does not mention how to obtain a project_id, but sibling context and common sense make this a minor gap.

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

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

There is only one parameter, project_id, and the schema has no description. The description compensates by framing project_id as the identifier of the project whose videos are listed, and by explaining the output's purpose. Format details are not given, but the parameter is self-explanatory in 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?

The description uses a specific verb ('List') and a precise resource ('videos inside a project'), which clearly distinguishes it from sibling tools like list_projects or list_models. It also states the intended downstream use of the returned video_id, making the purpose unmistakable.

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

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

The description gives clear context: use this to see a project's videos and obtain a video_id for instruct/export operations. It does not explicitly name alternatives or exclusions (e.g., when to use list_projects instead), but the intended use case is clear enough for an agent to select it appropriately.

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 destructiveHint annotation already signals mutation, and the description adds valuable behavioral context by noting the operation is deterministic and requires no full rebuild. This goes beyond the annotation without contradicting it.

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 core operation and the key replacement tip are front-loaded, making the description easy to scan and act on.

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 two-parameter destructive operation, the description covers what the tool does, the identifier used, the deterministic behavior, and the follow-up workflow for replacement. No output schema is present, so no return-value documentation is required.

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

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

Schema description coverage is 0%, so the description must compensate for parameter documentation. It clarifies that clip_id identifies the clip to remove, but project_id is not explicitly described. However, both parameter names are self-explanatory in 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?

The description states a specific action ('Remove a clip from a timeline') and identifies the key identifier (clip_id), with a concrete use-case example ('a bad take'). It is clearly distinguishable from siblings like video_editor_add_clip and video_editor_reorder_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 provides explicit guidance for the replacement workflow: remove, then add_clip the new asset at the same position. It does not enumerate alternative tools for other scenarios, but the primary usage context is made clear.

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

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

The annotations already mark the operation as destructive, and the description adds valuable detail by explaining that other clips on the track are renumbered. It also clarifies track scope and the video_id disambiguation behavior. This goes beyond the structured annotation without contradicting it.

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 deliver the core action, the side effect on other clips, and the optional disambiguating parameter. There is no filler or repetition, 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?

For a mutating operation with no output schema, the description covers the primary action, side effects, and optional video_id behavior. Minor gaps remain around index bounds and what the response looks like, but the essential calling context is present.

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

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

Schema description coverage is 0%, and while the description explains that to_index is a 0-based index and video_id defaults to the main video, it does not clarify clip_id or project_id semantics beyond their names. It compensates partially but not fully for the absent schema 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 starts with a specific verb and resource: 'Move a clip to a new 0-based index on its track.' It clearly distinguishes this from sibling tools like add or remove by emphasizing repositioning within an existing track.

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 operating context, such as renumbering and the optional video_id default, but it never explicitly compares this tool to alternatives like video_editor_add_clip or video_editor_remove_clip. It is usable, but leaves the agent to infer when reorder is the right choice.

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

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

Beyond the annotations (only destructiveHint=false), the description discloses the full behavioral contract: the returned object shape, the requirement to HTTP PUT raw bytes, the matching Content-Type header, and the follow-up registration steps. It also clarifies key traits like 'no size limit' and 'no base64,' which are not visible from the schema or annotations. This is exemplary transparency for a tool with minimal annotation coverage.

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

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

The description is compact and front-loaded with the core purpose and return format, then gives a clear numbered sequence and an explicit alternative. Every sentence adds information; there is no filler or repetition of the schema.

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 no output schema, the description explicitly lists the returned keys and all follow-up steps needed to use the uploaded file. It covers the complete workflow, the alternative tool, and the practical size threshold for selection. Nothing essential is missing for an agent to invoke and integrate 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 coverage is 100%, so the baseline is 3. The description adds extra meaning by saying to call with filename + content_type and by specifying that the content_type must be reused in the HTTP PUT header. This goes slightly beyond the schema's MIME-type example, earning a 4.

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 and resource: getting a presigned upload URL for a large local file. It explicitly distinguishes itself from the sibling video_editor_upload_file by referencing size limits and base64, and it names the returned fields. An agent can confidently identify what this tool does without ambiguity.

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 explicit when-to-use guidance: use this instead of video_editor_upload_file whenever a file may exceed a few MB. It also provides a numbered workflow connecting this tool to video_editor_add_reference and video_editor_add_clip, so the agent knows the expected sequence. This is strong routing and usage context.

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 destructiveHint=true, and the description adds the default behavior (replace) and the append option, which is critical for the agent to understand side effects. It does not mention potential overwrite of prior context explicitly, but 'replaces it' is implied and the append distinction covers the main behavioral nuance.

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

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

Two sentences, no filler. The purpose is stated first, followed by the two conditional behaviors. Every word adds value.

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

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

For a setter tool with no output schema, the description covers all essential operational details: the two scope modes, the append flag, and the fact that the context is read every turn. The destructive nature is already captured in annotations. 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 coverage is 0%, so the description must compensate. It explains the roles of video_id (scope selector), append (add vs replace), and context (the content being set). project_id is not explicitly described but is self-evident from the name and required field. The description adds significant meaning beyond the bare 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 states a specific verb ('Set') and resource ('creative context/brief'), and clearly distinguishes two scopes (video-specific vs project-wide) and append vs replace behavior. This differentiates it from sibling tools like video_editor_get_context and video_editor_instruct.

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

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

It gives explicit guidance on when to include video_id (to set that video's context) versus omitting it (project-wide context), and clarifies append:true semantics. It does not explicitly name alternative tools or state when not to use it, but the parameter-level guidance is clear enough for an agent to select the correct mode.

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

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

The annotation already declares destructiveHint: true. The description adds behavioral details: it explains that 'none' clears the transition and that the exporter runs an ffmpeg xfade. This goes beyond the annotation without contradicting it, providing useful context about the effect and mechanism.

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

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

The description is two sentences, front-loads the main action, and includes necessary details without any fluff. It is well-structured and 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 description covers the main action and how to reference the clip, and mentions the exporter behavior. However, it does not describe the return value or error handling, which is important given there is no output schema and the tool is destructive. It is adequate but not fully 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?

The description adds meaning for clip_id by specifying its source (from get_timeline) and reinforces the 'none' value for type. It does not add anything for project_id or duration, though duration already has a schema description. With 50% schema coverage, the description partially compensates but not fully.

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

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

The description clearly states the action (set or clear transition) on a specific resource (clip's out-edge), explains the blend into the next clip, and mentions the ffmpeg xfade mechanism. It also clarifies the 'none' value for clearing. This is specific and distinguishes it from sibling tools like add/remove/reorder 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?

It provides context that clip_id comes from get_timeline, which is a useful prerequisite. However, it does not explicitly mention alternatives or when not to use this tool. The purpose is clear enough that an agent can infer when to use it, but there is no explicit exclusion.

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 the destructive behavior ('Replaces existing captions unless append=true'), which aligns with the destructiveHint annotation. It also explains the rendering differences between 'static', 'wordpop', and 'karaoke', and the parsing of cues into timed rows. This goes beyond what annotations alone provide, offering useful behavioral context without contradiction.

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

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

The description is three sentences long and front-loaded with the core purpose. Each sentence adds meaningful detail: input methods, rendering modes, and replacement behavior. It is structured logically and avoids unnecessary fluff, though it could be slightly more concise in the rendering explanation.

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 8 parameters, including enums and a destructive flag, and no output schema. The description covers the main functionality, input methods, render modes, and append behavior, but it omits style semantics and the roles of video_id and project_id. While it addresses the most critical aspects, the missing parameter details and lack of return-value guidance leave it incomplete for an agent to fully understand all edge cases.

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 must compensate. It clarifies srt and asset_id (inline vs. asset), explains render modes in detail, and clarifies append behavior. However, it does not explain the style parameter (which has enums), nor video_id and project_id (though project_id is required). The description adds value for key parameters but leaves others undocumented, so it partially compensates for the low 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 a specific action: 'Import subtitles (SRT or VTT) onto a video as caption rows that burn in on export.' It names the resource (subtitles onto a video) and the verb (import), making the tool's purpose unambiguous. It does not explicitly differentiate from sibling tools like video_editor_export_captions, but the purpose is specific enough that an agent can infer when to use it.

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

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

The description explains two input methods ('Pass the text inline via srt, or an already-uploaded subtitle asset_id') and notes the default behavior ('Replaces existing captions unless append=true'). However, it does not explicitly state when to use this tool over alternatives (e.g., video_editor_upload_file or video_editor_export_captions). The guidance is contextual but not comparative, so it falls short of a strong usage guideline.

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

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

Annotations only provide a title and destructiveHint=false, so the description carries the behavioral burden. It adds valuable context: base64 inflation (~33%), the ~6 MB request cap, the 'Parse error' failure mode, persistence of the asset, @-mentionability, and that no credits are consumed. There is 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 front-loaded with the core purpose and the most important constraint. Every sentence earns its place: size limit, failure mode, alternative workflow, persistence result, and credit cost. It is dense but not padded.

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

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

For a tool with no output schema and minimal annotations, the description covers invocation needs well: required inputs, size constraint, failure behavior, alternative route, and post-upload outcome. The only notable gap is the absence of any hint about what the successful response returns, but the tool's role is still unambiguous.

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 80%, so the schema already documents most parameters. The description adds practical meaning beyond the schema by clarifying content_base64 as raw file bytes and reinforcing the ~6 MB size limit with the base64 inflation explanation. It does not detail project_id or the optional name, but those are adequately covered by 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 states a specific action and resource: upload a small raw file into a project library via base64-encoded bytes. It also distinguishes itself from the larger-file workflow by naming the alternative tools to use instead. The result is clear: the file becomes a persistent, @-mentionable asset.

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 explicit when-to-use guidance: use this tool for files under ~6 MB, and use video_editor_request_upload → PUT → video_editor_add_reference for anything bigger. It also notes the platform cap and the failure mode, so an agent can route correctly before invoking.

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