Add animated word-by-word captions (TikTok, Reels, Shorts style) to any video. Send a video URL or upload a file, pick one of 37 caption styles (Hormozi, Beast, Neon…), a position (top/middle/bottom or exact x/y) and colors, then download the captioned MP4. Auth: personal API key (free) from https://animatecaptions.com/developers sent as "Authorization: Bearer ac_live_…".
Scored across 9 tools
Most tools have clearly distinct purposes: create/start form a documented two-phase upload flow, while get/list/wait are differentiated as one-shot status, enumeration, and blocking poll. The create_caption_job vs start_caption_job split is the only genuinely confusable pair, and it is mitigated by explicit descriptions tying start to the presigned-PUT path.
All names are snake_case verb_noun patterns (create_caption_job, delete_caption_job, get_caption_job, list_caption_jobs, start_caption_job, wait_for_caption_job, list_caption_styles, get_account). The one deviation, download_captioned_video, still follows verb_object phrasing and reads predictably.
Nine tools cover the full captioning lifecycle without padding: create, upload-start, status checks, blocking wait, listing, download, deletion, plus style discovery and account limits. Each tool earns its place and nothing feels extraneous.
The surface covers creation, upload, polling, retrieval, listing, deletion, style discovery, and quota inspection, so core workflows have no dead ends. Minor gaps exist: no explicit cancel/abort for an in-flight job (delete is permanent) and no way to update caption settings after creation.
Start adding animated captions to a video. Provide ONE source:
source_url: a public direct link to the video file;
filename + file_size: returns a presigned upload URL; PUT the raw bytes there with the returned Content-Type header, then call start_caption_job. Optionally choose style, position (top/middle/bottom or position_x/position_y in %), colours, font size, animation. Returns the job_id. Then call wait_for_caption_job and download_captioned_video.
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Caption style id from list_caption_styles, e.g. "beast" (default), "punch" (Hormozi), "neon", "nova". | |
| filename | No | For uploading the file yourself: file name (.mp4/.mov). Requires file_size. Returns an upload URL to PUT the bytes to, then call start_caption_job. | |
| language | No | Spoken language code, or "auto" (default). | |
| position | No | Where the captions sit. Default: middle. Ignored when position_y is set. | |
| theme_id | No | Apply one of the account's saved caption themes. | |
| animation | No | ||
| file_size | No | Size in bytes (required with filename). | |
| font_size | No | ||
| uppercase | No | ||
| position_x | No | Custom horizontal centre of the captions, % of frame width (default 50). | |
| position_y | No | Custom vertical centre of the captions, % of frame height (0 = top, 100 = bottom). | |
| source_url | No | Public direct link to an .mp4/.mov file (not a web page). The service downloads it. | |
| font_family | No | Font family; see list_caption_styles → customization.font_family for allowed values. | |
| stroke_color | No | ||
| primary_color | No | Base text colour, hex (e.g. #FFFFFF). | |
| ai_highlighter | No | Automatically highlight key words. | |
| highlight_color | No | Accent colour for highlighted keywords, hex. | |
| background_color | No | Background block colour (hex) or "transparent". | |
| active_word_color | No | Colour of the word currently being spoken, hex. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (mutation, open-world, non-destructive), and the description adds genuine behavioral detail beyond them: the presigned PUT flow including the returned Content-Type header, the need to re-call start_caption_job after upload, and the returned job_id. Missing are auth/permission requirements, failure modes for an unreachable source_url, and any indication of processing duration or cost.
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 a tight bulleted breakdown of the two source modes, then the follow-up chain — efficient for a 19-parameter tool. The 'Optionally choose style, position, colours, font size, animation' sentence largely repeats property names already documented in the schema, so it is not entirely waste-free.
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 19-parameter mutation with no output schema, the description covers what an agent most needs: how to supply input, that job_id is returned, and which sibling to call next. The create_caption_job vs start_caption_job division of labour remains unexplained, which is the one meaningful gap for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 79%, the schema carries most definitions, but the description adds an important constraint the schema cannot express: the source parameters are mutually exclusive and exactly one must be chosen (the schema marks nothing required). The style/position/colour/font/animation roll-up is mostly a restatement of enum and property descriptions, which caps the value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Start adding animated captions to a video") and outlines the two intake paths, which is far more than a restatement of the name. However, the verb "Start" collides with the sibling tool start_caption_job, and the description never explains how create_caption_job differs from it, leaving a real ambiguity an agent must resolve on its own.
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 constrains input to ONE source and spells out the two mutually exclusive paths (source_url direct link vs filename + file_size presigned upload), plus the required follow-up sequence to wait_for_caption_job and download_captioned_video. It does not say when to prefer this tool over start_caption_job or what happens if no source is supplied despite zero required parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a job together with its source video and captioned output.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuine behavioral context beyond them: deletion cascades to the source video and the captioned output, not just the job record. It stops short of covering failure modes, such as what happens to a job that is still running or whether the upload is recoverable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler, and the irreversible nature plus cascade scope arrive before an agent has to decide. Nothing needs to be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with no output schema, the description covers the crucial data-loss scope, which is the most important thing. It is still incomplete on the input's provenance and on post-conditions (return value, behavior for in-flight jobs), which an agent needs before committing to an irreversible call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden for job_id and it does not mention the parameter at all. It never says where a job_id comes from (presumably list_caption_jobs or create_caption_job) or what an invalid id does, leaving the only input entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('permanently delete') and resource ('a job'), and adds the scope of what is removed: the source video and the captioned output. No sibling tool performs deletion, so the description alone separates it from get_caption_job, list_caption_jobs, and the create/start/wait lifecycle tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this is the tool for removing an existing caption job, and 'permanently' signals caution. However, there is no guidance on prerequisites (e.g., whether the job must be completed, or that the job_id comes from list_caption_jobs) and no explicit when-not-to-use statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a 1-hour download URL for the finished MP4 of a completed job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the readOnlyHint/openWorldHint annotations by disclosing the URL lifetime (1 hour) and the completed-job precondition — both are operationally important. It omits failure behavior when the job isn't complete or the URL has expired.
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 sentence, front-loaded with the verb and outcome, with the two key constraints (1-hour expiry, completed job) packed in without waste.
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 explains what is returned (an MP4 download URL) and its expiry. Only error/edge-case behavior for incomplete jobs is left unstated, which is minor for a one-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single job_id parameter, so the description carries the burden. Phrasing implies job_id identifies the job whose MP4 is wanted, but it adds no format, source, or how-to-obtain 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 ('Get') and resource ('download URL for the finished MP4 of a completed job'), which is clearly distinct from the job-status siblings like get_caption_job. It stops short of explicitly contrasting itself with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'of a completed job' implies a precondition on job state, which is useful selection guidance. However, it never names an alternative (e.g., check get_caption_job to confirm completion) or states what to do when the job isn't finished.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the account's plan, remaining monthly uploads/renders, and limits (max video length, file size, watermark).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the description does not contradict it. The description adds value by enumerating the returned payload (plan, quotas, limits), which matters because no output schema exists. It does not disclose whether the data is live or cached, whether auth is implicit from credentials, or any rate-limit behavior, so it stays at adequate rather than rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the resource first and the returned fields enumerated in parentheses, with zero filler. Every clause carries information an agent would otherwise have to infer.
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-argument read-only tool with annotations covering safety and no output schema, the description supplies the essential return content and the scope of the limits. Minor gaps remain: no indication of units or format for the quota values, and no note that the account is inferred from credentials rather than passed in.
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 per the baseline this starts at 4; however the description adds no notes about implicit scoping such as the account being derived from the calling credentials, which is the one semantic an agent might wonder about. The schema is empty and fully covers the (nonexistent) parameter surface.
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 pairs a specific verb ('Show') with a specific resource (the account's plan and usage) and enumerates exactly what is returned: plan, remaining monthly uploads/renders, and limits such as max video length, file size, and watermark. Sibling tools are all caption-job operations, so no overlap exists, though the description never explicitly states that this is the only account-level tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: reporting 'remaining monthly uploads/renders' and 'limits (max video length, file size, watermark)' strongly suggests a pre-flight quota check before submitting an upload or render. There is no explicit when-to-use statement, no mention of alternatives, and no stated caveats about when the numbers might be stale or cached.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a job's status: awaiting_upload, queued, transcribing, rendering, completed or failed. Completed jobs include a 1-hour download_url.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuine behavioral context not in the annotations: the full state machine and the fact that completed jobs carry a 1-hour (expiring) download_url. It stops short of stating which states are terminal or what a failed job implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the purpose and then the return-value detail. No filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only status getter with no output schema, the description carries the important return information: the status vocabulary and the presence of an expiring download URL on completion. It leaves a gap on terminal states and failure handling, but the core contract is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single job_id parameter is undocumented in both the schema and the description. The description never says where the job_id originates (create_caption_job/start_caption_job) or whether it is a UUID or opaque string, so it does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ("Get a job's status") and enumerates the exact status values, so the agent knows precisely what comes back. It does not differentiate from the sibling wait_for_caption_job, which also surfaces job status, so the agent must guess which one to use for polling.
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: a one-off status check keyed by job_id. There is no explicit guidance on when to poll this repeatedly instead of calling wait_for_caption_job, nor when the job_id is available (e.g., after create_caption_job or start_caption_job).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's recent caption jobs, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| before | No | Pagination cursor: next_before from the previous page. | |
| source | No | Only jobs created via the API, or via the website. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful ordering fact ('newest first') and account scoping, but says nothing about pagination behavior, default page size, or what the result set contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero waste, front-loading the verb and resource and ending with the ordering detail an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with annotations and no output schema, the definition covers purpose and ordering. It omits that the response supplies a next_before cursor for the 'before' parameter, which is the one behavior an agent paging through results would need to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter meaning; 'before' and 'source' are documented in the schema and 'limit' carries min/max bounds but no prose (67% coverage). The remaining gap is small and largely self-evident, so this sits at the baseline rather than below it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List' + 'caption jobs'), plus scope ('the account's recent') and ordering ('newest first'). This clearly separates it from get_caption_job and create_caption_job, though it does not name a sibling explicitly.
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: 'list' plus 'recent' signals a browse/recent-activity call, and the sibling set makes the read-vs-get distinction inferable. No explicit when-to-use or when-to-prefer-get_caption_job guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the available caption styles (ids, names, colours), the named positions, and the customization options accepted by create_caption_job.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context by spelling out what the listing returns (ids, names, colours, positions, customization options), which matters because there is no output schema. It does not mention whether the style catalogue is account-specific or static, which is the remaining 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?
A single sentence that front-loads the verb and resource, then packs the return contents and the downstream consumer into one clause. No filler or redundant restatement of the 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?
For a parameterless read-only listing, the description covers what the agent needs: what comes back and why it would call this (to feed create_caption_job). Without an output schema this is the right place to describe returned fields, and it does so adequately, though it leaves open whether the catalogue varies by account.
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 there is no parameter semantics for the description to compensate for; baseline is 4. Nothing about the description misrepresents the (empty) input contract.
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 (caption styles) and enumerates the payload contents (ids, names, colours, named positions, customization options). It also distinguishes itself from the sibling create_caption_job by positioning itself as the source of that tool's accepted options.
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 reference to 'customization options accepted by create_caption_job' clearly implies the when: call this to discover valid style ids and positions before creating a job. It stops short of an explicit 'call this before create_caption_job' instruction or any exclusion, so it is clear context rather than a full when/when-not rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start processing a job after its video was PUT to the upload URL from create_caption_job. Safe to call twice.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description's real added value is the upload-completion precondition; 'Safe to call twice' merely restates idempotentHint rather than adding new behavioral detail such as error behavior on an incomplete upload or whether processing is asynchronous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed by the precondition, with zero filler. Every clause carries information an agent needs before calling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation trigger with no output schema and one undocumented parameter, the description covers the precondition and idempotency but leaves the post-call path unstated: an agent does not learn whether to poll with wait_for_caption_job or call get_caption_job, nor what a call on a not-yet-uploaded job returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single job_id parameter, so the schema contributes nothing beyond the name. The description partially compensates by tying the job to create_caption_job, implying where job_id originates, but it never explicitly says job_id is the identifier returned by that sibling call.
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 ('Start processing') and resource ('a job'), and anchors it to a precise workflow position: after the video was PUT to the upload URL from create_caption_job. That sequencing is what separates it from siblings like get_caption_job, wait_for_caption_job, and create_caption_job without needing to open 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 an explicit precondition for use: only after the video has been PUT to the upload URL issued by create_caption_job. It does not name the natural follow-up alternative (wait_for_caption_job) or say what to do if the upload has not completed, so the routing guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait until a job is completed or failed (polls every 5 s, up to timeout_sec, max 50). If it times out, call it again.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| timeout_sec | No | Default 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and openWorldHint, and the description adds real operational detail beyond them: 5-second polling, a timeout ceiling of 50, and the fact that timeout is not terminal but should be retried. It stops short of saying what a failed job looks like or whether the return value differs on timeout versus failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, and the core blocking behavior plus polling interval is front-loaded before the retry instruction. Every clause carries information an agent needs to call it correctly.
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 polling tool this covers timing and retry well, but with no output schema the description should say what comes back when the job completes, fails, or times out — the agent currently cannot tell how to interpret the result of a timed-out call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: timeout_sec is documented in the schema with min 5 / max 50 / default 50, and the description restates the max-50 ceiling without adding much. job_id is undocumented in both places, though its meaning is self-evident from the tool name; baseline 3 fits a tool where the schema carries most of the load.
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 ('Wait until a job is completed or failed') and scopes it with polling cadence and a timeout ceiling. An agent can distinguish this blocking wait from siblings like get_caption_job or list_caption_jobs, though it never names the non-blocking alternative explicitly.
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 retry guidance ('If it times out, call it again'), which is genuinely actionable, and implies usage after a job is created. It does not say when NOT to use it (e.g., prefer get_caption_job for a non-blocking status check), so the agent must infer the tradeoff against siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_caption_jobdelete_caption_jobdownload_captioned_videoget_accountget_caption_joblist_caption_jobslist_caption_stylesstart_caption_jobwait_for_caption_job
Add one secure layer between your agents and this server.