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 disclosing behavior. It only says fades are added and gives units; it does not state whether the original file is modified in place, whether a new file is produced, or how existing fades are handled.

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

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

The description is a single sentence with no filler, front-loading the verb and object. The parenthetical '(seconds)' compactly communicates the required units.

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?

Parameter coverage is complete and the operation is conceptually simple, but the description omits output or destination behavior, which matters more because there is no output schema and no annotations. It is adequate for basic selection but not fully self-contained for an agent wanting to predict the mutation's result.

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

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

Schema description coverage is 100%, so the schema already documents video_path, fade_in, and fade_out. The description adds the 'and/or' relationship and seconds unit but does not provide meaning beyond what the schema already contains.

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 ('Add'), a specific resource ('a video'), and the exact effect ('fade-in and/or fade-out'), with units in seconds. This clearly distinguishes it from sibling video tools like trim_video or add_watermark.

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

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

The description implies the tool should be used when applying fades, but it does not explicitly say when to prefer it over alternatives or mention any exclusions or prerequisites. Usage is inferable from the name and action, but no direct guidance is 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?

With no annotations, the description carries the full burden of behavioral disclosure, but it only describes the action and offers a logo-format tip. It does not state whether the source video is modified in place, where output is written, or what side effects or dependencies exist.

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

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

The description is a single sentence with no filler, and the core action is front-loaded. Every word contributes to understanding the tool's purpose.

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

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

For a media-mutation tool with no annotations and no output schema, the lack of output/file behavior is a significant gap. An agent knows what the tool does but not whether it overwrites the input video or what the tool returns.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds only the 'PNG with transparency works best' tip for logo_path. Position semantics are already fully covered by the schema's enum and default.

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: 'Overlay a logo image ... on top of a video.' It also distinguishes from the sibling overlay_text by focusing on a logo image, though it never explicitly names alternatives.

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 like overlay_text or burn_subtitles. Usage must be inferred entirely from the verb and resource, with no conditions, exclusions, or workflow 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?

With no annotations provided, the description carries the full burden. It discloses that the tool modifies audio volume (a mutation) and explains the gain parameter's meaning. However, it does not mention potential side effects on other video properties, reversibility, or any required permissions. 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 single, concise sentence with zero wasted words. The key information (unit and examples) is front-loaded and easy to parse. It earns a high score 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?

For a simple two-parameter tool with 100% schema coverage and no output schema, the description is mostly complete. However, it lacks guidance on typical use cases or edge cases (e.g., clamping behavior at min/max). Given the simplicity, a 3 is appropriate; it's adequate but could mention that the gain is applied to the audio track.

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

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

Schema coverage is 100%, and the schema already provides descriptions for both parameters (gain in dB, video path). The description adds concrete examples of gain values (+6, -6), which clarifies the semantics slightly beyond the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the verb 'adjust' and the resource 'audio volume', and specifies the unit (decibels) with intuitive examples (+6 = louder, -6 = quieter). It is distinct from sibling tools like replace_audio or extract_audio, which have different purposes.

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

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

The description implies when to use it: when you need to adjust volume of an existing video. It doesn't explicitly state when not to use alternatives, but the context is clear given the sibling tools. A higher score would require 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?

No annotations are provided, so the description must carry the behavioral burden. It discloses the API key requirement and return path of the MP4, but omits other behavioral aspects like cost, latency, failure modes, or whether the input image is left unmodified. Adequate for a simple read-like generation tool, but not complete.

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 front-load the core purpose and then add necessary context (API key, output path). Every sentence earns its place, with no redundant information.

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

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

For a tool with four parameters, no output schema, and no annotations, the description covers the essential non-schema context: provider requirement, input location, and return format. Minor gaps like expected prompt style or model behavior are secondary given the schema already documents parameters.

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

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

Schema coverage is 100%, so each parameter has a description. The tool description repeats the local file path notion but adds no semantics beyond the schema (e.g., prompt guidance or duration caveats). Baseline 3 is appropriate since the schema already handles parameter meaning.

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: 'Animate a static image using AI image-to-video (fal)'. This clearly distinguishes it from siblings like generate_video (text/video) or edit_image, and includes the provider and input type, making the tool's 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 implies when to use the tool (when you have a static image to animate) and notes prerequisites (fal API key, local file path), but it provides no explicit alternatives or when-not-to-use guidance. With siblings such as generate_video, more direct routing would improve clarity.

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 burden and does state the key behavior: subtitles are burned into pixels and therefore universally visible, and style can be overridden with ASS force_style. However, it does not disclose the output path, whether the original file is modified, or what the tool returns on success. That leaves meaningful gaps for a mutation 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?

Two crisp sentences, with the core operation first and the optional style detail second. The example is useful and not padded. No redundant restatement 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?

For a simple 3-parameter tool without annotations or output schema, the description covers the inputs and the visual effect, which is enough to make a first correct call. The main gap is the absence of any statement about returned result or output file, which would be helpful since there is no output schema. Sibling navigation is not needed for this basic operation, but the usage guidance is thin.

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 value by calling out the optional ASS force_style string and giving a concrete example syntax (FontSize=24,PrimaryColour=&H00FFFFFF), which clarifies exact formatting beyond the schema. Video and SRT paths are also implied by the main sentence.

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 ('Burn') and resource ('.srt subtitle file' into 'video pixels'), and adds the platform-visibility consequence, clearly distinguishing it from soft-subtitle or text-overlay operations. It is immediately clear what the tool does. The optional style example reinforces the purpose.

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?

'Visible on every platform' implies a use case for burned-in/hardcoded subtitles, but no explicit alternatives or when-not-to-use guidance is given. An agent can infer intent but must compare with sibling tools itself. This is implied rather than explicit.

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

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

The description adds one behavioral trait: 'Video and audio stay in sync,' which is not present in annotations or schema. However, it lacks other behavioral details such as output format, file overwrite behavior, or performance implications, leaving gaps given no annotations are provided.

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 redundancy. The core action and key constraint are front-loaded, making it efficient and readable.

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 speed-adjustment tool with 2 well-documented parameters and no output schema, the description covers the essential behavior including sync. It could mention what happens to the original file or output location, but these are minor given the tool's simplicity.

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

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

The schema provides full descriptions for both parameters (rate with range and explanation, video_path with explanation). The description adds no additional parameter-specific meaning, so it does not exceed the baseline for a fully covered 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 'Change' and resource 'playback speed', with an explicit range (0.25x to 4x). This clearly distinguishes it from siblings like trim_video and adjust_volume, none of which address speed modification.

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

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

The description provides no guidance on when to use this tool versus alternatives. It simply states what it does without mentioning alternative tools or exclusion criteria, leaving the agent to infer 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that a hash is calculated; it does not explicitly disclose that the operation is read-only, the output format, or failure modes such as missing or unreadable files. This is a moderate gap for an unannotated 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, tightly written sentence that front-loads the exact operation. Every word earns its place, with no filler or redundant restatement 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?

For a simple one-parameter checksum tool, the essential invocation information is present. However, because there is no output schema and no mention of the return format or error behavior, an agent must infer details about the exact response.

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 fully documents the single parameter with 100% coverage, so the baseline of 3 applies. The description adds no new parameter-level detail, but none is really needed since the schema already describes file_path as the local path to the file.

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 ('Calculate') and a specific resource ('SHA-256 hash of any local file'), leaving no ambiguity about the tool's function. It is clearly distinguishable from all sibling tools, which are media/image/video processing operations.

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

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

There is no competing checksum/hash tool among the siblings, so the intended use case is clear by uniqueness. The description implies when to use it (whenever a SHA-256 hash of a local file is needed), though it does not explicitly state when not to use it or mention any prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the key operational trait: stream copy, no re-encode, plus the pre-requisite that clips must share codec/resolution. It does not mention output path or reversibility, but the core behavior is well specified.

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: the first states the purpose, the second delivers the constraint and the alternative. No filler or redundant phrasing, making it easy to parse.

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

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

The description covers prerequisites and behavior well, but with no output schema it omits what the tool returns or where the joined file is written. A brief note on the return value would make it complete for an agent.

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 videos parameter is already described as 'Paths of the clips, in order'. The description repeats the 2-4 count via minItems/maxItems and adds a constraint rather than new parameter semantics, which is acceptable but not additive.

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 'Join' with resource 'video clips' and outcome 'into one', clearly identifying the tool's function. It also distinguishes itself from the sibling transcode_video by stating that transcode must be used first if clips differ in codec/resolution.

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 an explicit decision rule: if codecs/resolutions differ, use transcode_video first. This tells the agent when not to use this tool directly and which alternative to choose, leaving no ambiguity.

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

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

Annotations are absent, so the description carries the burden. It does disclose one useful non-obvious behavior: JPEG conversion gives transparent areas a white background. However, it does not state whether the original file is overwritten, where the output is written, or what the return value is, which are material for a conversion tool.

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

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

Two short sentences with no filler. The action and target formats are front-loaded, and the important transparency caveat is placed in the second sentence. 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?

For a 2-parameter tool with no output schema, the basic calling contract is clear, but output and overwrite behavior are missing. The white-background caveat is helpful, yet an agent still cannot tell whether the operation is in-place or returns a new artifact.

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

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

Schema description coverage is 100%, with both image_path and format already described clearly. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Convert'), a clear resource ('an image'), and the exact allowed formats (PNG, JPEG, WebP). This distinguishes it from sibling tools like edit_image, resize_image, and transcode_video, so an agent can identify the tool's scope immediately.

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

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

The description gives no guidance on when to use this tool versus alternatives. It never names sibling tools or exclusion conditions, such as 'use for format conversion only, not for resizing or editing,' leaving the agent to infer usage context from the schema alone.

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. Although 'Create' implies a side effect (a new file), the description does not state whether the source video is left untouched, where the output is saved, what format the return value takes, or any permissions required. This minimal disclosure leaves significant behavioral uncertainty.

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

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

The description is a single, front-loaded sentence that wastes no words and clearly leads with the verb and core purpose. It is appropriately sized for a simple tool definition and earns its place 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?

With no output schema and no annotations, the description fails to convey what the tool returns (e.g., a file path, a success message, or binary data) or any other operational context such as output naming or potential failure modes. The schema covers parameters well, but the overall description leaves a 4-parameter tool with only one sentence, which is insufficient for an agent to invoke it confidently.

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

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

Schema description coverage is 100%, so all parameters (video_path, start, width, duration) are already well-described in the input schema with defaults and ranges. The description adds no additional parameter semantics—it only generically refers to 'a segment of a video'—so the baseline score of 3 applies.

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

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

The description explicitly states a specific verb ('Create') and resource ('a looping animated GIF') from a segment of a video, which clearly distinguishes it from siblings like trim_video or extract_frame. The phrase 'looping animated GIF' makes the tool's unique output format 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 provides no guidance on when to use this tool versus alternatives such as trim_video, extract_frame, or generate_video. It does not mention any selection criteria, exclusions, or context where a different tool would be more appropriate, leaving the agent to infer usage solely from the tool name and purpose.

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 must disclose behavioral traits. It mentions one constraint ('Width/height must be even numbers') but does not explain side effects (e.g., modifies file in place or creates new file), performance implications, or potential failures (e.g., crop exceeding video bounds). It lacks transparency about output 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 brief (two sentences) and front-loads the main action and the key constraint. No wasted words, though it could have added sibling differentiation without much length.

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

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

Given the complexity of a video operation with 5 parameters and no output schema, the description is minimal. It misses critical context such as coordinate system origin (top-left), bounds checking, whether the operation is in-place, and any format compatibility. The evenness constraint is mentioned but other common constraints 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?

The schema provides 100% coverage with descriptions for all 5 parameters. The description adds no additional parameter semantics beyond the evenness constraint. Since schema coverage is high, baseline is 3, and the description does not go beyond.

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 ('Cut') and resource ('a video') with a concrete action (to a rectangular region). It is clear and distinguishable from siblings like trim_video which typically implies temporal cutting, whereas this is spatial cropping. However, it doesn't explicitly name alternatives or clarify the difference from trim_video.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like trim_video or extract_frame. It only states the operation and a constraint, leaving the agent to infer the usage context. No mention of prerequisites or typical scenarios.

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 does usefully disclose that it uses fal or OpenAI, requires the matching provider key, and returns a path to the edited image. However, it does not state whether the original image is overwritten or a new file is created, which is a meaningful side-effect gap for an editing 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?

Three concise sentences front-load the core purpose and examples, then add provider, key, and return-value info. There is no redundant or filler content; 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?

For a 4-parameter tool with no output schema, the description covers what the tool does, example inputs, provider options, key prerequisite, and the return type. It does not explicitly point to set_provider_key as the way to configure the required key, but the core information needed to invoke the tool 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 coverage is 100%, so the structured schema already documents all parameters, which sets the baseline at 3. The description adds helpful illustrative prompt examples and the provider key requirement, but it does not materially deepen parameter semantics beyond the schema.

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

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

The description clearly identifies the operation as 'Edit an existing image using a text instruction' with concrete examples such as 'make the background blue'. This distinguishes it from sibling image tools like generate_image, remove_background, and replace_background because the defining trait is natural-language editing of an existing image.

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 an existing local image needs to be modified based on a text prompt. It does not explicitly name alternative siblings or state when not to use them, but the examples and 'existing image' qualifier give sufficient situational 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?

There are no annotations, so the description must carry the behavioral disclosure burden. It mentions output codec and container, but does not state where the resulting .m4a file is written, whether existing files are overwritten, or what success/failure looks like. The missing output-location behavior is material for correct use.

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

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

The description is one clear, front-loaded sentence with no filler. It efficiently communicates the core action and the output format, and every word contributes meaning.

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

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

While the tool has only one parameter and no output schema, the description omits critical operational details such as output file location and side effects. Without annotations, an agent cannot confidently predict the result of invoking this tool beyond knowing that an .m4a file is produced somewhere.

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 only parameter, video_path, is already fully described in the schema as 'Local path to the video,' with 100% coverage. The description does not add extra semantic precision or constraints beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific operation ('Pull the audio track out of a video') and the output format (AAC .m4a), so an agent knows what the tool does. It is clear but does not explicitly differentiate itself from siblings such as transcode_video or replace_audio.

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

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

No guidance is provided about when to use this tool versus alternatives like transcode_video or replace_audio. The intended use is implied by the name and description, but no explicit context, exclusions, or alternative routing is given.

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

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

No annotations are provided, so the description carries the behavioral burden. It usefully discloses the output format (PNG), the fact that exactly one frame is extracted, and the accepted timestamp forms. It does not specify whether the PNG is returned directly or saved to a path, but the core behavior is clear.

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

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

The entire description is one front-loaded sentence with no filler. The timestamp examples are compact and immediately useful, and every part of the 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?

For a simple two-parameter tool, the description covers the core action well. However, with no output schema and no annotations, it omits the output destination or return shape, leaving the agent to assume what happens to the generated PNG.

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 value beyond the schema by giving concrete timestamp format examples ('90', '1:30', '00:01:30'), which clarifies how the timestamp parameter should be expressed.

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: 'Grab a single frame from a video as a PNG image.' It also specifies the output format, which distinguishes it from sibling tools like extract_audio, trim_video, or create_gif.

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 intended use is implied—extract one still image at a timestamp—but there is no explicit when-to-use guidance or mention of alternatives. An agent must infer when to prefer this over create_gif or trim_video.

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 transformation but does not say whether the input video is overwritten, whether a new file is returned, or what the output format/location is. This is a significant transparency gap for a video-processing 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 a single sentence with no filler, front-loading the operation and its two possible directions. Every word earns its place, and the structure is easily scannable.

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 annotations and no output schema, the description must explain the tool's result and side effects. It fails to mention whether the original file is preserved, how the mirrored video is returned, or any prerequisites. An agent cannot fully predict the consequence of calling 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?

The input schema already documents both parameters with 100% coverage, including the direction enum. The description adds little beyond the schema, only restating that mirroring can be horizontal or vertical, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Mirror') and resource ('a video'), and scopes the operation to horizontal or vertical. This clearly distinguishes it from sibling video tools such as reverse_video, crop_video, or trim_video, whose operations are not mirror-like.

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

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

The description provides no guidance on when to use flip_video versus related video-editing tools, and it names no alternatives or exclusions. An agent must infer usage entirely from the tool name and the minimal description.

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 it delivers: it discloses the auth requirement (provider API key), the privacy-relevant behavior (image saved locally, not uploaded anywhere), and the Stability-specific quirk (any WxH mapped to nearest supported aspect ratio). No annotation contradiction since none exist.

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

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

Three sentences with zero waste: purpose, prerequisite, privacy note, and the provider quirk. The core purpose is front-loaded in the first clause, and every sentence earns its place with distinct, actionable information.

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

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

Despite having no output schema and no annotations, the description covers the essential operational aspects: what it does, the required key, where the output lands (locally), and a provider-specific caveat. The one minor gap is that the exact return value (e.g., a local file path) is not spelled out, though 'saved locally' implies it. Moderately complex tool, well covered.

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

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

Schema coverage is 100% and the schema already documents all four parameters including the provider enum, model examples, and size format. The description adds marginal value by mapping providers to named products (fal FLUX, DALL-E 3) and by explaining the Stability size-mapping behavior, but it does not meaningfully expand on the schema's parameter descriptions. 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?

States a specific verb (generate), resource (image), and method (text description via AI), and names the three providers (fal FLUX, DALL-E 3, Stability). This clearly distinguishes it from the media-generation siblings (generate_video, generate_music, generate_voiceover) and the image-editing siblings (edit_image, animate_image) 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 states the prerequisite (a provider API key via set_provider_key) and the local-save behavior, which give useful context. However, it never explicitly says when to choose this tool over generate_video, edit_image, or animate_image — the differentiation is only implied by the tool name and the stated purpose, with no explicit exclusions or alternative routing.

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 behavioral disclosure burden. It usefully discloses an external dependency and authentication requirement ('Requires a fal API key') and the return format ('Returns the path to the generated audio file'). It does not discuss failure behavior or default durations, but the key invocation traits are covered.

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 purpose, prerequisite, and return value with no filler. Each sentence adds essential information, and the purpose is front-loaded. This is an appropriately concise and well-structured description.

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

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

For a simple 3-parameter generation tool with no output schema, this description covers the essential invocation context: what to provide, the auth requirement, and what is returned. It lacks guidance on model/duration defaults, but those are already in the schema. A slightly richer mention of when to use it would make it 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%, so the schema already documents prompt, model, and duration. The description adds general context ('from a description') but no additional parameter-level detail beyond what the schema provides. The baseline of 3 applies because the schema does the heavy lifting.

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

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

States a specific action ('Generate instrumental background music') and resource ('from a description (fal)'), clearly distinguishing it from sibling tools like generate_voiceover or generate_image. The phrase 'instrumental background music' narrows the scope and makes the tool's role immediately understandable.

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

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

The description implies the use case: generate instrumental background music from a text description. It also notes a prerequisite ('Requires a fal API key'). However, it does not explicitly say when to prefer this tool over alternatives like generate_voiceover, nor does it mention conditions where it should not be used.

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. It discloses three key behaviors: it requires an API key, it is slow (minutes), and it returns a file path to an MP4. This is meaningful context beyond the schema. It doesn't mention potential failures or whether it's blocking, but covers the most essential behavioral aspects.

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 zero filler. The primary action is front-loaded, and each subsequent clause adds critical operational detail (API key, latency, output format). No unnecessary words.

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

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

For a generation tool with four parameters and no output schema, the description covers the essential: what it generates, how (providers), prerequisites (API key), performance (slow), and output (MP4 path). It could mention error handling or asynchronous behavior, but those are minor gaps given the tool's nature.

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

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

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds value by clarifying provider selection ('Omit to use the first configured key') and duration constraints ('Runway snaps to 5 or 10'), which are not fully captured in the schema descriptions. This goes beyond repeating schema info.

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 ('generate'), a resource ('short video from a text description'), and names the providers ('fal or Runway'). This clearly distinguishes it from sibling tools like generate_image, generate_voiceover, or video editing tools, leaving no ambiguity about what the tool does.

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

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

The description implicitly indicates when to use it: when you need a video from text, as opposed to image or audio generation. It also notes the requirement of an API key and the slowness, which sets expectations. However, it doesn't explicitly contrast with alternatives like generate_image or explain when NOT to use it, 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 provided, the description carries the full burden of behavioral disclosure. It does state the prerequisite of a provider API key and that it returns an MP3 path, which are important operational details. However, it does not mention potential side effects (e.g., cost, rate limits, asynchronous behavior, or error conditions) beyond creation. 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 concise: three short statements covering action, prerequisite, and output. It is front-loaded with the main purpose and then includes necessary context. No wasted words, though it could be slightly more compact by merging sentences. Still, it is efficient and well-structured.

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

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

For a tool with five parameters and no output schema, the description provides the essential context: what it does, what is required (API key), and what it returns (MP3 path). The schema covers parameter details, so the description does not need to explain them. Error handling or specific provider behaviors are not covered, but given the moderate complexity, the description is nearly 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 input schema provides 100% coverage for all five parameters, each with descriptive comments. The description itself adds very little beyond what the schema already states—it repeats the provider names and mentions text, but does not introduce any new semantic meaning or relationships. Baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool's function: generating a voiceover from text using AI text-to-speech, and specifically names the providers (fal, OpenAI, ElevenLabs). This distinguishes it from sibling generation tools like generate_music or generate_video, which produce different content types. The verb 'generate' and resource 'voiceover' 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 clearly implies the tool should be used when a voiceover is needed from text, making the context evident. However, it does not explicitly name alternative tools or exclude other scenarios (e.g., when to use generate_music instead). Lacks an explicit 'when not to use' statement, but the purpose is clear enough that an agent can infer correct 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?

With no annotations provided, the description carries the full burden, and it does well by disclosing that keys are only shown masked and that the output includes provider-to-tool associations. It does not explicitly state there are no side effects, but the verb 'check' and focus on reading configuration imply a read-only 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 two sentences with no unnecessary words. The most important behavioral detail, masked keys, is included up front, and the additional capability is stated in a second concise sentence.

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

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

For a zero-parameter status tool, the description is largely complete: it states what is checked, what is returned conceptually, and a key privacy constraint. It could go further by specifying the exact return format, but given the tool's simplicity, no critical information 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 there are no parameter semantics to clarify. The description appropriately does not invent parameter details, and the 100% schema coverage for an empty schema means nothing is left 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 clearly states the tool's purpose: checking which AI provider API keys are configured, with the important caveat that keys are shown masked. It also mentions an additional function—listing which providers each generation tool can use—which distinguishes it from key-setting siblings like set_provider_key.

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

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

The description provides clear context for when to use this tool: to inspect configured provider keys and provider availability for generation tools. It does not explicitly mention when not to use it or name an alternative, but the read-only diagnostic purpose is evident from the wording.

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 behavioral traits. It does not explicitly state that this is a read-only operation, how it handles missing paths, or whether it can fail. It names the output attributes but not the return structure or side effects. While reading a local image metadata is implied, the description does not confirm safety or error 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 a single, focused sentence that front-loads the verb and resource and immediately lists the returned fields. There is no filler, redundancy, or unnecessary detail. It is an excellent example of economical, well-structured prose.

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 one simple parameter and no output schema, so the description must compensate for missing return structure. It names the metadata fields but does not state the output format (e.g., JSON object, plain text). Given the tool's simplicity and clear purpose, the description is mostly adequate but leaves a small gap about the return shape and potential errors.

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 describes the only parameter (image_path with 'Local path to the image'), giving 100% coverage. The tool description adds no further parameter-level details, such as accepted formats, absolute vs relative paths, or validation rules. Under the high-coverage baseline of 3, this is adequate but not enhanced.

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 ('Get an image's') and enumerates exactly what is returned (dimensions, format, byte size, MIME type, SHA-256). This clearly distinguishes it from sibling tools like edit_image or resize_image, which modify images. It also differentiates from broader probes like probe_media by focusing on images specifically.

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

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

The description provides no guidance on when to choose this tool over closely related siblings such as probe_media or checksum_file, both of which could partially overlap. There is no mention of alternatives, exclusions, or context for when image_info is preferred. The usage context must be inferred entirely from the name and description.

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 that aspect ratio is preserved, a useful behavioral detail not in the schema. However, it does not mention output location, file format, or whether it overwrites, which is a gap for a tool that creates a new artifact.

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

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

A single concise sentence that front-loads the action and adds one key behavioral detail. No wasted words.

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

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

The tool is simple (2 params, no output schema), but the description does not explain what happens after execution—where the thumbnail is saved, what format, or how the agent should use the result. This is incomplete for a tool that produces a file, especially without any output schema to clarify the return value.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional parameter-specific meaning; it only restates that the output is a small preview, which is implicit in the tool name. Baseline 3 applies.

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

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

States a specific verb and resource ('create a small preview version of an image') and notes aspect ratio preservation, which clearly differentiates it from siblings like resize_image or convert_format. The purpose is immediately obvious.

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 such as resize_image. The description only states what it does, not when it should be selected, leaving the agent without routing information.

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 behavioral disclosure. It explicitly states what the tool does (lists tools with one-line descriptions) and implies the output is a collection of names and descriptions. For a read-only, side-effect-free meta-tool, no additional behavior needs disclosure. The description is transparent and complete within its scope.

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 short sentences. The first sentence states the core functionality with a specific verb and resource, and the second adds a practical use case. There is zero wasted wording, and the action 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 zero-parameter, no-output-schema tool, the description covers everything an agent needs to know: what it does and when to use it. The returned list's format is adequately implied by the phrase 'with a one-line description.' No additional context is necessary.

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

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

The tool takes zero parameters, so the baseline score of 4 applies. The description adds no parameter-specific information, but none is needed because the input schema is an empty object and there is nothing to explain.

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

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

The description states a specific verb ('List') and a specific resource ('every tool this server offers'), and clarifies the output format ('with a one-line description'). It clearly distinguishes this tool from all sibling tools, which are content operations, by being the only meta-tool that enumerates the available 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 a clear use case: 'Useful to plan multi-step content work.' This tells an agent when to call it. It doesn't explicitly mention alternatives or exclusions, but given that no sibling tool serves the same listing purpose, the guidance is sufficient and not misleading.

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 behavioral disclosure. It only reveals that text is centered by default; it does not state whether the input video is modified in place, whether a new file is produced, or anything about side effects, permissions, or failure 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 a single efficient sentence that leads with the core action and includes a useful example plus a key default. Every word earns its place, and there is no redundant restating 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?

Despite having five parameters and no output schema or annotations, the description omits what the tool returns, whether it creates a new file or mutates the input, and how the burned caption affects the video. For a video-editing mutation, important operational context is missing.

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

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

Schema description coverage is 100%, so each parameter already has a meaningful description. The tool description adds only one behavioral default, centered positioning. This is sufficient to meet the baseline but not much more.

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: 'Burn a text caption onto the video', and gives example use cases like hooks or calls to action. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as add_watermark or burn_subtitles.

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 examples 'a hook or a call to action' imply when a text overlay is useful, but the description gives no explicit guidance about when to use this tool instead of similar siblings like burn_subtitles or add_watermark. Usage context is implied, not 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?

With no annotations provided, the description carries the full behavioral burden. It explicitly states 'This tool does NOT upload or authenticate — it only prepares the metadata,' which is a key non-side-effect disclosure. It also describes the returned fields needed for subsequent calls, giving the agent a clear picture of expected behavior. Minor gaps like error handling or file existence validation are not covered, but the core behavioral scope is 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 three sentences, front-loaded with the primary purpose, then the workflow, then a crucial clarification of what it does not do. Every sentence earns its place, with no redundancy or fluff. The structure is clear and efficient.

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 tool with no output schema, the description is quite complete: it explains the use case, the workflow, the return values, and the non-destructive nature. It could mention potential error conditions (e.g., file not found) but that's a minor omission. Overall, an agent has sufficient information to call it correctly.

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

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

Schema description coverage is 100%, so both parameters (file_path and name) are already documented in the schema. The description adds no additional meaning beyond what the schema provides—it doesn't elaborate on the name field or provide format constraints. Since the schema already handles parameter semantics, a baseline of 3 is appropriate.

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

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

The description clearly states the specific action (format metadata for upload), the resource (local file for Postward), and the output (path, MIME type, byte size, SHA-256). It explicitly distinguishes itself from siblings by noting it does not upload or authenticate, and it names the exact follow-up tools in the workflow. This leaves no ambiguity about what the tool does.

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 it when the user asks to move content into Postward for storage, review, scheduling or publishing.' It also clarifies what it does not do (upload/authenticate) and outlines the required next steps, which helps an agent decide when to invoke it. It lacks an explicit 'when not to use' alternative, but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It implies a read-only operation ('Get detailed info') and local file access, but does not explicitly state that it is non-destructive or mention any side effects, errors, or limitations. The description is not misleading, but it could be more explicit about its read-only nature.

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

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

The description is a single, well-structured sentence with the key action and scope front-loaded. It wastes no words and conveys all essential information efficiently.

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 (1 parameter, no output schema), the description covers the purpose, scope, and basic return content. It could specify the return format (e.g., JSON) or error handling, but for a straightforward media probe, it is largely sufficient. The lack of an output schema is compensated by listing the returned fields.

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 describes the single parameter 'file_path' with a clear description. The tool description adds no additional meaning about the parameter beyond the schema, so the baseline of 3 is appropriate given 100% 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 verb ('Get'), a resource ('local media file'), and the exact information returned (duration, resolution, codecs, bitrate). It also specifies the scope (video, audio, images), which differentiates it from the sibling 'image_info' tool that presumably only handles images. This is a precise, non-tautological statement.

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

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

The description implies its use case (inspecting media files) but does not explicitly contrast it with alternatives like image_info or other analysis tools. It does not state when to prefer this over a sibling or provide exclusions. While the scope is clear, there is no explicit 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?

With no annotations, the description must carry behavioral disclosure. It does mention the output format (transparent PNG) and a key requirement (matching provider key). However, it omits where the output is saved, whether the original is modified, and error behavior. This is partial but not comprehensive.

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 main action and output are front-loaded, and the provider key note is placed second. No filler or redundant information. It earns its place efficiently.

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 explain what happens on success and failure. It only states the output is a transparent PNG but does not specify the output path, return value, or error conditions. For a transformation tool that produces a file, this is a significant gap.

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

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

The input schema has 100% description coverage, so all parameters are already documented. The description adds context about the provider key requirement, which clarifies the dependency between provider and key. This is a slight addition beyond the schema, so the 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 verb ('Remove') and resource ('background from an image'), and explicitly names the output ('transparent PNG'). This clearly distinguishes it from the sibling 'replace_background', which replaces rather than removes. The action and result are 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 implies usage: if you need to remove a background, this is the tool. However, it does not explicitly mention alternatives or when NOT to use it (e.g., for replacing a background, use replace_background). It only notes a prerequisite (provider key) but gives no comparative guidance.

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

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

The description adds a meaningful behavioral detail: output ends when the shortest input ends. However, with no annotations, it does not disclose whether the original video is overwritten, where the output file is written, or how audio encoding is handled.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the behavioral constraint is stated efficiently in the second sentence.

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

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

For a two-parameter tool this is reasonably usable, but the lack of annotations and output schema leaves an agent uncertain about the return value and output file behavior. The description should at least indicate whether a new file is produced or the source is modified.

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 describes both parameters with clear one-line descriptions, so the description adds no additional per-parameter meaning. Baseline 3 is appropriate given 100% 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?

States a specific verb and resource: swapping a video's audio track with another audio file. This clearly distinguishes it from sibling tools like extract_audio, adjust_volume, and trim_video.

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

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

No guidance is given about when to use this tool versus alternatives such as adjust_volume or extract_audio, and no prerequisites or exclusions are mentioned. The usage context must be inferred entirely from the description and tool name.

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 does disclose that a fal API key is required and that the tool returns the path to the new image. However, it does not mention whether the original image is modified, potential costs, rate limits, or other operational side effects, leaving significant 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?

The description is three short sentences, each earning its place: purpose, prerequisite, and output. It is front-loaded with the main action and contains no filler or 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?

While the description covers the core purpose, prerequisite, and return value, it omits important operational context for an agent, such as whether the fal API key can be set via sibling tools like set_provider_key, or whether the operation is synchronous and costly. With no annotations or output schema, more completeness would be expected.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds no new semantic meaning beyond what the schema provides, 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 states a specific verb ('Replace'), resource ('background of an image'), and condition ('following a text description'), making it distinct from siblings like remove_background. The parenthetical '(fal)' clarifies the service. This is a clear and specific purpose.

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

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

The description gives no guidance on when to use this tool versus alternatives such as remove_background or edit_image. It only mentions a prerequisite (fal API key) but does not explain when to prefer this tool over others or when not to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states only the scaling behavior and aspect-ratio preservation, but omits whether the original file is overwritten, where or how the resized image is returned, and what happens with unsupported formats—critical side effects for a tool with no output schema.

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 11-word sentence with no filler; the core constraint ('fit within width x height') and behavior ('aspect ratio preserved') are front-loaded. Every word contributes, and there is no unnecessary structural 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 a simple three-parameter tool, the description should still clarify the output/return behavior, especially because there is no output path parameter or output schema. The description doesn't state whether the image is modified in place, where the result is written, or what the tool returns, leaving a significant gap for an agent trying to use the result.

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 schema already documents all parameter meanings ('Max width in pixels', 'Max height in pixels', 'Local path to the image'). The description adds the 'fit within' framing and aspect-ratio preservation, but no additional syntax or format details, matching the baseline 3 for high schema coverage.

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

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

The description uses a specific verb ('Scale') and identifies the resource ('an image'), with precise constraints ('to fit within width x height', 'aspect ratio preserved'). It clearly states the tool's function, though it doesn't explicitly contrast with related siblings like upscale_image or image_thumbnail, so it's clear but not sibling-differentiated.

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

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

The description gives no information about when to use resize_image instead of alternatives such as upscale_image or image_thumbnail, nor any exclusions. An agent must infer the appropriate choice from the tool name and sibling list, so there is effectively no usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully notes that audio is included when present, but it does not state whether the tool modifies the input file, produces a new output file/path, or what the return value is.

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

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

The description is one concise sentence with a useful parenthetical qualifier. Every word earns its place, and the core behavior 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 simple one-parameter tool this is mostly adequate, but because there is no output schema and no annotations, the description should clarify what the result of reversing the video is—whether a new file is created, the original is modified, or playback is returned. Without that, an agent may not know what to expect from the call.

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 single parameter video_path is already fully described in the schema as 'Local path to the video', so schema coverage is 100%. The description adds no additional meaning or constraints beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Play a video backwards' with the additional detail that audio is included when present. This clearly identifies the operation and distinguishes it from siblings like trim_video, flip_video, and change_speed.

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 intended use is implied by the action itself: use this when you need a video played in reverse. However, there is no explicit guidance on when not to use it or how it differs from related tools such as change_speed or flip_video.

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 behavioral burden, and it does substantial work: it discloses local persistence to ~/.postward-creative/keys.json, file permission 0600, and the data-flow guarantee that keys are sent only to the relevant provider. It stops short of stating overwrite behavior or failure handling, and the 'never leave this machine — sent only to the provider' wording is slightly loose, but overall it is candid about 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?

Two sentences with the main action front-loaded and the security detail in the second sentence. Every phrase earns its place, with no filler or repetition of schema data. It is easy to scan and process.

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 2-parameter configuration tool with no output schema, the description is nearly complete: it covers purpose, storage location, file permissions, and data handling. It does not explicitly mention whether an existing key is overwritten or what a successful call returns, but those are minor gaps for this kind of 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 description coverage is 100%: provider and key already have clear descriptions plus an enum, and required status is in the schema. The tool description adds no parameter-level detail beyond the schema, so the baseline of 3 applies. Nothing is missing, but no extra semantic value is provided either.

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: 'Configure an AI provider API key.' It clearly identifies the tool as credential management, distinguishing it from the media-generation and processing siblings. An agent can immediately tell this is not a content 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?

Usage context is implied: an agent should call this when it needs to set or update a provider key before using provider-backed tools. However, the description never explicitly says when to use it versus related tools like get_provider_status, nor does it state when it should not be used. It relies on inference rather than providing direct usage guidance.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the video is 're-encoded' and that unknown aspect values are rejected with no silent fallback. However, it does not state whether the input file is overwritten or a new file is created, nor what the tool returns, which are important traits for a transformation 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?

A single, tightly written sentence that front-loads the core purpose, specifies the allowed values, and includes a useful behavioral caveat. Every part earns its place with 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 transformation semantics are clear, but with no output schema and no annotations, the description omits what happens after encoding: whether a new file is produced, whether the original is preserved, and what the agent receives as a result. These are meaningful gaps for a tool that takes a local path and produces an encoded output.

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 reinforces the aspect enum by listing the values in prose and adds the rejection behavior, but it adds no new meaning for video_path or quality beyond what the schema already documents.

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

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

The description states a specific verb ('Normalize'), resource ('a video'), and the exact transformation (fixed aspect ratio with padding, re-encoded). It also lists the three allowed aspect ratios, which clearly differentiates it from sibling tools like trim_video, crop_video, or convert_format.

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 use case is implied by 'Normalize a video to a fixed aspect ratio', but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives. An agent must infer that this is for aspect-ratio normalization rather than crop_video or convert_format.

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 key behaviors like snap-to-keyframe and stream copy (no re-encode), which are valuable. However, it omits crucial output behavior—whether it overwrites the file, creates a new file, or requires an output path—which is essential for an agent to safely invoke the tool.

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

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

Three sentences, each contributing unique value: the core action, timestamp format rules, and keyframe behavior. No redundancy, front-loaded with the primary function, and 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?

The tool is simple and the schema covers all parameters, but the description omits details about the output—whether a new file is created, if it overwrites, or if an output path is needed. For an agent to call this correctly, that output behavior is a critical missing piece, so the description 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?

Schema coverage is 100%, so baseline is 3. The description adds explicit timestamp format specifications (seconds, MM:SS, HH:MM:SS) and explains how keyframe snapping affects the interpretation of timestamps, which goes beyond the schema's examples and enriches 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 a specific action ('Cut a segment out of a video') with a clear temporal scope (start to end), which distinctly separates it from spatial operations like crop_video and concatenation tools like concat_videos. The verb and resource are explicit and unambiguous.

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

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

The description provides clear guidance on timestamp formats (seconds, MM:SS, HH:MM:SS) but does not explicitly state when to use this tool versus alternatives such as crop_video or extract_frame. The usage context is implied by the operation itself, but no exclusions or alternatives are mentioned.

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 must disclose behavioral traits. It mentions the provider key requirement but omits output location, side effects (e.g., writes new file vs overwrites), error handling, or whether the operation is destructive. This is a significant gap 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 a single, focused sentence that front-loads the core purpose and scale options. No redundant information; efficient and well-structured.

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

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

For a tool with no annotations and no output schema, the description is incomplete: it does not specify what the tool returns (e.g., output file path), nor does it address potential limitations or preconditions beyond the provider key. An agent calling this tool would lack critical operational details.

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 documents all parameters with 100% coverage. The description adds minimal semantic value beyond restating the scale and provider enums and the key requirement; it does not explain parameter nuances 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?

Clearly states the action (upscale) and resource (image), specifies scale factors (2x/4x) and providers (Replicate Real-ESRGAN/fal), distinguishing it from sibling resize_image and other image tools. The mention of AI providers signals a specialized upscaling capability.

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

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

The description implies the tool is for AI-based upscaling and mentions the provider key requirement, but does not explicitly contrast with alternatives like resize_image or state when not to use it. No exclusion criteria are given.

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