OpenClip

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

With empty annotations, the description carries full responsibility for behavioral disclosure. It accurately describes that the tool queues the video, returns an id and current status, and that the status may be 'processing' or 'pending_credits' if out of credits, settled later. It also discloses the error condition. This goes far beyond a basic 'starts processing' and gives the agent concrete expectations.

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 ~100 words, front-loaded with the main purpose, then prerequisites, then return and follow-up behavior. Every sentence adds necessary operational detail without fluff. It's concise yet comprehensive, structured for quick scanning.

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 one parameter and no output schema, the description covers everything an agent needs: when to call, what to pass, what it returns, what statuses to expect, how to resolve them, and what to do on error. The workflow context (create_upload → complete_upload → get_video_status) is fully explained, making it complete.

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

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

The schema already describes the 'video' parameter as the hashid from create_upload, and the description reinforces that. However, it adds crucial semantic context: the parameter must be used only after the file bytes have been PUT to the upload URL. This extra timing constraint is not present in the schema, so the description adds meaningful value.

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

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

The description opens with a clear verb and resource: 'Finish an upload started with create_upload.' It states the exact role in a multi-step workflow and differentiates itself from siblings like create_upload and get_video_status by describing the completion action. The purpose is 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?

It explicitly says to call this AFTER PUTting file bytes to upload_url, and to poll get_video_status for the final status. It also warns that calling it prematurely returns an error, telling the agent to retry after uploading. This is explicit when-to-use guidance, including the prerequisite and follow-up steps.

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 empty, so the description carries the full burden. It discloses that the operation is asynchronous, returns a `tool_job` id and `queued` status, requires polling, is free with size/duration limits, and that calling `complete_upload` would incorrectly trigger the paid pipeline. This goes well beyond the bare 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?

The description is longer than average, but each paragraph earns its place: core conversion purpose, upload workflow and exclusion of `complete_upload`, gif-only parameters, and async polling behavior. It is organized and free of fluff, though it could be tightened slightly.

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?

Even with no output schema and no annotations, the description fully equips the agent: it explains where `file` comes from, that `complete_upload` must NOT be called, how to obtain gif-specific parameters, the async polling flow with `get_tool_job_status`, and rate-limit behavior. Nothing critical is missing for a correct invocation.

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

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

The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds valuable context beyond the schema: `file` must be an uploaded video id from `create_upload` or `list_videos`, `complete_upload` must not be called, and `fps`/`width` apply only to gif output. This is useful, though the schema already covered the core meanings.

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 object: converting an uploaded video file into a target format. It enumerates supported formatsretically and distinguishes this from upload and paid pipelines by naming `complete_upload` as something to avoid, which helps disambiguate from sibling tools like `edit_video` and `extract_thumbnails`.

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

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

It explicitly tells the agent how to supply input: use the hashid from `create_upload` or `list_videos`, do not call `complete_upload`, and provides the exact upload workflow (`PUT` bytes to the returned URL before calling this tool). It also directs the agent to poll `get_tool_job_status` for the result, so follow-up behavior is unambiguous.

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

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

Annotations are empty, so the description carries the full burden. It discloses that the agent is shared across the team, that it fails if the team's plan limit is reached, and that it returns the agent's id. It also hints at behavior by saying 'Fails if the team has reached its plan's agent limit,' which is a useful constraint. However, it does not disclose any side effects beyond creation, such as whether existing agents are affected, but for a create operation that is acceptable.

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

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

The description is well-structured, starting with a clear purpose, followed by parameter summary, and ending with return value and failure condition. It is concise with no redundancy, and uses sentence structure that is easy to parse. Front-loads the key information about what an agent is and that it is shared.

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

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

Given the tool's complexity (7 params, nested objects, no output schema), the description is thorough. It covers the purpose, parameters, return value, and a key failure condition. Despite not having an output schema, it explains the return format ('id'). It also directs users to `describe_agent_settings` for details on nested objects, making it complete enough for an agent to call correctly.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description adds value by clarifying that `custom_personality_description` is required when `personality_preset` is 'custom', and by pointing to `describe_agent_settings` for the nested objects, which helps agents know how to fill those. It also clarifies the boolean nature of `repurpose_textual_content`. This goes beyond just listing parameters.

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

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

The description clearly states what the tool does: creates a processing 'agent' (a saved configuration) that controls video processing and rendering. It identifies the verb 'Create', the resource 'agent', and explains its purpose. It differentiates from siblings by noting it returns an 'id' used in submit_video, and mentions team-level sharing and limits, which is distinct.

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

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

The description provides some usage context: it says the returned id is passed to submit_video)Skip. However, it does not explicitly contrast with update_agent or list_agents to clarify when to use this versus those. It lacks exclusions or when-not-to-use guidance. The context of creating vs. updating is implied but not made explicit.

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

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

Annotations are empty, so the description carries the full burden—and it meets it well: it discloses that the tool only returns a presigned URL (doesn't attach the logo), that the upload is a separate HTTP PUT, that the URL expires, and that set_agent_logo must follow. It doesn't state failure modes or whether upload_url is single-use, but the core behavior 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?

Dense but organized: purpose first, then parameters, then the upload workflow with a concrete curl example. The curl example adds length but earns its place by clarifying the exact follow-up step.

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 still covers inputs, return values (upload_url, logo_key, expires_in_seconds), the mandatory follow-up set_agent_logo call, size and expiry constraints, and the required HTTP method. An agent can execute the full flow from this text alone.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by clarifying where agent comes from (list_agents), which content types are allowed, the 2 MB limit, and how the optional size parameter is used. This goes beyond the schema without duplicating it.

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

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

The description opens with a specific verb and resource: 'Start uploading a logo image' for a team agent, and immediately clarifies the purpose (watermark when logo_watermark_enabled). It clearly distinguishes the create-upload step from the later set_agent_logo attachment step, so an agent knows exactly what this 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 an explicit workflow: pass agent (from list_agents), filename, and content_type, get a presigned URL, PUT raw bytes without extra headers, then call set_agent_logo. It also states the 2 MB size constraint and that the URL expires, which are key usage constraints. Sibling tool distinction is implicit but sufficient.

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

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

Annotations are empty, so description must disclose behavior. It does: returns video id and upload_url, URL expiration (expires_in_seconds), single-PUT upload limit of 5GB, and suggests web uploader for larger files. No contradictions.

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?

Concise yet comprehensive: starts with core purpose, then actionable steps. Every sentence adds value; well-structured for quick comprehension.

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?

Covers all essential aspects: tool purpose, parameter usage, return values, follow-up steps, size constraint, and expiration. Complete for a multi-step upload tool without output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds context: filename used for title and extension, size optional but enforced, audio_language as spoken-language code. This enhances meaning 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 it initiates an upload of a LOCAL video file and explicitly distinguishes from sibling tool submit_video (for URLs). The verb 'start an upload' and resource 'local video file' are specific.

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

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

Provides explicit guidance: use when file is on disk, not URL; directs to call complete_upload after upload; explains that for files >5GB use web uploader. Also includes detailed steps for the HTTP PUT request with a curl example.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: both objects are closed sets with rejection of invalid keys/values, caption fields have no standalone default, color fields accept any CSS color string, and the logo image is set through separate logo-upload tools. This is rich behavioral context that an agent could not infer from annotations alone.

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

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

The description is well-structured: purpose, return contents, usage directive, then bulleted notes. Every sentence adds value, and the critical 'call this BEFORE' guidance is front-loaded before the detailed notes.

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 parameters and no output schema, this description is the sole documentation for the tool. It fully covers what is returned, when to call it, validation behavior, defaulting semantics, color format, and the related logo workflow, so an agent has everything it needs to invoke and interpret 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?

The tool has no parameters, so the schema contributes nothing and the baseline is 4. The description compensates by explaining the semantics of the objects and fields it returns, including defaults and accepted value ranges, even though these are output concepts rather than call parameters.

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

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

The description states a specific action—describing the nested agent settings for create_agent / update_agent—and names the two setting objects, composition_parameters and caption_style_overrides. It also lists exactly what is returned (fields, types, enums, bounds, defaults, descriptions), clearly distinguishing this reference tool from the sibling create/update tools.

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

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

It explicitly tells the agent to call this tool BEFORE setting either object so it uses real field names and valid values, which is strong usage guidance. It does not mention alternatives or exclusions, but none are needed for a zero-parameter introspection tool.

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

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

With no annotations, the description fully carries behavioral disclosure. It states the tool is FREE, requires only an account, is ASYNCHRONOUS, returns a `tool_job` hashid and `status: 'queued'`, requires polling get_tool_job_status, and notes rate limits and per-file size caps. This is exactly the behavioral context an agent needs beyond the 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?

The description is long but earned: it front-loads the purpose, then uses compact paragraphs and a bulleted operation list. Every sentence conveys actionable detail, and the async/rate-limit notes are grouped logically at the end.

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 multi-operation async tool with no output schema, the description covers the full lifecycle: how to supply input, what is returned, how to poll for completion, and what constraints apply. Nothing essential to calling the tool correctly is missing.

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

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

Although the schema covers all parameters, the description adds crucial relationships: per-operation parameter groups, defaults for quality and format, and the OR exclusivity between `aspect` and x/y/width/height in crop. This transforms a flat 9-parameter schema into a usable decision tree.

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: 'Edit an already-uploaded image `file`' and enumerates the exact operations (compress, resize, crop). This clearly differentiates it from upload and video siblings, so an agent knows exactly what the tool is for.

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

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

It gives a concrete usage flow: call create_upload, PUT bytes, pass the returned id, and explicitly says 'Do NOT call complete_upload' because that starts a different pipeline. It does not explicitly compare to image-adjacent siblings like convert_media or remove_background, but the operation list and upload prerequisite make the intended context clear.

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

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

Annotations are empty, so description carries full burden. It discloses that processing is asynchronous, returns tool_job and status 'queued', and requires polling get_tool_job_status until completed. Also mentions rate limits and size/duration caps, and explains how to lift limits. This is more than minimal behavioral context.

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

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

Well-structured: starts with core purpose and workflow, then an 'Operation params' section that readability is high. Every sentence serves a purpose; no redundant content. The async behavior is front-loaded near the end but clearly marked.

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?

Covers all necessary aspects: input file origin, operation options, async status, polling mechanism, and limitations. The output schema is absent so the return format is described. For a complex multi-operation tool, nothing critical is missing.

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

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

Schema coverage is 100%, but the description adds significant meaning by grouping parameters with their operations and clarifying alternatives (e.g., aspect OR x/y/width/height; target_mb OR crf). This goes beyond the schema's per-parameter descriptions. Slight deduction because it doesn't define allowed values for x, y, width, height beyond integers, but schema already lists them.

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: edit an already-uploaded video. It lists the six operations (crop, trim, rotate, resize, compress, mute) and clearly distinguishes it from complete_upload. This creates a unique identity among siblings.

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

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

Explicitly explains when to use this tool (free edits on uploaded files) and when not: do NOT call complete_upload for the paid pipeline. Gives clear steps: create_upload, PUT bytes, pass the id here. Provides per-operation guidance in detail.

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 empty, so the description carries the full burden. It discloses critical behaviors: the tool is asynchronous (returns tool_job and status queued), requires polling get_tool_job_status, and has rate limits with per-file caps. It also clarifies the upload process and that complete_upload is not needed, which is non-obvious.

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 fairly long but well-structured, with each section adding new information: purpose, prerequisites, async behavior, limits. It's front-loaded with the core purpose and free nature, then details. Could be slightly more concise, but every sentence earns its place.

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

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

Given the tool's complexity (async, multi-step upload, rate limits), the description covers all necessary context: how to obtain the file, how to handle async, what output to expect, and limitations. No output schema exists, so the description explains the return value enough.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description reinforces count (1-10, default) and width (optional), but adds no new semantics beyond what's in the schema. Baseline 3 is appropriate as the description adds minimal value 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 states what the tool does: extracts evenly-spaced thumbnail frames from an uploaded video file. It names the specific resource (video hashid) and the action, distinguishing it from sibling tools like edit_image or render_clip.

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

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

Provides explicit usage guidance: it explains the prerequisites (use create_upload, PUT bytes, pass id), what not to do (do NOT call complete_upload), and how to handle the asynchronous nature (poll get_tool_job_status). Also notes it's free compared to paid pipeline, giving clear context for selection.

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

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

With no annotations, the description carries the full burden, and it does so exceptionally. It discloses account gating, free-tier daily limits, credit metering, asynchronous processing with a job hashid, polling expectations, the relationship between script length and clip duration, override behavior for inline fields, and the one-shot caption path. There is no contradiction with annotations, which are empty.

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

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

The description is long but organized into purposeful sections: what it does, account constraints, identity selection, brief field definitions, optional parameters, and async return behavior. It is front-loaded with the core purpose and the example brief is valuable. It loses one point because a few trailing details (e.g., 'The `nudge` field is an optional suggestion') add limited value and some sentences could be tightened without loss.

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?

There is no output schema, so the description correctly explains return semantics: it returns a `ugc_job` hashid with `status: 'queued'`, to be polled with get_ugc_job_status until `completed`, then yields `video_url` and later `video`/`viral_moment` ids. It also covers the full parameter space, including optional start_frame and voice, and the async workflow is fully specified. An agent has everything needed to invoke and follow up correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It defines the inline brief's nine creative fields, gives a full example brief, explains how `creator`, `brief_name`, and `brief` interact with override precedence, clarifies how `script` drives both audio and captions, and explains `ref`, `seed`, and `caption_preset` behavior. This is far above the baseline for a schema-covered tool.

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

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

The description opens with a specific verb and resource: 'Generate a short (~7-12s) vertical UGC-style video clip from a creative brief.' It immediately distinguishes the tool from siblings like render_clip, edit_video, and list_ugc_creators by naming the workflow (start frame -> image-to-video -> clip). This is far beyond a tautology and gives the agent a precise model of what the tool produces.

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

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

The description gives explicit selection guidance: use a `creator` slug, `brief_name`, or inline `brief`; poll get_ugc_job_status after the async call; use render_clip with caption_preset when captioning is ready; and omit `ref` to generate a start frame. It also explains account-gating and quotas, so the agent knows when generation is allowed. This is excellent when-to-use and when-to-use-alternative guidance.

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

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

No annotations are provided, but the description carries the burden well: it identifies the operation as returning account/connection details and explains that it verifies credentials and credit availability. It doesn't mention error/expired-token behavior or whether it consumes credits, but the core behavioral contract 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?

One dense, front-loaded sentence listing return fields, followed by an actionable usage directive. No filler or repetition.

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

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

For a zero-parameter read-only endpoint, it fully describes what the agent gets (identity, plan, credits, scopes) and why to call it first. No output schema is present, but the description enumerates all meaningful return contents, so an agent can act on 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?

There are zero parameters, so schema cannot add meaning. Baseline 4 applies; the description properly focuses on the return payload instead of inventing parameter detail.

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 ('Return') and enumerates the exact contents: user id/email, team/plan, credits remaining, and granted scopes. This is clearly distinguished from render/status/job tools in the sibling list, so an agent knows exactly what this tool is for.

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

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

Explicitly says 'Use this first to confirm the connection works and the user has credits before submitting videos.' This gives the agent a concrete trigger condition and sequencing relative to submission tools.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral semantics: it is poll-only, 'completed' means a final render with a URL, 'failed' renders can be requested again, and completion is derived from the rendered clip rather than any intermediate flag. This is valuable behavior an agent cannot infer from the annotation alone.

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

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

The description is well-structured: it front-loads the purpose and required parameter, then uses a compact bullet list for status semantics. Every sentence adds useful information, and there is no filler or duplication of the schema beyond what is helpful.

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

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

The description covers the input IDs, optional narrowing, all status values, and the polling contract. An output schema exists, so return-value details need not be repeated. It does not explicitly mention how to trigger a render (e.g., via render_clip) when a status is 'failed' or 'not_rendered', but that is outside the tool's core responsibility and is inferable from the sibling list.

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 both parameters. The description repeats the hashid-from-list_videos hint and the optional narrowing behavior, but adds no new format, source, or validation details. Baseline 3 is appropriate given the high schema coverage.

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

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

The description states the specific resource ('the render state of a video's viral moments') and the action ('get'). It clearly distinguishes itself from sibling tools like get_video_status by focusing on render state and enumerating the exact statuses. The optional viral_moment narrowing further pins down the tool's scope.

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 polling guidance: 'This is poll-only: re-call until completed' and includes 'keep polling' under the rendering status. It does not explicitly name alternative tools or state when not to use this tool, but the polling context is clear enough for an agent to know when to invoke 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?

The description goes beyond the readOnlyHint annotation by detailing response behavior: returns `status`, `outputs` with CDN URLs on completion, and `error` on failure. It also explains the polling behavior and expected duration. This gives the agent a clear model of the tool's behavior without relying solely on annotations.

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

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

The description is concise and structured: it defines the purpose, enumerates possible statuses, outlines response fields, and provides polling guidance in three clear paragraphs. No wasted words; each sentence adds 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?

All necessary information for correct invocation is present: the tool's purpose, the parameter's source, response structure, and polling advice. Given no output schema, the description covers return values adequately. The tool's complexity is low with a single parameter, so this is 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 the parameter is fully documented. The description adds value by explaining what the parameter is (hashid from transcribe) and its role in the tool's purpose midpoint. It doesn't add format details but the schema already covers that.

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: retrieving the status of a free tool job by its `tool_job` id. It specifies the resource (tool job) and the action (get status), distinguishing it from sibling tools like `get_render_status` and `get_ugc_job_status` which are for different job types. The terminal states are also defined.

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

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

The description explicitly states when to use this tool: when polling a job created by `transcribe` (implied by the id source). It instructs to poll every 5-10s and stop polling on terminal states, providing clear usage context. It does not mention alternatives, but the tool is uniquely tied to free tool jobs, making it unambiguous among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: the overlap rule for time windows, the distinction between transcript_ready false and empty segments, and the untrusted_content warning. These go beyond annotations and inform safe, correct usage.

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 comprehensive but efficient. It front-loads the core purpose, then systematically explains parameters and edge cases. Every sentence adds value, and the structure logically moves from core function to specifics to security note. No fluff or repetition.

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

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

Given the tool's complexity (overlap semantics, readiness flag, untrusted content) and the existence of an output schema, the description covers all critical aspects an agent needs to call it correctly. It explains edge cases and safety considerations, making it complete for practical use.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds meaningful extra semantics: explains level options ('sentence' vs 'word'), clarifies start_ms/end_ms defaults and inclusive overlap behavior, and notes that times match list_clips, enabling direct reuse of clip windows. This enriches the schema without redundancy.

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 the tool's exact function: retrieving a video's transcript as time-coded segments by video id. It clearly specifies the resource (transcript) and the action (get), and differentiates from siblings like transcribe (which creates) and list_clips (which provides clip windows) by its focus on transcript retrieval and its connection to those 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?

Provides rich guidance on when to use the tool: how to slice time windows, overlap semantics, default behavior, and how to interpret transcript_ready vs empty segments. It also mentions integration with list_clips. However, it does not explicitly state when not to use it or name alternative tools (e.g., transcribe for generating transcripts if not ready), so there's room for explicit exclusion guidance.

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

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

Annotations already mark this as read-only, and the description adds rich behavioral detail: live `progress`/`progress_step` fields, terminal statuses, per-status payloads (`video_url`, `share_url`, `result_meta`, `error`), and a recommended polling cadence. No contradiction with annotations.

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

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

Every sentence adds operational value—statuses, progress semantics, terminal payloads, and polling timing—without redundant fluff. Front-loaded with purpose and id source.

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

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

No output schema exists, so the description must stand in for it; it covers all statuses, live progress, success/failure payloads, and polling behavior, enough for an agent to call and interpret 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?

The schema fully documents `ugc_job`; the description reinforces it with the useful facts that it's a hashid and is returned by generate_ugc. That's a small improvement over the schema, so above the baseline but not maximal.

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 ('Get'), the resource ('status of a UGC generation job'), and the exact input (ugc_job hashid), and it enumerates the possible status values. It's immediately distinguishable from other status tools like get_video_status and get_tool_job_status because the UGC-specific lifecycle is spelled out.

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 user-facing guidance: poll every 10-15s, stop on terminal states, and report progress. It also names generate_ugc as the source of the job id and marks rendering as in-flight, so an agent knows exactly when to keep polling vs. stop.

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

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

Annotations already mark readOnlyHint=true, so the description adds value by explaining credit accounting, field name legacy, and the structure of activity entries. It goes beyond the annotation to clarify exactly what data is returned and its semantics.

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 detailed but well-organized, with the core purpose upfront and explanatory detail in separate paragraphs. Each sentence earns its place; it could be slightly tighter but remains 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?

Since there is no output schema, the description fully specifies the return structure, field semantics, and parameter behavior. Nothing essential for invoking the tool correctly is missing.

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

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

Schema covers `limit` fully with a description matching the description text. The description repeats the range and default but adds no new meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Return') and resource ('team's credit usage'), defines the credit unit, and lists the returned fields. It is unique among siblings, and the purpose is unambiguous and immediately actionable.

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

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

Provides clear context on what the tool returns and how to control it via `limit`, but does not mention any alternative tool because none exists. The guidance is implied and sufficient for the intended use case.

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

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

Beyond the readOnlyHint annotation, it discloses the lifecycle (in-flight vs terminal), the meaning of pending_credits, when payment_required appears, and warns about untrusted_content. This is a rich behavioral model that adds far more than the annotation alone and does not contradict it.

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

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

The text is dense but orderly: the main action is first, then statuses, terminal transitions, and the untrusted-content warning. Every sentence contributes to effective invocation, so it earns a top score for structure and concision.

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?

It explains the one parameter, all output fields, status-to-action mapping, and the security note about untrusted_content. Given the output schema is present, the description still covers all external needs for a correct call and workflow handoff, making it complete.

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

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

The description repeats the video parameter's hashid provenance from the schema but adds no new semantics. Schema coverage is 100%, so by the rubric the baseline is 3 even with minimal parameter-specific description 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 exactly what the tool does: 'Get the processing status of one video by its video id'. It identifies the resource (video) and the referencing source tools (list_videos, submit_video), which clearly distinguishes it from sibling status tools like get_render_status or get_ugc_job_status.

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

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

It gives clear, actionable guidance: keep polling for in-flight statuses, stop for payment failures, proceed to list_clips after completion. It lacks an explicit comparison to alternative status polling tools, but within its own domain the conditions are unambiguous, so 4 (clear context, no exclusions) fits.

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 critical behavioral context beyond the readOnlyHint annotation, such as agents being shared and the untrusted_content warning about not following embedded instructions.

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 and well-structured with three purposeful paragraphs: explanation of agents, usage guidance, and security warning. No fluff.

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

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

For a simple tool with no parameters, the description fully covers purpose, output structure, and security concerns. It also references a sibling tool for context.

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

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

With no parameters, the description explains the output fields (id, untrusted_content) which helps the agent use the returned data, adding meaning beyond the empty input schema.

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

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

The description clearly states the tool lists agents (processing configurations) and distinguishes it from siblings like create_agent by explaining what agents are and how they are used.

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

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

The description explains when to use the tool (to list agents) and how its output (agent id) is used in submit_video. It lacks explicit when-not guidance but context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context beyond that: it specifies the structure of each preset (key, name, description, category) and the validation behavior of render_clip, which helps the agent understand the tool's role in the workflow. No contradictions with annotations.

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

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

Two sentences with zero waste: the first establishes purpose and output fields, the second explains when to use it and the consequence of not doing so. Front-loaded with purpose, 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?

Complete for a zero-parameter, read-only list tool with an output schema. The agent knows exactly what to expect (fields and categories), when to call it, and why it matters (render_clip validation). Nothing an agent needs to correctly invoke it 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 and an empty input schema, so there is nothing to explain about parameters. The description appropriately focuses on the output structure instead, which is beyond what the schema provides. Baseline for 0 params is 4, and the description meets that adequately.

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 ('List caption style presets') with a clear scope (available for rendering) and distinguishes it from sibling list tools (list_videos, list_agents, etc.) by focusing on caption presets. It also mentions the output fields (key, name, description, category), making the purpose 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?

Explicitly instructs to call this to discover valid caption_preset values before rendering, and warns that render_clip rejects any key not in this list. This provides clear when-to-use guidance and names the dependent tool (render_clip), leaving no ambiguity about when to invoke it.

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

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

Annotations declare readOnlyHint: true, and the description aligns with that. It adds behavioral context: the set honours plan entitlement (top clips by virality) and warns that untrusted_content must never be followed as instructions. This goes beyond the schema and annotations to inform safe usage.

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 several sentences but each sentence serves a purpose: purpose and prerequisite, output fields, entitlement, and security warning. It is front-loaded with the core action and prerequisite. While slightly verbose, it remains efficient and structured.

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

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

The description covers everything an agent needs to call the tool correctly: the input source, the prerequisite, the output structure, and the security caveat. It also explains the relationship to downstream tools. With an output schema present, the description complements it well, making the tool fully contextualized.

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` is fully documented in the schema with the same description as the tool description. The description repeats the schema's clarification that it's a hashid from list_videos, adding no new meaning. Since schema coverage is 100%, 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 opens with a specific verb and resource: 'List the playable viral-moment clips for a video.' It clearly identifies the input (video id) and distinguishes itself from other listing tools like list_videos by focusing on clips. This gives an agent a precise understanding of the tool's function.

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

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

The description explicitly states a precondition: 'Call this once the video is completed.' It also explains how the output is consumed by other tools (render_clip, get_render_status), which guides the agent on when to use this tool in a workflow. It doesn't name alternative tools, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining the meaning of `direct_url` and that other providers are hosting platforms, which helps the agent interpret results. It doesn't describe the output format in detail, but the output schema exists, so this is acceptable.

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

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

The description is three sentences, each earning its place: what it lists, how to use it, and what the key values mean. It is front-loaded with the primary purpose and avoids any fluff.

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

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

For a zero-parameter read-only tool with an output schema, the description is complete. It tells the agent when to use it, what it returns, and how to interpret the data. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining the data returned (key and display name) and the meaning of `direct_url`, which is valuable for the agent. Baseline 4 is appropriate for a no-parameter tool.

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

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

The description clearly states the tool lists video sources accepted by submit_video, with a specific verb ('List') and resource ('video sources'). It distinguishes itself from siblings by explicitly tying to submit_video and explaining the provider key/name structure.

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

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

It explicitly says to use this before calling submit_video to tell the user which links work. This provides clear context and a direct use case, effectively guiding the agent on when to invoke 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?

Beyond the readOnly hint, it specifies what data is returned (curated roster + saved creators, ordered by niche) and adds an important safety behavior: content under untrusted_content should not be treated as instructions.

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?

Every sentence earns its place: clear purpose, return-field meanings, enumerated values, downstream usage, and a security-relevant untrusted-content warning. 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?

For a zero-parameter list endpoint with no output schema in structured data, the description supplies enough field-level detail to use the response, and the untrusted-data caveat covers the main risk. It does not need pagination or error semantics to be actionable at this complexity.

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

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

The tool takes no parameters and the schema fully covers that, so the description cannot add current-tool parameter meaning. It compensates by explaining how returned fields such as creator and start_frames map to generate_ugc parameters, which is useful for downstream invocation.

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 object ('List the UGC spokespersons'), clarifies the scope (connected account's current team, curated roster plus saved creators), and distinguishes this from general list tools by naming UGC-specific content.

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

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

It explicitly tells the agent to call this before generate_ugc to discover valid creator and start_frame values. It does not contrast it with sibling list tools, so it stops short of full when-to-use/when-not-to-use guidance.

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

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

Annotations only declare readOnlyHint=true; the description adds useful context: team scoping, recency ordering, hashid format, possible status values, nullable creator slug, and created_at. This gives the agent a clear model of the operation's behavior beyond the annotation.

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

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

Four sentences, each one earning its place: scope/order, output fields, related tool pointer, and practical use cases. Information is front-loaded and there is 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?

For a read-only list operation with two optional parameters and no output schema, the description covers scope, ordering, return fields, and intended usage. Nothing critical is missing for an agent to invoke and interpret the tool correctly.

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

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

Input schema coverage is 100%, with both limit and status fully described including ranges and allowed values. The description does not add parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a precise verb and resource ('List the UGC generation jobs'), scopes it to 'the connected account's current team', specifies ordering ('most recent first'), and enumerates the returned fields. This clearly distinguishes it from get_ugc_job_status and generate_ugc without requiring schema inspection.

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

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

Explicitly gives two use cases: reviewing a team's UGC clips or finding a job id to poll. It also points the agent to get_ugc_job_status as the next step, but it does not explicitly contrast with sibling list tools like list_clips or list_videos.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds valuable behavioral context: status lifecycle semantics (in-flight, paused, terminal), and a security-relevant warning that untrusted_content is source-derived text that must never be treated as instructions. This goes well beyond what the annotations provide.

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

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

The description is front-loaded with the core action, then provides compact, high-value details about return fields, entry-point usage, status semantics, and the untrusted-content warning. Every sentence earns its place, and nothing is redundant with the schema or annotations.

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

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

For a read-only list tool with two optional parameters and an output schema, this description is complete: it explains what to do first, how to interpret statuses, what the returned fields mean, and how to handle untrusted content. No critical caller behavior is left unspecified.

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 semantic value beyond the schema by explaining what the status values mean (in-flight vs terminal, pending_credits paused) and what guidance to seek for paused videos. It does not add much for limit, but the schema already fully documents that parameter.

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

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

The description states a specific verb and resource ('List the videos in the connected account's current team'), adds ordering ('most recent first'), and describes what each entry includes. It also positions itself as the entry point for discovering video ids, distinguishing it from other video-scoped tools in the sibling list.

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

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

The description explicitly states when to use this tool: 'call it to discover video ids before using any other video-scoped tool.' It also routes the agent onward by telling it to call get_video_status for recovery guidance when videos are in pending_credits, giving concrete when-to-use and alternative-tool guidance.

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

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

Annotations are empty, so the description carries the full burden. It discloses that the tool is free, requires only an account, is asynchronous (returns tool_job and status 'queued'), is rate-limited per day, has a per-file size cap, and explains how errors indicate limit lifting. This is exhaustive behavioral context beyond any structured data.

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

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

The description is long but every sentence earns its place: it opens with the core purpose and output, then moves to workflow, async behavior, and limitations. It is logically ordered and front-loaded with the most critical information, with no fluff or redundancy.

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

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

Given the tool's complexity (async job, upload flow, rate limits), no annotations, and no output schema, the description covers everything an agent needs: how to call it, what to expect, how to poll, and what constraints apply. Nothing essential 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?

Although the schema covers the file parameter with 100% coverage, the description adds substantial meaning by explaining the provenance of the hashid (from create_upload, without complete_upload) and the exact workflow to obtain it. This enriches the parameter's semantics beyond the schema's concise note.

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'), a resource ('background from an already-uploaded image'), and the output ('transparent PNG'). It also references the upstream create_upload flow and distinguishes itself from sibling tools like complete_upload and edit_image by explicitly disclaiming the paid pipeline and noting it reads the file directly.

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

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

Provides explicit step-by-step instructions for local files (create_upload → PUT bytes → pass id) and a clear exclusion: 'Do NOT call complete_upload (that starts the paid clip pipeline).' It also directs the agent to poll get_tool_job_status until completion, covering the full usage lifecycle.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly reveals that rendering is asynchronous, that existing renders are replaced, that in-flight renders are idempotent, and what not_dispatched indicates.

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 well-structured and front-loaded: purpose, explicit behavior, async instructions, retry semantics, and failure meaning. Every sentence adds necessary information 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?

For an asynchronous tool with two required string ids and one optional preset, it covers dispatch, polling, replacement, retries, and preconditions. Return-value details are appropriately deferred to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces that both ids are hashids from list_clips and that caption_preset supports preset keys, but it does not add substantial meaning beyond the schema's already explicit parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Produce a final captioned render of one viral moment.' It clearly distinguishes this action tool from read-only siblings like get_render_status and list_clips by framing it as an explicit, on-demand render.

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

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

It gives explicit when-to-use and when-not-to-use guidance: call this to (re)render now, and use get_render_status or list_clips to just read an existing render. It also covers safe retry behavior and the meaning of not_dispatched.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond the annotation: it returns 'the most relevant documentation pages with their title, canonical URL, and a short matching excerpt,' clarifying the tool's output and behavior during invocation.

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

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

Two sentences, both information-dense. The primary purpose and usage condition are front-loaded, followed by a succinct return-value description. No filler or redundancy.

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

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

For a simple read-only search tool with two well-documented parameters specificed in the schema and no output schema, the description covers the key decision context (when to invoke), the behavior, and the return shape. Nothing material is missing for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents 'query' and 'max_results'. The description does not add parameter-level detail, but it does not need to—the baseline of 3 applies here because the schema already carries the semantic weight.

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: 'Search the OpenClip product documentation.' It immediately distinguishes this tool from all sibling tools (none of which are documentation-related) and states exactly what it does in one clear sentence.

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 an explicit invocation condition: 'Call this before answering questions about OpenClip features... when the answer is not already present in the conversation.' This tells the agent both when to use the tool and when not to, which is strong usage guidance for a retrieval tool.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses that the tool verifies the uploaded image exists, enforces a 2 MB limit, attaches the logo, returns a public logo_url, and errors if the upload has not happened yet.

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 tightly written, front-loads the prerequisite flow, and packs the key behavioral and routing details into a few sentences without redundancy. 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 two-parameter tool with no output schema, the description covers the full call sequence, return value, failure mode, retry guidance, size limit, and the relevant alternative for watermark configuration. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful flow-level semantics: logo_key must be the value returned by create_agent_logo_upload, and the upload URL must be used before calling this tool. This goes beyond the schema's field-level descriptions.

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

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

The description clearly states a specific verb and resource: finishing an agent's logo attachment after the upload step. It also distinguishes itself from the sibling create_agent_logo_upload by framing this as the follow-up step.

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

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

It explicitly says when to use the tool: after calling create_agent_logo_upload and PUT-ing the image bytes to the upload URL. It also provides an error-recovery path (upload then retry) and routes watermark placement control to update_agent via composition_parameters, covering the main alternative.

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?

Rich behavioral disclosure: async processing returns status immediately, parking in pending_credits, payment failure details, dedup behavior, failed-url retry semantics, and unsupported-agent/URL rejection. Even though annotations are empty, the description fully discloses what happens in each outcome path.

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

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

The description is long but earned: every paragraph covers a distinct concern (purpose, async behavior, dedup, errors). Key claims are front-loaded in the first sentenceaiman. It uses consistently formatted inline code (url), makes repetitive semantics (deduplicated, pending_credits) coherent, and avoids redundancy across paragraphs.

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

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

Given the tool has an output schema, the description need not list return fields, but it still covers the critical runtime concerns: poll destination, payment-repair path, retry behavior, and agent validation. An agent has everything needed to invoke it correctly with zero additional lookups.

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

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

Schema coverage is 100% with clear descriptions, and the tool description goes beyond: it explains that `agent` controls processing/rendering defaults and is checked for team membership, that `url` must be from supported providers (exhaustive list), and that `title` defaults to source title. This adds operational meaning beyond schema type/required flags.

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 ('Submit a source video URL') and states the core action: turn the source into viral clips, with acceptable providers enumerated. It also mentions the returned id/status which is the key artifact of submission. This clearly differentiates from siblings that edit, generate, or convert media.

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

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

Explicitly names sibling tools (edit_video, generate_ugc, remove_background, convert_media) as alternatives for other video tasks, telling the agent when NOT to use this tool. It also provides clear guidance on polling get_video_status and not polling pending_credits, as well as dedup/retry semantics. No ambiguity remains about when to invoke this tool.

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

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

Annotations are empty, so the description carries the full burden, and it excels: it discloses asynchronous processing ('returns a tool_job hashid and status: queued'), polling expectations, output formats (json/srt/vtt URLs), free/rate-limited nature, file caps, and the non-substantive 'nudge' field. This is rich context that goes beyond what any structured field could provide.

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 structured into four clear paragraphs: core purpose, upload setup, async processing, and limits/notes. Every sentence adds necessary context—no filler—and the main 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 tool involving upload state, async job polling, and rate limits, the description covers everything an agent needs: how to prepare input, how to avoid the wrong pipeline, how to retrieve results, and what to do on rate limits. No output schema exists, but the description explains the return shape sufficiently.

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

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

Schema coverage is 100% and the schema descriptions already explain each parameter ('e.g. "en", omit to auto-detect', 'Defaults to true', 'from create_upload ... or list_videos'). The description essentially restates this same information, adding pipeline context but little new parameter-level meaning. Baseline 3 is appropriate given 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 opens with a specific verb and resource: 'Transcribe an already-uploaded video ... into time-coded text.' It clearly differentiates from the paid clip pipeline by explicitly warning 'Do NOT call complete_upload for transcription,' and from other siblings like get_transcript by framing this as the job-starting tool.

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

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

Provides explicit when-to-use and when-not-to-use guidance: it says to use create_upload for local files, not to use complete_upload because that starts the paid pipeline, and to poll get_tool_job_status for results. It also covers optional parameters and rate-limit conditions, so an agent knows exactly how to select and invoke this tool.

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

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

Annotations are empty, so the description must carry behavior alone. It discloses partial-update behavior, the id source, the return value, the team restriction, and how nested overrides merge, plus the custom personality requirement. It does not mention error behavior or reversibility, but covers the key operational facts.

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?

Well organized: purpose first, then the partial-update rule, then the field list, then the scope restriction. No wasted sentences. Slight redundancy with schema (e.g., personality enum) but it adds eligible-value context, so it 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 mutation tool with no annotations and no output schema, the description covers partial-update semantics, return value, team scoping, required custom description, and nested-object mutation rules. It lacks explicit error/reversibility caveats, but for an update endpoint the essentials are 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 already describes every parameter well at 100% coverage Mend. The description adds real value: the agent id is a hashid from list_agents, omitting fields preserves them, personality presets are enumerated, custom requires caption, and unknown nested keys are rejected. This exceeds the baseline for fully-covered schemas.

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

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

Description opens with a precise verb+resource statement: 'Update one of the team's agents.' It clearly identifies the operation, the target resource, and what differentiates it (modifying existing agents) from sibling tools like list_agents or create_agent.

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

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

Gives clear usage context: pass an agent id from list_agents, partial update semantics (only provided fields change), and a team-scope restriction. It points to helper tools (list_agents, describe_agent_settings) but never explicitly says when not to use it or contrasts with create_agent.

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