OpenClip

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

Goes well beyond the annotations by disclosing metering (2 free per month, paid unlimited), idempotency (re-captioning the same video doesn't recount), the asynchronous state machine (processing/rendering/not_dispatched), polling cadence and deadline, and a bounded recovery call. This is exactly the operational context annotations cannot carry.

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?

Purpose and routing are front-loaded and the async rules are bulleted, so it is navigable. It is nonetheless very long with some repetition in the polling/recovery instructions, leaving room to tighten.

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 an output schema exists, return values need not be explained; the description instead covers the async lifecycle, error/terminal states, metering, and retry/recovery policy. An agent has everything needed to call it and interpret results 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 two parameters are already documented; the description mostly restates video/preset sources but adds the non-obvious workflow constraint that create_upload does not require complete_upload first. That workflow nuance is the only genuine added value over the schema.

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

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

States a specific verb, resource, and scope: 'Caption a whole short video (up to 3 minutes) in a caption_preset and get back a captioned MP4.' It explicitly distinguishes itself from the sibling render_clip by noting that clip-pipeline videos are captioned per clip, so an agent can tell the two apart without opening either schema.

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

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

Gives explicit routing: use it 'for a finished short video or a UGC clip,' source uploads via create_upload (with an explicit 'Do NOT call complete_upload' exclusion), and names render_clip as the alternative for clip-pipeline videos. Both when-to-use and when-not-to-use are spelled out.

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

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

Annotations only declare the generic write/safety profile (readOnly=false, destructive=false, openWorld=false). The description adds substantial context beyond that: it queues processing, returns id and status, the final outcome is settled asynchronously (processing or pending_credits on out-of-credit teams), and it errors if bytes were not uploaded. That is the async, credit-gated behavior an agent must know.

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?

Front-loaded with the action, then prerequisites, return values, and the error/retry case, each in a compact sentence. 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?

With no output schema, the description carries the burden of describing returns and does so (id and current status), plus the async settling behavior and the credit-gated outcome. Nothing an agent needs to invoke or interpret this call is missing.

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

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

Schema description coverage is 100% and the single parameter's schema text nearly duplicates the description's explanation, so the description adds little parameter-level detail. The only extra value is the sequencing constraint (PUT bytes before passing the id), which borders on usage rather than parameter semantics. 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+resource ('Finish an upload started with create_upload and begin processing') and immediately ties itself to the sibling that precedes it. An agent can distinguish it from create_upload and submit_video without opening any schema.

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

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

Gives explicit preconditions ('AFTER you have PUT the file bytes to its upload_url'), names the creating sibling (create_upload), and routes status checking to another sibling (poll get_video_status). It also states the failure case ('If the file hasn't been uploaded yet, an error is returned: upload it, then retry').

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 non-read-only, non-destructive, and closed-world, but the description adds substantial operational context: the operation is free and needs no subscription, returns a queued tool_job asynchronously, requires polling get_tool_job_status, and is rate-limited daily with per-file size and duration caps. It also explicitly separates this free path from the paid complete_upload clip pipeline.

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 purpose and format list, then gives the local-file workflow, gif options, and asynchronous behavior in a logical sequence. Each section earns its place by covering cost, prerequisites, polling, and limits for a multi-step conversion tool.

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

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

With no output schema, the description carries the full return-value burden and does so by explaining the tool_job hashid, queued status, polling requirement, and final downloadable URL. It also covers free-tier rate limits and error behavior, making the definition complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description clarifies file provenance and gif-only fps/width behavior, but the schema already documents required fields, format options, and gif defaults, so the description adds little parameter-specific 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?

The description states a specific verb and resource: convert an uploaded file to another format, enumerating video, gif, and audio targets. It explicitly distinguishes this from create_upload and complete_upload, so an agent can identify when this tool applies without opening the schema.

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

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

It gives explicit workflow guidance for local files, including create_upload, PUT to upload_url, then this tool, and warns 'Do NOT call complete_upload' because that starts the paid clip pipeline. It also names get_tool_job_status as the required polling tool for asynchronous completion.

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 cover the safety profile (not read-only, not destructive, closed world), and the description adds real value beyond them: team-wide sharing semantics, the id (hashid) return, the plan-limit failure mode, and that repurpose_textual_content costs 1 credit per minute charged once per video. Remaining gap is what happens to skipped/omitted fields on defaults, though composition_parameters defers to describe_agent_settings.

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

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

Two tight paragraphs, front-loaded with the definition and the required parameter before optional detail, and the return/failure note closes it. Minor redundancy in re-listing the personality_preset values that the schema already enumerates.

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

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

With no output schema, the description correctly states the return (new agent id/hashid) and the failure mode, and it delegates the nested rendering/caption objects to describe_agent_settings. For a 7-param tool with nested objects this is nearly complete, though the deferral leaves composition_parameters fully opaque in this definition.

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 still adds cross-tool routing (caption_preset comes from list_caption_presets, composition_parameters/caption_style_overrides from describe_agent_settings), the conditional requirement on custom_personality_description, and the credit cost of the repurpose flag. It does partly restate the personality_preset enum already in the schema.

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

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

States a specific verb+resource ('Create a processing agent') and immediately defines what an agent is — a saved team-shared configuration controlling video processing/rendering. This clearly separates it from list_agents, update_agent, and submit_video without opening any schema.

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

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

Gives the required/optional parameter split, the conditional rule for custom_personality_description, and a failure condition (plan's agent limit). It implies creation-versus-modification via the sibling set but never explicitly says 'to change an existing agent use update_agent'.

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

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

Annotations only establish that this is a non-destructive write operation. The description adds the real behavioral context: presigned upload_url and logo_key are returned, a single HTTP PUT with no extra headers is required, the url expires (expires_in_seconds), the image is capped at 2 MB, and the size is re-checked later at set_agent_logo.

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?

Front-loaded with the purpose, then the required arguments, the return contract, and a concrete curl example. Every part is useful, though the sequence runs a few sentences long and the inline example could be trimmed 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?

No output schema exists, so the description compensates by naming the return values (upload_url, logo_key, expires_in_seconds) and describing the full upload-then-attach lifecycle. For a multi-step presigned-upload tool, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it identifies the agent id as a hashid from list_agents, enumerates the allowed content_type values in prose, and clarifies the optional size param is rejected up front. Only the size/filename handling overlaps with the schema.

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

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

States a specific verb and resource ('Start uploading a logo image for one of the team's agents') and immediately scopes it to the watermark feature tied to composition_parameters.logo_watermark_enabled. Clearly distinguishes this from set_agent_logo, which is named 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?

Gives an explicit end-to-end flow: call this tool, PUT the raw bytes, then call set_agent_logo with the same agent and logo_key. It also names list_agents as the source of the agent hashid, so the agent knows exactly when and how to use this versus the sibling.

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false); the description supplies the operationally critical facts beyond that: the return is not a completed upload, a separate HTTP PUT is required, the 5 GB PUT limit, that uploading alone spends no credits or starts no processing, and an explicit anti-fabrication warning. That is substantial context the annotations cannot convey.

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?

Front-loaded with the single most important fact (this returns an id and upload URL, not a completed upload), and most sentences carry actionable information. It is dense and runs long, with some safety boilerplate ('Never invent file bytes') that could be tightened, but nothing is truly wasted.

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 though an output schema exists, the description goes further by explaining the two-step PUT workflow and the downstream tool routing, which an output schema alone could not express. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so the four parameters (size, filename, content_type, audio_language) are already fully documented in the schema. The description adds essentially no per-parameter detail beyond restating the 5 GB limit and referring to the returned `video` id being passed as another tool's `file` argument. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create an upload for a video, audio file, or image') and immediately disambiguates from the sibling complete_upload by clarifying it does not produce a finished upload. An agent can tell exactly what this produces (an opaque `video` id plus a presigned PUT URL) without opening any schema.

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

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

Gives explicit routing: which follow-up tool to call per media type (caption_video, complete_upload, transcribe, edit_video, convert_media, extract_thumbnails, edit_image), an explicit when-not ('complete_upload ONLY for the paid video clipping pipeline', 'Media utilities and caption_video do NOT need complete_upload'), and a fallback path for clients without file transfer. This is a model of alternative selection 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 establish the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context beyond them: both objects are closed sets so unknown keys/out-of-range values are rejected with feedback, caption fields inherit from caption_preset rather than having their own defaults, and color fields accept any CSS string. It stops short of describing output shape, but that is a minor gap given annotations cover safety.

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 core purpose, return shape, and call-order directive are front-loaded, and the Notes block is broken into scannable bullets that each carry distinct information (closed-set rejection, field vs additional_fields, default inheritance, logo exclusion). It is somewhat long, but no sentence is 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?

There is no output schema, so the description must explain the return value, and it does so thoroughly (per-setting fields, types, enum values, bounds, units, defaults). Combined with zero parameters and full annotation coverage, nothing an agent needs to call this discovery 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?

With zero input parameters, the baseline of 4 applies. The description instead characterizes the returned field metadata (type, values, min/max, unit, default, description), which primes the agent for what it will receive, though this is arguably output semantics rather than parameter semantics.

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

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

The description names a specific verb (describe) and resource (nested agent settings), and explicitly scopes what it covers: composition_parameters and caption_style_overrides. It also distinguishes itself from siblings by tying the call sequence to create_agent/update_agent, so an agent can tell it apart from list_caption_presets or search_docs.

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 an explicit directive: 'Call this BEFORE setting either object so you use real field names and valid values.' It further routes the agent away from expecting a logo field here, naming the logo-upload tools as the correct path instead, which is exactly the when-not guidance the dimension asks for.

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 mark it as non-read-only/non-destructive; the description adds substantial behavior beyond them: asynchronous execution returning a tool_job hashid with status 'queued', the required polling loop via get_tool_job_status, per-day rate limits, a per-file size cap, and self-explaining limit errors.

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?

Front-loads purpose and the free/paid distinction, then workflow, then per-operation params, then async behavior. Well-organized with bullets, though slightly dense and mildly repetitive about the free path.

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

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

For an async tool with no output schema, it fully covers what an agent needs: input flow, operation params, the queued job return shape, how to poll for completion, and where the final output URL appears.

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 already 100%, so the baseline is 3. The description adds real value by grouping parameters per operation (compress: quality/format; resize: width/height/optional format; crop: aspect OR x/y/width/height) and clarifying the mutually exclusive crop inputs, which the flat schema does not express.

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 image file') and enumerates the three operations (compress, resize, crop). It is readily distinguishable from siblings like edit_video and complete_upload by naming image editing and the operations it covers.

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 context (free, only needs an account, no subscription) and an explicit exclusion: 'Do NOT call complete_upload (that starts the paid clip pipeline).' It also prescribes the exact alternative workflow (create_upload, PUT bytes, pass id) and routes polling to get_tool_job_status.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: the operation is FREE with no subscription, processing is asynchronous and returns a tool_job hashid with status queued, and free usage is rate-limited with per-file size/duration caps. It does not, however, state whether the original file is preserved or overwritten by an edit, which is the one behavioral question left open for a mutation tool.

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

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

Front-loads the purpose and the operation list, then the usage workflow, then a per-operation param block. Every section is useful, though the per-operation param list partially duplicates the schema descriptions, adding length without new information in a few spots.

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

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

With no output schema, the description carries the return-value burden and does so: it explains the tool_job hashid, the queued status, the polling target, and where the downloadable URL eventually appears. Rate limits and error behavior are also flagged, so nothing an agent needs to call and complete this workflow 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 baseline is 3, but the description earns credit by mapping parameters to operations (e.g., trim requires start_ms and end_ms; rotate takes degrees and/or flip; compress takes target_mb OR crf) in a way the flat schema does not express. It stops short of documenting the crf range or aspect enum in the prose, leaving some detail to the schema.

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

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

States a specific verb (edit) and resource (already-uploaded video file), then enumerates the six supported operations (crop, trim, rotate, resize, compress, mute). An agent can distinguish this from edit_image and convert_media purely from the text.

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

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

Gives an explicit workflow for local files (create_upload -> PUT bytes -> pass id here) and explicitly instructs NOT to call complete_upload, naming the consequence (starts the paid clip pipeline). It also names the follow-up tool (get_tool_job_status) and the condition for polling.

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 mark it as non-read-only and non-destructive; the description adds the critical traits an agent cannot infer: it is asynchronous, returns a tool_job with status queued, requires polling, is free with no subscription, and is rate-limited with per-file size and duration caps. That is rich behavioral disclosure beyond structured fields.

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

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

Front-loads the core action and the free/no-subscription fact, then proceeds in logical order: input source, workflow, parameters, async behavior, limits. Multi-sentence and somewhat dense, but each sentence carries actionable information; slight length keeps it from a 5.

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

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

With no output schema, the description compensates by describing the return (a tool_job hashid and queued status), the completion path via get_tool_job_status, and the final downloadable zip output. Nothing needed to invoke and follow through correctly is missing.

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

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

Schema coverage is 100%, so file/count/width are already documented with ranges and defaults. The description restates count (1-10, default 1) and width scaling but adds no syntax or format detail 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+resource ('Extract one or more evenly-spaced thumbnail frames'), names the input source (video hashid from create_upload or list_videos), and explicitly distinguishes itself from complete_upload. An agent can tell exactly what this does and where its input comes from without opening another schema.

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

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

Gives an explicit end-to-end procedure (create_upload -> PUT bytes -> pass id here), an explicit exclusion ('Do NOT call complete_upload; that starts the paid clip pipeline'), and names the follow-up tool (get_tool_job_status) for polling. Conditions for use and non-use are both covered.

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?

The readOnlyHint annotation already establishes this is a safe read, and the description adds substantial context beyond it: the full meaning of each status value, the fact that completion is derived from the rendered clip rather than an intermediate flag, and the cadence/terminal conditions for polling. This is exactly the behavioral detail an agent needs for a long-running render flow.

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?

Front-loads the purpose in the first sentence, then uses an efficient indented list for the status enum values and a compact paragraph for polling rules. Every sentence carries actionable information and nothing is repeated across sections.

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

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

Despite the output schema existing, the description goes further by enumerating the status values and their implications, which is the part of the response semantics an agent must reason about. With annotations covering safety and the schema covering inputs, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents that `video` comes from list_videos and that `viral_moment` narrows the result. The description restates this without adding format, syntax, or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource: it retrieves the render state of a video's viral moments, scoped to a video id and optionally a single moment. This is clear enough to separate it from the other status tools (get_video_status, get_tool_job_status, get_ugc_job_status), but it never explicitly contrasts itself against them, so an agent must infer which status tool applies to which resource.

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 operational context: pass the video hashid from list_videos, optionally narrow to one viral_moment. The polling rules are unusually explicit (poll every 10-15s only while `rendering`, stop on the other states, give up after 15 minutes). It stops short of naming an alternative tool to use instead, which is the only missing piece for a 5.

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

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

Annotations only cover safety (read-only, non-destructive, closed-world). The description adds substantive behavior beyond that: the full status enum with polling semantics, what each terminal state returns (outputs/result_meta vs error), and that output URLs are permanent CDN links. That is rich polling-behavior context the schema does not carry.

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?

Front-loaded with the core action, then status semantics, then return shapes, then polling guidance. Every sentence carries new information; 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?

With no output schema, the description carries the burden of return values and does so well (status enum, outputs, result_meta, error). Minor gap: no explicit contrast with the sibling status tools to route the agent 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?

Only one parameter and schema coverage is 100%, so the schema already documents tool_job. The description restates that it is the hashid from the creating tools but adds no format or validation detail beyond the schema.

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

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

Specific verb+resource ('Get the status of a free tool job') and it names the exact id source and the producing siblings (transcribe, edit_video, convert_media, extract_thumbnails, edit_image). It is clearly distinguishable from get_render_status, get_ugc_job_status, and get_video_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?

Gives concrete polling cadence ('every 5-10s'), states that processing means keep polling and that failed/completed are terminal, which is exactly when-to-use/when-to-stop guidance. It does not explicitly contrast with the sibling status tools, so it falls short of a 5.

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

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

Annotations declare a safe read, and the description adds substantial context beyond them: overlap-based range semantics, the meaning of transcript_ready independent of the window, the empty-segments-with-ready=true case, and a prompt-injection warning about untrusted_content.

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?

Front-loaded with the core action, then organized into a labeled 'Range semantics' block and a behavioral note. Dense but every sentence earns its place; no restatement of the schema.

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

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

With an output schema present, the description does not need to explain return values, yet it still covers the ambiguous cases (ready-vs-empty, overlap semantics) and the safety warning. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new meaning: that any segment OVERLAPPING the window is returned, and that times match list_clips windows. It also explains the start-only/end-only cases, which the schema's 'defaults' phrasing does not.

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 ('Get the transcript of a video by its video id'), names the id source (list_videos), and the return shape (time-coded segments). An agent can distinguish it from siblings like transcribe or get_video_status without opening the schema.

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

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

Explicitly routes to get_video_status to check processing state before waiting, references list_videos for the id and list_clips for time compatibility, and describes how to omit/pass bounds for different window behaviors. Clear when-to-use and how-to-interpret-empty-result 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the credit economy (one credit = one minute of source video, AI UGC billed per second of output) and the signed-delta convention for activity entries.

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 purpose and credit semantics before drilling into return fields. It is long, but the dense field enumeration is justified because no output schema exists; only the restated `limit` range is mildly redundant.

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

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

With no output schema, the description carries the full burden of documenting the return shape and does so thoroughly: credits_remaining, trial_credits_remaining, and every field of each activity entry including the legacy field-name caveat. Nothing an agent needs to interpret the response is missing.

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

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

Schema description coverage is 100% and the single `limit` parameter is fully documented in the schema with the same range and default the description repeats. The description adds no syntax or format information beyond that, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ('Return the team's credit usage') and immediately defines what a credit means, so the tool's purpose is unmistakable. It does not differentiate from the potentially adjacent get_account sibling, which the rubric requires for a 5.

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

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

Usage is only implied – an agent can infer this is the tool to call when it needs the team's remaining balance or recent credit activity. There is no explicit when-to-use statement and no mention of alternatives such as get_account, so the guidance is adequate but thin.

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 readOnlyHint already covers the safety profile, but the description adds substantial behavior beyond it: the polling contract per status value, the payment_required/billing_url recovery path, and an explicit prompt-injection warning about untrusted_content being display-only. It stops short of describing rate limits or caching, so a 4 rather than a 5.

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

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

Front-loads the purpose, then walks status semantics in a compact line-per-group structure, ending with the untrusted_content safety note. No sentence is redundant and the actionable instruction (poll / stop / call list_clips) is easy to extract.

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

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

An output schema exists, so the description was not obliged to explain returns, yet it goes further by interpreting each status value for decision-making. Combined with the polling guidance and the next-step tool, an agent has everything needed to drive this tool in a loop correctly.

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

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

Schema coverage is 100% for the single `video` parameter and the schema already documents it as the hashid returned by list_videos or submit_video. The description restates that provenance without adding format, validation, or alternative-input detail, so this is the baseline case where the schema does the work.

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 (get) and resource (processing status of one video), and immediately scopes it to a single video identified by a hashid. This cleanly separates it from the many sibling status tools (get_render_status, get_tool_job_status, get_ugc_job_status) by naming exactly which job class it covers.

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 tells the agent which states are in-flight ('keep polling'), which one means stop polling (pending_credits), which are terminal, and what to call next when completed (list_clips). It also names the upstream tools that produce the id (list_videos, submit_video), giving the full call sequence.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), but the description adds substantial context beyond them: agents are shared across the team, the id is a hashid, and name/caption_preset are untrusted user-authored content that must be shown but never followed. The prompt-injection warning is genuinely valuable behavioral disclosure.

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

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

Front-loads the definition of an agent, then the usage pattern, then the security caveat. Every sentence earns its place with no redundancy.

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

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

With no output schema, the description still names the key returned fields (id, name, caption_preset, and their untrusted_content nesting). Nothing an agent needs to correctly call and interpret this tool 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 takes zero parameters, so the schema fully covers its (empty) input contract and the baseline is 4. The description instead clarifies the related `agent` argument of submit_video and the returned id's role, which is useful but not a parameter of this 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?

States a specific verb (List) and resource (agents) and immediately defines what an agent is (saved rendering configuration with caption preset and defaults). It distinguishes itself from nearby siblings like list_caption_presets and describe_agent_settings by explaining the team-shared configuration concept.

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

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

Explicitly ties usage to the sibling tool: pass the agent's `id` as the optional `agent` argument to submit_video, or omit it to use the team default. The trigger condition is stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful downstream constraint that render tools reject unknown keys, but beyond that it discloses no pagination, ordering, or completeness behavior for the returned list.

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

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

Three tight sentences, front-loaded with the purpose and followed by the return shape and the routing/validation advice. No filler or restatement of the name/title.

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

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

Despite an output schema existing, the description complements it by naming the fields and, more importantly, closing the loop on where the keys are consumed. For a zero-parameter discovery tool, everything an agent needs to select and use it is present.

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

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

The tool takes zero parameters, so the baseline is 4 and the schema has nothing to document. The description adds value not present in structured data by explaining what a preset `key` is for and that it maps to the `caption_preset` argument of other tools.

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 the caption style presets available for rendering') and even enumerates the fields of each returned item (key, name, description, category). An agent can immediately distinguish this discovery tool from other list_* siblings like list_clips or list_agents.

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 when to call it: 'Call this to discover valid `caption_preset` values before rendering.' It also names the consuming tools (render_clip, caption_video) and gives the reason — both reject keys not in this list — so there is no ambiguity about why or 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 readOnlyHint annotation, it discloses the entitlement constraint ('honours the team's plan entitlement (top clips by virality)'), describes the shape and semantics of returned fields, and adds a safety directive about untrusted_content never being followed as instructions. That is substantive context an agent cannot get from the annotation or 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?

Three short paragraphs, each front-loaded and purposeful: what it lists and the precondition, what each clip contains and where the id is consumed, and the untrusted-content caution. No sentence is filler.

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

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

An output schema exists, and the description still adds the pieces the schema cannot convey: the completed-video gate, entitlement scoping, and the injection-safety rule. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already defines `video`. The description reinforces that it is a hashid sourced from list_videos, which is mildly useful but largely duplicates the schema description; baseline 3 applies.

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

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

States a specific verb and resource ('List the playable viral-moment clips for a video') and immediately scopes it by input ('by its `video` id (a hashid from list_videos)'). It is clearly distinguishable from the sibling list_videos, which is cited as the source of the id.

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

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

Gives an explicit precondition: 'Call this once the video is `completed`.' It also points to render_clip and get_render_status as downstream consumers of the clip id. It does not state when NOT to use it or name a competing alternative, so it falls short of the 5 bar.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds the return shape (title, canonical URL, matching excerpt), which matters since there is no output schema, but it says nothing about result limits beyond the param or about behavior on empty results.

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

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

Three sentences, front-loaded with the purpose, then the trigger condition, then the return contract. No filler or repetition of schema content.

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

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

For a two-parameter read-only search with no output schema, the description covers purpose, invocation conditions, and return format. An agent has everything needed to call it correctly without additional context.

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

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

Schema description coverage is 100%: both 'query' and 'max_results' (including the 1-10 range and default of 5) are fully documented in the schema. The description adds no query syntax, phrasing, or result-handling guidance beyond that, so the 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 (Search) and resource (OpenClip product documentation) with a clear scope. No sibling tool covers documentation lookup, so the agent can distinguish it immediately.

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

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

Gives an explicit trigger ('Call this before answering questions about OpenClip features, settings, workflows, integrations, or troubleshooting') plus a when-not condition ('when the answer is not already present in the conversation'). Nothing about when to invoke it is left to inference.

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

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

Beyond the annotations, it discloses the 2 MB limit, that it verifies the upload exists, that it returns a public logo_url, and the error behavior (retry after uploading). It does not explain the destructiveHint=true implication (whether an existing logo is replaced), which is the one notable gap.

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

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

Front-loaded with the core action, then the prerequisite chain and limits. Slightly long due to the multi-step workflow, but each sentence carries actionable information and none is redundant.

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

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

With no output schema, the description supplies the return value (public logo_url), the failure mode, the size constraint, and the follow-up for watermark control. An agent has everything needed to invoke it correctly in sequence.

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, and the description earns above that by clarifying the derivation and ordering of both params – logo_key must come from create_agent_logo_upload after the image bytes are PUT. This adds workflow meaning beyond the schema text.

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

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

States a specific verb+resource ('Finish setting an agent's logo') and precisely positions itself relative to the sibling it depends on ('after uploading the image with create_agent_logo_upload'). An agent can distinguish this finish step from the upload step without opening either schema.

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

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

Explicitly states when to use it (after the image upload + PUT to upload_url), names the preceding tool, and routes the agent elsewhere for a related concern ('use composition_parameters.logo_watermark_* via update_agent'). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does so richly: asynchronous processing, possible pending_credits pause with payment_required/billing_url, dedup with a 24h window, retry-after-failure, and rejection of invalid URLs or foreign agents. It discloses side effects and failure modes 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?

Dense but well-structured, with purpose front-loaded and separate paragraphs for async behavior, agent, clip options, dedup, and errors. Every sentence carries actionable content, though the length is near the upper bound for practical 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 5-param asynchronous submission tool, the description covers inputs, async lifecycle, dedup semantics, error paths, and payment pause guidance. With an output schema present, return-value detail is correctly not duplicated beyond the status hints.

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 already 100%, but the description adds real meaning: the agent hashid comes from list_agents and must be a team agent, clip_guidance rejection behavior and the 'only picking moments' constraint, and how agent/clip preferences interact with dedup. It stops short of full syntax detail but clearly exceeds the schema baseline.

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

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

States a specific verb (submit), resource (source video url), supported providers, and what it produces (viral clips, returning id + status). It is clearly distinguishable from siblings like render_clip, caption_video, and get_video_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?

Explicitly says when to poll get_video_status vs when NOT to poll (pending_credits), when to pass agent vs omit it, and describes the dedup rule (same url+agent+prefs returns existing run in 24h; different prefs start new run). Alternatives and exclusions are named.

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

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

With readOnlyHint=false the agent needs to know what side effects occur; the description covers them thoroughly: asynchronous queuing, the returned tool_job hashid and status, the polling loop needed to get json/srt/vtt URLs, cost (free, account only), and rate/size/duration caps with error behavior. It also clarifies that the `nudge` field is informational output.

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?

Front-loaded with the core action, then grouped into purpose, workflow, options, and async behavior. Every sentence carries a distinct fact (cost, prerequisite, the complete_upload trap, polling, limits) 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?

No output schema exists, so describing the return shape (tool_job, status queued, eventual download URLs) is essential and it is done. Combined with the async polling instructions and limit behavior, an agent has everything needed to call and follow through 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 default 3 applies for the three params, but the description adds genuine extra meaning: where the `video` hashid comes from, that `language` can be omitted for auto-detect, and that `diarize` labels speakers (default true). No syntax beyond the schema's examples is provided, but the workflow context is real 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?

States a specific verb and resource ('Transcribe an already-uploaded video or audio file into time-coded text'), including the expected output form. An agent immediately knows what this does and what it 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?

Explicitly distinguishes this tool from complete_upload ('Do NOT call complete_upload for transcription -- that starts the paid clip pipeline'), names the prerequisite tools that produce the `video` id, and routes the agent onward to get_tool_job_status for polling. The free-vs-paid condition and rate-limit fallback are spelled out.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding the patch semantics ('anything you omit is left as-is'), which materially softens how an agent should read that destructive hint. It also discloses the return ('Returns the updated agent') and the team-scope authorization limit. It does not describe side effects of changing presets or credit-charging behavior beyond what the schema already carries.

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?

Front-loaded with the action and the partial-update contract, then a scannable list of updatable fields, then the return and scope constraint — no filler sentences. The inline field enumeration mildly duplicates the schema and is presented as a complete 'Updatable:' list while skipping two nested-object parameters, which is a small structure/precision cost.

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 8-parameter mutation tool with nested objects and no output schema, the description covers the key contract (partial update, team scope, return value) and routes the caller to helper tools for the opaque nested objects. The omission of composition_parameters and caption_style_overrides from the updatable list is the only notable gap, and the schema documents them fully.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds genuine value by cross-referencing the correct source tools for identifiers and preset keys (list_agents, list_caption_presets, describe_agent_settings). Its inline enumeration of the updatable fields partially duplicates the schema, and it omits composition_parameters and caption_style_overrides from that list, which slightly undercuts the 'Updatable:' framing.

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 ('Update one of the team's agents') and immediately bounds the scope ('Only agents on your current team can be updated'). It differentiates itself from siblings by naming the sources of its identifiers (list_agents, list_caption_presets), so an agent can tell it apart from create_agent or describe_agent_settings without opening a schema.

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

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

Gives clear operational guidance: pass the agent hashid from list_agents and only the fields you want to change, since omitted fields are left as-is — this tells the caller this is a partial update, not a replace. It also states the team-scoping precondition. It stops short of naming an alternative tool or a when-not-to-use condition (e.g., when to edit settings via describe_agent_settings first).

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