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

With no annotations, the description carries the transparency burden. It discloses that the tool uploads the product image and creates a client review link, which are notable side effects, and mentions credential requirements. However, it does not cover reversibility, data retention, failure modes, or rate limits, leaving some behavioral 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?

Three sentences, each earning its place: purpose, workflow, and prerequisite. It is front-loaded with the main action and contains no fluff 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 description explains the workflow and prerequisite well, but with no output schema it does not clarify what the tool returns (e.g., the review link URL or a status). Since this is an external API integration with multiple side effects, the missing output info is a notable gap.

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

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

Schema coverage is 100% so all parameters already have descriptions. The description reinforces that prompt is a styling prompt and product_image_path is the image source, but adds no new parameter-specific detail beyond what the schema 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 'Generate image ad variants from a product photo using Higgsfield AI' and outlines the full pipeline: upload, generate variants with prompt, create a client review link carousel. This distinguishes it from sibling tools like create_review_link and prepare_product_asset by focusing on the generation workflow.

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

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

The description implies usage for generating ad variants from a product photo and notes the prerequisite of Higgsfield credentials. However, it does not explicitly compare to alternatives or state when not to use the tool, leaving usage guidance largely implicit.

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

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

With no annotations, the description carries full responsibility for disclosing side effects. It does not mention whether cancellation is irreversible, whether it only applies to pending posts, or what happens to the post after cancellation. The lack of such details leaves behavioral expectations unclear.

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 core action and operand. It wastes no words and is appropriately 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?

This is a mutation tool with no annotations and no output schema. The description is minimal and does not explain the effects, success criteria, or any limitations. Given its mutating nature, the lack of contextual detail leaves the description incomplete for an agent to fully understand the tool's behavior.

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% coverage for the post_id parameter, so the description adds no new semantic value. It repeats 'by ID' without adding format, source, or validation details, but since the schema is complete, 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 action (cancel) and the resource (a pending scheduled post), and it distinguishes itself from sibling tools like schedule_post and publish_now. The verb is 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 does not provide guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It only states the basic function, leaving the agent to infer when cancellation 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only says 'Check whether...' which is a read-only implication, but it does not explicitly state that no side effects occur, nor does it mention error behavior, authentication requirements, or response format. This is minimal beyond 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 two sentences, with the first stating the purpose and the second providing a usage example. Every sentence earns its place, and there is no redundant or extraneous information. It is front-loaded and easy to parse.

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

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

The tool is simple: one parameter, no output schema, and no annotations. The description provides the essential information for invocation (token extraction) and implies the outcome (approved or changes requested). However, since there is no output schema, the description does not specify the return format, which is a minor gap. Overall, it is sufficient for basic use.

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 describes the token as 'The 12-character review token from the review URL.' The description adds value by giving a concrete example and clarifying how to extract it from the URL, which goes beyond the schema definition. This is helpful but not transformative, so a score of 4 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 purpose: 'Check whether a client has approved or requested changes on a review link.' This uses a specific verb ('Check') and a clear resource ('review link'), and distinguishes it from sibling tools like create_review_link. The action is 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 usage guidance by instructing to pass the token from the URL and gives an example. However, it does not explicitly state when to use this tool versus alternatives or any exclusions. The 'when' is implied by the purpose (checking review status) but not spelled out.

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

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

With no annotations, the description carries the full burden, and it does well: it explains the typing animation, 3D camera pan, return of a finished MP4 path, and how to use the output. It doesn't mention side effects, but for a rendering tool this is acceptable.

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?

It's slightly longer than the briefest possible, but every sentence adds value: purpose, use case, effects, styles, and output usage. It's front-loaded with the core action and maintains a logical flow.

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

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

Given the tool's complexity (8 parameters, nested object, no output schema), the description is remarkably complete. It covers what the tool does, the visual output, all enum choices, defaults, and downstream integration points. No significant gap remains.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining what each effect looks like (e.g., billboard_flip 'words fly from Z-depth and snap into place') and how font_size and duration_sec auto-scale, which goes beyond the schema's terse property 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 opens with a specific verb+resource: 'Render a standalone cinematic typing-animation video.' It clearly distinguishes itself from siblings by explaining the output feeds into publish_now or create_video_assembly, and it describes the animation effects and styles in detail.

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 a clear use case ('great for explainer intros that visually demo what a user types into the prompt') and describes the three effects and styles to guide selection. It doesn't explicitly name alternatives to avoid, but the context with sibling tools is sufficient.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It explains the no-account-required client experience, the Approve/Request Changes options, and that a URL is returned. This is substantial added context, though it stops short of mentioning side effects like link expiration mechanics or prerequisites beyond assembling the video.

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

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

Two sentences deliver a complete workflow: trigger condition, steps, client interaction, and the returned artifact. Information is front-loaded and every clause earns its place without redundancy.

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

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

For a tool with no output schema, the description clearly states the return value ('Returns the review URL'). It covers the client-facing flow and the setup step, which is sufficient for basic usage. However, it omits details like what happens when the video isn't ready, link expiration defaults (though in schema), or how to check review status, which is delegated to a sibling tool and need not be in this 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 description adds marginal value by linking output_path to create_video_assembly and noting that metadata is 'shown in the review room', but does not elaborate on parameter formats or behaviors that the schema already documents. It does not compensate beyond the schema's existing 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 uses a specific verb ('generate') and resource ('private shareable review link') with a clear trigger condition ('After assembling a video'). It clearly distinguishes from sibling tools by describing the client-facing review flow (Preview Room, Approve/Request Changes), which is unique among the listed 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 'After assembling a video' establishes a clear sequencing context, and the note that output_path should be 'the path returned by create_video_assembly' explicitly ties usage to a prior tool. However, it does not mention when not to use this tool (e.g., for internal review, or if public sharing is needed), 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?

With no annotations, the description carries the full burden and excels: it discloses the local pipeline, transcription, subject-aware focal point detection, Ken Burns motion, audio mixing, automatic folder expansion, style_ref inference, and return path. It also mentions the hosted mode uploads to the user's account and the TWELVE_LABS_API_KEY 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 long but front-loaded with the core purpose, then systematically covers process, inputs, and output. Every sentence adds specific information (e.g., focal point, audio mix, destination modes). It could be slightly tightened, but it remains efficient for a 12-parameter tool.

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

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

Given the tool's high complexity (12 parameters, 5 enums, multiple modes) and no output schema, the description is remarkably complete: it covers local vs hosted, style inference, B-roll sources, and the final MP4 path. It doesn't explain failure modes or environment prerequisites, but the core operational flow is fully described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the A-roll/B-roll relationship, style_ref auto-inference ('so you don't have to describe them'), folder expansion, and that B-roll audio becomes a 'low faded bed'. This contextualizes parameters without duplicating their 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 opens with a specific verb+resource: 'Turn an A-roll talking-head/performance clip into a polished vertical (9:16) short by editing in B-roll cutaways.' It clearly distinguishes from siblings like assemble_image_ad or create_kinetic_text by describing the full video assembly workflow.

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

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

The description gives clear context for when to use it (making a short from A-roll with B-roll, local pipeline, publishes via publish_now/schedule_post). It does not explicitly name alternatives or state when not to use, but the usage context is strong enough for an agent to choose it over 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?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the destructive nature ('delete'/'removed') and the surprising bulk behavior of removing all rules sharing the keyword, which is valuable beyond the tool name alone.

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 states the core action and the key edge case. Every word earns its place, with 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?

For a one-parameter delete tool with no output schema, the description fully covers the action, the identifying key, and the mass-deletion side effect. It is complete and self-contained.

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 fully documents the only parameter 'keyword' with a matching description. The tool description adds no further parameter semantics, so the baseline 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 ('Delete') and names the resource ('keyword→link rule') with the deletion key ('by its keyword'). This clearly distinguishes it from sibling tools like set_keyword_link and list_keyword_links.

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 implies when to use the tool: when you want to delete keyword-link rules by keyword. It adds the important caveat about multiple rules sharing a keyword being removed, but does not explicitly mention alternatives or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention any side effects, output format, platform-specific limits, or whether it requires an active connection (despite sibling tools like list_connections). The behavior beyond 'generate' is opaque.

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 or repetition. Every word contributes to conveying the tool's function.

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

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

The tool is simple with two well-documented parameters, but the description does not mention the return structure (e.g., how captions and hashtags are returned) or how this fits into the larger workflow (e.g., that it only generates and does not publish). It is minimally viable but leaves some gaps.

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

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

Schema coverage is 100% and both parameters have clear descriptions ('Video or content title/description.' and 'Target platform.'). The tool description adds no additional parameter meaning, so the baseline 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 ('Generate') and identifies the resource ('an AI caption and hashtags') plus the scope ('for a post on a specific platform'). This clearly distinguishes it from sibling tools like swap_caption_style, which modifies existing 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 description provides clear context for when to use the tool: when generating a caption and hashtags for a specific platform. It does not explicitly mention when not to use it or name alternatives, but the context 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?

With no annotations, the description discloses important behaviors: caching and idempotency ('re-running skips already-indexed files'), return type (index_id), and environment requirement (TWELVE_LABS_API_KEY). This goes beyond the schema and helps the agent understand side effects and prerequisites. It does not mention external side effects (creating an index in Twelve Labs) but is adequately 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?

Three sentences each earn their place: purpose, usage/caching behavior, and return value/prerequisite. No fluff, front-loaded with the core action. Ideal 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?

Given the tool's simplicity (2 params, no output schema), the description fully covers the essential context: what it does, when to call, what it returns, how to use the result, and the required environment variable. It is complete for the 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?

Schema coverage is 100% for both parameters, so the schema already documents their meanings. The description adds contextual value by explaining the purpose of the folder and the returned index_id, but does not add new parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific action ('Index a local folder of screen recordings and OBS videos with Twelve Labs') and its purpose ('so they can be searched semantically inside create_video_assembly'). This clearly distinguishes it from sibling tools like suggest_clips or create_video_assembly, which consume the index rather than create 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?

Provides explicit usage guidance: 'Call this once per folder' and explains re-run behavior ('indexing is cached, so re-running skips already-indexed files'). It also tells the user what to do with the return value (pass as explainer_index_id in create_video_assembly) and mentions the API key prerequisite. It slightly lacks explicit exclusions or alternative tools, but the guidance 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?

No annotations are provided, so the description must carry the behavioral disclosure. It discloses that the tool lists connected accounts and returns each account's connection ID, covering the primary behavior. It does not mention auth prerequisites or error conditions, but for a simple list operation with no parameters, 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?

Two sentences, front-loaded with the core action in the first sentence and usage guidance in the second. 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?

The description covers what it does, what it returns, and how to use the result. Given the simple nature (zero params, no output schema) and the sibling tool context, the description is fully sufficient.

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 no parameters (empty schema), so the baseline for this dimension is 4. The description adds value by explaining how the output (connection ID) is used in other tools' account_ids parameter, but this is not about its own 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 uses the specific verb 'List' and identifies the resource as 'your connected social media accounts' with examples (TikTok, Instagram, YouTube). It clearly differentiates itself from publishing/scheduling siblings by explaining it returns connection IDs.

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 the user to pass the returned IDs to publish_now, schedule_post, and send_to_drafts via the account_ids parameter, and notes the specific condition 'when you have multiple accounts on the same platform.' This provides clear usage context and direct reference to alternative/succeeding 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?

With no annotations, the description is the sole source of behavioral information. It communicates a read-only action via 'List' but doesn't disclose details such as ordering, pagination, or whether it returns all rules at once. For a simple list tool this is adequate but not enriching.

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 words. Perfectly 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 tool is simple (no params, no output schema), and the description states exactly what is listed. It doesn't mention output format or details, but for this simple operation the description is largely 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 schema has zero parameters, so no parameter information is needed. The description doesn't add parameter semantics, but the baseline for 0-param tools is 4, which is appropriate here.

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

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

The description uses the specific verb 'List' with a clear resource ('keyword→link DM-automation rules'), distinguishing it from sibling tools like set_keyword_link and delete_keyword_link. It clearly states the 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?

No explicit when-to-use or alternative guidance is provided. Usage is implied by the verb 'List'—it's the read operation for keyword link rules—but there's no mention of when to prefer it over other tools or 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?

No annotations are provided, so the description carries the burden. 'List' implies a read-only operation, and 'your posts' indicates scope, including ownership. However, it does not disclose behavior like result ordering, pagination, or what happens when no posts exist, which could be useful context for this type of tool.

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

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

The description is a single, front-loaded clause with no wasted words. It is concise and immediately conveys the action and target. However, the mention of 'scheduled' instead of the schema's 'pending' is a minor accuracy issue that slightly detracts.

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 tool with one optional parameter and no output schema, the description provides a basic outline. It does not enumerate all statuses (leaving out 'pending' and 'cancelled') nor explain the return format. Given the absence of annotations and output schema, more detail would be helpful, but the tool's complexity is low.

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

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

Schema coverage is 100%, so baseline is 3, but the description introduces confusion: 'scheduled' is not an enum value (the schema uses 'pending'), and it omits 'cancelled' and 'pending'. This misalignment reduces clarity beyond what the schema already provides, effectively harming parameter understanding.

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

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

The description states 'List your scheduled, published, or failed posts,' which clearly identifies the verb (list), resource (posts), and scope (your scheduled/published/failed). It distinguishes from siblings like 'list_connections' and 'publish_now'. However, it omits the 'cancelled' and 'pending' statuses from the schema, so it's not fully exhaustive.

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 listing posts, but does not mention alternatives or when not to use it. The schema's parameter description ('Omit to list all posts') adds some usage guidance, but there is no explicit comparison to sibling tools like 'list_connections' or 'cancel_post'.

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 no annotations, the description carries full burden. It discloses the upload side effect and return value, but does not mention authentication, what verification entails, or failure behavior. It provides a basic sense of behavior but leaves gaps for an agent.

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, information-dense sentence that efficiently lists the steps without filler. It is front-loaded with the first action and 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 one parameter and no output schema, the description covers the main workflow steps and explicitly states the return value (stable cloud URL). It does not explain verification specifics or error states, but for a simple preparation tool it is reasonably complete.

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

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

Schema description coverage is 100% for the single parameter, and the description repeats the same information (local path/public URL) without adding extra detail such as accepted formats or size constraints. The schema is sufficient, so the description adds little value.

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 sequence of actions (download, verify, upload) and the exact resource (product image) and output (stable cloud URL). It distinguishes itself from sibling tools by anchoring to 'Higgsfield image ad generation', making its role in the pipeline 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 conveys clear context: this tool is for preparing a product asset for Higgsfield image ads. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to select it over siblings like assemble_image_ad or publish 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?

With no annotations provided, the description carries the full burden and does so well. It discloses the conversion to a 1080×1920 MP4, the draft vs. publish behavior, the audio baking, the ffmpeg dependency, and the output type (single video post). It also explains platform-specific API limitations, providing transparency beyond basic 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 three sentences long, each earning its place. The first sentence front-loads the core action, the second gives detailed usage cases, and the third covers prerequisites and outcome. 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 complexity (8 parameters, no output schema), the description provides enough context for an agent to decide when to invoke it: it covers the main use cases, output type, and a key prerequisite. The schema handles parameter details, and the description's statement about the return type compensates for the lack of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant new parameter-level meaning beyond the schema; it mentions the resolution and ffmpeg requirement but leaves detailed parameter semantics to the schema. The 'audio_path' and 'mode' behaviors are already described in the schema, so the description adds minimal value here.

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: 'Convert a folder of images into a 1080×1920 slideshow MP4 and publish it.' It also distinguishes this from a standard carousel post by noting 'Returns a single video post, not a carousel post.' This makes the purpose specific and differentiates it from sibling tools like publish_now or publish_to_meta.

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 lists two scenarios for using this tool: (a) when a TikTok DRAFT is wanted (due to TikTok's API rejecting photo carousels for drafts) and (b) when attaching a specific MP3 to the carousel (since TikTok/IG don't allow audio on photo posts). It also notes a prerequisite ('Requires ffmpeg installed locally'), giving clear when-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?

No annotations are provided, so the description bears the full burden. It discloses immediate publishing, folder-to-carousel behavior, and account targeting, which is useful. However, it does not mention that publishing is irreversible/live, authentication requirements, or what happens to uploaded files, leaving some behavioral gaps for a mutation tool.

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

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

The description is three concise sentences, front-loaded with the core action, then adding carousel behavior and account targeting. Every sentence carries useful information with no filler or repetition of the tool name.

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 and full schema coverage, the description adequately explains purpose, platforms, file/folder input, and account selection. It does not explain the return value or error cases, but with no output schema, this is a minor gap for an otherwise clear publish action.

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

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

The input schema covers 100% of parameters with descriptive text, so the baseline is 3. The description largely reiterates schema details, such as folder paths for carousels and account_ids precedence. It adds little beyond the schema, mainly cross-referencing list_connections, which is already in 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 clearly states the verb and resource: 'Upload local file(s) and publish immediately' to TikTok, Instagram, and/or YouTube. It also distinguishes itself from sibling tools by emphasizing immediacy, unlike schedule_post or send_to_drafts, and by describing the carousel behavior for 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?

It provides explicit guidance on when to use account_ids vs platforms: 'Use account_ids (from list_connections) to target a specific account when you have multiple accounts on the same platform.' It does not explicitly mention exclusions or alternatives like scheduled posting, but the 'immediately' phrasing and sibling tool names imply the 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but does not disclose that publishing is immediate and irreversible, may require authenticated connections, or what the result/confirmation looks like. For a mutation tool, this is a significant gap.

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: the first states the core function, the second gives the usage trigger. There is no fluff, and the essential 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?

While the schema documents parameters well, the description omits critical behavioral context for a publishing tool: side effects (immediate public post, irreversibility), prerequisites (connected accounts), and expected return value. This makes the description incomplete for an agent to safely anticipate the tool's outcomes.

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 covers 100% of parameters with clear descriptions for media_url, platforms, and caption. The description adds workflow context (approved variant) but does not add parameter-level meaning beyond the schema. The baseline of 3 is appropriate.

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

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

The description clearly states the action (publish), the resource (image or video), and the target platforms (Instagram and/or Facebook). It also ties the tool to a specific workflow step (after client approval from assemble_image_ad), distinguishing it from scheduling or drafting 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 provides an explicit when-to-use condition: 'Use after a client approves an image ad variant from assemble_image_ad.' This gives clear context. However, it does not mention when not to use the tool or compare it with immediate siblings like publish_now or schedule_post, so it stops short of a 5.

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

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

With no annotations, the description discloses key behaviors: A-roll trimming, rest shifting, cached B-roll reuse, re-render, and streaming into the editor. It does not explicitly mention rollback or destructive warnings, but the 'cut out' language implies irreversibility.

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 pack the purpose, examples, and effects with no filler. The description is front-loaded and every clause 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?

Given low complexity, full schema coverage, and no output schema, the description covers purpose, behavior, and output effect ('streams into the editor'). It is sufficiently complete for an agent to select and 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?

The schema already covers all parameters at 100%. The description adds meaning by showing [from_sec, to_sec] as a contiguous span and giving examples, while job_id is left to the schema's own description.

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

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

The description clearly identifies a specific operation: removing an internal time span from a Swap & Refine video, with concrete examples. It distinguishes itself from edge-trimming by explaining the backbone A-roll is trimmed and the rest shifts up.

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 clear use cases ('duplicated opening sentence or dead pause'), indicating when removal is appropriate. It does not explicitly name alternatives like trim_clip, but the context is sufficient.

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

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

With no annotations, the description carries the full burden. It discloses cost ('Costs a render/credits'), async behavior ('Returns immediately'), effects ('Captions, hook, overlays and motion are applied here'), and where results land ('finished preview lands on the project'). This exceeds minimal expectations, though it omits failure modes or whether previous renders are overwritten.

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 efficient sentences, front-loaded with the core action. Every clause adds useful information (workflow position, effects, cost, async behavior, next steps) with zero 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?

The tool has a single optional param and no output schema, so the description adequately covers purpose, workflow sequence, cost, async behavior, and the result location. This is sufficient context for an agent to invoke it correctly without additional documentation.

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

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

Schema coverage is 100% for the single job_id parameter, which already includes the semantics ('Omit to use VIRALSPIN_HOSTED_JOB_ID'). The description adds nothing specific beyond referring to the 'current hosted Swap & Refine timeline', which is redundant with 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?

The description explicitly states the tool's action: 'Bake the current hosted Swap & Refine timeline into a final MP4' — a specific verb, resource, and output format. It also distinguishes itself from siblings by calling it 'the ONE cloud render after a batch of instant timeline edits' and clarifies it is not a publish step.

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 sequencing: 'after a batch of instant timeline edits (swap_clip / trim_clip / reorder_scenes)' and 'then publish with publish_now or schedule_post'. This tells the agent when to use it and what comes next. However, it does not explicitly state when not to use it or name alternatives beyond the publish 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It does mention that omitted ids are dropped, which is helpful. However, it misleadingly says 'apply it and re-render' without noting that re-rendering is optional and costs credits (as specified in the schema). This could cause an agent to assume re-render always happens. It also omits details about the default job_id and the timeline-only edit mode.

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 tool's purpose, then clear usage instructions. Every phrase earns its place; no fluff or repetition of schema content.

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 two main modes (list and reorder) and mentions the return format for listing (id + label + time). However, it misses critical context about the `render` parameter (cost and default false) and the optional `job_id` default. These gaps make it incomplete for a mutation tool with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no meaningful parameter semantics beyond the schema; it repeats the `order` parameter's behavior (omitted ids are removed) and does not discuss `job_id` or `render` at all. The schema already 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 states a specific action ('See or reorder') with a clear resource (the A-roll's backbone scenes in a Swap & Refine project). It clearly distinguishes the tool's dual list/apply functionality from sibling tools like swap_clip and trim_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 usage instructions: call with no `order` to list, call with `order` to apply. It implies the context but does not explicitly name alternatives or exclusion criteria. Still, the guidance is clear enough to select this tool over 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?

No annotations are provided, so the description must carry the safety/behavioral burden. It only describes the basic upload-and-schedule behavior and the carousel folder path, which largely duplicates schema info. No side effects, prerequisites, or error behavior are disclosed.

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

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

Two sentences, front-loaded with purpose, and no redundant wording.

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

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

The description gives the core action and a key nuance (folder → carousel), but for a 7-parameter tool with no output schema, it omits any mention of return values, failure behavior, or what occurs when optional parameters are omitted.

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 does not add parameter-specific information 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 the main purpose clearly: upload local files and schedule a post for future time. Distinguishes from siblings like publish_now (immediate) and send_to_drafts.

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?

Clear context that this is for future-time scheduling, which differentiates it from immediate publishing tools. However, no explicit exclusions or alternatives are named.

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 no annotations provided, the description carries the transparency burden. It discloses key behavioral traits: drafts are for mobile finishing, Instagram is not supported and will error, and folder paths trigger carousel drafts. It does not cover auth requirements or reversibility, but the core side effects are clearly stated.

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, front-loaded with the primary action and purpose, then adds platform-specific caveats and carousel behavior. Every sentence earns its place without redundancy or fluff.

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 tool's purpose, use case, platform limitations, and folder handling. Given the absence of an output schema, return value details are not required. It does not mention auth preconditions, but for a drafts-sending tool, the provided information is largely sufficient.

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 input schema already explains all parameters in detail, including paths behavior and caption caveats. The description adds some extra context (e.g., folder → carousel, Instagram error) but largely repeats what the schema already provides, meeting the baseline 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 action: 'Upload local file(s) and send to the platform's drafts', with specific destination details (TikTok inbox / YouTube as private). It distinguishes itself from sibling tools like publish_now and schedule_post by focusing on drafts for later mobile finishing.

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 context for when to use this tool: 'useful when they want to add licensed music or polish before publishing'. It also gives a clear when-not via the Instagram limitation, noting that Instagram returns an error. However, it does not explicitly name alternative tools for immediate publishing, so it falls just short of a perfect score.

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 no annotations, the description carries the full burden. It transparently discloses delivery activation timing, upsert behavior, and platform limitations ('Only Instagram delivers today'). It doesn't cover auth or rate limits, but the key behavioral traits are well communicated.

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, each earning its place. It front-loads the purpose, then adds essential operational details without fluff or repetition of schema content.

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

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

Given the tool's complexity (6 params, no output schema, no annotations), the description covers the most critical aspects: function, update behavior, scope, and platform limitation. It could mention return values or error cases, but overall it's sufficiently complete for an AI 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?

Although schema coverage is 100%, the description adds semantic value by explaining the media_id field (global vs single post) and the platform limitation. It also highlights the composite scope for the upsert behavior, which is not evident from the schema alone.

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 clear verb and resource: 'Map a keyword to a resource/destination link for DM automation.' This directly states the tool's function and distinguishes it from sibling tools like list_keyword_links and delete_keyword_link, which are read and delete operations respectively.

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 useful context on when to use this tool, including re-running for updates and the distinction between global and per-post rules via media_id. It doesn't explicitly name alternatives, but the sibling tool names make the CRUD role obvious, and the upsert behavior clarifies this is the create/update tool.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the interactive nature (browser link, picker's search box), the Google limitation on programmatic access, the return of a sessionId for later use, and the account connection requirement. This exceeds typical transparency and fully informs the agent of the tool's behavior.

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

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

The description is three sentences, front-loaded with the main purpose. Each sentence adds distinct value: what it does, how to use it interactively, and what to do next. There is no repetition or fluff, making it 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?

Given the tool has no input schema, no output schema, and no annotations, the description fully compensates by explaining the complete workflow: opening the picker, receiving a link, using the search box, selecting photos, and passing the sessionId to create_video_assembly. It also notes the account requirement, making it sufficiently complete for an agent to use 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?

The input schema has zero parameters, so the baseline is 4. The description adds context about the implicit prerequisite (connected Google account) and the output sessionId, which compensates for the lack of schema details. Although not directly about input parameters, it provides necessary semantic context for using the tool.

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

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

The description clearly states the tool's function: 'Open a Google Photos picker to choose B-roll for create_video_assembly.' It specifies the action (open picker), the resource (Google Photos), and the purpose (choose B-roll for create_video_assembly), distinguishing it from sibling tools like suggest_clips or list_connections.

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 context: pick B-roll for create_video_assembly. It also gives a when-not/alternative: 'Google does not allow listing or searching your albums programmatically — so use the picker's OWN search box to find an album or topic.' It further instructs the next step of calling create_video_assembly with the returned sessionId, and notes the prerequisite of a connected Google account.

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 no annotations available, the description explains behavior in detail: it lists what each mode returns (ranked alternatives with thumbnails, timeline cutaways with segment info, library matches with matched tags). It implies read-only behavior but does not explicitly state side-effect freedom or error cases, which is a minor gap.

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 long but well-structured: a front-loaded summary sentence followed by clearly separated LOCAL and HOSTED sections. Every sentence delivers essential information about mode-specific behavior and outputs, though it could be slightly more compact without losing clarity.

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?

Since there is no output schema, the description thoroughly explains return values for each mode (e.g., 'segment id + the beat each covers + current clip' and 'library tags it matched on'). It also covers the full workflow by mentioning the follow-up swap_clip call, making it complete for a tool with this complexity.

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

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

Schema description coverage is 100%, and the description largely repeats the same parameter details as the schema. It adds some context on how parameters interact (e.g., job_id vs cut) and what each mode produces, but the schema already conveys individual parameter semantics. Therefore, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'See a project's cutaways and find better B-roll for one of them.' This uses a specific verb and resource, and it distinguishes from the sibling tool swap_clip by explicitly saying 'Then call swap_clip to apply a choice.'

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 LOCAL vs HOSTED modes, and within HOSTED, when to omit vs provide a query. It also points to an alternative tool (swap_clip) for applying a choice, giving clear context for usage.

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?

No annotations are provided, so the description must disclose behavioral traits. It discloses that it re-renders and uses cached data, sparing re-transcription and B-roll analysis. However, it does not mention whether the change is reversible, how it affects the existing project, or the output format/return behavior, which are important for a mutation-like operation.

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

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

The description is extremely concise: two sentences, the first stating the action, the second explaining performance and listing styles. Every word contributes value, with no 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 no output schema and no annotations, so the description must cover prerequisites, behavior, and results. It covers the main purpose, performance characteristics, and style choices, but does not address potential lack of a 'most recently assembled video', error handling, or what the re-render returns. Given the simplicity of the tool, 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?

Schema description coverage is 100%, and the schema already explains each parameter, including the style enum and job_id semantics. The tool description adds a slight restatement of the styles but no substantial new information beyond the schema, so 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 ('Change the caption style'), the resource ('most recently assembled video'), and the effect ('re-render'). It also lists the available styles, distinguishing this from sibling tools like generate_caption or create_kinetic_text by specifying it operates on an existing assembly.

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 applies to the most recently assembled video and emphasizes it is faster than full re-assembly because it uses cached edit data. However, it does not explicitly mention when not to use it or name alternatives (e.g., if no assembly exists), so it falls short of full explicit 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?

With no annotations, description carries full burden. It discloses async behavior ('Returns immediately'), render cost implication, hosted timeline syncing, and provenance storage. Minor conflict: opening says 'then re-render' but hosted mode defaults render=false; clarified later. Otherwise strong disclosure.

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?

Dense but structured with explicit LOCAL/HOSTED labels. Every sentence provides needed operational detail; no filler. Slightly long but warranted given two modes and 8 params.

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?

No output schema, so description should explain return/outcome. It states MP4 path for LOCAL and immediate return for HOSTED, but doesn't specify hosted return payload shape. Enough context for an agent to follow up with check_review_status. Overall complete for a complex 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?

Schema coverage is 100%, so baseline 3. Description adds value by grouping params into LOCAL/HOSTED sets, explaining conditional requirements (e.g., omit job_id to use env var), and linking asset/segment_id to suggest_clips output. Enhances schema semantics.

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 'Replace' + resource 'cutaway' + asset source 'from suggest_clips'. Clearly distinguishes two operation modes (LOCAL vs HOSTED), making it distinct from siblings like swap_caption_style, trim_clip, render_project.

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?

Explicitly ties input params to project modes; names suggest_clips as prerequisite; tells when to use render_project for final render ('iterate freely, then call render_project once'). Gives clear decision path.

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 no annotations provided, the description carries the full burden and excels. It discloses that it's audio-safe, preserves total video length, and performs an instant timeline edit by default without rendering. It also explicitly instructs to call render_project when done, making the behavior and required follow-up 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?

The description is exactly three sentences, front-loaded with the core function, followed by a key safety property and the usage workflow. Each sentence adds necessary information without redundancy or filler, achieving high information density.

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 moderate complexity (4 params, no output schema), the description covers the purpose, the prerequisite (suggest_clips), the default behavior (no render), and the follow-up action (render_project). It is fully self-contained for an agent to use it correctly in the given 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful value beyond the schema by specifying where to obtain segment_id ('from suggest_clips') and clarifying the effect of duration_sec via 'freeing that time back to the A-roll'. This slightly exceeds the baseline by enriching parameter origin and consequence.

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 (shorten/restore), the target resource (ONE B-roll cutaway in a Swap & Refine project), and the effect (freeing time back to A-roll). It distinguishes from siblings like swap_clip and suggest_clips by focusing on adjusting the on-screen duration of a single cutaway.

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 workflow context: get the segment id from suggest_clips, then use this tool, and finally call render_project when done. It implicitly says when to use (for single cutaway duration adjustments) but doesn't explicitly state 'when not to use' or contrast with alternatives like swap_clip for replacing clips. The guidance is strong but not fully exhaustive.

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