Which integrations are available for this server?

Provides tools for interacting with Wistia's API to manage media, folders, captions, channels, webinars, sharing, analytics, and uploads. Includes read and confirmed write operations, exact caption matching/editing, media upload via URL or local file, engagement and job status checks, and private account selection.

How do I use Wistia MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Wistia MCP Server find the video about onboarding and locate this wording in its captions" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Wistia MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Wistia MCP Server & CLI

npm License YouTube LinkedIn

Wistia MCP server and CLI for Codex and AI agents. 169 tools: 86 reads and 83 confirmed writes for media, folders, captions, channels, webinars, sharing, analytics and uploads.

One package provides local MCP, the same operations as task CLI commands, and a bundled Claude Desktop .mcpb extension.

Built and maintained by Navid Moazzez. Complete installation and private account setup are in INSTALL.md.

The terminal illustrates shipped caption tools with sample data. It is a presentation preview, not a verified live account edit.

You need a private scoped Wistia Bearer token and appropriate endpoint/account permissions. Service features, quota and charges apply. The wrapper preserves AGPL-3.0-or-later; this is a community product maintained by Navid Media.

Wistia already offers an official MCP and task CLI. Our added safeguards and bounded workflows are compared below, without unsupported coverage or efficiency claims.

Two ways to use it

Command line

npm install -g @thenavidm/wistia-mcp-cli@latest
wistia-cli
wistia-cli list-media --help
wistia-cli schema edit-captions-text
wistia-cli list-media --per-page 5 --agent

Configure private access before account calls. Every mutation requires --confirm; --yes and --agent do not authorize it.

MCP server, for your AI app

codex mcp add wistia -- npx -y @thenavidm/wistia-mcp-cli@latest

Then ask: Find the video I choose and locate this exact wording in its captions. Complete client/OS wiring is in INSTALL.md.

Which one

Where you work	Surface
Codex, Cursor or another shell agent	Local MCP, CLI or both
Claude Desktop chat	Local MCP or desktop archive
Scripts/CI	Shared task CLI or an MCP client
Remote-URL-only clients	Official hosted Wistia MCP

Related MCP server: mux-mcp

Features

Capability	CLI	MCP
Media and folders	list-media / list-folders	list_media / list_folders
Exact caption matching	find-caption-matches	find_caption_matches
Guarded caption editing	edit-captions-text	edit_captions_text
Upload URL / local file	upload-media / upload-media-file	Same underscore names
Channels and webinars	list-channels / list-webinars	Same shared schemas
Stats and background jobs	get-media-engagement / get-job-status	Same account permissions
Private account selection	list-accounts / --account	list_accounts / account
Setup diagnosis	doctor / login	CLI utilities

Number	Section	Covers
1	What you can ask it	Prompts and coverage
2	Quick install	CLI, MCP and desktop
3	Set up Wistia access	Token, version, permissions and quota
4	Connect your client	Clients and OS
5	Check it works	Doctor and first read
6	Output, flags and exit codes	Inputs, JSON and scripting
7	MCP or CLI and token cost	Real client usage evidence
8	Every tool and argument	All tools and arguments
9	Media, caption and webinar workflows	Media, captions, sharing and webinars
10	Pagination, quotas and background jobs	Bounded pages and async outcomes
11	Several private accounts	Named credentials
12	Writing safely	Confirmation and private generated tokens
13	How it works	Shared framework and regeneration
14	Your data	Private data handling
15	Environment variables	Credential, safety and tuning
16	Updates and removal	Upgrade and revoke
17	Troubleshooting	Symptoms and remedies
18	API coverage and comparisons	Official/community comparison
19	Versions	Version history and migration
20	FAQ	Accordion questions

1. What you can ask it

Find the intended folder and inspect a short media list.
Read an authorized caption track and locate exact wording before editing it.
Upload the particular local video or public URL I approved.
Copy, move or archive only the media IDs I selected.
Inspect channels, webinars, registrations and existing sharing settings.
Read media analytics or Stats data for the requested date range.
Watch a returned background job without treating acceptance as completion.

The published September schema has 167 HTTP operations. Separate form and local-file uploader commands make 168 shared API tools; the private account helper brings the total to 169 tools: 86 reads and 83 confirmed writes. Find Caption Matches is a nonmutating POST, so it is a read and remains available in read-only mode.

Wistia already offers official MCP and CLI products. This owned package adds a mandatory local mutation guard, named private account selection, bounded page retrieval and private output for created access credentials. These differences are supported by fixtures, real protocol discovery and a reviewed official binary. They do not establish overall superiority or token savings. Account outcomes and desktop GUI installation remain separately unverified.

2. Quick install

npm install -g @thenavidm/wistia-mcp-cli@latest
wistia-cli --version
wistia-cli login
wistia-cli doctor
wistia-cli tools

Manual MCP/CLI installs require Node 22 or newer. Help, discovery and schemas work before authentication. Account requests require privately configured access. The wistia-2.0.0.mcpb desktop archive bundles production dependencies for a compatible host. Full client/OS wiring is in INSTALL.md.

Codex local MCP, after private environment configuration:

codex mcp add wistia -- npx -y @thenavidm/wistia-mcp-cli@latest
codex mcp list

3. Set up Wistia access

Get a narrowly scoped private token

Sign in to the intended Wistia account. An Account Owner creates account API tokens.
Open Account Settings > API, following Wistia's access-token instructions.
Create a named token with only the permissions your task needs. Copy the token when it is shown at creation and store it privately.
Set WISTIA_TOKEN_FILE to an absolute token-only file outside repositories, or configure WISTIA_API_TOKEN only in private local client/shell settings.
Run wistia-cli doctor, then wistia-cli doctor --network for one account read. A token without permission to read account details can fail doctor while having narrower resource permissions.

Tokens use a Bearer header. Do not supply passwords, cookies or token values as tool arguments. This package has no automatic .env loader, OS keychain integration or OAuth callback. login prints instructions without generating or saving credentials. The official hosted MCP has its own OAuth connection, and the official CLI offers keychain setup.

On macOS/Linux, keep the token file owner-only (0600), with a private parent directory (0700). On Windows, protect it with user-only filesystem ACLs. Token files must be regular, not symlinks, and at most 64 KB. A file takes precedence over the environment token and is cached until the process restarts. GUI clients may not inherit terminal environment variables. Enter actual credentials only in private local settings, never project files, chats or issues.

Permissions and feature eligibility

Read-media workflows normally need the read-folder/media permission. Editing, deleting, sharing, caption ordering, account administration and analytics use their specific endpoint permissions. The operation reference preserves the provider's declared permission requirements. Delegated tokens follow the assigned contact's permissions; they do not elevate access. A 401/403 may indicate token scope, account status, role or feature access, not a broken installation.

Webinars, localizations, accessibility orders, trials, media capacity and purchases depend on current account features and allowances. Installation does not purchase a plan or create quota. Read the intended endpoint and account's billing settings before chargeable operations. No universal paid-plan requirement is invented for every Data API call. Official hosted MCP access is documented for owners and managers. Keep that rule separate from the permission model of a scoped API token.

Modern routes and dated API version

The service URL is https://api.wistia.com/modern. Requests include X-Wistia-Api-Version: 2026-09 by default. The pinned official CLI v2026.9.0 schema identifies its document as 2026.09.0. Set WISTIA_API_VERSION only to a reviewed YYYY-MM release. The provider may resolve an unsupported date to an earlier supported release and may retire older versions; a header is not an indefinite compatibility guarantee. See the modern migration guide.

The uploader remains https://upload.wistia.com/, with form or multipart encoding and private Bearer authentication. Modern media/folder requests use the current schema. Folder request bodies retain some camelCase fields; uploader project_id is still valid. Do not mechanically rename every property to snake_case. Stats routes retain /stats/projects; a folder rename does not imply every Stats URL changed.

Shared quota

Wistia documents 600 requests per minute across Data and Upload APIs for an account. The local default is 150 ms between requests per account/process, but other integrations and duplicate labels still share the provider's quota. Every page and retried read counts. GET 429 handling respects Retry-After only when the delay is at most ten seconds; a longer delay returns exit 7 for explicit caller pacing. POST queries and all mutations have no automatic retries. No process-local pacing setting reserves quota.

4. Connect your client

INSTALL.md covers Codex, Claude Code, Claude Desktop extension/manual settings, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other stdio clients on macOS, Windows and Linux. Use command npx and arguments -y, @thenavidm/wistia-mcp-cli@latest, with private local environment settings. Codex is the current setup/validation priority; Claude Code is optional.

A client accepting only a remote HTTPS URL can use the official Wistia MCP at https://api.wistia.com/mcp/api, with its OAuth or supported Bearer setup. It supports toolset selection. The local package does not expose a public HTTP relay. Use separate server names if comparing both.

The npm package ships SKILL.md. Copy or link it into your agent's supported skills location for shell use; npm installation does not register a skill automatically. An agent should inspect current commands/schemas and help configure private settings without requesting tokens in chat.

5. Check it works

wistia-cli --version
wistia-cli doctor
wistia-cli doctor --network
wistia-cli list-accounts --agent
wistia-cli list-media --per-page 5 --agent

Network doctor performs GET /modern/account and reports success without printing account details. The first list is a small authorized read, not a mutation. A successful read proves only that operation's access. Full discovery exposes 169 tools; read-only exposes 86. Missing configuration exits 10; missing arguments or an unconfirmed write exit 2. Use actual returned hashed IDs, numeric IDs and timestamps according to each schema, not guessed identifier types.

6. Output, flags and exit codes

Tool names become dashed commands; underscores are accepted too. Path parameter names follow the discovered schema, such as media_hashed_id → --media-hashed-id. Body tools accept individual top-level flags, complete --payload JSON, or --payload-file pointing to a regular JSON body file up to 5 MB. Do not mix those body routes. Path/query flags remain separate. Nested objects take JSON and array flags repeat once per item; a whole array is not a single item.

wistia-cli get-media --help
wistia-cli schema create-captions
wistia-cli list-media --hashed-ids MEDIA_A --hashed-ids MEDIA_B --per-page 5 --agent
wistia-cli list-media --cursor '{"enabled":1}' --per-page 5 --agent

IDs above are illustrative; use discovered resources from your own account. Nullable fields require an actual JSON null inside payload; --field null is a string. Nested values preserve current upstream constraints; unknown top-level body fields are refused. Body-required fields are validated during execution even when the wrapper schema allows an alternative payload route. Operations whose upstream request body is required need body flags or an explicit payload; a deliberately supplied empty object is sent as JSON, never omitted.

Flag	Behavior
--help / schema COMMAND	Current argument help / full JSON Schema
--json	Structured JSON
--compact	One-line JSON
--agent	Compact JSON, no prompts or color
--select a,b.c	Keep selected fields, including nested objects/arrays
--no-color / --no-input	Noninteractive house flags
--yes	Never replaces write confirmation
--confirm	Confirm only the requested mutation
--account NAME	Select private local credentials
--payload JSON / --payload-file PATH	Complete request body, mutually exclusive with body flags

Exit	Meaning
0	Success
2	Invalid arguments or refused write
3	Resource not found
4	Authentication/permission failure
5	API/transport failure
7	Rate limit
10	Missing or invalid private configuration

Results go to stdout, errors as JSON to stderr. Selection changes local output, not the original API response or quota charge. API success is not proof of notification delivery or a completed export.

7. MCP or CLI and token cost

MCP and CLI use the same SDK server, schemas, validation and HTTP handlers. The CLI talks to that server through the SDK's in-memory transport; there is no second API implementation.

Measurement	What to include
Eager MCP loading	All tool schemas and instructions
Default/deferred tool search	Actual selected schemas and discovery overhead
Skill read once	Full SKILL.md and command discovery
Recurring skill discovery	The installed skill's listing text
Matched successful task	Help/schema, reasoning, calls/commands, results, errors and retries

Fresh Codex usage measurements are pending. Claude Code measurements are deferred and do not block this release. Do not estimate tokens from characters, substitute another repo's results or declare zero CLI cost. Record model/client/package versions and date, loading settings, input/output usage, latency and equivalent outcomes. Compare a small folder/media query and repeated focused caption and media work across supported official/local surfaces, using the same authorized data and result fields. API quota and service costs remain separate. No measured superiority is claimed.

8. Every tool and argument

All 167 stable HTTP operations derive from the pinned official September schema. The uploader has separate URL-form and local-file commands. list_accounts is local. Schemas validate complete body requirements whichever body input route you use. Each tool maps to its dashed CLI name. The permission column summarizes the provider requirements, not a substitute for the full endpoint reference.

Tool	API operation	Mode	Permission requirement
`upload_media`	`POST /`	Write, confirms	See current endpoint/account permission
`upload_media_file`	`POST /`	Write, confirms	See current endpoint/account permission
`list_review_bundles`	`GET /review_bundles`	Read	Read all folder and media data
`create_review_bundle`	`POST /review_bundles`	Write, confirms	Read, update & delete anything
`delete_review_bundle`	`DELETE /review_bundles/{reviewBundleHashedId}`	Write, confirms	Read, update & delete anything
`list_deleted_media`	`GET /deleted_media`	Read	Read all folder and media data
`restore_deleted_media`	`POST /deleted_media/restore`	Write, confirms	Upload and view media
`list_media`	`GET /medias`	Read	Read all folder and media data
`get_media`	`GET /medias/{mediaHashedId}`	Read	Read all folder and media data
`update_media`	`PUT /medias/{mediaHashedId}`	Write, confirms	Read, update & delete anything
`delete_media`	`DELETE /medias/{mediaHashedId}`	Write, confirms	Read, update & delete anything
`copy_media`	`POST /medias/{mediaHashedId}/copy`	Write, confirms	Read, update & delete anything
`swap_media`	`PUT /medias/{mediaHashedId}/swap`	Write, confirms	Read, update & delete anything
`get_media_stats`	`GET /medias/{mediaHashedId}/stats`	Read	Read all folder and media data
`translate_media`	`POST /medias/{mediaHashedId}/translate`	Write, confirms	Read, update & delete anything
`import_media_from_url`	`POST /medias/import_url`	Write, confirms	Read, update & delete anything
`archive_media`	`PUT /medias/archive`	Write, confirms	Read, update & delete anything
`move_media`	`PUT /medias/move`	Write, confirms	Read, update & delete anything
`restore_media`	`PUT /medias/restore`	Write, confirms	Read, update & delete anything
`bulk_copy_media`	`PUT /medias/copy`	Write, confirms	Read, update & delete anything
`get_customizations`	`GET /medias/{mediaId}/customizations`	Read	Read all folder and media data
`create_customizations`	`POST /medias/{mediaId}/customizations`	Write, confirms	Read, update & delete anything
`update_customizations`	`PUT /medias/{mediaId}/customizations`	Write, confirms	Read, update & delete anything
`delete_customizations`	`DELETE /medias/{mediaId}/customizations`	Write, confirms	Read, update & delete anything
`get_appearance_customizations`	`GET /medias/{mediaId}/customizations/appearance`	Read	Read all folder and media data
`update_appearance_customizations`	`PUT /medias/{mediaId}/customizations/appearance`	Write, confirms	Read, update & delete anything
`get_playback_customizations`	`GET /medias/{mediaId}/customizations/playback`	Read	Read all folder and media data
`update_playback_customizations`	`PUT /medias/{mediaId}/customizations/playback`	Write, confirms	Read, update & delete anything
`get_thumbnail_customizations`	`GET /medias/{mediaId}/customizations/thumbnail`	Read	Read all folder and media data
`update_thumbnail_customizations`	`PUT /medias/{mediaId}/customizations/thumbnail`	Write, confirms	Read, update & delete anything
`get_accessibility_customizations`	`GET /medias/{mediaId}/customizations/accessibility`	Read	Read all folder and media data
`update_accessibility_customizations`	`PUT /medias/{mediaId}/customizations/accessibility`	Write, confirms	Read, update & delete anything
`get_chapters_customizations`	`GET /medias/{mediaId}/customizations/chapters`	Read	Read all folder and media data
`update_chapters_customizations`	`PUT /medias/{mediaId}/customizations/chapters`	Write, confirms	Read, update & delete anything
`get_engagement_customizations`	`GET /medias/{mediaId}/customizations/engagement`	Read	Read all folder and media data
`update_engagement_customizations`	`PUT /medias/{mediaId}/customizations/engagement`	Write, confirms	Read, update & delete anything
`get_related_media_customizations`	`GET /medias/{mediaId}/customizations/related_media`	Read	Read all folder and media data
`update_related_media_customizations`	`PUT /medias/{mediaId}/customizations/related_media`	Write, confirms	Read, update & delete anything
`get_sharing_customizations`	`GET /medias/{mediaId}/customizations/sharing`	Read	Read all folder and media data
`update_sharing_customizations`	`PUT /medias/{mediaId}/customizations/sharing`	Write, confirms	Read, update & delete anything
`get_lead_capture_customizations`	`GET /medias/{mediaId}/customizations/lead_capture`	Read	Read all folder and media data
`update_lead_capture_customizations`	`PUT /medias/{mediaId}/customizations/lead_capture`	Write, confirms	Read, update & delete anything
`get_access_customizations`	`GET /medias/{mediaId}/customizations/access`	Read	Read all folder and media data
`update_access_customizations`	`PUT /medias/{mediaId}/customizations/access`	Write, confirms	Read, update & delete anything
`resolve_share_link`	`GET /share_links/{identifier}`	Read	Read all folder and media data
`get_share_link`	`GET /medias/{mediaId}/share_link`	Read	Read all folder and media data
`update_share_link`	`PUT /medias/{mediaId}/share_link`	Write, confirms	Read, update & delete anything
`delete_share_link`	`DELETE /medias/{mediaId}/share_link`	Write, confirms	Read, update & delete anything
`list_captions`	`GET /medias/{mediaHashedId}/captions`	Read	Read all folder and media data
`create_captions`	`POST /medias/{mediaHashedId}/captions`	Write, confirms	Read, update & delete anything
`list_all_captions`	`GET /captions`	Read	Read all folder and media data
`find_caption_matches`	`POST /caption_matches`	Read	Read all folder and media data
`purchase_captions`	`POST /medias/{mediaHashedId}/captions/purchase`	Write, confirms	Read, update & delete anything
`get_captions`	`GET /medias/{mediaHashedId}/captions/{languageCode}`	Read	Read all folder and media data
`update_captions`	`PUT /medias/{mediaHashedId}/captions/{languageCode}`	Write, confirms	Read, update & delete anything
`delete_captions`	`DELETE /medias/{mediaHashedId}/captions/{languageCode}`	Write, confirms	Read, update & delete anything
`edit_captions_text`	`POST /medias/{mediaHashedId}/captions/{languageCode}/edits`	Write, confirms	Read, update & delete anything
`list_localizations`	`GET /medias/{mediaHashedId}/localizations`	Read	Read all data
`create_localization`	`POST /medias/{mediaHashedId}/localizations`	Write, confirms	Read, update & delete anything
`get_localization`	`GET /medias/{mediaHashedId}/localizations/{localizationHashedId}`	Read	Read all data
`delete_localization`	`DELETE /medias/{mediaHashedId}/localizations/{localizationHashedId}`	Write, confirms	Read, update & delete anything
`create_media_from_trims`	`POST /medias/{mediaHashedId}/trims`	Write, confirms	Read, update & delete anything
`list_media_extended_audio_descriptions`	`GET /media_extended_audio_descriptions`	Read	See current endpoint/account permission
`get_media_extended_audio_description`	`GET /media_extended_audio_descriptions/{id}`	Read	See current endpoint/account permission
`delete_media_extended_audio_description`	`DELETE /media_extended_audio_descriptions/{id}`	Write, confirms	See current endpoint/account permission
`order_extended_audio_description`	`POST /media_extended_audio_descriptions/order`	Write, confirms	See current endpoint/account permission
`get_order_status`	`GET /media_extended_audio_descriptions/order_status/{id}`	Read	See current endpoint/account permission
`list_brands`	`GET /brands`	Read	Read all data
`create_brand`	`POST /brands`	Write, confirms	All data
`get_brand`	`GET /brands/{brandId}`	Read	Read all data
`update_brand`	`PUT /brands/{brandId}`	Write, confirms	All data
`delete_brand`	`DELETE /brands/{brandId}`	Write, confirms	All data
`apply_brand`	`POST /brands/{brandId}/apply`	Write, confirms	All data
`list_speakers`	`GET /speakers`	Read	Read all data
`list_tags`	`GET /tags`	Read	Read all data
`create_tags`	`POST /tags`	Write, confirms	Read, update & delete anything
`delete_tag`	`DELETE /tags/{name}`	Write, confirms	Read, update & delete anything
`create_bulk_actions`	`POST /bulk`	Write, confirms	Read, update & delete anything
`create_bulk_purchase`	`POST /bulk/purchase`	Write, confirms	Read, update & delete anything
`bulk_tag`	`POST /taggings/bulk_create`	Write, confirms	Read, update & delete anything
`list_folders`	`GET /folders`	Read	Read all folder and media data
`create_folder`	`POST /folders`	Write, confirms	Read, update & delete anything
`get_folder`	`GET /folders/{id}`	Read	Read all folder and media data
`update_folder`	`PUT /folders/{id}`	Write, confirms	Read, update & delete anything
`delete_folder`	`DELETE /folders/{id}`	Write, confirms	Read, update & delete anything
`copy_folder`	`POST /folders/{id}/copy`	Write, confirms	Read, update & delete anything
`list_folder_sharings`	`GET /folders/{folderId}/sharings`	Read	Read all data
`create_folder_sharing`	`POST /folders/{folderId}/sharings`	Write, confirms	Read, update & delete anything
`get_folder_sharing`	`GET /folders/{folderId}/sharings/{sharingId}`	Read	Read all data
`update_folder_sharing`	`PUT /folders/{folderId}/sharings/{sharingId}`	Write, confirms	Read, update & delete anything
`delete_folder_sharing`	`DELETE /folders/{folderId}/sharings/{sharingId}`	Write, confirms	Read, update & delete anything
`list_subfolders`	`GET /folders/{folderId}/subfolders`	Read	Read all folder and media data
`create_subfolder`	`POST /folders/{folderId}/subfolders`	Write, confirms	Read, update & delete anything
`get_subfolder`	`GET /folders/{folderId}/subfolders/{subfolderId}`	Read	Read all folder and media data
`update_subfolder`	`PUT /folders/{folderId}/subfolders/{subfolderId}`	Write, confirms	Read, update & delete anything
`delete_subfolder`	`DELETE /folders/{folderId}/subfolders/{subfolderId}`	Write, confirms	Read, update & delete anything
`bulk_delete_subfolders`	`DELETE /folders/{folderId}/subfolders/bulk_delete`	Write, confirms	Read, update & delete anything
`list_channels`	`GET /channels`	Read	Read all folder and media data
`create_channel`	`POST /channels`	Write, confirms	See current endpoint/account permission
`get_channel`	`GET /channels/{channelHashedId}`	Read	Read all folder and media data
`update_channel`	`PUT /channels/{channelHashedId}`	Write, confirms	See current endpoint/account permission
`delete_channel`	`DELETE /channels/{channelHashedId}`	Write, confirms	See current endpoint/account permission
`get_channel_episode`	`GET /channels/{channelHashedId}/channel_episodes/{channelEpisodeId}`	Read	Read all folder and media data
`list_channel_episodes_by_channel`	`GET /channels/{channelHashedId}/channel_episodes`	Read	Read all folder and media data
`create_channel_episode`	`POST /channels/{channelHashedId}/channel_episodes`	Write, confirms	Read, update & delete anything
`list_channel_episodes`	`GET /channel_episodes`	Read	Read all folder and media data
`update_channel_episode`	`PUT /channel_episodes/{channelEpisodeHashedId}`	Write, confirms	Read, update & delete anything
`delete_channel_episode`	`DELETE /channel_episodes/{channelEpisodeHashedId}`	Write, confirms	Read, update & delete anything
`publish_channel_episode`	`PUT /channel_episodes/{channelEpisodeHashedId}/publish`	Write, confirms	Read, update & delete anything
`un_publish_channel_episode`	`PUT /channel_episodes/{channelEpisodeHashedId}/unpublish`	Write, confirms	Read, update & delete anything
`list_channel_collaborators`	`GET /channels/{channelHashedId}/collaborators`	Read	Read all data
`create_channel_collaborator`	`POST /channels/{channelHashedId}/collaborators`	Write, confirms	Read, update & delete anything
`delete_channel_collaborator`	`DELETE /channels/{channelHashedId}/collaborators/{id}`	Write, confirms	Read, update & delete anything
`list_webinars`	`GET /webinars`	Read	Read all data
`create_webinar`	`POST /webinars`	Write, confirms	Read, update & delete anything
`get_webinar`	`GET /webinars/{id}`	Read	Read all data
`update_webinar`	`PUT /webinars/{id}`	Write, confirms	Read, update & delete anything
`delete_webinar`	`DELETE /webinars/{id}`	Write, confirms	Read, update & delete anything
`list_webinar_registrations`	`GET /webinars/{webinarId}/registrations`	Read	Read all data
`create_webinar_registration`	`POST /webinars/{webinarId}/registrations`	Write, confirms	Read, update & delete anything
`list_webinar_collaborators`	`GET /webinars/{webinarId}/collaborators`	Read	Read all data
`create_webinar_collaborator`	`POST /webinars/{webinarId}/collaborators`	Write, confirms	Read, update & delete anything
`delete_webinar_collaborator`	`DELETE /webinars/{webinarId}/collaborators/{id}`	Write, confirms	Read, update & delete anything
`get_account`	`GET /account`	Read	(any scope allowed)
`get_account_usage`	`GET /account_usage`	Read	(any scope allowed)
`get_credit_balance`	`GET /credits/balance`	Read	(any scope allowed)
`get_brand_preload`	`GET /brand_preload`	Read	(any scope allowed)
`update_brand_preload`	`PUT /brand_preload`	Write, confirms	(any scope allowed)
`get_brand_kit_colors`	`GET /brand_kit_colors`	Read	(any scope allowed)
`invite_contacts`	`POST /contacts`	Write, confirms	Read, update & delete anything
`dismiss_desktop_install_prompt`	`POST /contact/dismiss_desktop_install_prompt`	Write, confirms	Read, update & delete anything
`start_account_trial`	`POST /account/trials`	Write, confirms	Read, update & delete anything
`get_current_token`	`GET /token`	Read	See current endpoint/account permission
`search`	`GET /search`	Read	Read all data
`resolve_resource_urls`	`GET /resource_urls`	Read	Read all data
`create_expiring_access_token`	`POST /expiring_token`	Write, confirms	Read, update & delete anything
`get_job_status`	`GET /background_job_status/{backgroundJobStatusId}`	Read	Read all data
`list_allowed_domains`	`GET /allowed_domains`	Read	Read all data
`create_allowed_domain`	`POST /allowed_domains`	Write, confirms	Read, update & delete anything
`get_allowed_domain`	`GET /allowed_domains/{domain}`	Read	Read all data
`delete_allowed_domain`	`DELETE /allowed_domains/{domain}`	Write, confirms	Read, update & delete anything
`get_account_stats`	`GET /stats/account`	Read	Read detailed stats
`get_account_stats_by_date`	`GET /stats/account/by_date`	Read	Read detailed stats
`get_project_stats`	`GET /stats/projects/{projectId}`	Read	Read detailed stats
`get_media_stats_stats_media`	`GET /stats/medias/{mediaId}`	Read	Read detailed stats
`get_media_stats_by_date`	`GET /stats/medias/{mediaId}/by_date`	Read	Read detailed stats
`get_media_engagement`	`GET /stats/medias/{mediaId}/engagement`	Read	Read detailed stats
`list_visitors`	`GET /stats/visitors`	Read	Read detailed stats
`get_visitor`	`GET /stats/visitors/{visitorKey}`	Read	Read detailed stats
`list_events`	`GET /stats/events`	Read	Read detailed stats
`get_event`	`GET /stats/events/{eventKey}`	Read	Read detailed stats
`get_account_analytics`	`GET /analytics/account`	Read	Read detailed stats
`get_account_analytics_timeseries`	`GET /analytics/account/timeseries`	Read	Read detailed stats
`get_account_top_content`	`GET /analytics/account/top_content`	Read	Read detailed stats
`get_account_embed_locations`	`GET /analytics/account/embed_locations`	Read	Read detailed stats
`find_media_by_embed_location`	`GET /analytics/account/media_by_embed_location`	Read	Read detailed stats
`get_media_analytics`	`GET /analytics/medias/{mediaId}`	Read	Read detailed stats
`get_media_analytics_timeseries`	`GET /analytics/medias/{mediaId}/timeseries`	Read	Read detailed stats
`get_media_embed_locations`	`GET /analytics/medias/{mediaId}/embed_locations`	Read	Read detailed stats
`get_media_embed_locations_timeseries`	`GET /analytics/medias/{mediaId}/embed_locations_timeseries`	Read	Read detailed stats
`get_media_traffic_breakdown`	`GET /analytics/medias/{mediaId}/traffic`	Read	Read detailed stats
`get_media_form_conversions`	`GET /analytics/medias/{mediaId}/conversions`	Read	Read detailed stats
`get_media_languages`	`GET /analytics/medias/{mediaId}/languages`	Read	Read detailed stats
`get_webinar_analytics`	`GET /analytics/webinars/{webinarId}`	Read	Read detailed stats
`get_webinar_registration_timeseries`	`GET /analytics/webinars/{webinarId}/registration`	Read	Read detailed stats
`get_webinar_traffic_breakdown`	`GET /analytics/webinars/{webinarId}/traffic`	Read	Read detailed stats
`get_webinar_audience`	`GET /analytics/webinars/{webinarId}/audience`	Read	Read detailed stats
`get_webinar_histograms`	`GET /analytics/webinars/{webinarId}/histograms`	Read	Read detailed stats
`list_accounts`	Local, no network	Read	No remote permission

upload_media

wistia-cli upload-media

Argument	Required	Type	Details
`project_id`	No; body/guard rules still apply	string	The hashed id of the project to upload media into.
`name`	No; body/guard rules still apply	string	A display name to use for the media in Wistia. maxLength: `255`.
`description`	No; body/guard rules still apply	string	A description to use for the media in Wistia.
`contact_id`	No; body/guard rules still apply	integer	A Wistia contact id.
`url`	No; body/guard rules still apply	string	The publicly accessible web location of the media file to import. format: `uri`.
`low_priority`	No; body/guard rules still apply	boolean	Inform the encoding service that this upload can be considered lower priority than others. This is especially useful for platform customers doing bulk uploads or migrations. Setting this to "false" has no effect.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `url`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: url.

upload_media_file

wistia-cli upload-media-file

Argument	Required	Type	Details
`project_id`	No; body/guard rules still apply	string	The hashed id of the project to upload media into.
`name`	No; body/guard rules still apply	string	A display name to use for the media in Wistia. maxLength: `255`.
`description`	No; body/guard rules still apply	string	A description to use for the media in Wistia.
`contact_id`	No; body/guard rules still apply	integer	A Wistia contact id.
`file`	No; body/guard rules still apply	string	Absolute regular local file, no symlinks, at most 250 MiB locally. Bytes are sent after explicit confirmation. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `file`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: file.

list_review_bundles

wistia-cli list-review-bundles

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	Restrict the results to the review bundles with these hashed IDs. Array items: string.
`name`	No; body/guard rules still apply	string	Restrict the results to review bundles whose name contains this value (case-insensitive).
`media_hashed_id`	No; body/guard rules still apply	string	Restrict the results to review bundles that include the media with this hashed ID.
`folder_hashed_id`	No; body/guard rules still apply	string	Restrict the results to review bundles that include any media from the folder with this hashed ID.
`sort_by`	No; body/guard rules still apply	string	Field to order by. The default is id. Values: `id`, `name`, `created`, `updated`.
`sort_direction`	No; body/guard rules still apply	integer	Direction to order by. (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_review_bundle

wistia-cli create-review-bundle

Argument	Required	Type	Details
`media_hashed_ids`	No; body/guard rules still apply	array	The hashed ids of the media to include in the bundle. Limited to 25 media. Array items: string.
`name`	No; body/guard rules still apply	string	The bundle display name.
`allow_downloads`	No; body/guard rules still apply	boolean	Whether the videos in the bundle can be downloaded.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `media_hashed_ids`, `name`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: media_hashed_ids, name.

delete_review_bundle

wistia-cli delete-review-bundle

Argument	Required	Type	Details
`review_bundle_hashed_id`	Yes	string	The hashed id of the review bundle. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

list_deleted_media

wistia-cli list-deleted-media

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	Restrict the results to the deleted media with these hashed IDs. Array items: string.
`sort_by`	No; body/guard rules still apply	string	Field to order by. When omitted, results are ordered most-recently-deleted first. Values: `id`, `deleted`, `name`, `type`, `created`.
`sort_direction`	No; body/guard rules still apply	integer	Direction to order by. (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

restore_deleted_media

wistia-cli restore-deleted-media

Argument	Required	Type	Details
`media_hashed_ids`	No; body/guard rules still apply	array	The hashed ids of the soft-deleted media to restore. Up to 1000 at a time. Array items: string.
`folder_id`	No; body/guard rules still apply	string	Optional hashed id of the folder to restore the media into. If omitted, each media returns to the folder it was deleted from.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `media_hashed_ids`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: media_hashed_ids.

list_media

wistia-cli list-media

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`name`, `updated`, `position`) require offset pagination. Values: `name`, `created`, `updated`, `position`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`folder_id`	No; body/guard rules still apply	string	A hashed ID specifying the folder from which you would like to get results.
`name`	No; body/guard rules still apply	string	Find a media or medias whose name exactly matches this parameter.
`description_format`	No; body/guard rules still apply	string	Format for media descriptions
`include`	No; body/guard rules still apply	string	Set to `speakers` to include active transcript speaker assignments used for diarization. Webinar hosts and panelists are not included. Values: `speakers`.
`type`	No; body/guard rules still apply	string	A string specifying which type of media you would like to get. Values: `Video`, `Audio`, `Image`, `PdfDocument`, `MicrosoftOfficeDocument`, `Swf`, `UnknownType`.
`hashed_ids`	No; body/guard rules still apply	array	Find all of the medias by these hashed_ids. Array items: string.
`tags`	No; body/guard rules still apply	array	Find all of the medias that match all of these tag names. Array items: string.
`archived`	No; body/guard rules still apply	boolean	Filter by archived status. True will return only archived medias, while false will return only active medias.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

get_media

wistia-cli get-media

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`description_format`	No; body/guard rules still apply	string	Format for media descriptions
`include`	No; body/guard rules still apply	string	Set to `speakers` to include active transcript speaker assignments used for diarization. Webinar hosts and panelists are not included. Values: `speakers`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_media

wistia-cli update-media

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`name`	No; body/guard rules still apply	string	The media’s new name.
`new_still_media_id`	No; body/guard rules still apply	string	The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.
`description`	No; body/guard rules still apply	string	A new description for this media. Accepts plain text or markdown.
`tags`	No; body/guard rules still apply	array	An array of tag names to apply to the media. This replaces any existing tags. To add tags without replacing existing tags, use bulk-tag-media. Array items: string.
`custom_metadata`	No; body/guard rules still apply	object	Custom metadata field values to set, keyed by field key. Values take the same shapes as the Set Custom Metadata Field Value endpoint; a null value clears that field and omitted fields are untouched. Requires the custom metadata feature on the account.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

delete_media

wistia-cli delete-media

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

copy_media

wistia-cli copy-media

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`folder_id`	No; body/guard rules still apply	integer	The ID of the folder where you want the new copy placed. Defaults to the source media’s current folder if omitted or invalid.
`owner`	No; body/guard rules still apply	string	An email address specifying the owner of the new media. Defaults to the source media’s current owner if omitted or invalid. format: `email`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

swap_media

wistia-cli swap-media

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media to be replaced. minLength: `1`.
`replacement_media_id`	No; body/guard rules still apply	string	The hashed ID of the media that will replace the original media. Must be the same media type as the original.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `replacement_media_id`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: replacement_media_id.

get_media_stats

wistia-cli get-media-stats

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

translate_media

wistia-cli translate-media

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`target_language`	No; body/guard rules still apply	string	The language to translate the transcript to. Use the bibliographic ISO 639-2 form or a supported regional or script IETF tag.
`source_language`	No; body/guard rules still apply	string	The language of the source transcript. Use the bibliographic ISO 639-2 form or a supported regional or script IETF tag. If not provided, the media's default transcript language will be used.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `target_language`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: target_language.

import_media_from_url

wistia-cli import-media-from-url

Argument	Required	Type	Details
`url`	No; body/guard rules still apply	string	The publicly accessible URL of the media file to import. format: `uri`.
`folder_id`	No; body/guard rules still apply	string	The hashed ID of the folder (project) to import the media into. If not provided, a new folder will be created.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `url`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: url.

archive_media

wistia-cli archive-media

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	An array of the media hashed IDs to be archived. Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `hashed_ids`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: hashed_ids.

move_media

wistia-cli move-media

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	An array of the media hashed IDs to be moved. Array items: string.
`folder_id`	No; body/guard rules still apply	string	The hashed ID of the folder where you want the media moved.
`subfolder_id`	No; body/guard rules still apply	string	Optional. The hashed ID of the subfolder where you want the media moved. If not provided, media will be moved to the folder's default subfolder. The subfolder must belong to the specified folder.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `hashed_ids`, `folder_id`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: hashed_ids, folder_id.

restore_media

wistia-cli restore-media

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	An array of the media hashed IDs to be restored. Array items: string.
`folder_id`	No; body/guard rules still apply	string	The hashed ID of the folder to restore the medias to.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `hashed_ids`, `folder_id`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: hashed_ids, folder_id.

bulk_copy_media

wistia-cli bulk-copy-media

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	An array of the media hashed IDs to be copied. Array items: string.
`folder_id`	No; body/guard rules still apply	string	The hashed ID of the destination folder where the copies will be placed.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `hashed_ids`, `folder_id`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: hashed_ids, folder_id.

get_customizations

wistia-cli get-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

create_customizations

wistia-cli create-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`autoPlay`	No; body/guard rules still apply	boolean	If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers.
`controlsVisibleOnLoad`	No; body/guard rules still apply	boolean	If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.
`copyLinkAndThumbnailEnabled`	No; body/guard rules still apply	boolean	If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.
`doNotTrack`	No; body/guard rules still apply	boolean	If set to true, data for each viewing session will not be tracked.
`email`	No; body/guard rules still apply	string	Associate a specific email address with this video’s viewing sessions.
`endVideoBehavior`	No; body/guard rules still apply	string	Determines what happens when the video ends. Options are default (stays on the last frame), reset (shows thumbnail and controls), and loop (plays again from the start).
`fakeFullscreen`	No; body/guard rules still apply	boolean	If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.
`fitStrategy`	No; body/guard rules still apply	string	Resizes the video when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none.
`fullscreenButton`	No; body/guard rules still apply	boolean	If set to true, the fullscreen button will be available as a video control.
`fullscreenOnRotateToLandscape`	No; body/guard rules still apply	boolean	If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.
`keyMoments`	No; body/guard rules still apply	boolean	If set to false, the key moments feature will be disabled.
`muted`	No; body/guard rules still apply	boolean	If set to true, the video will start in a muted state.
`playbackRateControl`	No; body/guard rules still apply	boolean	If set to false, the playback speed controls in the settings menu will be hidden.
`playbar`	No; body/guard rules still apply	boolean	If set to true, the playbar will be available. If set to false, it will be hidden.
`playButton`	No; body/guard rules still apply	boolean	Indicates if the play button is visible.
`playerColor`	No; body/guard rules still apply	string	Changes the base color of the player. Expects a hexadecimal rgb string.
`playlistLinks`	No; body/guard rules still apply	boolean	Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.
`playlistLoop`	No; body/guard rules still apply	boolean	If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.
`playsinline`	No; body/guard rules still apply	boolean	If set to false, videos will play within the native mobile player.
`playPauseNotifier`	No; body/guard rules still apply	boolean	If set to false, animations for the Pause and Play symbols will be removed.
`playSuspendedOffScreen`	No; body/guard rules still apply	boolean	If set to false for a muted autoplay video, the video won't pause when out of view.
`plugin`	No; body/guard rules still apply	object	Current schema
`preload`	No; body/guard rules still apply	string	Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.
`qualityControl`	No; body/guard rules still apply	boolean	If set to false, the video quality selector in the settings menu will be hidden.
`qualityMax`	No; body/guard rules still apply	integer	Specifies the maximum quality the video will play at.
`qualityMin`	No; body/guard rules still apply	integer	Specifies the minimum quality the video will play at.
`resumable`	No; body/guard rules still apply	string	Determines if the video should resume from where the viewer left off. Options are true, false, and auto.
`seo`	No; body/guard rules still apply	boolean	If set to true, the video’s metadata will be injected into the page’s markup for SEO.
`settingsControl`	No; body/guard rules still apply	boolean	If set to true, the settings control will be available.
`silentAutoPlay`	No; body/guard rules still apply	string	Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are true, allow, and false.
`smallPlayButton`	No; body/guard rules still apply	boolean	Current schema
`stillUrl`	No; body/guard rules still apply	string	Overrides the thumbnail image that appears before the video plays.
`time`	No; body/guard rules still apply	string	Sets the starting time of the video.
`thumbnailAltText`	No; body/guard rules still apply	string	Sets the Thumbnail Alt Text for the media.
`videoFoam`	No; body/guard rules still apply	JSON union	When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height. At least one schema branch must match.
`volume`	No; body/guard rules still apply	number	Sets the volume of the video.
`volumeControl`	No; body/guard rules still apply	boolean	When set to true, a volume control is available over the video.
`wmode`	No; body/guard rules still apply	string	If set to transparent, the background behind the player will be transparent instead of black.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.videoThumbnail`	No	object	Current schema
`plugin.videoThumbnail.clickToPlayButton`	No	boolean	If set to false, removes the “Click to Play” button on video thumbnails.
`plugin.socialbar-v1`	No	object	Current schema
`plugin.socialbar-v1.buttons`	No	string	Current schema
`plugin.socialbar-v1.showTweetCount`	No	boolean	Current schema
`plugin.socialbar-v1.tweetText`	No	string	Current schema
`plugin.socialbar-v1.height`	No	integer	Current schema
`plugin.chapters`	No	object	Current schema
`plugin.chapters.visibleOnLoad`	No	boolean	Current schema
`plugin.chapters.chapterList`	No	array	Array items: object.
`plugin.chapters.chapterList[].id`	No	string	Current schema
`plugin.chapters.chapterList[].title`	No	string	Current schema
`plugin.chapters.chapterList[].time`	No	string	Current schema
`plugin.chapters.chapterList[].deleted`	No	string	Current schema
`plugin.chapters.on`	No	boolean	Current schema
`plugin.postRoll-v1`	No	object	Adds a Call To Action to your Video
`plugin.postRoll-v1.rewatch`	No	boolean	If set to true, allows the video to be rewatched.
`plugin.postRoll-v1.text`	No	string	The URL of the text to be displayed.
`plugin.postRoll-v1.link`	No	string	The URL of the link to be displayed.
`plugin.postRoll-v1.time`	No	JSON union	The time when the post-roll should be displayed. Can be a string like "end" or a number representing seconds. Exactly one of 2 schema branches; inspect the complete schema.
`plugin.postRoll-v1.autoSize`	No	boolean	If set to true, the post-roll will automatically adjust its size.
`plugin.postRoll-v1.style`	No	object	Current schema
`plugin.postRoll-v1.style.backgroundColor`	No	string	The background color of the post-roll.
`plugin.postRoll-v1.ctaType`	No	string	The type of call-to-action to be displayed. Typically set to "text". Other options are "image" which allows for "altText", and "html".
`plugin.postRoll-v1.on`	No	boolean	If set to true, the post-roll is enabled.
`plugin.postRoll-v1.conversionOpportunityKey`	No	string	The key used for tracking conversion opportunities.
`plugin.captions-v1`	No	object	Enables closed captions for the video
`plugin.captions-v1.on`	No	boolean	If set to true, the captions plugin is enabled and captions controls will be available to viewers.
`plugin.captions-v1.onByDefault`	No	boolean	If set to true, captions will be turned on automatically when the video loads. Only takes effect when the captions plugin is enabled.

update_customizations

wistia-cli update-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`autoPlay`	No; body/guard rules still apply	boolean	If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers.
`controlsVisibleOnLoad`	No; body/guard rules still apply	boolean	If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.
`copyLinkAndThumbnailEnabled`	No; body/guard rules still apply	boolean	If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.
`doNotTrack`	No; body/guard rules still apply	boolean	If set to true, data for each viewing session will not be tracked.
`email`	No; body/guard rules still apply	string	Associate a specific email address with this video’s viewing sessions.
`endVideoBehavior`	No; body/guard rules still apply	string	Determines what happens when the video ends. Options are default (stays on the last frame), reset (shows thumbnail and controls), and loop (plays again from the start).
`fakeFullscreen`	No; body/guard rules still apply	boolean	If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.
`fitStrategy`	No; body/guard rules still apply	string	Resizes the video when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none.
`fullscreenButton`	No; body/guard rules still apply	boolean	If set to true, the fullscreen button will be available as a video control.
`fullscreenOnRotateToLandscape`	No; body/guard rules still apply	boolean	If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.
`keyMoments`	No; body/guard rules still apply	boolean	If set to false, the key moments feature will be disabled.
`muted`	No; body/guard rules still apply	boolean	If set to true, the video will start in a muted state.
`playbackRateControl`	No; body/guard rules still apply	boolean	If set to false, the playback speed controls in the settings menu will be hidden.
`playbar`	No; body/guard rules still apply	boolean	If set to true, the playbar will be available. If set to false, it will be hidden.
`playButton`	No; body/guard rules still apply	boolean	Indicates if the play button is visible.
`playerColor`	No; body/guard rules still apply	string	Changes the base color of the player. Expects a hexadecimal rgb string.
`playlistLinks`	No; body/guard rules still apply	boolean	Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.
`playlistLoop`	No; body/guard rules still apply	boolean	If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.
`playsinline`	No; body/guard rules still apply	boolean	If set to false, videos will play within the native mobile player.
`playPauseNotifier`	No; body/guard rules still apply	boolean	If set to false, animations for the Pause and Play symbols will be removed.
`playSuspendedOffScreen`	No; body/guard rules still apply	boolean	If set to false for a muted autoplay video, the video won't pause when out of view.
`plugin`	No; body/guard rules still apply	object	Current schema
`preload`	No; body/guard rules still apply	string	Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.
`qualityControl`	No; body/guard rules still apply	boolean	If set to false, the video quality selector in the settings menu will be hidden.
`qualityMax`	No; body/guard rules still apply	integer	Specifies the maximum quality the video will play at.
`qualityMin`	No; body/guard rules still apply	integer	Specifies the minimum quality the video will play at.
`resumable`	No; body/guard rules still apply	string	Determines if the video should resume from where the viewer left off. Options are true, false, and auto.
`seo`	No; body/guard rules still apply	boolean	If set to true, the video’s metadata will be injected into the page’s markup for SEO.
`settingsControl`	No; body/guard rules still apply	boolean	If set to true, the settings control will be available.
`silentAutoPlay`	No; body/guard rules still apply	string	Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are true, allow, and false.
`smallPlayButton`	No; body/guard rules still apply	boolean	Current schema
`stillUrl`	No; body/guard rules still apply	string	Overrides the thumbnail image that appears before the video plays.
`time`	No; body/guard rules still apply	string	Sets the starting time of the video.
`thumbnailAltText`	No; body/guard rules still apply	string	Sets the Thumbnail Alt Text for the media.
`videoFoam`	No; body/guard rules still apply	JSON union	When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height. At least one schema branch must match.
`volume`	No; body/guard rules still apply	number	Sets the volume of the video.
`volumeControl`	No; body/guard rules still apply	boolean	When set to true, a volume control is available over the video.
`wmode`	No; body/guard rules still apply	string	If set to transparent, the background behind the player will be transparent instead of black.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.videoThumbnail`	No	object	Current schema
`plugin.videoThumbnail.clickToPlayButton`	No	boolean	If set to false, removes the “Click to Play” button on video thumbnails.
`plugin.socialbar-v1`	No	object	Current schema
`plugin.socialbar-v1.buttons`	No	string	Current schema
`plugin.socialbar-v1.showTweetCount`	No	boolean	Current schema
`plugin.socialbar-v1.tweetText`	No	string	Current schema
`plugin.socialbar-v1.height`	No	integer	Current schema
`plugin.chapters`	No	object	Current schema
`plugin.chapters.visibleOnLoad`	No	boolean	Current schema
`plugin.chapters.chapterList`	No	array	Array items: object.
`plugin.chapters.chapterList[].id`	No	string	Current schema
`plugin.chapters.chapterList[].title`	No	string	Current schema
`plugin.chapters.chapterList[].time`	No	string	Current schema
`plugin.chapters.chapterList[].deleted`	No	string	Current schema
`plugin.chapters.on`	No	boolean	Current schema
`plugin.postRoll-v1`	No	object	Adds a Call To Action to your Video
`plugin.postRoll-v1.rewatch`	No	boolean	If set to true, allows the video to be rewatched.
`plugin.postRoll-v1.text`	No	string	The URL of the text to be displayed.
`plugin.postRoll-v1.link`	No	string	The URL of the link to be displayed.
`plugin.postRoll-v1.time`	No	JSON union	The time when the post-roll should be displayed. Can be a string like "end" or a number representing seconds. Exactly one of 2 schema branches; inspect the complete schema.
`plugin.postRoll-v1.autoSize`	No	boolean	If set to true, the post-roll will automatically adjust its size.
`plugin.postRoll-v1.style`	No	object	Current schema
`plugin.postRoll-v1.style.backgroundColor`	No	string	The background color of the post-roll.
`plugin.postRoll-v1.ctaType`	No	string	The type of call-to-action to be displayed. Typically set to "text". Other options are "image" which allows for "altText", and "html".
`plugin.postRoll-v1.on`	No	boolean	If set to true, the post-roll is enabled.
`plugin.postRoll-v1.conversionOpportunityKey`	No	string	The key used for tracking conversion opportunities.
`plugin.captions-v1`	No	object	Enables closed captions for the video
`plugin.captions-v1.on`	No	boolean	If set to true, the captions plugin is enabled and captions controls will be available to viewers.
`plugin.captions-v1.onByDefault`	No	boolean	If set to true, captions will be turned on automatically when the video loads. Only takes effect when the captions plugin is enabled.

delete_customizations

wistia-cli delete-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the media whose customizations are to be deleted. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

get_appearance_customizations

wistia-cli get-appearance-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_appearance_customizations

wistia-cli update-appearance-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`playerColor`	No; body/guard rules still apply	string	Base color of the player as a hexadecimal RGB string (no leading '#').
`playerColorGradient`	No; body/guard rules still apply	object	Optional gradient applied to the player color.
`roundedPlayer`	No; body/guard rules still apply	integer	Corner radius of the player in pixels. 0 disables rounding.
`opaqueControls`	No; body/guard rules still apply	boolean	If true, player controls render on an opaque background.
`contrastIcons`	No; body/guard rules still apply	boolean	If true, control icons use a higher-contrast treatment.
`branding`	No; body/guard rules still apply	boolean	If false, Wistia branding is hidden on the player.
`showCustomerLogo`	No; body/guard rules still apply	boolean	If true, your customer logo is shown on the player.
`customerLogoImageUrl`	No; body/guard rules still apply	string	URL of the customer logo image to display on the player.
`customerLogoTargetUrl`	No; body/guard rules still apply	string	URL the customer logo links to when clicked.
`customerLogoPlacement`	No; body/guard rules still apply	string	Placement of the customer logo on the player (e.g. top-right).
`customerLogoSizePercent`	No; body/guard rules still apply	integer	Size of the customer logo as a percentage of the player.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`playerColorGradient.on`	No	boolean	Whether the gradient is enabled.
`playerColorGradient.colors`	No	array	Ordered list of [hex color, stop] pairs defining the gradient. Array items: array.

get_playback_customizations

wistia-cli get-playback-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_playback_customizations

wistia-cli update-playback-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`autoPlay`	No; body/guard rules still apply	boolean	If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers.
`silentAutoPlay`	No; body/guard rules still apply	string	Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are "true", "allow", and "false".
`muted`	No; body/guard rules still apply	boolean	If set to true, the video will start in a muted state.
`volume`	No; body/guard rules still apply	number	Sets the volume of the video.
`controlsVisibleOnLoad`	No; body/guard rules still apply	boolean	If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.
`playButton`	No; body/guard rules still apply	boolean	Indicates if the play button is visible.
`smallPlayButton`	No; body/guard rules still apply	boolean	If set to true, the small play button control is shown.
`playbar`	No; body/guard rules still apply	boolean	If set to true, the playbar will be available. If set to false, it will be hidden.
`volumeControl`	No; body/guard rules still apply	boolean	When set to true, a volume control is available over the video.
`fullscreenButton`	No; body/guard rules still apply	boolean	If set to true, the fullscreen button will be available as a video control.
`settingsControl`	No; body/guard rules still apply	boolean	If set to true, the settings control will be available.
`playbackRateControl`	No; body/guard rules still apply	boolean	If set to false, the playback speed controls in the settings menu will be hidden.
`qualityControl`	No; body/guard rules still apply	boolean	If set to false, the video quality selector in the settings menu will be hidden.
`qualityMin`	No; body/guard rules still apply	integer	Specifies the minimum quality the video will play at.
`qualityMax`	No; body/guard rules still apply	integer	Specifies the maximum quality the video will play at.
`videoQuality`	No; body/guard rules still apply	string	Sets the default video quality the video will play at.
`hls`	No; body/guard rules still apply	boolean	If set to true, HLS adaptive bitrate streaming is enabled.
`endVideoBehavior`	No; body/guard rules still apply	string	Determines what happens when the video ends. Options are "default" (stays on the last frame), "reset" (shows thumbnail and controls), and "loop" (plays again from the start).
`playsinline`	No; body/guard rules still apply	boolean	If set to false, videos will play within the native mobile player.
`playlistLoop`	No; body/guard rules still apply	boolean	If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.
`playlistLinks`	No; body/guard rules still apply	boolean	Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.
`playPauseNotifier`	No; body/guard rules still apply	boolean	If set to false, animations for the Pause and Play symbols will be removed.
`playSuspendedOffScreen`	No; body/guard rules still apply	boolean	If set to false for a muted autoplay video, the video won’t pause when out of view.
`resumable`	No; body/guard rules still apply	string	Determines if the video should resume from where the viewer left off. Options are "true", "false", and "auto".
`preload`	No; body/guard rules still apply	string	Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.
`time`	No; body/guard rules still apply	string	Sets the starting time of the video.
`keyMoments`	No; body/guard rules still apply	boolean	If set to false, the key moments feature will be disabled.
`fullscreenOnRotateToLandscape`	No; body/guard rules still apply	boolean	If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.
`fakeFullScreen`	No; body/guard rules still apply	boolean	If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.
`videoFoam`	No; body/guard rules still apply	JSON union	When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height. At least one schema branch must match.
`wmode`	No; body/guard rules still apply	string	If set to transparent, the background behind the player will be transparent instead of black.
`bpbTime`	No; body/guard rules still apply	string	Controls when the big play button appears, expressed as a string.
`spherical`	No; body/guard rules still apply	boolean	If set to true, the video is rendered as a spherical (360-degree) video.
`clickForSound`	No; body/guard rules still apply	boolean	If set to true, viewers can click to enable sound on a muted video.
`seo`	No; body/guard rules still apply	boolean	If set to true, the video’s metadata will be injected into the page’s markup for SEO.
`doNotTrack`	No; body/guard rules still apply	boolean	If set to true, data for each viewing session will not be tracked.
`copyLinkAndThumbnailEnabled`	No; body/guard rules still apply	boolean	If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.
`email`	No; body/guard rules still apply	string	Associate a specific email address with this video’s viewing sessions.
`googleAnalytics`	No; body/guard rules still apply	string	Google Analytics tracking configuration to associate with this video’s viewing sessions.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

get_thumbnail_customizations

wistia-cli get-thumbnail-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_thumbnail_customizations

wistia-cli update-thumbnail-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`stillUrl`	No; body/guard rules still apply	string	Overrides the thumbnail image that appears before the video plays.
`thumbnailAltText`	No; body/guard rules still apply	string	Alt text for the thumbnail image, used for accessibility.
`fitStrategy`	No; body/guard rules still apply	string	Resizes the thumbnail when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none.
`unalteredStillImageAsset`	No; body/guard rules still apply	string	Reference to the original, unaltered still image asset.
`plugin`	No; body/guard rules still apply	object	Container for thumbnail-related player plugin configurations.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.videoThumbnail`	No	object	Looping video thumbnail (a short clip used as the poster).
`plugin.videoThumbnail.clickToPlayButton`	No	boolean	If set to false, removes the “Click to Play” button on video thumbnails.
`plugin.videoThumbnail.clickForSound`	No	boolean	If set to true, shows a click-for-sound affordance on the video thumbnail.
`plugin.videoThumbnail.hashedId`	No	string	The hashed ID of the media used as the looping video thumbnail.
`plugin.videoThumbnail.trimStart`	No	string	Start time of the trimmed clip used as the video thumbnail.
`plugin.videoThumbnail.trimEnd`	No	string	End time of the trimmed clip used as the video thumbnail.
`plugin.videoThumbnail.priorityMode`	No	string	Priority mode controlling how the video thumbnail is loaded.
`plugin.thumbnailTextOverlay-v2`	No	object	Text overlay rendered on top of the thumbnail.
`plugin.thumbnailTextOverlay-v2.on`	No	boolean	If set to true, the text overlay is enabled.
`plugin.thumbnailTextOverlay-v2.text`	No	string	The text displayed in the overlay.

get_accessibility_customizations

wistia-cli get-accessibility-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_accessibility_customizations

wistia-cli update-accessibility-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`captionsBackgroundColor`	No; body/guard rules still apply	string	Background color of the captions as a hexadecimal RGB string (no leading '#').
`captionsBorderRadius`	No; body/guard rules still apply	integer	Corner radius of the captions background in pixels.
`captionsTextColor`	No; body/guard rules still apply	string	Color of the captions text as a hexadecimal RGB string (no leading '#').
`captionsTextSize`	No; body/guard rules still apply	integer	Size of the captions text in pixels.
`captionsFontFamily`	No; body/guard rules still apply	string	Font family used for the captions text.
`transcriptEnabled`	No; body/guard rules still apply	boolean	If true, the interactive transcript is shown alongside the video.
`showTranscriptSpeakers`	No; body/guard rules still apply	boolean	If true, speaker labels are displayed in the transcript.
`audioDescriptionControl`	No; body/guard rules still apply	boolean	If true, the audio description control is available to viewers.
`plugin`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.captions`	No	object	Modern captions plugin configuration.
`plugin.captions.on`	No	boolean	If set to true, the captions plugin is enabled and captions controls will be available to viewers.
`plugin.captions.onByDefault`	No	boolean	If set to true, captions will be turned on automatically when the video loads. Only takes effect when the captions plugin is enabled.
`plugin.captions-v1`	No	object	Enables closed captions for the video.
`plugin.captions-v1.on`	No	boolean	If set to true, the captions plugin is enabled and captions controls will be available to viewers.
`plugin.captions-v1.onByDefault`	No	boolean	If set to true, captions will be turned on automatically when the video loads. Only takes effect when the captions plugin is enabled.
`plugin.extendedAudioDescription`	No	object	Enables an extended audio description track for the video.
`plugin.extendedAudioDescription.on`	No	boolean	If set to true, the extended audio description plugin is enabled.

get_chapters_customizations

wistia-cli get-chapters-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_chapters_customizations

wistia-cli update-chapters-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the media to be customized. minLength: `1`.
`plugin`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.chapters`	No	object	Current schema
`plugin.chapters.on`	No	boolean	Whether chapters are enabled.
`plugin.chapters.visibleOnLoad`	No	boolean	Whether the chapter list is visible when the player loads.
`plugin.chapters.chapterList`	No	array	The ordered list of chapters. Array items: object.
`plugin.chapters.chapterList[].id`	No	string	Current schema
`plugin.chapters.chapterList[].title`	No	string	Current schema
`plugin.chapters.chapterList[].time`	No	string	Start time of the chapter, in seconds.
`plugin.chapters.chapterList[].deleted`	No	string	Current schema
`plugin.audioChapters`	No	object	Current schema
`plugin.audioChapters.on`	No	boolean	Current schema
`plugin.audioChapters.visibleOnLoad`	No	boolean	Current schema
`plugin.audioChapters.chapterList`	No	array	Array items: object.
`plugin.audioChapters.chapterList[].id`	No	string	Current schema
`plugin.audioChapters.chapterList[].title`	No	string	Current schema
`plugin.audioChapters.chapterList[].time`	No	string	Current schema
`plugin.audioChapters.chapterList[].deleted`	No	string	Current schema

get_engagement_customizations

wistia-cli get-engagement-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_engagement_customizations

wistia-cli update-engagement-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`plugin`	No; body/guard rules still apply	object	Container for engagement plugin configurations.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.postRoll-v1`	No	object	Adds a Call To Action to your Video.
`plugin.postRoll-v1.rewatch`	No	boolean	If set to true, allows the video to be rewatched.
`plugin.postRoll-v1.text`	No	string	The text to be displayed.
`plugin.postRoll-v1.link`	No	string	The URL of the link to be displayed.
`plugin.postRoll-v1.time`	No	JSON union	The time when the post-roll should be displayed. Can be a string like "end" or a number representing seconds. Exactly one of 2 schema branches; inspect the complete schema.
`plugin.postRoll-v1.autoSize`	No	boolean	If set to true, the post-roll will automatically adjust its size.
`plugin.postRoll-v1.style`	No	object	Current schema
`plugin.postRoll-v1.style.backgroundColor`	No	string	The background color of the post-roll.
`plugin.postRoll-v1.ctaType`	No	string	The type of call-to-action to be displayed. Typically set to "text". Other options are "image" which allows for "altText", and "html".
`plugin.postRoll-v1.on`	No	boolean	If set to true, the post-roll is enabled.
`plugin.postRoll-v1.conversionOpportunityKey`	No	string	The key used for tracking conversion opportunities.
`plugin.midrollLink-v1`	No	object	Timed annotation links that appear over the video at specific times.
`plugin.midrollLink-v1.on`	No	boolean	If set to true, the timed annotation links are enabled.
`plugin.midrollLink-v1.links`	No	array	The set of annotation links. Array items: object.
`plugin.midrollLink-v1.links[].text`	No	string	The text of the annotation link.
`plugin.midrollLink-v1.links[].url`	No	string	The URL the annotation link points to.
`plugin.midrollLink-v1.links[].time`	No	string	The time (in seconds) at which the link appears.
`plugin.midrollLink-v1.links[].duration`	No	string	How long (in seconds) the link remains visible.

wistia-cli get-related-media-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

wistia-cli update-related-media-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`plugin`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.relatedMedia`	No	object	Configuration for the related-media recommendations plugin.
`plugin.relatedMedia.on`	No	boolean	Whether related-media recommendations are enabled.
`plugin.relatedMedia.hashedIdList`	No	array	Ordered list of media hashed IDs to recommend. Array items: string.
`plugin.relatedMedia.shouldShowOnPause`	No	boolean	If true, recommendations are shown when the video is paused.
`plugin.relatedMedia.shouldShowOnEnd`	No	boolean	If true, recommendations are shown when the video ends.
`plugin.relatedMedia.mediaLabelText`	No	string	Label text displayed above the recommended media.
`plugin.relatedMedia.watchButtonText`	No	string	Text shown on the watch button for a recommended media.

wistia-cli get-sharing-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

wistia-cli update-sharing-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`plugin`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`plugin.share`	No	object	Configuration for the share bar plugin.
`plugin.share.on`	No	boolean	Whether the share bar is enabled.
`plugin.share.channels`	No	array	Complete ordered list of share channels to enable on the share bar. This replaces the entire list : include every channel you want active. To enable downloads, include "download" here AND set downloadType. Array items: string.
`plugin.share.tweetText`	No	string	Default text used when sharing the video to X/Twitter.
`plugin.share.downloadType`	No	string	Which download quality is offered to viewers. Only takes effect when "download" is included in the channels array. Values: `sd_mp4`, `hd_mp4`, `original`, `all_qualities`.
`plugin.share.overrideUrl`	No	string	URL used in place of the default share URL.
`plugin.share.pageUrl`	No	string	URL of the page the share bar should reference.
`plugin.share.pageTitle`	No	string	Title of the page the share bar should reference.
`plugin.share.conversionOpportunityKey`	No	string	The key used for tracking conversion opportunities. Managed by Wistia when the share bar is enabled.

get_lead_capture_customizations

wistia-cli get-lead-capture-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_lead_capture_customizations

wistia-cli update-lead-capture-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`provider`	No; body/guard rules still apply	string	Which lead-capture mechanism to configure. Values: `wistia_form`, `hubspot`, `marketo`, `pardot`.
`enabled`	No; body/guard rules still apply	boolean	Whether the selected provider is turned on. Defaults to true.
`settings`	No; body/guard rules still apply	object	Provider-specific settings. Only the fields relevant to the chosen provider are used.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `provider`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: provider.

Nested body fields:

Field	Required	Type	Details
`settings.time`	No	string	When the form appears: "start"/"before", a number of seconds, or "end".
`settings.allowSkip`	No	boolean	Whether the viewer may skip the form.
`settings.hashedId`	No	string	(Wistia Form) The hashed ID of the Wistia form to embed.
`settings.displayMode`	No	string	(Wistia Form) How the form is displayed.
`settings.showLogo`	No	boolean	(Wistia Form) Whether to show the Wistia logo on the form.
`settings.backgroundColor`	No	string	Background color of the form as a hex string.
`settings.formId`	No	string	(HubSpot/Marketo/Pardot) The external form identifier.
`settings.portalId`	No	string	(HubSpot) The HubSpot portal/account identifier.

get_access_customizations

wistia-cli get-access-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_access_customizations

wistia-cli update-access-customizations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video to be customized. minLength: `1`.
`private`	No; body/guard rules still apply	object	Current schema
`encrypted`	No; body/guard rules still apply	object	Current schema
`plugin`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`private.password_protect_on`	No	boolean	Whether password protection is enabled for the video.
`encrypted.password_protect_password`	No	string	The password viewers must enter. Stored encrypted; also returned by the show endpoint.
`plugin.passwordProtectedVideo`	No	object	Current schema
`plugin.passwordProtectedVideo.on`	No	boolean	Whether the password-protection plugin is enabled.
`plugin.passwordProtectedVideo.challenge`	No	string	Optional challenge/prompt text shown to viewers.
`plugin.passwordProtectedVideo.src`	No	string	Internal source marker for the protection plugin.
`plugin.passwordProtectedVideo.async`	No	boolean	Whether the password check is performed asynchronously.

wistia-cli resolve-share-link

Argument	Required	Type	Details
`identifier`	Yes	string	The share link's URL segment : its hashed ID or custom slug. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

wistia-cli get-share-link

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

wistia-cli update-share-link

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`visibility`	No; body/guard rules still apply	string	Controls who can view the media via this share link. - `unlocked`: anyone with the link can view the media. - `account`: only signed-in members of the media's account can view. - `locked`: only contacts with access to the media's folder can view. - `domain_verified`: only viewers signed in with an email address at a domain verified on the media's account can view. Requires the account to be enrolled in the domain validation gate; otherwise setting this value returns 400. Values: `unlocked`, `account`, `locked`, `domain_verified`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `visibility`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: visibility.

wistia-cli delete-share-link

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

list_captions

wistia-cli list-captions

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media for which captions are to be retrieved. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

create_captions

wistia-cli create-captions

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media for which captions are to be added. minLength: `1`.
`caption_file`	No; body/guard rules still apply	string	Either an attached SRT file or a string parameter with the contents of an SRT file.
`language`	No; body/guard rules still apply	string	An optional parameter that denotes which language this file represents. Should conform to ISO-639–2. If left unspecified, the language code will be detected automatically.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `caption_file`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: caption_file.

list_all_captions

wistia-cli list-all-captions

Argument	Required	Type	Details
`media_id`	No; body/guard rules still apply	string	Find captions for a particular media by providing the media hashed ID
`media_ids`	No; body/guard rules still apply	array	Find captions belonging to any of these media hashed IDs. IDs that don't match a media the token can access are ignored rather than returning an error. Array items: string.
`languages`	No; body/guard rules still apply	array	Find captions in any of these languages, using the codes returned in each caption's `language` field (for example `eng` or `spa`). When combined with `media_ids[]`, captions must match both. Array items: string.
`include`	No; body/guard rules still apply	string	Set to `metadata` to omit caption text and return only track metadata. Omitting this parameter preserves the existing response, including SRT text. Values: `metadata`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id` is supported. default: `id`. Values: `id`, `created`, `updated`, `language`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) default: `1`. Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

find_caption_matches

wistia-cli find-caption-matches

Argument	Required	Type	Details
`media_ids`	No; body/guard rules still apply	array	Explicit hashed IDs of the media whose captions should be searched. minItems: `1`. maxItems: `50`. Array items: string.
`target_text`	No; body/guard rules still apply	string	Exact caption wording to locate. minLength: `1`. maxLength: `500`.
`language_code`	No; body/guard rules still apply	string	Exact IETF language tag. Omit when each media has only one caption track. minLength: `1`.
`occurrence`	No; body/guard rules still apply	integer	One-based exact occurrence to return, including occurrences after the first 10. minimum: `1`.
`start_ms`	No; body/guard rules still apply	integer	Optional start of a time range used to disambiguate the match. minimum: `0`.
`end_ms`	No; body/guard rules still apply	integer	Optional end of a time range used to disambiguate the match. minimum: `0`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `media_ids`, `target_text`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: media_ids, target_text.

purchase_captions

wistia-cli purchase-captions

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	Unique identifier for the media. minLength: `1`.
`automated`	No; body/guard rules still apply	boolean	Order computer-generated captions or human-reviewed ones. What each costs depends on the account's plan and billing settings; computer-generated captions are included at no cost on some plans and billed per minute on others. default: `False`.
`rush`	No; body/guard rules still apply	boolean	Enable rush order for one business day turnaround instead of the standard four, for human-reviewed captions only. Rush bills at the account's higher per-minute rate. default: `True`.
`automatically_enable`	No; body/guard rules still apply	boolean	Automatically enable captions for the media once the order is ready or hold the captions for review before manually enabling. default: `True`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

get_captions

wistia-cli get-captions

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media from which captions are to be retrieved. minLength: `1`.
`language_code`	Yes	string	The 3-character ISO 639-2 language code of the captions to be retrieved (e.g., `eng`, `fra`, `spa`). Some languages use extended IETF subtags (e.g., `zh-Hant`). minLength: `1`.
`include`	No; body/guard rules still apply	string	Set to `segments` for time-coded caption cues or `diarized_segments` for speaker-turn segments in JSON responses. Values: `segments`, `diarized_segments`.
`include_speakers`	No; body/guard rules still apply	boolean	For TXT responses, set to true to group the transcript by speaker turns and include speaker labels. Ignored for other response formats. default: `False`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_captions

wistia-cli update-captions

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	Unique identifier for the media. minLength: `1`.
`language_code`	Yes	string	Language code conforming to ISO-639-2 for which the captions should be updated. minLength: `1`. pattern: `^[a-z]{3}$`.
`caption_file`	No; body/guard rules still apply	string	Either an attached SRT file or a string parameter with the contents of an SRT file.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `caption_file`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: caption_file.

delete_captions

wistia-cli delete-captions

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	Unique identifier for the media. minLength: `1`.
`language_code`	Yes	string	Language code conforming to ISO-639-2 for which the captions should be removed. minLength: `1`. pattern: `^[a-z]{3}$`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

edit_captions_text

wistia-cli edit-captions-text

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media whose transcript should be edited. minLength: `1`.
`language_code`	Yes	string	The 3-character ISO 639-2 language code of the caption track to edit (e.g., `eng`, `fra`, `spa`). Some languages use extended IETF subtags (e.g., `zh-Hant`). minLength: `1`.
`edits`	No; body/guard rules still apply	array	The corrections to apply, all-or-nothing, in one new version. minItems: `1`. maxItems: `20`. Array items: object.
`expected_version`	No; body/guard rules still apply	integer	The active caption version returned with the caption content used to prepare these edits. The edit applies only if that is still the active version; otherwise it returns 409 so you re-read and retry.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `edits`, `expected_version`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: edits, expected_version.

Nested body fields:

Field	Required	Type	Details
`edits[].target_text`	Yes inside object	string	The exact transcript text to replace. Matched exactly after normalization (case, punctuation, and whitespace are ignored). Fuzzy matches are never applied : they are only returned as suggestions.
`edits[].replacement_text`	Yes inside object	string	The text to substitute for the target. Use an empty string to delete the target.
`edits[].start_ms`	No	integer	Optional lower bound (inclusive, in the requested media's coordinate space) restricting the match to a time window. Must be sent with end_ms.
`edits[].end_ms`	No	integer	Optional upper bound (inclusive) restricting the match to a time window. Must be sent with start_ms.

list_localizations

wistia-cli list-localizations

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media to list localizations for. minLength: `1`.
`include_transcript`	No; body/guard rules still apply	boolean	Whether to include the transcript in the response. default: `False`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

create_localization

wistia-cli create-localization

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media to create a localization for. minLength: `1`.
`output_language`	No; body/guard rules still apply	string	The language to localize the media to as a 3-character IETF language code.
`auto_enable`	No; body/guard rules still apply	boolean	Whether to automatically enable the localization. default: `True`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `output_language`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: output_language.

get_localization

wistia-cli get-localization

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the localization's media. minLength: `1`.
`localization_hashed_id`	Yes	string	The hashed ID of the localization. minLength: `1`.
`include_transcript`	No; body/guard rules still apply	boolean	Whether to include the transcript in the response. default: `False`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

delete_localization

wistia-cli delete-localization

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the localization's media. minLength: `1`.
`localization_hashed_id`	Yes	string	The hashed ID of the localization to delete. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

create_media_from_trims

wistia-cli create-media-from-trims

Argument	Required	Type	Details
`media_hashed_id`	Yes	string	The hashed ID of the media. minLength: `1`.
`trims`	No; body/guard rules still apply	array	An array of strings matching the format of HH:MM:SS.mmm-HH:MM:SS.mmm where HH is hours, MM is minutes, SS is seconds and mmm is milliseconds. When keep_trims is false (default), the ranges specify parts of the media to remove. When keep_trims is true, the ranges specify parts of the media to keep. Array items: string.
`keep_trims`	No; body/guard rules still apply	boolean	When set to true, the trims parameter is treated as ranges to keep rather than ranges to remove. Defaults to false. default: `False`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `trims`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: trims.

list_media_extended_audio_descriptions

wistia-cli list-media-extended-audio-descriptions

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`hashed_ids`	No; body/guard rules still apply	array	Filter extended audio descriptions to only those matching these hashed ids. Array items: string.
`sort_by`	No; body/guard rules still apply	string	Field to order by. The default is id. Values: `language`, `created`, `updated`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Direction to order by. (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

get_media_extended_audio_description

wistia-cli get-media-extended-audio-description

Argument	Required	Type	Details
`id`	Yes	string	The hashed id of the Media Extended Audio Description minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

delete_media_extended_audio_description

wistia-cli delete-media-extended-audio-description

Argument	Required	Type	Details
`id`	Yes	string	The hashed id of the Media Extended Audio Description minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

order_extended_audio_description

wistia-cli order-extended-audio-description

Argument	Required	Type	Details
`media_id`	No; body/guard rules still apply	string	The hashed id of the media to order the extended audio description for.
`enabled`	No; body/guard rules still apply	boolean	Whether the extended audio description should be automatically enabled once the order is complete. default: `True`.
`ai_enabled`	No; body/guard rules still apply	boolean	Whether to use AI-generated audio descriptions (cheaper) or human-generated (higher quality). AI is only available for English orders. default: `True`.
`order_instructions`	No; body/guard rules still apply	string	Optional instructions for the audio description provider.
`ietf_language_tag`	No; body/guard rules still apply	string	IETF language tag for the audio description. Defaults to `eng` (English). Non-English orders must set `ai_enabled: false` : AI-generated audio descriptions are only available in English. Spanish (`es-419`) orders are only accepted when the source media is tagged as a Spanish-language variant or has no detected language (e.g. silent videos). Spanish orders against a media in another language return `400`. default: `eng`. Values: `eng`, `es-419`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `media_id`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: media_id.

get_order_status

wistia-cli get-order-status

Argument	Required	Type	Details
`id`	Yes	string	The hashed ID of the order returned from the order endpoint. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

list_brands

wistia-cli list-brands

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id`, `updated` and `created` are supported. All other sort_by options require offset pagination. Values: `name`, `created`, `updated`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc) Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_brand

wistia-cli create-brand

Argument	Required	Type	Details
`name`	No; body/guard rules still apply	string	The brand's display name. Renaming the account-level default brand is ignored; its name is managed by Wistia.
`primary_color`	No; body/guard rules still apply	JSON union	The primary brand color, used for primary buttons and the player playbar. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. Exactly one of 3 schema branches; inspect the complete schema.
`page_background_color`	No; body/guard rules still apply	JSON union	The brand color used for page backgrounds. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. Exactly one of 3 schema branches; inspect the complete schema.
`body_font_family`	No; body/guard rules still apply	string/null	The brand font family for body text.
`headline_font_family`	No; body/guard rules still apply	string/null	The brand font family for headlines.
`button_font_family`	No; body/guard rules still apply	string/null	The brand font family for buttons.
`border_radius`	No; body/guard rules still apply	integer/null	The border radius in pixels for rounded corners.
`contrast_icons`	No; body/guard rules still apply	string/null	Controls whether the player icon color is always white or uses an accessible contrast color when necessary. Values: `enabled`, `disabled`, `unset`, `None`.
`opaque_controls`	No; body/guard rules still apply	string/null	Controls the opacity of the video player control bar and big play button. Values: `enabled`, `disabled`, `unset`, `None`.
`page_logo`	No; body/guard rules still apply	object/null	The brand logo used for pages. `url` must be a Wistia delivery URL : see the note on uploading below. On accounts without custom branding the player logo is ignored, but the page logo is always applied.
`player_logo`	No; body/guard rules still apply	object/null	The brand logo used for the player. `url` must be a Wistia delivery URL : see the note on uploading below. Ignored on accounts whose plan doesn't include custom branding.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`page_logo.url`	No	string	The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one.
`page_logo.dimensions`	No	object/null	Current schema
`page_logo.dimensions.width`	No	integer	Current schema
`page_logo.dimensions.height`	No	integer	Current schema
`page_logo.size`	No	number/null	The size multiplier of the logo.
`player_logo.url`	No	string	The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one.
`player_logo.dimensions`	No	object/null	Current schema
`player_logo.dimensions.width`	No	integer	Current schema
`player_logo.dimensions.height`	No	integer	Current schema
`player_logo.size`	No	number/null	The size multiplier of the logo.

get_brand

wistia-cli get-brand

Argument	Required	Type	Details
`brand_id`	Yes	string	The id of the brand. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_brand

wistia-cli update-brand

Argument	Required	Type	Details
`brand_id`	Yes	string	The id of the brand minLength: `1`.
`name`	No; body/guard rules still apply	string	The brand's display name. Renaming the account-level default brand is ignored; its name is managed by Wistia.
`primary_color`	No; body/guard rules still apply	JSON union	The primary brand color, used for primary buttons and the player playbar. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. Exactly one of 3 schema branches; inspect the complete schema.
`page_background_color`	No; body/guard rules still apply	JSON union	The brand color used for page backgrounds. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. Exactly one of 3 schema branches; inspect the complete schema.
`body_font_family`	No; body/guard rules still apply	string/null	The brand font family for body text.
`headline_font_family`	No; body/guard rules still apply	string/null	The brand font family for headlines.
`button_font_family`	No; body/guard rules still apply	string/null	The brand font family for buttons.
`border_radius`	No; body/guard rules still apply	integer/null	The border radius in pixels for rounded corners.
`contrast_icons`	No; body/guard rules still apply	string/null	Controls whether the player icon color is always white or uses an accessible contrast color when necessary. Values: `enabled`, `disabled`, `unset`, `None`.
`opaque_controls`	No; body/guard rules still apply	string/null	Controls the opacity of the video player control bar and big play button. Values: `enabled`, `disabled`, `unset`, `None`.
`page_logo`	No; body/guard rules still apply	object/null	The brand logo used for pages. `url` must be a Wistia delivery URL : see the note on uploading below. On accounts without custom branding the player logo is ignored, but the page logo is always applied.
`player_logo`	No; body/guard rules still apply	object/null	The brand logo used for the player. `url` must be a Wistia delivery URL : see the note on uploading below. Ignored on accounts whose plan doesn't include custom branding.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`page_logo.url`	No	string	The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one.
`page_logo.dimensions`	No	object/null	Current schema
`page_logo.dimensions.width`	No	integer	Current schema
`page_logo.dimensions.height`	No	integer	Current schema
`page_logo.size`	No	number/null	The size multiplier of the logo.
`player_logo.url`	No	string	The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one.
`player_logo.dimensions`	No	object/null	Current schema
`player_logo.dimensions.width`	No	integer	Current schema
`player_logo.dimensions.height`	No	integer	Current schema
`player_logo.size`	No	number/null	The size multiplier of the logo.

delete_brand

wistia-cli delete-brand

Argument	Required	Type	Details
`brand_id`	Yes	string	The id of the brand minLength: `1`.
`sync_to_customizations`	No; body/guard rules still apply	boolean	When true, the brand's values are baked into the customizations of everything it was applied to before it is deleted, so those items keep their current appearance. Defaults to false.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

apply_brand

wistia-cli apply-brand

Argument	Required	Type	Details
`brand_id`	Yes	string	The id of the brand to apply minLength: `1`.
`resource_type`	No; body/guard rules still apply	string	The kind of resource being branded. Webinars can't be branded through this endpoint yet. Values: `media`, `folder`, `channel`.
`resource_id`	No; body/guard rules still apply	string	The id of the resource being branded.
`clear_overrides`	No; body/guard rules still apply	boolean	When true (the default), appearance settings the resource had set directly are cleared for the fields the brand controls, so the brand is what shows. Set to false to leave them in place, in which case they continue to win over the brand. default: `True`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `resource_type`, `resource_id`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: resource_type, resource_id.

list_speakers

wistia-cli list-speakers

Argument	Required	Type	Details
`name`	No; body/guard rules still apply	string	Restrict the results to speaker profiles whose name contains this value (case-insensitive).
`sort_by`	No; body/guard rules still apply	string	Field to order by. The default is id. Values: `id`, `name`, `created`, `updated`.
`sort_direction`	No; body/guard rules still apply	integer	Direction to order by. (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

wistia-cli list-tags

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id`, `updated` and `created` are supported. All other sort_by options require offset pagination. Values: `name`, `created`, `updated`, `taggingsCount`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc) Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_tags

wistia-cli create-tags

Argument	Required	Type	Details
`name`	No; body/guard rules still apply	string	The tag name. Stored lowercased with whitespace squished, 50 characters max, and must not already exist on the account.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `name`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: name.

delete_tag

wistia-cli delete-tag

Argument	Required	Type	Details
`name`	Yes	string	Name of the tag to delete minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

create_bulk_actions

wistia-cli create-bulk-actions

Argument	Required	Type	Details
`actions`	No; body/guard rules still apply	array	An array of actions to process, one per record. Maximum 1000 actions per request, and the request body must stay under 2 MB -- whichever limit is reached first. An oversized body is rejected with a `413` and no action in it runs. Each action specifies an operation (create, update, delete, or move), a resource type, and the relevant payload or record ID. Use `job` instead when every record takes the same payload. minItems: `1`. maxItems: `1000`. Array items: object.
`job`	No; body/guard rules still apply	object	One change applied to many records, named by a parent (`scope`) or listed explicitly (`ids`). The server resolves the target and runs one action per record, so a folder of 400 media takes one job rather than 400 actions. A `scope` resolves to exactly what the matching list endpoint returns for that parent, including its defaults -- so a `folder` scope on `media` reaches media in that folder's subfolders, and includes archived media. A job resolves to at most 5000 records. Beyond that it is rejected rather than truncated, so a job never silently acts on part of the set you named -- narrow the scope, or send the records as an actions array. Cannot be used with `create`, which has no record to address, and is not available to external contacts. Object requires: `operation`, `resource_type`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`actions[].operation`	Yes inside object	string	The operation to perform. Media creation is not supported here -- uploads and URL imports have their own endpoints. `delete` also soft-deletes media inside a `folder` or `subfolder`. An account owner or manager can restore it from the trash until it purges. `move` applies to `media` only, one action per media. Each action carries its own destination, so a single request can move media into many different folders. Values: `create`, `update`, `delete`, `move`.
`actions[].resource_type`	Yes inside object	string	The type of resource to operate on. `folder` means a top-level folder (previously called a project); use `subfolder` for a folder nested inside one. `captions` operates on a single caption track -- one media in one language. The `customization_*` types each write one concern of a media's player customizations and accept `update` only. Their `id` is the media's hashed ID, and their payload matches the corresponding Update Customizations endpoint (for example, `customization_appearance` takes the same fields as Update Appearance Customizations). Sending a field another concern owns fails that action rather than writing it, so a batch can never quietly overwrite unrelated player settings. Values: `media`, `folder`, `subfolder`, `channel`, `channel_episode`, `captions`, `customization_access`, `customization_accessibility`, `customization_appearance`, `customization_chapters`, `customization_engagement`, `customization_lead_capture`, `customization_playback`, `customization_related_media`, `customization_sharing`, `customization_thumbnail`.
`actions[].id`	No	string	The hashed ID of the resource. Required for update, delete, and move operations. For `captions` this is the caption track's own ID (the `id` field returned by List Captions), not the media's -- a media can have a track per language.
`actions[].payload`	No	object	The data for the operation. Required for create, update, and move operations. The accepted fields depend on the resource type and match the corresponding create or update endpoint's request body (for example, a channel_episode create takes the same fields as the Create Channel Episode endpoint, including channel_id). Creating a subfolder requires `folder_id` (the parent folder's hashed ID) and `name`. Creating captions requires `media_id` and `caption_file` (the SRT contents as a string; the multipart file upload the Create Captions endpoint accepts is not available here) and takes an optional `language`, detected from the file when omitted. Updating captions takes `caption_file`; the track's language is fixed by the record. Creating captions for a language that already has a track replaces it, matching the Create Captions endpoint. Moving a media requires `folder_id` (the destination folder's hashed ID) and accepts an optional `subfolder_id`, which must belong to that folder. Omit `subfolder_id` to move the media to the folder's root level. A `customization_*` payload is a partial update of that concern only: just the fields you send are changed, and a field naming another concern's setting fails the action. A `media` update payload can also carry a `custom_metadata` object mapping field keys to the values to set, in the same shapes the Set Custom Metadata Field Value endpoint accepts for each field's type. A `null` value clears that field; fields the object omits are left untouched. Requires the custom metadata feature on the account, and each write is recorded with its actor and source.
`job.operation`	Yes inside object	string	The operation to apply to every matching record. `create` is not accepted here. Values: `update`, `delete`, `move`.
`job.resource_type`	Yes inside object	string	The type of record to operate on, using the same vocabulary as a single action. Which parents are valid depends on it -- see `scope`. Values: `media`, `folder`, `subfolder`, `channel`, `channel_episode`, `captions`, `customization_access`, `customization_accessibility`, `customization_appearance`, `customization_chapters`, `customization_engagement`, `customization_lead_capture`, `customization_playback`, `customization_related_media`, `customization_sharing`, `customization_thumbnail`.
`job.scope`	No	object	The parent whose records the job applies to. Which parent types are valid depends on the job's `resource_type` and `operation`: - `media` and the `customization_*` types: `account`, `folder`, `subfolder`, `channel`. - `captions` with `update` or `delete`, which address a caption track: `account`, `media`, `folder`, `channel`. - `channel_episode`: `account`, `channel`, `media`. - `subfolder`: `account`, `folder`. - `folder` and `channel`: `account`. An invalid combination is rejected with the valid parents listed. Object requires: `type`.
`job.scope.type`	Yes inside object	string	The kind of parent `id` names. Required, because a hashed ID does not say what it belongs to -- the same value could name a folder or a channel. Use `account` to mean every record the job could reach, with no `id`. Values: `account`, `folder`, `subfolder`, `channel`, `media`.
`job.scope.id`	No	string	The parent's hashed ID. Required for every scope type except `account`.
`job.ids`	No	array	The records to apply the change to, named explicitly. Use this instead of `scope` when the records do not share a parent -- it is still far cheaper than one action each, since only the ids repeat and the payload is stated once. Give either `scope` or `ids`, never both. minItems: `1`. maxItems: `1000`. Array items: string.
`job.payload`	No	object	The data applied to every matching record, in the same shape a single action's payload takes for this resource type. Required for `update` and `move`.

create_bulk_purchase

wistia-cli create-bulk-purchase

Argument	Required	Type	Details
`actions`	No; body/guard rules still apply	array	The orders to place, one per media. Maximum 1000 per request, and the request body must stay under 2 MB -- whichever limit is reached first. An oversized body is rejected with a `413` and no order in it is placed. Every order is priced and placed independently: one failing (an ineligible media, an account without a saved card, a language that already has a localization) does not stop the rest of the batch. Use `job` instead to order for a whole folder, channel, or account. minItems: `1`. maxItems: `1000`. Array items: object.
`job`	No; body/guard rules still apply	object	One order placed for many media, named by a parent (`scope`) or listed explicitly (`ids`), so ordering captions for a folder of 47 videos takes one job rather than 47 orders. A `scope` resolves to exactly what List Media returns for that parent, including media in the folder's subfolders and archived media, and to at most 5000 media -- beyond that the job is rejected rather than truncated. The job attempts one order for every media it resolves to. Ineligible media fail individually without placing an order; successful orders are metered and may incur charges according to the account's plan. Confirm the scope and potential cost with the customer before submitting. Not available to external contacts. Object requires: `operation`, `resource_type`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`actions[].operation`	Yes inside object	string	Always `purchase`. This endpoint places orders only; to create, update, or delete records in bulk use the Create Bulk Actions endpoint, which does not accept `purchase`. Values: `purchase`.
`actions[].resource_type`	Yes inside object	string	What to order for the media. `captions` orders Wistia-generated English captions -- computer-generated or human-reviewed. `localization` orders a dubbed, language-specific version of the media. `extended_audio_description` orders an extended audio description track. `text_translation` translates the media's existing transcript into another language, leaving the audio alone. Values: `captions`, `localization`, `extended_audio_description`, `text_translation`.
`actions[].id`	Yes inside object	string	The hashed ID of the media to order for. Always the media's own ID: what the order produces does not exist yet.
`actions[].payload`	No	object	Order options. The accepted fields depend on the resource type and match the corresponding single-media endpoint's request body. Omit it to take every default. `captions` accepts `automated` (order computer-generated captions instead of human-reviewed ones), `rush` (one business day turnaround instead of four, human-reviewed only, at a higher per-minute rate), and `automatically_enable` (show the captions on the video as soon as they are ready). Each is treated as `false` when omitted or unrecognized. What each option costs depends on the account's plan and billing settings. `localization` requires `output_language`, a 3-character IETF language code, and accepts `auto_enable` (default `true`). `extended_audio_description` accepts `enabled` (default `true`), `ai_enabled` (default `true`), `ietf_language_tag` (default `eng`), and `order_instructions`. `text_translation` requires `target_language` and accepts `source_language` (which transcript to translate from, defaulting to the media's own language). Use the bibliographic ISO 639-2 form or a supported regional or script IETF tag for either value.
`job.operation`	Yes inside object	string	Always `purchase`. Values: `purchase`.
`job.resource_type`	Yes inside object	string	What to order for the media. `captions` orders Wistia-generated English captions -- computer-generated or human-reviewed. `localization` orders a dubbed, language-specific version of the media. `extended_audio_description` orders an extended audio description track. `text_translation` translates the media's existing transcript into another language, leaving the audio alone. Values: `captions`, `localization`, `extended_audio_description`, `text_translation`.
`job.scope`	No	object	The parent whose media the order applies to. An order always addresses the media, so the valid parent types are the same for every resource type here. Object requires: `type`.
`job.scope.type`	Yes inside object	string	The kind of parent `id` names. Required, because a hashed ID does not say what it belongs to -- the same value could name a folder or a channel. Use `account` to order for every media in the account. Values: `account`, `folder`, `subfolder`, `channel`.
`job.scope.id`	No	string	The parent's hashed ID. Required for every scope type except `account`.
`job.ids`	No	array	The media to order for, named explicitly. Use this instead of `scope` when the media do not share a parent. Give either `scope` or `ids`, never both. minItems: `1`. maxItems: `1000`. Array items: string.
`job.payload`	No	object	Order options applied to every matching media, in the same shape a single order's payload takes for this resource type.

bulk_tag

wistia-cli bulk-tag

Argument	Required	Type	Details
`hashed_ids`	No; body/guard rules still apply	array	An array of the media hashed IDs to be tagged. Array items: string.
`tag_names`	No; body/guard rules still apply	array	An array of tag names to add to each media. Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `hashed_ids`, `tag_names`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: hashed_ids, tag_names.

list_folders

wistia-cli list-folders

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id`, `updated` and `created` are supported. All other sort_by options require offset pagination. Values: `name`, `created`, `updated`, `mediaCount`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`hashed_ids`	No; body/guard rules still apply	array	A collection of hashed ids belonging to folders to fetch Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_folder

wistia-cli create-folder

Argument	Required	Type	Details
`name`	No; body/guard rules still apply	string	The name of the folder you want to create.
`adminEmail`	No; body/guard rules still apply	string	The email address of the person you want to set as the owner of this folder. Defaults to the Wistia Account Owner.
`description`	No; body/guard rules still apply	string	The folder’s description.
`anonymousCanUpload`	No; body/guard rules still apply	boolean	Whether anonymous users can upload media to the folder.
`anonymousCanDownload`	No; body/guard rules still apply	boolean	Whether anonymous users can download media from the folder.
`public`	No; body/guard rules still apply	boolean	A flag indicating whether or not the folder is enabled for public access.
`personalLibrary`	No; body/guard rules still apply	boolean	When true, creates the folder inside the requesting user's personal "My Library" (owned by them) instead of a shared account folder.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

get_folder

wistia-cli get-folder

Argument	Required	Type	Details
`id`	Yes	string	Folder Hashed ID minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_folder

wistia-cli update-folder

Argument	Required	Type	Details
`id`	Yes	string	Folder Hashed ID minLength: `1`.
`name`	No; body/guard rules still apply	string	The folder’s new name.
`description`	No; body/guard rules still apply	string	The folder’s new description.
`anonymousCanUpload`	No; body/guard rules still apply	boolean	Whether anonymous users can upload media to the folder.
`anonymousCanDownload`	No; body/guard rules still apply	boolean	Whether anonymous users can download media from the folder.
`public`	No; body/guard rules still apply	boolean	A flag indicating whether or not the folder is enabled for public access.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

delete_folder

wistia-cli delete-folder

Argument	Required	Type	Details
`id`	Yes	string	Folder Hashed ID minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

copy_folder

wistia-cli copy-folder

Argument	Required	Type	Details
`id`	Yes	string	Folder Hashed ID minLength: `1`.
`adminEmail`	No; body/guard rules still apply	string	The email address of the account Manager that will be the owner of the new folder. Defaults to the Account Owner if invalid or omitted.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

list_folder_sharings

wistia-cli list-folder-sharings

Argument	Required	Type	Details
`folder_id`	Yes	string	Folder Hashed ID minLength: `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id` is supported. default: `id`. Values: `created`, `updated`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) default: `1`. Values: `0`, `1`.
`hashed_ids`	No; body/guard rules still apply	array	Filter sharings by their hashed IDs Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

wistia-cli create-folder-sharing

Argument	Required	Type	Details
`folder_id`	Yes	string	Hashed ID of the folder to be shared minLength: `1`.
`sharing`	No; body/guard rules still apply	object	Object requires: `with`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `sharing`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: sharing.

Nested body fields:

Field	Required	Type	Details
`sharing.with`	Yes inside object	string	The email address of the person with whom you want to share the folder. format: `email`.
`sharing.requirePassword`	No	boolean	A flag indicating whether or not a password is required. Defaults to true.
`sharing.canShare`	No	boolean	Whether the user is allowed to share the folder with others. Defaults to false.
`sharing.canDownload`	No	boolean	Whether the user is allowed to download files from the folder. Defaults to false.
`sharing.canUpload`	No	boolean	Whether the user is allowed to upload files to the folder. Defaults to false.
`sharing.sendEmailNotification`	No	string	Deprecated! Email notifications are always sent now. Values: `0`, `1`.

wistia-cli get-folder-sharing

Argument	Required	Type	Details
`folder_id`	Yes	string	Hashed ID for the folder for which you'd like to see sharings. minLength: `1`.
`sharing_id`	Yes	integer	The ID of the specific sharing object that you want to see.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

wistia-cli update-folder-sharing

Argument	Required	Type	Details
`folder_id`	Yes	string	ID of the folder minLength: `1`.
`sharing_id`	Yes	string	ID of the sharing to be updated minLength: `1`.
`sharing`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`sharing.canShare`	No	boolean	Allow the user or group to share the folder with others.
`sharing.canDownload`	No	boolean	Allow the user or group to download media from the folder.
`sharing.canUpload`	No	boolean	Allow the user or group to upload media to the folder.
`sharing.isAdmin`	No	boolean	Give this user admin rights to the folder.

wistia-cli delete-folder-sharing

Argument	Required	Type	Details
`folder_id`	Yes	string	Hashed ID of the folder minLength: `1`.
`sharing_id`	Yes	string	ID of the sharing to be deleted minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

list_subfolders

wistia-cli list-subfolders

Argument	Required	Type	Details
`folder_id`	Yes	string	The hashed ID of the folder minLength: `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Field to sort by. When using cursor pagination (see cursor param), only `id` is supported. default: `position`. Values: `name`, `created`, `updated`, `position`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Sort direction (0 = desc, 1 = asc; default is 1) default: `1`. Values: `0`, `1`.
`hashed_ids`	No; body/guard rules still apply	array	Filter subfolders by their hashed IDs Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_subfolder

wistia-cli create-subfolder

Argument	Required	Type	Details
`folder_id`	Yes	string	The hashed ID of the folder minLength: `1`.
`name`	No; body/guard rules still apply	string	The display name of the subfolder. maxLength: `255`.
`description`	No; body/guard rules still apply	string/null	A description for the subfolder. maxLength: `1000`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `name`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: name.

get_subfolder

wistia-cli get-subfolder

Argument	Required	Type	Details
`folder_id`	Yes	string	The hashed ID of the folder minLength: `1`.
`subfolder_id`	Yes	string	The hashed ID of the subfolder minLength: `1`.
`description_format`	No; body/guard rules still apply	string	Format for media descriptions
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_subfolder

wistia-cli update-subfolder

Argument	Required	Type	Details
`folder_id`	Yes	string	The hashed ID of the folder minLength: `1`.
`subfolder_id`	Yes	string	The hashed ID of the subfolder minLength: `1`.
`name`	No; body/guard rules still apply	string	The new name for the subfolder maxLength: `255`.
`description`	No; body/guard rules still apply	string/null	The new description for the subfolder maxLength: `1000`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

delete_subfolder

wistia-cli delete-subfolder

Argument	Required	Type	Details
`folder_id`	Yes	string	The hashed ID of the folder minLength: `1`.
`subfolder_id`	Yes	string	The hashed ID of the subfolder minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

bulk_delete_subfolders

wistia-cli bulk-delete-subfolders

Argument	Required	Type	Details
`folder_id`	Yes	string	The hashed ID of the folder containing the subfolders minLength: `1`.
`hashed_ids`	No; body/guard rules still apply	array	An array of the subfolder hashed IDs to be deleted. Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `hashed_ids`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: hashed_ids.

list_channels

wistia-cli list-channels

Argument	Required	Type	Details
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`page`	No; body/guard rules still apply	integer	Page number to retrieve minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	Number of channels per page minimum: `1`. maximum: `100`.
`sort_by`	No; body/guard rules still apply	string	Ordering. Default is ID ASC. Note: Only 'id' and 'created' are supported when using cursor pagination. Values: `created`, `id`, `updated`, `name`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`hashed_ids`	No; body/guard rules still apply	array	Find all of the channels limited to these hashed_ids. Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_channel

wistia-cli create-channel

Argument	Required	Type	Details
`name`	No; body/guard rules still apply	string/null	The display name for the channel
`description`	No; body/guard rules still apply	string/null	The channel's description.
`auto_publish_enabled`	No; body/guard rules still apply	boolean	Whether the episodes are automatically published when added to the channel. Cannot be enabled if podcasting is on.
`podcast_enabled`	No; body/guard rules still apply	boolean	Whether podcasting is enabled for this channel.
`custom_url`	No; body/guard rules still apply	string/null	Use if embedding the channel on your own site. The custom URL ensures links always direct to your page and not Wistia's.
`podcast_settings`	No; body/guard rules still apply	object	Podcast specific settings for a channel. These settings only take effect if podcasting is enabled for the channel. These values appear in the channel's publicly accessible podcast RSS feed.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`podcast_settings.copyright`	No	string/null	The channel's copyright information, published in the RSS feed as ``.
`podcast_settings.episode_format`	No	JSON union	The format for episodes for the podcast channel, published in the RSS feed as ``. `episodic_with_seasons` is published as `episodic`. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.author_name`	No	string/null	The name of the author(s) for the channel, published in the RSS feed as ``.
`podcast_settings.explicit`	No	boolean/null	Whether the channel contains explicit content, published in the RSS feed as ``.
`podcast_settings.owner_name`	No	string/null	The podcast owner's name, published in the channel's public RSS feed as ``. Podcast directories use this as the show's administrative contact.
`podcast_settings.owner_email`	No	string/null	The podcast owner's email address, published in the channel's public RSS feed as ``. Podcast directories such as Apple Podcasts require it for ownership verification.
`podcast_settings.category1`	No	JSON union	The primary category for the channel, published in the RSS feed as ``. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.category2`	No	JSON union	The secondary category for the channel, published in the RSS feed as ``. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.category3`	No	JSON union	The third category for the channel, published in the RSS feed as ``. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.language`	No	string/null	The ISO 639-1 language code for the channel, published in the RSS feed as ``. Values: `af`, `be`, `bg`, `ca`, `cs`, `da`, `de-at`, `de-ch`, `de-de`, `de-li`, `de-lu`, `de`, `el`, `en-au`, `en-bz`, `en-ca`, `en-gb`, `en-ie`, `en-jm`, `en-nz`, `en-ph`, `en-tt`, `en-us`, `en-za`, `en-zw`, `en`, `es-ar`, `es-bo`, `es-cl`, `es-co`, `es-cr`, `es-do`, `es-ec`, `es-es`, `es-gt`, `es-hn`, `es-mx`, `es-ni`, `es-pa`, `es-pe`, `es-pr`, `es-py`, `es-sv`, `es-uy`, `es-ve`, `es`, `et`, `eu`, `fi`, `fo`, `fr-be`, `fr-ca`, `fr-ch`, `fr-fr`, `fr-lu`, `fr-mc`, `fr`, `ga`, `gd`, `gl`, `haw`, `hr`, `hu`, `in`, `is`, `it-ch`, `it-it`, `it`, `ja`, `ko`, `mk`, `nl-be`, `nl-nl`, `nl`, `no`, `pl`, `pt-br`, `pt-pt`, `pt`, `ro-mo`, `ro-ro`, `ro`, `ru-mo`, `ru-ru`, `ru`, `sk`, `sl`, `sq`, `sr`, `sv-fi`, `sv-se`, `sv`, `tr`, `uk`, `zh-cn`, `zh-tw`.

get_channel

wistia-cli get-channel

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	The hashed ID of the channel. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_channel

wistia-cli update-channel

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	The hashed id of the Channel minLength: `1`.
`name`	No; body/guard rules still apply	string/null	The display name for the channel
`description`	No; body/guard rules still apply	string/null	The channel's description.
`auto_publish_enabled`	No; body/guard rules still apply	boolean	Whether the episodes are automatically published when added to the channel. Cannot be enabled if podcasting is on.
`podcast_enabled`	No; body/guard rules still apply	boolean	Whether podcasting is enabled for this channel.
`custom_url`	No; body/guard rules still apply	string/null	Use if embedding the channel on your own site. The custom URL ensures links always direct to your page and not Wistia's.
`podcast_settings`	No; body/guard rules still apply	object	Podcast specific settings for a channel. These settings only take effect if podcasting is enabled for the channel. These values appear in the channel's publicly accessible podcast RSS feed.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`podcast_settings.copyright`	No	string/null	The channel's copyright information, published in the RSS feed as ``.
`podcast_settings.episode_format`	No	JSON union	The format for episodes for the podcast channel, published in the RSS feed as ``. `episodic_with_seasons` is published as `episodic`. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.author_name`	No	string/null	The name of the author(s) for the channel, published in the RSS feed as ``.
`podcast_settings.explicit`	No	boolean/null	Whether the channel contains explicit content, published in the RSS feed as ``.
`podcast_settings.owner_name`	No	string/null	The podcast owner's name, published in the channel's public RSS feed as ``. Podcast directories use this as the show's administrative contact.
`podcast_settings.owner_email`	No	string/null	The podcast owner's email address, published in the channel's public RSS feed as ``. Podcast directories such as Apple Podcasts require it for ownership verification.
`podcast_settings.category1`	No	JSON union	The primary category for the channel, published in the RSS feed as ``. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.category2`	No	JSON union	The secondary category for the channel, published in the RSS feed as ``. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.category3`	No	JSON union	The third category for the channel, published in the RSS feed as ``. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.language`	No	string/null	The ISO 639-1 language code for the channel, published in the RSS feed as ``. Values: `af`, `be`, `bg`, `ca`, `cs`, `da`, `de-at`, `de-ch`, `de-de`, `de-li`, `de-lu`, `de`, `el`, `en-au`, `en-bz`, `en-ca`, `en-gb`, `en-ie`, `en-jm`, `en-nz`, `en-ph`, `en-tt`, `en-us`, `en-za`, `en-zw`, `en`, `es-ar`, `es-bo`, `es-cl`, `es-co`, `es-cr`, `es-do`, `es-ec`, `es-es`, `es-gt`, `es-hn`, `es-mx`, `es-ni`, `es-pa`, `es-pe`, `es-pr`, `es-py`, `es-sv`, `es-uy`, `es-ve`, `es`, `et`, `eu`, `fi`, `fo`, `fr-be`, `fr-ca`, `fr-ch`, `fr-fr`, `fr-lu`, `fr-mc`, `fr`, `ga`, `gd`, `gl`, `haw`, `hr`, `hu`, `in`, `is`, `it-ch`, `it-it`, `it`, `ja`, `ko`, `mk`, `nl-be`, `nl-nl`, `nl`, `no`, `pl`, `pt-br`, `pt-pt`, `pt`, `ro-mo`, `ro-ro`, `ro`, `ru-mo`, `ru-ru`, `ru`, `sk`, `sl`, `sq`, `sr`, `sv-fi`, `sv-se`, `sv`, `tr`, `uk`, `zh-cn`, `zh-tw`.

delete_channel

wistia-cli delete-channel

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	The hashed id of the Channel minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

get_channel_episode

wistia-cli get-channel-episode

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	The hashed ID of the channel. minLength: `1`.
`channel_episode_id`	Yes	string	The hashed ID of the channel episode. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

list_channel_episodes_by_channel

wistia-cli list-channel-episodes-by-channel

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	The hashed ID of the channel to grab channel episodes from. minLength: `1`.
`sort_by`	No; body/guard rules still apply	string	Ordering. Default is ID ASC. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`position`, `title`, `updated`, `published_at`) require offset pagination. Values: `position`, `title`, `created`, `updated`, `published_at`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`media_id`	No; body/guard rules still apply	array	Filter by media id. Accepts either the numeric id or the hashed id of a media. Array items: string.
`hashed_ids`	No; body/guard rules still apply	array	Filter by hashed id Array items: string.
`published`	No; body/guard rules still apply	boolean	Filter by published status.
`title`	No; body/guard rules still apply	string	Filter by channel episode name/title.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_channel_episode

wistia-cli create-channel-episode

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	The hashed ID of the channel to add the episode to. minLength: `1`.
`media_id`	No; body/guard rules still apply	string	The alphanumeric hashed ID of the media to be added as a channel episode.
`title`	No; body/guard rules still apply	string	The episode's title. If not provided, the channel episode uses the title of the media used to create it.
`description`	No; body/guard rules still apply	string	The episode's description or episode notes.
`summary`	No; body/guard rules still apply	string	A short summary of the episode that is displayed when space is limited.
`publish_status`	No; body/guard rules still apply	string	The status of whether or not the episode has been published to your channel. Values: `draft`, `published`, `scheduled`.
`publish_at`	No; body/guard rules still apply	string	The date and time when the episode should be published in UTC timezone. Required when publish_status is 'scheduled'. Must be a valid ISO8601 timestamp in UTC (ending with 'Z'). Can only be provided when publish_status is 'scheduled.' format: `date-time`.
`podcast_settings`	No; body/guard rules still apply	object	Podcast specific settings for a channel episode. These settings only take effect if podcasting is enabled for the channel.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`podcast_settings.episode_type`	No	JSON union	The type of episode. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.episode_number`	No	integer/null	The number of the episode.
`podcast_settings.season_number`	No	integer/null	The season number of the episode.
`podcast_settings.explicit_content`	No	boolean	Whether the episode contains explicit content.
`podcast_settings.hide_from_feed`	No	boolean	Whether to hide the episode from the podcast feed.

list_channel_episodes

wistia-cli list-channel-episodes

Argument	Required	Type	Details
`channel_id`	No; body/guard rules still apply	string	The hashed ID of the channel to grab channel episodes from.
`sort_by`	No; body/guard rules still apply	string	Ordering. Default is ID ASC. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`position`, `title`, `updated`, `published_at`) require offset pagination. Values: `position`, `title`, `created`, `updated`, `published_at`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`media_id`	No; body/guard rules still apply	array	Filter by media id. Accepts either the numeric id or the hashed id of a media. Array items: string.
`hashed_ids`	No; body/guard rules still apply	array	Filter by hashed id Array items: string.
`published`	No; body/guard rules still apply	boolean	Filter by published status.
`title`	No; body/guard rules still apply	string	Filter by channel episode name/title.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

update_channel_episode

wistia-cli update-channel-episode

Argument	Required	Type	Details
`channel_episode_hashed_id`	Yes	string	The hashed id of the Channel Episode minLength: `1`.
`description`	No; body/guard rules still apply	string/null	The episode's description or episode notes.
`title`	No; body/guard rules still apply	string/null	The episode's title. If not provided, the channel episode uses the title of the media used to create it.
`media_hashed_id`	No; body/guard rules still apply	string	The unique alphanumeric identifier for the media associated with this channel episode.
`live_stream_event_hashed_id`	No; body/guard rules still apply	string	The unique alphanumeric identifier for the live stream event associated with this channel episode.
`summary`	No; body/guard rules still apply	string/null	A short summary of the episode that is displayed when space is limited.
`publish_status`	No; body/guard rules still apply	string	The status of whether or not the episode has been published to your channel. Values: `draft`, `published`, `scheduled`.
`publish_at`	No; body/guard rules still apply	string	The date and time when the episode is scheduled to be published in UTC timezone. format: `date-time`.
`episode_notes`	No; body/guard rules still apply	string	Additional notes for the episode.
`podcast_settings`	No; body/guard rules still apply	object	Podcast specific settings for a channel episode. These settings only take effect if podcasting is enabled for the channel.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`podcast_settings.episode_type`	No	JSON union	The type of episode. Exactly one of 2 schema branches; inspect the complete schema.
`podcast_settings.episode_number`	No	integer/null	The number of the episode.
`podcast_settings.season_number`	No	integer/null	The season number of the episode.
`podcast_settings.explicit_content`	No	boolean	Whether the episode contains explicit content.
`podcast_settings.hide_from_feed`	No	boolean	Whether to hide the episode from the podcast feed.

delete_channel_episode

wistia-cli delete-channel-episode

Argument	Required	Type	Details
`channel_episode_hashed_id`	Yes	string	The hashed id of the Channel Episode minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

publish_channel_episode

wistia-cli publish-channel-episode

Argument	Required	Type	Details
`channel_episode_hashed_id`	Yes	string	The hashed id of the Channel Episode minLength: `1`.
`publish_at`	No; body/guard rules still apply	string	The date and time when the episode is scheduled to be published in UTC timezone. format: `date-time`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

un_publish_channel_episode

wistia-cli un-publish-channel-episode

Argument	Required	Type	Details
`channel_episode_hashed_id`	Yes	string	The hashed id of the Channel Episode minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

list_channel_collaborators

wistia-cli list-channel-collaborators

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	Channel Hashed ID minLength: `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id` is supported. default: `id`. Values: `created`, `updated`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) default: `1`. Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_channel_collaborator

wistia-cli create-channel-collaborator

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	Hashed ID of the channel minLength: `1`.
`email`	No; body/guard rules still apply	string	Email address of the contact to invite. Creates a new contact if one doesn't exist. format: `email`.
`role`	No; body/guard rules still apply	string	The role to grant the collaborator. Values: `admin`, `viewer`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `email`, `role`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: email, role.

delete_channel_collaborator

wistia-cli delete-channel-collaborator

Argument	Required	Type	Details
`channel_hashed_id`	Yes	string	Channel Hashed ID minLength: `1`.
`id`	Yes	integer	Collaborator ID
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

list_webinars

wistia-cli list-webinars

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Field to sort by. When using cursor pagination (see cursor param), only `id` and `scheduled_for` are supported. All other sort_by options (`title`, `created`, `updated`) require offset pagination. Values: `scheduled_for`, `title`, `created`, `updated`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Sort direction (0 = desc, 1 = asc; default is 1) Values: `0`, `1`.
`hashed_ids`	No; body/guard rules still apply	array	Filter by specific webinars IDs Array items: string.
`started`	No; body/guard rules still apply	string	Filter by whether the webinar has started. Use "true" for webinars that have started, "false" for webinars that have not started yet Values: `true`, `false`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_webinar

wistia-cli create-webinar

Argument	Required	Type	Details
`title`	No; body/guard rules still apply	string	The title of the webinar
`description`	No; body/guard rules still apply	string	The description of the webinar
`scheduled_for`	No; body/guard rules still apply	string	The scheduled start time as a UTC formatted ISO 8601 string (offset `Z` or `+00:00`). format: `date-time`.
`event_duration`	No; body/guard rules still apply	integer	Duration of the event in minutes (minimum 15) minimum: `15`.
`time_zone`	No; body/guard rules still apply	string	The IANA time zone identifier the webinar is scheduled in.
`folder_id`	No; body/guard rules still apply	string	Hashed ID of the folder to place this webinar in. Defaults to the account's default webinar folder if not provided.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `title`, `scheduled_for`, `event_duration`, `time_zone`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: title, scheduled_for, event_duration, time_zone.

get_webinar

wistia-cli get-webinar

Argument	Required	Type	Details
`id`	Yes	string	The hashed ID of the webinar minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_webinar

wistia-cli update-webinar

Argument	Required	Type	Details
`id`	Yes	string	The hashed ID of the webinar minLength: `1`.
`webinar`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`webinar.title`	No	string	The title of the webinar
`webinar.description`	No	string	The description of the webinar
`webinar.scheduled_for`	No	string	The scheduled start time as a UTC formatted ISO 8601 string (offset `Z` or `+00:00`). format: `date-time`.
`webinar.event_duration`	No	integer	Duration of the webinar in minutes (minimum 15) minimum: `15`.
`webinar.time_zone`	No	string	The IANA time zone identifier the webinar is scheduled in.
`webinar.folder_id`	No	string	Hashed ID of the folder to move this webinar to. Can only be changed before the webinar has started.

delete_webinar

wistia-cli delete-webinar

Argument	Required	Type	Details
`id`	Yes	string	The hashed ID of the webinar minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

list_webinar_registrations

wistia-cli list-webinar-registrations

Argument	Required	Type	Details
`webinar_id`	Yes	string	Hashed ID of the webinar. minLength: `1`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return per page (max 100). minimum: `1`. maximum: `100`. default: `100`.
`cursor`	No; body/guard rules still apply	string	Cursor for pagination. Use the value from the previous response's `page_info.end_cursor` or `page_info.start_cursor`.
`sort_direction`	No; body/guard rules still apply	integer	Sort direction (0 = desc/previous page, 1 = asc/next page; default is 1) default: `1`. Values: `0`, `1`.
`attendance`	No; body/guard rules still apply	string	Filter registrations by attendance status. default: `all`. Values: `all`, `attendees`, `non_attendees`.
`restriction`	No; body/guard rules still apply	string	Filter registrations by restriction status. default: `all`. Values: `all`, `restricted`, `allowed`.
`emails`	No; body/guard rules still apply	array	Filter registrations by email addresses. Array items: string.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

create_webinar_registration

wistia-cli create-webinar-registration

Argument	Required	Type	Details
`webinar_id`	Yes	string	Hashed ID of the webinar minLength: `1`.
`email`	No; body/guard rules still apply	string	Email address of the registrant format: `email`.
`first_name`	No; body/guard rules still apply	string	First name of the registrant
`last_name`	No; body/guard rules still apply	string	Last name of the registrant
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `email`, `first_name`, `last_name`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: email, first_name, last_name.

list_webinar_collaborators

wistia-cli list-webinar-collaborators

Argument	Required	Type	Details
`webinar_id`	Yes	string	Webinar Hashed ID minLength: `1`.
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id` is supported. default: `id`. Values: `created`, `updated`, `id`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) default: `1`. Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_webinar_collaborator

wistia-cli create-webinar-collaborator

Argument	Required	Type	Details
`webinar_id`	Yes	string	Hashed ID of the webinar minLength: `1`.
`email`	No; body/guard rules still apply	string	Email address of the contact to invite. Creates a new contact if one doesn't exist. Note that viewers cannot be webinar collaborators. format: `email`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `email`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: email.

delete_webinar_collaborator

wistia-cli delete-webinar-collaborator

Argument	Required	Type	Details
`webinar_id`	Yes	string	Webinar Hashed ID minLength: `1`.
`id`	Yes	integer	Collaborator ID
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

get_account

wistia-cli get-account

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_account_usage

wistia-cli get-account-usage

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_credit_balance

wistia-cli get-credit-balance

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_brand_preload

wistia-cli get-brand-preload

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

update_brand_preload

wistia-cli update-brand-preload

Argument	Required	Type	Details
`selected_player_color`	No; body/guard rules still apply	string	Hex color string (e.g. "#3366FF") for the account's default player color : 6 hex digits, with or without the leading `#`. Omit or send an empty string to leave the current color untouched (there is no clear operation : color always has a value). Malformed values are rejected at the API boundary; without this check, the model's sanitize step would return nil and silently reset the account color to the global default. pattern: `^(#?[0-9a-fA-F]{6})?$`.
`selected_logo_hashed_id`	No; body/guard rules still apply	string	Bakery hashed_id of an uploaded logo image, which will become the account's default page logo. Omit to leave the current logo untouched. Pass an empty string to clear the logo.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

get_brand_kit_colors

wistia-cli get-brand-kit-colors

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

invite_contacts

wistia-cli invite-contacts

Argument	Required	Type	Details
`contacts`	No; body/guard rules still apply	string	A comma-, whitespace-, or newline-separated list of email addresses to invite to the account. Each entry becomes a new contact if one does not already exist for that email.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `contacts`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: contacts.

dismiss_desktop_install_prompt

wistia-cli dismiss-desktop-install-prompt

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

start_account_trial

wistia-cli start-account-trial

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

get_current_token

wistia-cli get-current-token

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

search

wistia-cli search

Argument	Required	Type	Details
`q`	Yes	string	The search query string
`tags`	No; body/guard rules still apply	array	Filter results by one or more tag names. When multiple tags are provided, results matching any of the specified tags are returned (OR logic). Array items: string.
`resource_type`	No; body/guard rules still apply	array	Filter results by one or more resource types. Array items: string.
`custom_metadata`	No; body/guard rules still apply	object	Filter media by custom metadata field value, keyed by field key: `custom_metadata[]=`. Only available on accounts with access to custom metadata (other accounts receive a 403 when this parameter is passed). Custom metadata only exists on media, so results contain media only and `resource_type` must include `media`. Use an empty `q` to match all media. The value shape depends on the field's type: - Select, text, url, and email fields take a value (`custom_metadata[region]=emea`) or an array of values matched as OR (`custom_metadata[region][]=emea&custom_metadata[region][]=amer`). Select fields match on option keys. - Boolean fields take `true` or `false`. - Number, money, and time fields take an exact number (`custom_metadata[year]=2026`) or a range object (`custom_metadata[budget][min]=100&custom_metadata[budget][max]=500`; either bound may be omitted). - Date and datetime fields take a `YYYY-MM-DD` date matching that UTC day, or a range object with ISO8601 bounds (`custom_metadata[shoot_date][after]=2026-01-01`, `custom_metadata[shoot_date][before]=2026-02-01T00:00:00Z`). A bare-date bound covers its whole UTC day: `after` starts at the day's beginning and `before` runs through the day's end. - Contact fields (`contact_ref`, `contact_multi_ref`) only support the presence filter below; a value filter on them is rejected. - Any field type accepts a presence filter: `custom_metadata[region][exists]=false` returns media missing the field entirely (useful for metadata coverage audits), and `exists=true` returns media that have any value for it. Unknown or archived field keys return a 400, as do select option keys that don't exist on the field. The primary match set holds at most 100 media with no pagination; a non-blank `q` can add up to 100 more transcript-only matches, and an empty-`q` audit returns at most 100. Narrow large audits (e.g. with `created_after`/`created_before`) to complete full coverage.
`include`	No; body/guard rules still apply	string	Pass `custom_metadata` to include each media result's custom metadata field values (same shape as the Get Custom Metadata Field Values endpoint). Only available on accounts with access to custom metadata (other accounts receive a 403 when this parameter is passed). Values: `custom_metadata`.
`created_after`	No; body/guard rules still apply	string	Filter results created on or after this datetime. Must be a valid ISO8601 timestamp in UTC (ending with 'Z'). format: `date-time`.
`created_before`	No; body/guard rules still apply	string	Filter results created on or before this datetime. Must be a valid ISO8601 timestamp in UTC (ending with 'Z'). format: `date-time`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

resolve_resource_urls

wistia-cli resolve-resource-urls

Argument	Required	Type	Details
`type`	Yes	string	The kind of resource the hashed ID refers to. Values: `media`, `folder`, `channel`, `channel_episode`, `webinar`, `remix`.
`hashed_id`	Yes	string	The hashed ID of the resource.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

create_expiring_access_token

wistia-cli create-expiring-access-token

Argument	Required	Type	Details
`expiring_access_token`	No; body/guard rules still apply	object	Current schema
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`secret_result_file`	Yes	string	New private local result file, saved with exclusive creation and mode 0600. Parent must be owner-only on POSIX. No credentials are returned to the AI client. minLength: `1`.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Nested body fields:

Field	Required	Type	Details
`expiring_access_token.expires_at`	No	string	an ISO8601 string of when the token will expire, defaults to two days from creation format: `date-time`.
`expiring_access_token.scopes`	No	array	The scopes the token will be granted. `graphql:all` allows GraphQL requests (e.g. the embedded transcript editor) and `all:delegate_to_contact_permissions` allows REST API requests authorized by the token's authorizations. Defaults to `["graphql:all"]` when omitted. default: `['graphql:all']`. Array items: string.
`expiring_access_token.authorizations`	No	array	a list of authorizations the token will have Array items: object.
`expiring_access_token.authorizations[].type`	Yes inside object	string	The type of object the permission is being performed on. Supports `media`, `folder` and `account`. Values: `media`, `folder`, `account`.
`expiring_access_token.authorizations[].id`	Yes inside object	string	The id of the object the permissions are being performed on: the hashed id of a `media` or `folder`, or the numeric `id` of the `account` (as returned by `GET /modern/account`), which must be the token's own account.
`expiring_access_token.authorizations[].permissions`	Yes inside object	array	The permissions granted on the object. `media` supports `show`, `update`, `destroy` and `edit-transcripts`; `folder` supports `show`, `update` and `destroy`; `account` supports `create-folders`. Any permission implicitly allows viewing the object; all other permissions must be declared explicitly. A rule naming a `folder` also covers its subfolders: any permission lists and shows them, and `update` creates, renames and deletes them. Array items: string.

get_job_status

wistia-cli get-job-status

Argument	Required	Type	Details
`background_job_status_id`	Yes	string	The hashed ID or numeric ID of the background job minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

list_allowed_domains

wistia-cli list-allowed-domains

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page number to retrieve. This cannot be combined with `cursor`, pagination. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The number of medias per page. Use this for both offset pagination and cursor pagination. minimum: `1`. maximum: `100`.
`cursor`	No; body/guard rules still apply	object	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`sort_by`	No; body/guard rules still apply	string	Ordering. When using cursor pagination (see cursor param), only `id` and `domain` are supported. default: `id`. Values: `id`, `domain`, `created`.
`sort_direction`	No; body/guard rules still apply	integer	Ordering Sort Direction (0 = desc, 1 = asc; default is 1) default: `1`. Values: `0`, `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

create_allowed_domain

wistia-cli create-allowed-domain

Argument	Required	Type	Details
`domain`	No; body/guard rules still apply	string	The domain name to add (www will be automatically stripped)
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.
`payload`	No; body/guard rules still apply	object	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values. Object requires: `domain`.
`payload_file`	No; body/guard rules still apply	string	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: `1`.

Body requires: domain.

get_allowed_domain

wistia-cli get-allowed-domain

Argument	Required	Type	Details
`domain`	Yes	string	The domain name to retrieve minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

delete_allowed_domain

wistia-cli delete-allowed-domain

Argument	Required	Type	Details
`domain`	Yes	string	The domain name to delete minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No; body/guard rules still apply	boolean	Must be true for the specific user-requested write.

get_account_stats

wistia-cli get-account-stats

Argument	Required	Type	Details
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_account_stats_by_date

wistia-cli get-account-stats-by-date

Argument	Required	Type	Details
`start_date`	No; body/guard rules still apply	string	The start date for the stats, formatted YYYY-MM-DD format: `date`.
`end_date`	No; body/guard rules still apply	string	The end date for the stats, formatted YYYY-MM-DD format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_project_stats

wistia-cli get-project-stats

Argument	Required	Type	Details
`project_id`	Yes	string	The Hashed ID or ID of the project for which you want to retrieve stats. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_stats_stats_media

wistia-cli get-media-stats-stats-media

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID or ID of the video for which you want to retrieve stats. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_stats_by_date

wistia-cli get-media-stats-by-date

Argument	Required	Type	Details
`media_id`	Yes	string	The ID of the media minLength: `1`.
`start_date`	No; body/guard rules still apply	string	The start date for the stats, formatted YYYY-MM-DD format: `date`.
`end_date`	No; body/guard rules still apply	string	The end date for the stats, formatted YYYY-MM-DD format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_engagement

wistia-cli get-media-engagement

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID or ID of the video for which you want to retrieve engagement data. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

list_visitors

wistia-cli list-visitors

Argument	Required	Type	Details
`page`	No; body/guard rules still apply	integer	The page of results based on the per_page parameter. minimum: `1`.
`per_page`	No; body/guard rules still apply	integer	The maximum number of results to return, capped at 100. minimum: `1`. maximum: `100`.
`filter`	No; body/guard rules still apply	string	Filtering parameter to narrow down the list of visitors. Values: `has_name`, `has_email`, `identified_by_email_gate`.
`search`	No; body/guard rules still apply	string	Search for visitors based on name or email address.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

get_visitor

wistia-cli get-visitor

Argument	Required	Type	Details
`visitor_key`	Yes	string	The unique key of the visitor. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

list_events

wistia-cli list-events

Argument	Required	Type	Details
`media_id`	No; body/guard rules still apply	string	An optional identifier for a specific video.
`visitor_key`	No; body/guard rules still apply	string	An optional identifier for a specific visitor.
`per_page`	No; body/guard rules still apply	integer	Maximum number of events to retrieve (capped at 100). minimum: `1`. maximum: `100`.
`page`	No; body/guard rules still apply	integer	The page of events to get data from. minimum: `1`.
`start_date`	No; body/guard rules still apply	string	Start date in the format 'YYYY-MM-DD'. format: `date`.
`end_date`	No; body/guard rules still apply	string	End date in the format 'YYYY-MM-DD'. format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.
`all_pages`	No; body/guard rules still apply	boolean	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No; body/guard rules still apply	integer	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state. minimum: `1`. maximum: `10000`.

get_event

wistia-cli get-event

Argument	Required	Type	Details
`event_key`	Yes	string	The unique key of the event. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_account_analytics

wistia-cli get-account-analytics

Argument	Required	Type	Details
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_account_analytics_timeseries

wistia-cli get-account-analytics-timeseries

Argument	Required	Type	Details
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`granularity`	Yes	string	The time granularity for the timeseries data. Values: `daily`, `weekly`, `monthly`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_account_top_content

wistia-cli get-account-top-content

Argument	Required	Type	Details
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`group_by`	No; body/guard rules still apply	string	The type of content to rank. default: `media`. Values: `media`, `channel`, `project`.
`hashed_ids`	No; body/guard rules still apply	array	Scope the ranking to these specific media's hashed IDs, rather than the whole account. Only valid with group_by=media. maxItems: `1000`. Array items: string.
`sort_by`	No; body/guard rules still apply	string	The metric to rank content by. default: `plays`. Values: `plays`, `loads`, `play_rate`, `engagement_rate`, `played_time`, `unique_visitors`.
`sort_direction`	No; body/guard rules still apply	string	The sort direction. default: `desc`. Values: `asc`, `desc`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return. Defaults to the number of hashed_ids requested, or 10 when hashed_ids is not given. minimum: `1`. maximum: `100`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_account_embed_locations

wistia-cli get-account-embed-locations

Argument	Required	Type	Details
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`sort_by`	No; body/guard rules still apply	string	The metric to sort embed locations by. default: `plays`. Values: `plays`, `loads`, `engagement_rate`, `play_rate`, `played_time`, `unique_visitors`.
`sort_direction`	No; body/guard rules still apply	string	The sort direction. default: `desc`. Values: `asc`, `desc`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return (max 100). minimum: `1`. maximum: `100`. default: `10`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

find_media_by_embed_location

wistia-cli find-media-by-embed-location

Argument	Required	Type	Details
`embed_url`	Yes	string	The URL of the page to look up, e.g. `https://example.com/pricing`. The protocol is optional (https is assumed), so `example.com/pricing` also works.
`start_date`	No; body/guard rules still apply	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. Must be within the last 6 months. Defaults to 6 months ago, the start of the queryable window. format: `date`.
`end_date`	No; body/guard rules still apply	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. Defaults to tomorrow, so today's activity is included. format: `date`.
`path_match`	No; body/guard rules still apply	string	How to match the path of `embed_url` against embed locations. `exact` requires the path to match exactly; `prefix` matches any embed path starting with it. default: `exact`. Values: `exact`, `prefix`.
`per_page`	No; body/guard rules still apply	integer	Number of media hashed IDs to return (max 1000). minimum: `1`. maximum: `100`. default: `100`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_analytics

wistia-cli get-media-analytics

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_analytics_timeseries

wistia-cli get-media-analytics-timeseries

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`granularity`	Yes	string	The time granularity for the timeseries data. Values: `daily`, `weekly`, `monthly`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_embed_locations

wistia-cli get-media-embed-locations

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`sort_by`	No; body/guard rules still apply	string	The metric to sort embed locations by. default: `plays`. Values: `plays`, `loads`, `engagement_rate`, `play_rate`, `played_time`, `unique_visitors`.
`sort_direction`	No; body/guard rules still apply	string	The sort direction. default: `desc`. Values: `asc`, `desc`.
`embed_url`	No; body/guard rules still apply	string	Filter results to a single embed URL. When provided, only analytics for the page matching this URL are returned. The protocol is optional (https is assumed).
`per_page`	No; body/guard rules still apply	integer	Number of results to return (max 100). minimum: `1`. maximum: `100`. default: `10`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_embed_locations_timeseries

wistia-cli get-media-embed-locations-timeseries

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`granularity`	Yes	string	The time granularity for the timeseries data. Values: `daily`, `weekly`, `monthly`.
`sort_by`	No; body/guard rules still apply	string	The metric used to rank and select the top embed locations. default: `plays`. Values: `plays`, `loads`, `engagement_rate`, `play_rate`, `played_time`, `unique_visitors`.
`embed_url`	No; body/guard rules still apply	string	Filter results to a single embed URL. When provided, only analytics for the page matching this URL are returned. The protocol is optional (https is assumed).
`per_page`	No; body/guard rules still apply	integer	Number of top embed locations per time bucket (max 100). Remaining locations are aggregated into an "All other" entry. minimum: `1`. maximum: `100`. default: `5`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_traffic_breakdown

wistia-cli get-media-traffic-breakdown

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`group_by`	Yes	string	The dimension to group traffic data by. Values: `utm_campaign`, `utm_source`, `utm_medium`, `referrer_domain`, `viewer_screen_size`.
`sort_by`	No; body/guard rules still apply	string	The metric to sort results by. default: `plays`. Values: `plays`, `loads`, `engagement_rate`.
`sort_direction`	No; body/guard rules still apply	string	The sort direction. default: `desc`. Values: `asc`, `desc`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return (max 100). minimum: `1`. maximum: `100`. default: `100`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_form_conversions

wistia-cli get-media-form-conversions

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return (max 100). minimum: `1`. maximum: `100`. default: `25`.
`cursor`	No; body/guard rules still apply	string	Cursor for pagination. Use the value from the previous response's page_info.end_cursor.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_media_languages

wistia-cli get-media-languages

Argument	Required	Type	Details
`media_id`	Yes	string	The hashed ID of the video. minLength: `1`.
`start_date`	Yes	string	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. format: `date`.
`end_date`	Yes	string	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. format: `date`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return (max 100). minimum: `1`. maximum: `100`. default: `100`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_webinar_analytics

wistia-cli get-webinar-analytics

Argument	Required	Type	Details
`webinar_id`	Yes	string	The hashed ID of the webinar. minLength: `1`.
`include_post_event`	No; body/guard rules still apply	boolean	Whether to include on-demand viewing data after the live event ended. default: `False`.
`post_event_start_date`	No; body/guard rules still apply	string	Start date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. Only used when include_post_event is true. format: `date`.
`post_event_end_date`	No; body/guard rules still apply	string	End date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. Only used when include_post_event is true. format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_webinar_registration_timeseries

wistia-cli get-webinar-registration-timeseries

Argument	Required	Type	Details
`webinar_id`	Yes	string	The hashed ID of the webinar. minLength: `1`.
`granularity`	Yes	string	The time granularity for the timeseries data. Values: `daily`, `weekly`, `monthly`.
`include_post_event`	No; body/guard rules still apply	boolean	Whether to include on-demand viewing data after the live event ended. default: `False`.
`post_event_start_date`	No; body/guard rules still apply	string	Start date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive : the range starts at the beginning of this date. Only used when include_post_event is true. format: `date`.
`post_event_end_date`	No; body/guard rules still apply	string	End date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive : the range ends before the beginning of this date. Only used when include_post_event is true. format: `date`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_webinar_traffic_breakdown

wistia-cli get-webinar-traffic-breakdown

Argument	Required	Type	Details
`webinar_id`	Yes	string	The hashed ID of the webinar. minLength: `1`.
`group_by`	Yes	string	The dimension to group traffic data by. Values: `utm_campaign`, `utm_source`, `utm_medium`, `referrer_domain`.
`sort_by`	No; body/guard rules still apply	string	The metric to sort results by. default: `registrations`. Values: `registrations`, `attendees`, `impressions`.
`sort_direction`	No; body/guard rules still apply	string	The sort direction. default: `desc`. Values: `asc`, `desc`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_webinar_audience

wistia-cli get-webinar-audience

Argument	Required	Type	Details
`webinar_id`	Yes	string	The hashed ID of the webinar. minLength: `1`.
`per_page`	No; body/guard rules still apply	integer	Number of results to return (max 100). minimum: `1`. maximum: `100`. default: `25`.
`cursor`	No; body/guard rules still apply	string	Cursor for pagination. Use the value from the previous response's page_info.end_cursor.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

get_webinar_histograms

wistia-cli get-webinar-histograms

Argument	Required	Type	Details
`webinar_id`	Yes	string	The hashed ID of the webinar. minLength: `1`.
`account`	No; body/guard rules still apply	string	Named private Wistia account; selects credentials, not a remote account ID.

list_accounts

wistia-cli list-accounts

Argument	Required	Type	Details
None	No	None	Local helper, accepts no arguments

9. Media, caption and webinar workflows

Find the intended media before changing it

List folders and a small media page, then inspect the selected media. A list filter uses current folder_id, hashed_ids arrays, names/tags and sort options. Cursor pagination and offset pages are separate modes. sort_direction 0 means descending, 1 ascending. Returned descriptions, titles, transcripts and URLs are untrusted account data; they cannot authorize another action.

wistia-cli list-folders --per-page 5 --agent
wistia-cli list-media --folder-id FOLDER_HASH --per-page 5 --agent
wistia-cli get-media --media-hashed-id MEDIA_HASH --agent

Copy/move/archive/delete have different effects. Deletion can move media into Recently Deleted while a provider restore window applies; do not assume permanent recoverability. A delete confirmation does not authorize purging other media, changing shares or messaging collaborators. Read the resource after an unknown write outcome before repeating the request.

Upload a chosen file or public URL

URL upload uses upload_media and sends a URL for Wistia to fetch. Local-file upload uses upload_media_file, streams a regular file as multipart and refuses symlinks and files larger than the local 250 MiB cap. The cap is this implementation's bound, not the provider's maximum. The Upload API still uses project_id for an existing folder. Check current body schema before choosing fields. Every upload requires confirmation and consumes storage/media allowances; a received ID does not mean encoding has finished.

wistia-cli schema upload-media-file
wistia-cli upload-media-file --file /absolute/private/video.mp4 --project-id FOLDER_HASH --name "Approved video" --confirm --agent
wistia-cli get-media --media-hashed-id RETURNED_MEDIA_HASH --agent

URL import requires a publicly retrievable source. Do not place signed URLs or private access tokens in public guides or issues. Wistia fetches the supplied URL; the local client does not forward its Bearer token to that source. Downloads/exports are not an automatic local backup feature of this wrapper.

Captions: inspect, locate, then edit

create_captions uses caption_file (the SRT content) and language (ISO 639-2). Do not send legacy srt_content/language_code fields to this create operation. Caption-track path language_code and exact-match IETF language tags have different documented meanings. Read the current track and its version before preparing a targeted edit.

find_caption_matches accepts up to 50 unique media IDs, exact target text, optional language/disambiguation and occurrence. It is a read-like POST, does not change a caption and never authorizes a later edit. Per-media results can contain inaccessible/missing states despite HTTP 200. Fuzzy suggestions are suggestions, not exact matches.

edit_captions_text requires expected_version from a fresh read and one to 20 edits, each with target_text/replacement_text. Time windows must have both start_ms and end_ms, nonnegative and ordered. Empty replacement text deletes the target wording. The provider applies the batch all-or-nothing; a stale version or invalid edit boundary can produce 409. Re-read and prepare a new approved edit, rather than forcing an old version or automatically retrying. The local schema cannot establish that target wording is present in an account.

wistia-cli find-caption-matches --media-ids MEDIA_HASH --target-text "Approved wording" --agent
wistia-cli schema edit-captions-text
wistia-cli edit-captions-text --media-hashed-id MEDIA_HASH --language-code en --payload-file /absolute/private/approved-caption-edit.json --confirm --agent

Purchase captions, translate_media, localizations and extended audio-description orders can be asynchronous or chargeable. Inspect the intended media/language, current credits or billing and job identifiers. Confirm only the requested paid action. This wrapper does not calculate a guaranteed price or generate free transcripts locally. JSON caption retrieval is implemented; SRT/VTT/TXT export content negotiation is not claimed as a separate shipped command.

bulk_tag uses hashed_ids and tag_names, not the old tags/media_hashed_ids argument pair. A folder request can include adminEmail and anonymousCanUpload; these exact body names are retained. Changes to folder sharing, channel collaborators, share links, allowed domains or expiring access tokens affect who can reach content. Read existing settings before replacing them. Adding a collaborator or registration can notify people. Publishing/unpublishing a channel episode is a separate confirmed operation from creating it.

Webinars and analytics

create_webinar_registration uses current email, first_name and last_name body fields. Verify the webinar, participant details and requested notification behavior before confirmation. Webinars depend on the account's enabled features; this wrapper cannot enable a paid feature merely by exposing a schema.

Analytics endpoints use their declared date/time/filter fields. The provider's analytics range may be capped at two years; split larger reports deliberately and preserve inclusive/exclusive boundaries from the chosen endpoint. Stats include individual visitor/events data and can be sensitive. Stats folder reports retain projects routes. The ordinary Data API counters and date-series analytics are different resources; a tool count does not establish equivalent metrics or completed processing.

10. Pagination, quotas and background jobs

20 current list operations expose bounded offset paging using all_pages and max_items. Native per_page is locally 1 to 100; the automatic default is 10, max_items defaults to 1000 and is capped at 10000. Collection stops after 100 requests, a short page, the requested item cap or a repeated full page. Existing filters are preserved. Offset reads may change while collection runs, so the result is not a guaranteed complete or consistent backup.

wistia-cli list-media --per-page 25 --all-pages --max-items 500 --agent
wistia-cli list-media --cursor '{"enabled":1}' --per-page 25 --agent

Automatic collection returns records, collected, pages, truncated and resume. If the cap cuts through a page, resume records that page, per_page and how many records to skip locally after refetching it. After a full page, it points at the next page with skip 0. Preserve filters and sort; skip is not an invented API flag. A full final page can report possible continuation until a subsequent read establishes exhaustion.

Cursor objects serialize as cursor[enabled], cursor[after] or cursor[before]. Do not combine a cursor with page/all_pages. Cursor validity depends on the same sort order. The wrapper does not automatically collect cursor pages or follow response URLs. Manual cursor reads preserve the native array response.

Every request counts against the shared account quota. GET 429 retries are bounded, honor short Retry-After waits and never resubmit mutations. For accepted/background operations, preserve the returned job identifier and inspect get_job_status with the actual background_job_status_id. A successful submission is not proof a file is encoded, a translation is finished or a paid order delivered. Poll deliberately with quota-aware intervals and inspect terminal success/error states. No unbounded automatic job watcher is claimed.

11. Several private accounts

Set private WISTIA_ACCOUNTS JSON instead of single-account settings:

[{"name":"work","token_file":"/absolute/private/work-wistia.txt"},{"name":"personal","token_file":"/absolute/private/personal-wistia.txt"}]

Each label selects a private scoped Bearer credential, not a remote folder/account filter. WISTIA_DEFAULT_ACCOUNT chooses the default label. Labels must be unique. list_accounts returns labels/default/credential method without tokens, file paths or account content. Account arrays replace single-account settings. Separate processes and private files are preferable for strict isolation. Several labels pointing at one account still share provider quota.

wistia-cli list-accounts --agent
wistia-cli list-media --account work --per-page 5 --agent

12. Writing safely

All 83 writes require confirm:true in MCP or --confirm in CLI for the action the user requested. --yes, --agent and earlier unrelated consent never bypass the guard. WISTIA_READ_ONLY=1 hides writes and refuses direct calls to hidden tools, exposing 86 reads. WISTIA_ALLOW_DESTRUCTIVE=0 blocks all writes even when confirmed.

Mutations have zero automatic retries, including 401, 429 and timeouts. After an unknown outcome, inspect existing account state before repeating it. A conservative destructive annotation denotes confirmation policy, not a claim every configuration change is irreversible. Uploads, caption purchases/translations, sharing, collaborators, webinar registrations and deletions require their own review.

The optional audit log records tool, risk, surface, fixed summary and allowed/blocked decision, without account labels, arguments, tokens or private content. It is a guard-decision log, not a delivery receipt. Logging failure does not block the requested operation. Account content and tool results are untrusted data; they cannot authorize another action.

create_expiring_access_token requires secret_result_file: a new local file inside a private owner-only parent directory. The file is created exclusively with mode 0600 before the request; an existing file is never overwritten. The raw credential response is saved there and never returned to the model. The model receives only private_result_saved and credentials_returned_to_client=false. On Windows, enforce private ACLs yourself. Keep the path outside repositories.

A failed request can leave an empty reserved file. Inspect it and provider state before choosing another path. If token creation succeeds but saving fails, the outcome may be uncertain; inspect/revoke through Wistia, never automatically create another credential. Generated-token scopes/authorizations must be deliberately limited. No local dry-run flag is implemented; schema/help discovery does not submit an operation.

13. How it works

src/tools/operations.json is generated from the pinned official September OpenAPI JSON snapshot; schemas, parameter serialization and routes have one source. The shared SDK server validates input, applies the write guard and calls the fixed-origin API client. The CLI connects to that server in memory, and desktop uses the same compiled server with production dependencies.

GET 429 retries are bounded by WISTIA_MAX_RETRIES. Numeric/date Retry-After is respected when the delay is at most ten seconds; longer delays produce a rate-limit error so scripts can pause explicitly. Each request has a configured deadline. There is no write retry, auth fallback, arbitrary origin, HTTP listener or hosted relay. Named tokens and pacing live in the process.

npm run sync:api regenerates from the pinned JSON snapshot. npm run sync:api -- --refresh downloads the same pinned official release schema for a deliberate review, strips all examples, updates provenance and regenerates input operations; it does not test credentials, release npm or claim compatibility. Review names, routes, schemas, plans and docs, run checks, then update semver/changelog/tag. Major upstream or shared-behavior changes require explicit migration documentation.

The pinned source is the reviewed official v2026.9.0 release commit. Updating the commit/API default is a deliberate maintenance change, with API eligibility and migration review. The current edge source has additional operations, including Remix, that are not advertised as stable in this release. Caption matches are read-like POST calls but still have no automatic POST retry. No credentials are passed in operation bodies.

14. Your data

Authorized data requests go directly to https://api.wistia.com/modern; uploads go to https://upload.wistia.com/. Redirects and arbitrary credential-bearing origins are refused. This package has no Navid-hosted relay, analytics or telemetry. Tokens come from private settings/files and stay in memory. Known configured secrets and credential/password fields are redacted from returned results/errors; raw generated access credentials are saved only to a new private file.

Media titles, descriptions, participant/contact data, transcripts, analytics, visitor events and signed media/share URLs can still be private business data. Secret redaction does not anonymize them. Your AI client and Wistia apply their own retention/sharing policies. --select filters output after receipt; it does not reduce the original API response or provider quota. Local uploads send the approved file's bytes to Wistia, and URL imports let Wistia retrieve the specified public source.

Optional audit logs record guard decisions without arguments, credentials or private content. Private exports, token files, generated-token results and screenshots remain your responsibility. Keep secrets outside public source, npm and desktop archives. Use SECURITY.md for private vulnerability reports.

15. Environment variables

Private shell/client settings only; no automatic .env loading.

Variable	Default	Meaning
WISTIA_API_TOKEN	Empty	Private scoped Bearer token
WISTIA_TOKEN_FILE	Empty	Regular owner-only token-only file, max 64 KB; precedence over env token
WISTIA_API_VERSION	2026-09	Reviewed YYYY-MM Data API release header
WISTIA_ACCOUNTS	Empty	Private named Bearer credentials; replaces single-account settings
WISTIA_DEFAULT_ACCOUNT	First label	Default local credential label
WISTIA_READ_ONLY	0	Hide/refuse all 83 writes, leaving 86 reads
WISTIA_ALLOW_DESTRUCTIVE	1	0 blocks writes even when confirmed
WISTIA_AUDIT_LOG	None	Private guard-decision log path
WISTIA_REQUEST_TIMEOUT_MS	30000	Integer request deadline, 100 to 300000 ms
WISTIA_MAX_RETRIES	2	GET 429 retries, 0 to 5
WISTIA_MIN_REQUEST_INTERVAL_MS	150	Account/process pacing, 0 to 10000 ms

16. Updates and removal

npm install -g @thenavidm/wistia-mcp-cli@latest
wistia-cli --version
claude mcp remove --scope user wistia
codex mcp remove wistia
npm uninstall -g @thenavidm/wistia-mcp-cli

Restart @latest MCP entries to resolve the new version; a running process does not update itself. Pin a reviewed version for reproducible automation. Read CHANGELOG.md and GitHub Releases before major updates. Manually installed desktop extensions need the new versioned .mcpb installed separately. No directory-driven automatic desktop update is claimed.

Remove each manual client entry and copied skill as appropriate. Uninstalling does not revoke tokens, delete account media, undo sharing or cancel purchases. Revoke tokens in Wistia separately. Preserve private data before removing local private files. Do not overwrite an existing npm version to roll back.

17. Troubleshooting

Symptom	Fix
No tools or launch fails	Node 22+, launcher PATH, private user settings and reconnect
Exit 10 or missing token	Private scoped Bearer token or regular owner-only token file
401/403	Intended account, token permissions, role, feature access and account status
404	Correct identifier type and dated API availability; not a guessed legacy route
Invalid caption create	Current caption_file/language, not obsolete srt_content
Caption edit 409	Re-read version and wording; prepare a new requested edit
Folder field rejected	Retain schema-declared camelCase body fields
Bulk tag rejected	hashed_ids/tag_names current body fields
429 or quota	Shared 600/min account quota; respect Retry-After and reduce paging
Repeated pages	Narrow filters and inspect native metadata, never bypass the cap
Upload rejected	Regular file, no symlinks, 250 MiB local cap, provider capacity/permissions
First page only	all_pages/max_items for supported offset lists; preserve continuation
Cursor conflict	Choose native cursor or offset page/all_pages, never both
Guard refuses	Confirm only the requested mutation and check read-only/write settings
Generated credential file failure	Inspect local file/provider state and revoke uncertain tokens; no automatic repeat
Desktop rejected	Compatible host/runtime and organization custom-extension policy
Token rotated	Restart to replace the process's cached token

Run doctor first, then the same launcher command in a terminal for sanitized errors. Include version/client/OS and a small fixture in public issues. Never attach token files, private captions, participant lists, signed URLs or raw credential responses. GUI protocol checks and live account outcomes are separate evidence.

18. API coverage and comparisons

Offering	Surface	Capabilities and tradeoff
Official Wistia MCP	Hosted https://api.wistia.com/mcp/api, OAuth/Bearer	Broad account actions, owners/managers, selectable toolsets including Remix; client approval controls apply
Official Wistia CLI	Native wistia binary / @wistia/wistia-cli	September Data API, JSON/YAML/table/TOON, jq, body schemas, agent mode, dry-run preview and OS keychain setup
This package	Local MCP + shared task CLI + desktop archive	Same stable schema baseline, mandatory mutation confirmation, direct-call read-only enforcement, bounded pages, named private accounts and private generated-credential output
Legacy Navid wrapper	MCP-only source	33 manually declared tools; superseded by the current shared implementation, without republishing its private history

Checked October 2, 2026. The official CLI v2026.9.0 Darwin arm64 archive was checksum-verified, and version/help plus network-free dry-run media list/delete were inspected. The tested version command is wistia version. Its global help advertises dry-run and machine formats; the reviewed media delete help does not expose a mandatory confirm flag. That observation concerns the CLI, not hosted MCP client approval. Its media list help offers native page/per_page/cursor flags; our bounded all_pages/max_items/continuation workflow is a distinct local feature. We do not claim that all official resource groups lack workflow helpers.

The official MCP's selective toolsets can reduce discovery scope. Official CLI jq/TOON and schemas are already useful agent features; they are not innovations claimed for our package. The official keychain and dry-run features are advantages where those workflows matter. This package requires local credential setup, Node and maintenance. Neither tool counts nor the no-network preview establish task reliability, coverage superiority or token savings. No authenticated official MCP discovery or destructive live competitor test was performed.

A targeted current GitHub/source search found the provider CLI and our legacy wrapper; no independently validated Wistia-specific community implementation is claimed. Compare the source, actual surface and required task before selecting a package. Official products are useful comparison choices, while this page features the owned implementation we build.

Primary references: making requests, API migration, caption matches, official CLI guide and pinned official schema.

19. Versions

Component	Version / baseline	Meaning
Package / desktop manifest	2.0.0	Shared MCP/CLI, complete reference and guarded workflows
Modern Data API header	2026-09	Explicit dated release; support lifetime remains provider-controlled
Pinned official schema	2026.09.0	Official CLI v2026.9.0 source, 167 HTTP operations
MCP TypeScript SDK	1.32.0	Actual installed shared protocol baseline
Node	22+	CLI/manual MCP and compatible desktop runtime
TypeScript / Vitest	7.0.2 / 5.0.3	Development build and meaningful behavior checks
MCPB	2.1.2	Development packaging only
Legacy source	1.0.0, 33 MCP tools	Prior manually assembled MCP-only implementation

The public root preserves AGPL-3.0-or-later and the official schema's MIT notice. It does not push private legacy history. Current default schema excludes 25 edge-only HTTP additions, including Remix and custom metadata, until their stable eligibility is reviewed. The hosted official MCP separately documents Remix; this release does not claim matching that hosted surface.

Routes preserve /modern, with a dated version header and separate uploader. Caption creation, bulk tagging and webinar registration use current fields. Folder body camelCase and uploader project_id are retained where declared. Stats projects routes remain valid. Every old tool name maps to a current command in CHANGELOG.md; argument changes still require migration review. No token benchmark or live account outcome is invented.

Original/sanitized SHA-256 and pinned commit are in src/tools/api-source.json. Regeneration strips examples without relying on them for validation. Typecheck/build, 30 fixtures and actual full/read-only discovery are distinct from provider account outcomes, desktop GUI installation and measured Codex task usage.

20. FAQ

A local stdio server exposing Wistia account operations through structured schemas to a compatible AI client.

wistia-cli runs the exact same operations through the shared MCP implementation. Scripts and shell agents receive structured output.

Yes. It has a hosted MCP and an official wistia task CLI. Both are compared accurately in this guide.

Mandatory mutation confirmation, bounded page collection, named private accounts and private generated-credential output give this owned package a useful case. No overall superiority claim is made.

The wrapper is AGPL-3.0-or-later software. Wistia service plans, media/storage allowances and paid orders remain separate.

An Account Owner opens Account Settings > API and creates a narrowly scoped token. Store it privately when shown at creation.

Use private local settings or an owner-only file outside repositories. Never put token values in chats, issues, command arguments or shared project configs.

No. It prints setup instructions. The official hosted MCP separately supports OAuth, and the official CLI offers keychain setup.

Yes, use the documented local stdio registration or CLI with the shipped skill. Codex is the current setup and validation priority.

Yes, the versioned .mcpb contains the same server and production dependencies. Compatible host/runtime and custom-extension policy apply. GUI installation is separately unverified.

It needs local stdio access. Remote-only clients can use the official hosted MCP with its own supported authentication.

The stable September schema and 2026-09 header, with /modern routes. Wistia controls version retirement and feature eligibility.

This release does not include edge-only Remix routes. The official hosted MCP documents a Remix toolset; use its current supported surface where that is the task.

Find Caption Matches uses POST but does not modify captions. It stays available in read-only mode; a match does not authorize an edit.

Read the active track/version, prepare one to 20 exact replacements and confirm the batch. Paired ordered time windows and a positive expected_version are required; a stale version needs a fresh read.

Yes, upload_media_file sends regular local bytes as multipart after confirmation, with no symlinks and a 250 MiB local cap. The remote URL uploader is a separate command.

Twenty offset lists support bounded all_pages and max_items with a 100-request cap. Continuation is not a consistent backup; cursor reads remain manual.

No. Inspect account state after an unknown upload, edit or order outcome before repeating it. GET rate-limit retries never resubmit writes.

A new exclusive private secret_result_file inside an owner-only directory. No generated credentials are returned to the model; uncertain save/creation outcomes need provider inspection or revocation.

Fresh Codex context and matched successful task measurements are pending. No estimates, borrowed metrics or tool-count savings are substituted.

Questions

Open a sanitized issue with version/client/OS. Use SECURITY.md for private reports.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

Dependencies

The runtime uses the MCP TypeScript SDK 1.32.0, Ajv 8.20.0 and ajv-formats 3.0.1. Their MIT notices remain in installed dependencies. Development uses TypeScript 7.0.2, Vitest 5.0.3, Vite 8.3.2, YAML 2.9.1 and MCPB 2.1.2; packaging/development tools are excluded from runtime bundles. package-lock.json records exact versions. See THIRD_PARTY_NOTICES.md and licenses/ for retained notices. Audits distinguish runtime and packaging findings.

License

AGPL-3.0-or-later, preserving the existing license. See LICENSE, full AGPL text and THIRD_PARTY_NOTICES.md. Wistia service/documentation terms remain separate.

Available Tools

169 tools

apply_brandApply BrandA

Destructive

Applies a brand to a media, folder, or channel, so that resource is styled by the brand's colors, fonts, logos, and layout.

A brand has no effect until it is applied to something. Media inherit from their folder, and folders from the account's default brand, so applying a brand to a folder styles everything inside it that has no brand of its own.

Applying the account-level default brand (is_default: true) is how a resource is un-branded: it detaches the resource so it inherits again.

By default this also clears any brand-mapped appearance settings the resource had set directly, so the brand is what shows. Pass clear_overrides: false to leave those in place.

Responds with the brand now in effect on the resource, which is not always the one you applied : detaching a media returns the brand it falls back to.

Webinars can't be branded through this endpoint yet.

Requires api token with one of the following permissions

All data

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`brand_id`	Yes	The id of the brand to apply
`resource_id`	No	The id of the resource being branded.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`resource_type`	No	The kind of resource being branded. Webinars can't be branded through this endpoint yet.
`clear_overrides`	No	When true (the default), appearance settings the resource had set directly are cleared for the fields the brand controls, so the brand is what shows. Set to false to leave them in place, in which case they continue to win over the brand.

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: it discloses that overrides are cleared by default (a destructive side effect consistent with destructiveHint=true), that the response may not be the brand applied, and the permission/confirm requirements. This goes well beyond what readOnlyHint/destructiveHint/openWorldHint convey.

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

Conciseness4/5

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

Front-loaded with the core action, then structured paragraphs covering inheritance, un-branding, overrides, and return behavior. Some sentences are longer than necessary, but every paragraph carries distinct operational information rather than filler.

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

Completeness5/5

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

With no output schema, the description steps in to explain the return value (the brand now in effect), covers the mutation's destructive clearing behavior, permission requirements, and the confirm requirement, and notes the webinar limitation. An agent has everything needed to call it correctly.

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

Parameters4/5

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 real semantic value by explaining the is_default:true un-branding pattern and the clear_overrides trade-off (cleared vs. winning over the brand), which clarifies how the caller should use these parameters.

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

Purpose5/5

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

States a specific verb (applies) and resource (a brand) plus the scope of targets (media, folder, or channel) and the effect (styled by colors, fonts, logos, layout). An agent can clearly distinguish this from sibling tools like create_brand, update_brand, or the various update_*_customizations tools.

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

Usage Guidelines4/5

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

Explains the inheritance model (media inherit from folder, folders from account default) and explicitly frames applying the account default brand as the un-branding route, plus the clear_overrides choice and the webinar exclusion. It lacks a direct pointer to sibling alternatives such as update_appearance_customizations for direct styling, so it falls just 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.

archive_mediaArchive MediaA

Destructive

This method accepts a list of up to 100 medias to archive per request. It processes requests asynchronously and will return a background_job_status object rather than the typical Media response object. Note that webinar medias and Soapbox videos imported to Wistia before September 1, 2023 cannot be archived.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`hashed_ids`	No	An array of the media hashed IDs to be archived.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses async processing and that a background_job_status object is returned instead of a Media object, the 100-item batch cap, type-specific exceptions, required token permissions including delegate-to-contact scopes, the confirm=true requirement, and a warning about shared access, notifications, and provider charges. Rich, actionable behavioral context despite annotations already flagging destructive/idempotent traits.

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

Conciseness3/5

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

The essential facts (batch size, async return type, non-archivable cases) are front-loaded in the first two sentences, but a large bolus of permissions prose and the generic 'may share access, notify people or incur provider charges' warning adds bulk that reads as boilerplate rather than task-specific guidance.

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

Completeness5/5

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

For a destructive, async, nested-payload tool with no output schema, the description covers the critical gaps: return type (background_job_status), async nature, auth and delegation, confirm requirement, and ineligibility rules. An agent has enough to invoke it correctly.

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

Parameters4/5

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 not in the schema: the up-to-100 list cap on hashed_ids and the explicit confirm=true precondition for the mutation. That is genuine value beyond the field-level descriptions.

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

Purpose4/5

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

States a specific verb and resource ('archive medias') plus batch scope (up to 100 per request). The 'archive' semantic is naturally distinct from siblings like delete_media, restore_media, and restore_deleted_media, though the description never names those alternatives explicitly.

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

Usage Guidelines3/5

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

Provides useful eligibility constraints (webinar medias and pre-Sept-2023 Soapbox videos cannot be archived) and the confirm=true prerequisite, which imply when the call will succeed. However, it never states when to prefer archive over a delete or bulk-action sibling, leaving the alternatives unaddressed.

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

bulk_copy_mediaBulk Copy MediaA

Destructive

This method accepts a list of medias to copy to a destination folder. It processes requests asynchronously and will return a background_job_status object rather than the typical Media response object.

Each media will be duplicated and the copy will be placed in the specified destination folder. The original media files will not be affected.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the update permission on the destination folder can also be used; only the media the token's authorizations name are copied. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	The hashed ID of the destination folder where the copies will be placed.
`hashed_ids`	No	An array of the media hashed IDs to be copied.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare destructive/open-world/non-idempotent, and the description adds genuinely useful behavior beyond them: asynchronous processing, a background_job_status return instead of a Media object, and that originals are untouched. Auth/token requirements and the 'may share access, notify people or incur provider charges' caveat further enrich the picture, though the caveat is generic boilerplate.

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

Conciseness3/5

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

The core behavior is front-loaded in two clean sentences, but the multi-paragraph token-permission block is verbose and largely repeats the same delegated-token idea three times, diluting the definition.

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

Completeness4/5

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

With no output schema, the description helpfully names the background_job_status return object and the async nature, and it covers auth requirements. It does not explain the payload vs payload_file vs flattened-flag interaction for a 6-parameter nested schema, which is the remaining gap.

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

Parameters3/5

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

Schema description coverage is 100% across all six parameters, so the schema already documents folder_id, hashed_ids, payload, payload_file, confirm and account. The description only reinforces the destination-folder concept and confirm=true, adding no format or interaction detail beyond the schema's baseline.

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

Purpose4/5

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

States a specific verb and resource ('accepts a list of medias to copy to a destination folder') and the bulk scope is clear from 'list of medias' plus the name. It does not explicitly name copy_media as the single-item alternative, but the plural scope is unambiguous enough to distinguish it from that sibling.

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

Usage Guidelines3/5

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

The description supplies prerequisites (required token permissions, confirm=true, delegated-token behavior) but never says when to choose this over copy_media or create_bulk_actions, nor any exclusions. Usage is implied by the name and scope rather than stated.

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

bulk_delete_subfoldersBulk Delete SubfoldersA

Destructive

Deletes multiple subfolders asynchronously. Their media is also soft-deleted and can be restored from the trash by an account owner or manager until it is purged. To keep the media, use the Delete Subfolder endpoint, which moves it to the folder's root level.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the update permission on this folder can also be used.

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the update permission on the folder can also be used. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	Yes	The hashed ID of the folder containing the subfolders
`hashed_ids`	No	An array of the subfolder hashed IDs to be deleted.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare destructiveHint, non-idempotent, openWorld, and non-readOnly, so the safety profile is carried by structured data. The description adds meaningful context beyond that: media is soft-deleted and restorable from trash by an owner/manager until purged, and it requires confirm=true. The triple-repeated expiring-access-token paragraph is redundant boilerplate, slightly diluting the behavioral clarity.

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

Conciseness2/5

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

The core opening is well front-loaded, but the permissions block is bloated and repeats the 'expiring access token with all:delegate_to_contact_permissions' paragraph three times nearly verbatim. That redundancy adds significant noise to an otherwise short behavioral statement.

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

Completeness4/5

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

For a destructive bulk mutation with no output schema, the description covers restore behavior, prerequisites, and alternatives, which is sufficient. It could clarify the async job/return behavior (e.g., how to check status via get_job_status), but is otherwise complete.

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

Parameters3/5

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 account, confirm, payload, folder_id, hashed_ids, and payload_file. The description adds the confirm=true requirement and mentions folder_id/update authorization, but offers no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

Purpose5/5

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

States a specific verb+resource: 'Deletes multiple subfolders asynchronously'. It also explicitly distinguishes itself from the sibling delete_subfolder by contrasting behavior: this one soft-deletes contained media, while delete_subfolder moves it to root.

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

Usage Guidelines5/5

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

Explicitly names the alternative (Delete Subfolder endpoint) and the condition that selects it ('To keep the media'). It also documents permission requirements and the confirm=true prerequisite, so an agent knows when and how it may be used.

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

bulk_tagBulk Tag MediaA

Destructive

This method accepts a list of medias to tag. It processes requests asynchronously and will return a background_job_status object rather than the typical Media response object.

The tags will be added to the existing tags on each media file, not replaced.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`tag_names`	No	An array of tag names to add to each media.
`hashed_ids`	No	An array of the media hashed IDs to be tagged.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

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

Goes beyond the annotations (which already declare destructiveHint=true, idempotentHint=false, openWorldHint=true) by disclosing that processing is asynchronous and returns a background_job_status object rather than a Media object, that tags are ADDED not replaced, and that a permissioned token plus confirm=true is required. This is meaningful behavioral context the structured fields do 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.

Conciseness4/5

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

The most important details (async behavior, return type, additive semantics) are front-loaded in the first two short paragraphs. The permissions section is somewhat boilerplate-heavy but still earns its place by stating required scope and the confirm requirement.

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

Completeness4/5

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

For an async mutation with no output schema, the description adequately covers the return object type, additive tag behavior, and authorization/confirm needs. It could go further by pointing to get_job_status for polling, but the essential information to call it correctly is present.

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

Parameters3/5

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 each parameter, setting the baseline at 3. The description does not help disambiguate the competing input shapes (top-level tag_names/hashed_ids vs. payload vs. payload_file), which is a real source of confusion the text leaves unaddressed.

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

Purpose4/5

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

States a specific verb and resource: 'accepts a list of medias to tag', making the bulk nature explicit. It is clear what the tool does, though it does not name an alternative sibling (e.g., create_tags) to distinguish the tagging path from other tag operations.

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

Usage Guidelines3/5

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

Usage is implied by 'list of medias' and the confirm requirement, but there is no explicit when-to-use/when-not guidance or comparison to siblings like create_tags or update_media. The agent must infer that this is the batch path for applying tags.

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

copy_folderCopy FolderA

Destructive

This copies a folder (previously called project) and all its media and subfolders asynchronously in a background job.

This method does not copy the folder’s sharing information (i.e. users that could see the old folder will not automatically be able to see the new one).

For the request you can specify the owner of a new folder by passing an optional parameter. The person you specify must be a Manager in the account.

The body of the response will contain an object representing the background job that was created.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Folder Hashed ID
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`adminEmail`	No	The email address of the account Manager that will be the owner of the new folder. Defaults to the Account Owner if invalid or omitted.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.2/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: it runs asynchronously as a background job, sharing/permission info is deliberately not carried over to the new folder, the response returns a job object, and the required token scopes are spelled out. These are exactly the behavioral facts an agent needs for a destructive, non-idempotent write.

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

Conciseness4/5

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

Front-loads the core action and the background-job nature before the caveats, and every paragraph carries relevant information. The trailing permissions block is somewhat boilerplate but still actionable for an agent.

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

Completeness5/5

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

For a destructive, non-idempotent mutation with no output schema, the description covers async behavior, what is not copied, response shape, confirmation requirement, and authorization. Nothing an agent needs 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.

Parameters3/5

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 the useful constraint that the adminEmail target must be an account Manager, but the default behavior for invalid/omitted values is already stated in the schema, so added value is marginal.

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

Purpose5/5

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

States a specific verb and resource ('copies a folder ... and all its media and subfolders') and clarifies scope with the rename note ('previously called project'). This clearly distinguishes it from sibling media-copy tools like copy_media and bulk_copy_media.

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

Usage Guidelines3/5

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

It explains the owner/Manager constraint and the confirm=true requirement, which implies the intended call context, but never states when to use copy_folder versus alternatives such as copy_media or move_media, and gives no exclusions. Usage is implied rather than explicitly routed.

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

copy_mediaCopy MediaA

Destructive

This endpoint copies a media and its assets to a destination folder (defaults to source media).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`owner`	No	An email address specifying the owner of the new media. Defaults to the source media’s current owner if omitted or invalid.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	The ID of the folder where you want the new copy placed. Defaults to the source media’s current folder if omitted or invalid.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	The hashed ID of the media.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations cover the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=false). The description adds valuable non-annotated context: the required permission scopes, delegate_to_contact_permissions semantics, the confirm=true requirement, and side effects like sharing access, notifying people, or incurring provider charges.

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

Conciseness3/5

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

The opening sentence is front-loaded and clear, but the permission block and scope details are verbose and mix prose with a code-fenced permission name. Reasonably sized but could be tightened.

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

Completeness4/5

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

Covers the mutation, its side effects, auth scopes, and the confirm requirement for a write tool with no output schema. Given 7 params and a nested payload object, this is largely complete, though it doesn't clarify the owner/account selection nuances beyond what the schema states.

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

Parameters3/5

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

Schema description coverage is 100% and the schema itself documents all parameters including nested payload properties, so the baseline is 3. The description adds the confirm=true constraint which reinforces what the schema says but doesn't extend it further.

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

Purpose4/5

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

States a specific verb+resource ('copies a media and its assets') and names the destination behavior (defaults to source folder). Doesn't explicitly differentiate from sibling bulk_copy_media, move_media, or swap_media, so an agent could confuse which copy variant to use.

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

Usage Guidelines3/5

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

Describes the operation context (copies to a destination folder) and includes permission requirements, but gives no explicit when-to-use vs when-not-to guidance or alternatives like bulk_copy_media or move_media. Usage is implied by the copy semantics rather than stated.

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

create_allowed_domainCreate Allowed DomainA

Destructive

Creates an allowed domain for the account.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`domain`	No	The domain name to add (www will be automatically stripped)
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare the write/destructive/non-idempotent/open-world profile, so the bar is lower, and the description adds real value on top: the exact token permission needed, the delegate_to_contact_permissions alternative, the confirm=true requirement, and side effects ('may share access, notify people or incur provider charges'). It omits what happens on duplicate domains or whether creation is reversible.

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

Conciseness4/5

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

Purpose is front-loaded in the first sentence, followed by a compact permission block and the confirm/side-effect notes. The fenced permission listing is boilerplate-heavy but each element is actionable for a mutation call.

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

Completeness4/5

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

For a destructive mutation with no output schema, the description supplies the missing operational context: auth requirements, the confirm gate, and potential side effects. The remaining gap is the absence of any statement about duplicate-domain behavior or error outcomes.

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

Parameters3/5

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 domain, account, confirm, payload and payload_file, including the 'www stripped' behavior. The description only echoes the confirm requirement and adds no format or semantics beyond the schema, so the baseline of 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Creates an allowed domain for the account'), which clearly distinguishes it from list_allowed_domains, get_allowed_domain and delete_allowed_domain by verb. It does not explicitly name those siblings, so it falls short of a 5.

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

Usage Guidelines3/5

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

The description covers authorization context (required token permission, delegate scope) and the confirm=true gate, which is useful pre-call guidance. However it never states when to use this tool versus the sibling list/get/delete allowed-domain tools, so usage routing is only implied.

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

create_brandCreate BrandA

Destructive

Creates a brand. A brand is a saved set of branding options (colors, fonts, logos, and layout) that can then be applied to media, folders, and channels. name is required; every other field is optional and left unset when omitted.

A new brand isn't applied to anything : it has no effect until you apply it to a resource with POST /brands/{brandId}/apply.

Accounts whose plan doesn't include multiple brands can only hold one brand.

Requires api token with one of the following permissions

All data

ParametersJSON Schema

Name	Required	Description
`name`	No	The brand's display name. Renaming the account-level default brand is ignored; its name is managed by Wistia.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`page_logo`	No	The brand logo used for pages. `url` must be a Wistia delivery URL — see the note on uploading below. On accounts without custom branding the player logo is ignored, but the page logo is always applied.
`player_logo`	No	The brand logo used for the player. `url` must be a Wistia delivery URL — see the note on uploading below. Ignored on accounts whose plan doesn't include custom branding.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`border_radius`	No	The border radius in pixels for rounded corners.
`primary_color`	No	The primary brand color, used for primary buttons and the player playbar. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples.
`contrast_icons`	No	Controls whether the player icon color is always white or uses an accessible contrast color when necessary.
`opaque_controls`	No	Controls the opacity of the video player control bar and big play button.
`body_font_family`	No	The brand font family for body text.
`button_font_family`	No	The brand font family for buttons.
`headline_font_family`	No	The brand font family for headlines.
`page_background_color`	No	The brand color used for page backgrounds. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples.

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already declare this is a non-readonly, destructive, non-idempotent, open-world write, and the description goes well beyond them: required api token permission ('All data'), delegate_to_contact scope behavior, the confirm=true requirement, side effects ('may share access, notify people or incur provider charges'), the plan-based brand limit, and the constraint that logo URLs must reference existing account images. This is unusually rich behavioral disclosure for a mutation.

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

Conciseness4/5

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

Front-loads the purpose, then the apply-later behavior, then plan/logo caveats, then the permission block. The auth paragraph is somewhat boilerplate-heavy, but every sentence carries operational meaning; nothing is redundant padding.

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

Completeness4/5

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

For a 15-parameter nested write tool with no output schema, the description covers creation scope, permission requirements, confirm gating, plan limits, and logo URL restrictions. It leaves the payload/payload_file/body-flag exclusivity to the schema and does not resolve the name-required ambiguity, so it is not fully complete but is adequate.

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

Parameters3/5

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 all 15 parameters, including nested logo objects and color formats — baseline 3 applies. The description adds only that `name` is required and everything else is left unset when omitted, and that claim conflicts with the schema's empty top-level and payload `required` arrays, which weakens rather than strengthens parameter clarity.

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

Purpose5/5

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

States a specific verb and resource ('Creates a brand') and then defines what a brand actually is (a saved set of branding options applicable to media, folders, channels). This clearly separates it from list_brands, get_brand, update_brand, delete_brand, and especially apply_brand, which the description explicitly says is a separate step.

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

Usage Guidelines4/5

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

Gives real routing context: a new brand has no effect until applied via POST /brands/{brandId}/apply, and plan-tier accounts are limited to one brand. It does not explicitly enumerate when-not-to-create or name competing alternatives, but the apply step and plan constraint are strong practical guidance.

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

create_bulk_actionsCreate Bulk ActionsA

Destructive

Submits a batch of up to 1000 create, update, delete, and move actions to be processed asynchronously. Returns a background job status whose Show endpoint reports aggregate progress and per-action results, including the hashed IDs of created records.

Supported resource types are media, folder, subfolder, channel, channel_episode, captions, and the ten customization_* concerns. A folder is a top-level folder (previously called a project); a subfolder is nested inside one and requires folder_id and name when created. A captions action operates on one caption track -- one media in one language.

Because caption actions carry SRT contents inline, they are the resource type most likely to reach the request body limit before the action cap. Purchasing captions is not available here -- it has its own endpoint.

A move action targets one media and accepts a destination folder_id and optional subfolder_id. Bulk moves can use different destinations and are not subject to the Move Media endpoint's 100-item limit or separate throttle.

Player customizations are addressed one concern at a time (customization_appearance, customization_playback, and so on), matching the Update Customizations endpoints; each accepts update only, takes the media's hashed ID as its id, and takes the same payload as its corresponding endpoint. There is no batch equivalent of the broad customize endpoint, so a batch always states which slice of the player it is changing.

A media update payload can also carry a custom_metadata object mapping field keys to the values to set (null clears a field; omitted fields are left untouched). Values are validated against each field's type exactly as the Set Custom Metadata Field Value endpoint validates them, and each write is recorded with its actor and source. Requires the custom metadata feature on the account; without it actions carrying custom_metadata fail individually.

Deleting a folder or subfolder also soft-deletes its media. An account owner or manager can restore that media from the trash until it purges. To keep the media when deleting a subfolder, use the Delete Subfolder endpoint; it moves the media to the folder's root level instead.

Each action in the batch is authorized and processed independently: failures (including authorization failures) are reported per action and do not prevent other actions from completing. Media creation is not supported -- uploads and URL imports have their own endpoints.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`job`	No	One change applied to many records, named by a parent (`scope`) or listed explicitly (`ids`). The server resolves the target and runs one action per record, so a folder of 400 media takes one job rather than 400 actions. A `scope` resolves to exactly what the matching list endpoint returns for that parent, including its defaults -- so a `folder` scope on `media` reaches media in that folder's subfolders, and includes archived media. A job resolves to at most 5000 records. Beyond that it is rejected rather than truncated, so a job never silently acts on part of the set you named -- narrow the scope, or send the records as an actions array. Cannot be used with `create`, which has no record to address, and is not available to external contacts.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`actions`	No	An array of actions to process, one per record. Maximum 1000 actions per request, and the request body must stay under 2 MB -- whichever limit is reached first. An oversized body is rejected with a `413` and no action in it runs. Each action specifies an operation (create, update, delete, or move), a resource type, and the relevant payload or record ID. Use `job` instead when every record takes the same payload.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds substantial context beyond them: asynchronous job processing, per-action independent authorization and failure reporting, hard limits (1000 actions, 2MB body, 5000 records), rejection rather than truncation, soft-delete and restore behavior, feature-gated custom metadata writes, and the confirm=true requirement.

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

Conciseness4/5

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

The description is front-loaded with the core purpose and is organized into clear thematic paragraphs. It is somewhat long and repeats some details that appear in the schema descriptions, but given the complexity of the nested job/actions model, the length is largely justified.

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

Completeness5/5

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

For a complex async bulk mutation tool with no output schema, the description is highly complete: it covers what the job returns, limits, per-action failure isolation, soft-delete consequences, feature requirements, permission context, and alternatives. An agent has everything needed to call it correctly.

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

Parameters4/5

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema, such as the inline SRT body-size nuance for caption actions and the fact that bulk moves bypass the Move Media endpoint's 100-item limit and throttle, helping the agent understand parameter implications without opening the schema.

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

Purpose5/5

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

The description states a specific verb+resource: 'Submits a batch of up to 1000 create, update, delete, and move actions to be processed asynchronously.' It also names the return mechanism, distinguishing it from siblings like bulk_tag, bulk_copy_media, and bulk_delete_subfolders.

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

Usage Guidelines5/5

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

It explicitly routes the agent to alternatives and exclusions: media creation is not supported ('uploads and URL imports have their own endpoints'), caption purchasing has its own endpoint, and to keep media when deleting a subfolder, use Delete Subfolder instead. It also distinguishes job vs actions usage implicitly through limits and supported operations.

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

create_bulk_purchaseCreate Bulk PurchaseA

Destructive

Submits either an actions array of up to 1000 orders or one job that can resolve to up to 5000 media. Orders are placed asynchronously. Returns a background job status whose Show endpoint reports aggregate progress and per-order results.

Orders in the batch can incur charges, so a saved credit card is required. Supported resource types are captions (Wistia-generated English captions), localization (a dubbed, language-specific version of a media), extended_audio_description, and text_translation (the media's transcript translated into another language, audio untouched). Each order's id is the hashed ID of the media to order for.

What an order costs depends on the account, not on this endpoint. Automated captions are included at no cost on plans that provide them and billed at the account's configured per-minute rate otherwise; human-reviewed captions bill per minute at the account's standard or rush rate; localizations bill per minute once the account's free-dub allowance is used up; text translations bill as an overage once the account's included translation minutes are used up. Check the account's plan and billing settings for its actual rates.

Orders are priced and placed individually: failures -- an ineligible media, a language that already has a localization, an account not entitled to buy -- are reported per order and do not stop the rest of the batch. Pricing and eligibility match the equivalent single-media endpoints exactly.

Use the Create Bulk Actions endpoint for create, update, and delete work; it does not accept purchase, and this endpoint accepts nothing else.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`job`	No	One order placed for many media, named by a parent (`scope`) or listed explicitly (`ids`), so ordering captions for a folder of 47 videos takes one job rather than 47 orders. A `scope` resolves to exactly what List Media returns for that parent, including media in the folder's subfolders and archived media, and to at most 5000 media -- beyond that the job is rejected rather than truncated. The job attempts one order for every media it resolves to. Ineligible media fail individually without placing an order; successful orders are metered and may incur charges according to the account's plan. Confirm the scope and potential cost with the customer before submitting. Not available to external contacts.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`actions`	No	The orders to place, one per media. Maximum 1000 per request, and the request body must stay under 2 MB -- whichever limit is reached first. An oversized body is rejected with a `413` and no order in it is placed. Every order is priced and placed independently: one failing (an ineligible media, an account without a saved card, a language that already has a localization) does not stop the rest of the batch. Use `job` instead to order for a whole folder, channel, or account.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations declare destructive=true, openWorld=true, idempotent=false, readOnly=false, but the description adds critical behavioral context beyond those flags: asynchronous execution, background job status via a Show endpoint, aggregate and per-order results, per-order independent pricing/placement, individual failure behavior, billing mechanics per resource type, and the saved-card requirement. It also notes that a 5000-media scope is rejected rather than truncated, which is operationally important.

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

Conciseness4/5

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

The description is front-loaded with the core abstraction (actions vs job, async, background job result) and then layers billing and error semantics. It is longer than ideal and the billing paragraph is dense, but each paragraph carries operational information an agent needs before invoking a paid, destructive batch endpoint.

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

Completeness5/5

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

Given this is a destructive, paid, open-world batch mutation with no output schema, the description covers what an agent needs: async semantics and status retrieval, per-order failure isolation, billing variability, saved-card requirement, scope size limits, and sibling routing. Almost nothing required 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.

Parameters3/5

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

Schema coverage is 100% and the nested schemas already document job/actions/scope/ids/payload extensively, including per-resource payload options. The description reinforces the actions-vs-job split and the per-order pricing/eligibility model, but that overlaps with what the schema already states, so it adds marginal value over structured data.

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

Purpose5/5

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

The description states a specific verb (submits/places orders) and resource (bulk purchase of captions/localization/extended_audio_description/text_translation), and explicitly distinguishes itself from the sibling create_bulk_actions by noting that this endpoint accepts only 'purchase' while the other does not. An agent can tell it apart from purchase_captions, order_extended_audio_description, and create_localization because it operates on batches.

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

Usage Guidelines5/5

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

Explicitly tells when to use `actions` (up to 1000 orders named by id) vs `job` (one scope resolving to up to 5000 media), and names the alternative sibling (Create Bulk Actions) for non-purchase work. It also states prerequisites (saved credit card, confirm=true) and per-order failure semantics, which is strong routing guidance.

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

create_captionsCreate CaptionsA

Destructive

Adds captions to a specified media by providing an SRT file or its contents directly.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`language`	No	An optional parameter that denotes which language this file represents. Should conform to ISO-639–2. If left unspecified, the language code will be detected automatically.
`caption_file`	No	Either an attached SRT file or a string parameter with the contents of an SRT file.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	The hashed ID of the media for which captions are to be added.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and non-idempotency. The description adds real value beyond that: the exact permission scope, the delegation-token caveat, the confirm=true gate, and side effects (sharing access, notifying people, provider charges). It stops short of describing what happens to pre-existing captions for the same language.

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

Conciseness4/5

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

The purpose sentence is front-loaded and the requirements are separated into scannable blocks. The permission section is long but carries actionable content rather than filler.

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

Completeness4/5

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

For a non-idempotent mutation with 7 parameters and no output schema, the description covers auth, the confirm gate, and side-effect exposure well. The main omission is the effect on existing captions for the same media/language and any response expectation.

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

Parameters3/5

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 media_hashed_id, caption_file, language, payload, and payload_file. The description restates only the SRT input form and adds no format or precedence detail (e.g., payload vs. body flags, caption_file string vs. file upload) beyond what the schema provides.

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

Purpose4/5

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

The first sentence gives a specific verb (adds), resource (captions), and target (a specified media), plus the input form (SRT file or its contents). It is clear, though it does not explicitly differentiate from sibling caption mutators like update_captions or edit_captions_text.

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

Usage Guidelines3/5

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

Usage context is implied by the permission and confirm=true requirements, which tell the agent this is a gated write. However, it never states when to choose this tool over update_captions, edit_captions_text, or purchase_captions, all of which live in the same sibling cluster.

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

create_channelCreate ChannelB

Destructive

Creates a channel. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`name`	No	The display name for the channel
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`custom_url`	No	Use if embedding the channel on your own site. The custom URL ensures links always direct to your page and not Wistia's.
`description`	No	The channel's description.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`podcast_enabled`	No	Whether podcasting is enabled for this channel.
`podcast_settings`	No	Podcast specific settings for a channel. These settings only take effect if podcasting is enabled for the channel. These values appear in the channel's publicly accessible podcast RSS feed.
`auto_publish_enabled`	No	Whether the episodes are automatically published when added to the channel. Cannot be enabled if podcasting is on.

TDQS

B3.2/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, but the description adds real context beyond them: the confirm=true gate and side effects (sharing access, notifying people, incurring charges) that are nowhere in the schema. This is the strongest part of the definition.

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

Conciseness4/5

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

Two short sentences with no padding, and the precondition is front-loaded before the side-effect warning. Nothing here is expendable, though the brevity comes at the cost of coverage.

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

Completeness4/5

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

For a 10-parameter tool with nested objects, the annotations carry the safety profile and the schema carries the parameter detail, so the description is adequate. It omits the mutually exclusive input modes (flags vs payload vs payload_file), which is the one gap an agent could stumble on.

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

Parameters3/5

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 all 10 parameters in detail. The description only touches the confirm parameter and adds no format or semantics beyond the schema, so the baseline 3 applies.

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

Purpose3/5

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

"Creates a channel" states a specific verb and resource, but it is essentially a restatement of the tool name and title, adding no scope or distinguishing detail. With siblings like create_brand and create_channel_episode present, nothing here separates this tool from the rest.

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

Usage Guidelines2/5

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

There is no when-to-use guidance and no routing to or away from alternatives such as create_channel_episode or update_channel. The confirm requirement is a hard precondition rather than usage context, so an agent is left to infer when this tool applies.

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

create_channel_collaboratorCreate Channel CollaboratorA

Destructive

Invites a collaborator to a channel by specifying their email address and role. Creates a new contact if one doesn't exist with that email.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`role`	No	The role to grant the collaborator.
`email`	No	Email address of the contact to invite. Creates a new contact if one doesn't exist.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`channel_hashed_id`	Yes	Hashed ID of the channel

TDQS

A3.7/5.0

Behavior4/5

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

Beyond the annotations (which already flag a destructive, non-idempotent open-world mutation), the description discloses meaningful behavioral traits: it creates a contact as a side effect when the email doesn't exist, requires confirm=true before the mutation, and warns that it may share access, notify people, or incur provider charges. These are non-obvious consequences the annotations do not convey.

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

Conciseness4/5

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

The purpose is front-loaded in the first sentence, followed by a clearly separated requirements block. The permission boilerplate is lengthy but carries genuinely required information, so it earns most of its space.

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

Completeness4/5

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

For a mutating tool with no output schema, the definition covers the essentials: permissions, the confirm gate, side effects on contacts, and cost/notification risk. The only real gap is the absence of alternatives or a stated return value, the latter being unimportant without an output schema.

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

Parameters3/5

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 every field including the role enum, confirm flag, and payload structure. The description adds the email-creates-contact nuance, which the schema also states, so there is little added meaning beyond the structured fields – baseline 3.

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

Purpose4/5

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

The description states a specific verb and resource – 'Invites a collaborator to a channel by specifying their email address and role' – which is unambiguous about what the tool does. It does not explicitly name or distinguish itself from close siblings like create_webinar_collaborator or invite_contacts, so it stops short of a 5.

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

Usage Guidelines3/5

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

It supplies real prerequisites (required token permissions, confirm=true) that tell the agent the conditions under which the call will succeed. However, it gives no guidance on when to prefer this tool over create_webinar_collaborator or invite_contacts, leaving the choice to inference.

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

create_channel_episodeCreate Channel EpisodeA

Destructive

Creates a new channel episode in a channel.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`title`	No	The episode's title. If not provided, the channel episode uses the title of the media used to create it.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`summary`	No	A short summary of the episode that is displayed when space is limited.
`media_id`	No	The alphanumeric hashed ID of the media to be added as a channel episode.
`publish_at`	No	The date and time when the episode should be published in UTC timezone. Required when publish_status is 'scheduled'. Must be a valid ISO8601 timestamp in UTC (ending with 'Z'). Can only be provided when publish_status is 'scheduled.'
`description`	No	The episode's description or episode notes.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`publish_status`	No	The status of whether or not the episode has been published to your channel.
`podcast_settings`	No	Podcast specific settings for a channel episode. These settings only take effect if podcasting is enabled for the channel.
`channel_hashed_id`	Yes	The hashed ID of the channel to add the episode to.

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already declare openWorldHint=true, destructiveHint=true, idempotentHint=false, but the description adds genuine context beyond them: required token permission scopes, the delegation scope, the confirm=true requirement for the mutation, and side effects ('May share access, notify people or incur provider charges'). This is meaningful 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.

Conciseness4/5

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

The purpose is front-loaded in the first sentence, followed by structured permission and mutation requirements. The permission markdown block is somewhat heavy, but it is relevant given the authentication complexity and earns its space.

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

Completeness4/5

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

For a destructive mutation with a nested payload and no output schema, the description covers permissions, the confirm requirement, and side-effect warnings well. It does not describe the post-creation return behavior, but with no output schema this is a minor gap.

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

Parameters3/5

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 all 12 parameters including the nested payload and podcast_settings. The description adds no parameter-level detail beyond mentioning confirm=true, 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.

Purpose4/5

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

The description opens with a specific verb+resource: 'Creates a new channel episode in a channel.' This clearly states what the tool does and is not a tautology of the title. However, it offers no differentiation from related siblings such as create_channel, update_channel_episode, or publish_channel_episode.

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

Usage Guidelines2/5

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

There is no explicit when-to-use guidance or comparison to alternatives like create_channel, publish_channel_episode, or update_channel_episode. The confirm=true and permission notes describe how to invoke but not when this tool is the right choice over its siblings.

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

create_customizationsCreate CustomizationsA

Destructive

Set customizations for a video. Replaces the customizations explicitly set for this video.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`seo`	No	If set to true, the video’s metadata will be injected into the page’s markup for SEO.
`time`	No	Sets the starting time of the video.
`email`	No	Associate a specific email address with this video’s viewing sessions.
`muted`	No	If set to true, the video will start in a muted state.
`wmode`	No	If set to transparent, the background behind the player will be transparent instead of black.
`plugin`	No
`volume`	No	Sets the volume of the video.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`playbar`	No	If set to true, the playbar will be available. If set to false, it will be hidden.
`preload`	No	Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.
`autoPlay`	No	If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers.
`media_id`	Yes	The hashed ID of the video.
`stillUrl`	No	Overrides the thumbnail image that appears before the video plays.
`resumable`	No	Determines if the video should resume from where the viewer left off. Options are true, false, and auto.
`videoFoam`	No	When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height.
`doNotTrack`	No	If set to true, data for each viewing session will not be tracked.
`keyMoments`	No	If set to false, the key moments feature will be disabled.
`playButton`	No	Indicates if the play button is visible.
`qualityMax`	No	Specifies the maximum quality the video will play at.
`qualityMin`	No	Specifies the minimum quality the video will play at.
`fitStrategy`	No	Resizes the video when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none.
`playerColor`	No	Changes the base color of the player. Expects a hexadecimal rgb string.
`playsinline`	No	If set to false, videos will play within the native mobile player.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`playlistLoop`	No	If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.
`playlistLinks`	No	Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.
`volumeControl`	No	When set to true, a volume control is available over the video.
`fakeFullscreen`	No	If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.
`qualityControl`	No	If set to false, the video quality selector in the settings menu will be hidden.
`silentAutoPlay`	No	Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are true, allow, and false.
`settingsControl`	No	If set to true, the settings control will be available.
`smallPlayButton`	No
`endVideoBehavior`	No	Determines what happens when the video ends. Options are default (stays on the last frame), reset (shows thumbnail and controls), and loop (plays again from the start).
`fullscreenButton`	No	If set to true, the fullscreen button will be available as a video control.
`thumbnailAltText`	No	Sets the Thumbnail Alt Text for the media.
`playPauseNotifier`	No	If set to false, animations for the Pause and Play symbols will be removed.
`playbackRateControl`	No	If set to false, the playback speed controls in the settings menu will be hidden.
`controlsVisibleOnLoad`	No	If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.
`playSuspendedOffScreen`	No	If set to false for a muted autoplay video, the video won't pause when out of view.
`copyLinkAndThumbnailEnabled`	No	If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.
`fullscreenOnRotateToLandscape`	No	If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds real value beyond them: it discloses the replace-not-merge semantics for explicitly-set customizations, the exact permission scopes required, and the side effects (may share access, notify people, incur provider charges). It stops short of describing what happens to unmentioned customizations.

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

Conciseness4/5

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

Front-loads the core action and its replace semantics in one sentence, then separates auth preconditions. The fenced code block for permissions is slightly heavy for a single scope but not wasteful overall.

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

Completeness4/5

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

For a 43-parameter mutation with no output schema, the description covers the important behavioral context: auth, confirm requirement, destructive replace semantics, and side effects. The main omission is the relationship to update_customizations and whether omitted customizations are preserved.

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

Parameters3/5

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

Schema description coverage is 95%, so nearly every one of the 43 parameters is documented in the schema itself. The description adds no parameter-level meaning (e.g., how the flat body flags relate to payload/payload_file), 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.

Purpose4/5

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

States a specific verb and resource ('Set customizations for a video') and adds a meaningful scope qualifier ('Replaces the customizations explicitly set for this video'). It does not, however, distinguish itself from the sibling update_customizations, leaving ambiguity about which mutation to pick.

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

Usage Guidelines3/5

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

Provides precondition guidance (required token permission, confirm=true for the mutation), which is useful. But it gives no explicit when-to-use-vs-alternatives guidance relative to update_customizations or the granular update_*_customizations siblings, so the agent must infer intent.

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

create_expiring_access_tokenCreate Expiring Access TokenA

Destructive

🚫 Alert
This API is still under development and can change at any time.

This endpoint is for creating expiring access tokens which can be used for some iframe embeds and, when granted the all:delegate_to_contact_permissions scope, for REST API requests authorized by the token's authorizations.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`secret_result_file`	Yes	New private local result file, saved with exclusive creation and mode 0600. Parent must be owner-only on POSIX. No credentials are returned to the AI client.
`expiring_access_token`	No

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds meaningful context beyond them: the under-development warning, the exact permission requirement ("Read, update & delete anything"), the delegation semantics of scoped tokens, and the note that the call may share access, notify people or incur provider charges. This is strong disclosure; only return-format behavior is left unaddressed.

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

Conciseness3/5

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

The development alert is front-loaded, which is good, but the description is verbose and repeats scope/permission details that already live in the schema, so not every sentence earns its place. Structure is navigable via headings but the payload is heavier than necessary.

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

Completeness4/5

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

For a mutation tool with nested objects and no output schema, the description covers the permission model, the confirm requirement, the delegated-authorization behavior and the maturity caveat. The remaining gap — what the call returns and how the secret result file relates to it — is partly addressed by the schema, leaving it largely complete.

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

Parameters3/5

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

Schema coverage is 83%, so the schema documents the critical fields (scopes, expires_at, authorizations, confirm, secret_result_file). The description restates the `confirm=true` requirement and the scope concept but adds little parameter meaning beyond what the schema already provides, so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource ("creating expiring access tokens") and names the concrete use cases: iframe embeds and REST API requests authorized by the token's authorizations. An agent can distinguish this token-minting operation from the sibling read tool `get_current_token` 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.

Usage Guidelines4/5

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

Gives clear context for when the token is applicable (iframe embeds, REST API with the `all:delegate_to_contact_permissions` scope) and states the required permissions and the `confirm=true` prerequisite. It stops short of explicit when-not-to-use guidance or naming a sibling alternative, but for a niche token-creation endpoint the positive conditions are well covered.

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

create_folderCreate FolderA

Destructive

Creates a new folder (previously called project). If the folder is created successfully the Location HTTP header will point to the new folder.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an account authorization granting the create-folders permission can also be used. The folder's creator is the contact behind the token (the account owner for a token minted from an account-level token); adminEmail selects the folder's administrator (defaults to the account owner). personalLibrary creates the folder inside the My Library of the contact behind the token. The new folder is not covered by the token that created it, so follow-up requests need a token whose authorizations name the returned hashed id. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`name`	No	The name of the folder you want to create.
`public`	No	A flag indicating whether or not the folder is enabled for public access.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`adminEmail`	No	The email address of the person you want to set as the owner of this folder. Defaults to the Wistia Account Owner.
`description`	No	The folder’s description.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`personalLibrary`	No	When true, creates the folder inside the requesting user's personal "My Library" (owned by them) instead of a shared account folder.
`anonymousCanUpload`	No	Whether anonymous users can upload media to the folder.
`anonymousCanDownload`	No	Whether anonymous users can download media from the folder.

TDQS

A4.2/5.0

Behavior5/5

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

Far exceeds the annotations (destructiveHint, openWorldHint, idempotentHint). It discloses the Location header on success, the confirm=true requirement, that the creating token does not cover the new folder so follow-ups need a token naming the hashed id, and that the call may share access, notify people or incur provider charges. This is exactly the behavioral context an agent needs for a mutation.

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

Conciseness3/5

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

The core purpose is front-loaded in one sentence, but the remainder is a dense, lengthy auth block with idiosyncratic formatting that is hard to scan. A fair amount of it is necessary for a tool with this many token variants, but the structure is heavy relative to the operation being performed.

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

Completeness4/5

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 success signal (Location HTTP header pointing to the new folder) and covers the confirm requirement and follow-up token constraint. It is close to complete, though it does not describe error behavior or the relationship to subfolder creation.

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

Parameters4/5

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 adds real meaning: what determines the folder's creator, how adminEmail selects the administrator and defaults to the account owner, and what personalLibrary does to ownership. It clarifies the semantics behind parameters rather than repeating the schema.

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

Purpose5/5

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

Specific verb+resource with a useful disambiguation note that folders were previously called projects, which helps separate this from create_subfolder and create_channel in a crowded sibling set. An agent knows exactly what is created.

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

Usage Guidelines3/5

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

The description goes deep on auth prerequisites (which token scopes and permissions are required, how delegated tokens behave), which is genuinely useful gating context, but it never states when to prefer this tool over siblings like create_subfolder or create_channel. Usage is implied through the permission details rather than contrasted with alternatives.

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

create_folder_sharingCreate Folder SharingA

Destructive

Creates a new sharing object for a folder by specifying the email of the person to share with and other optional parameters.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`sharing`	No
`folder_id`	Yes	Hashed ID of the folder to be shared
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

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

Adds meaningful context beyond the annotations: it discloses the required token scope, the delegate_to_contact_permissions fallback, the mandatory confirm=true flag, and warns that the call 'may share access, notify people or incur provider charges.' That last point is a valuable non-obvious side effect that the destructiveHint annotation alone does not convey.

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

Conciseness4/5

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

The opening sentence front-loads the core action and is efficient. The permissions block is longer than ideal but each line carries operative constraint information (scope, delegation, confirm), so nothing is clearly wasted.

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

Completeness4/5

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

For a mutation tool with no output schema and a nested schema, the description covers the authorization model, the confirm gate, and side-effect risk. It omits any note about the payload/payload_file vs body-flags mutual exclusion, but the schema itself documents that constraint.

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

Parameters3/5

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

Schema description coverage is high (83%), so the schema already documents confirm, account, folder_id, and the nested sharing fields including defaults. The description only gestures at 'email ... and other optional parameters,' adding little beyond the structured schema; baseline 3 is appropriate.

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

Purpose4/5

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

States a specific verb and resource ('Creates a new sharing object for a folder') and identifies the key input (recipient email). It is distinguishable from update_folder_sharing/delete_folder_sharing by the 'creates new' framing, though it never explicitly names those siblings.

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

Usage Guidelines3/5

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

Provides context on required permissions and the confirm=true prerequisite, which are real usage conditions. However, it gives no guidance on when to use this versus update_folder_sharing or the other sharing siblings, so the alternative-selection question 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.

create_localizationCreate LocalizationA

Destructive

Creates a new localization.

Creating a localization can incur a charge on your account. Accounts get a free-dub allowance; once it is used up, dubs bill per minute at the account's configured rate.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`auto_enable`	No	Whether to automatically enable the localization.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	The hashed ID of the media to create a localization for.
`output_language`	No	The language to localize the media to as a 3-character IETF language code.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already mark this destructive, non-idempotent and open-world, so the bar is lower, yet the description still adds substantive context: the free-dub allowance and per-minute billing model, the exact token scope required, and the delegated-permission path. It stops short of describing whether the dub is processed asynchronously and how completion is tracked.

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

Conciseness4/5

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

Front-loads the action sentence, then layers cost and authorization details in short paragraphs. The permission-scope block is boilerplate but consequential, and nothing is redundant enough to be cut.

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

Completeness3/5

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

For a charged, confirm-gated mutation with a nested payload and no output schema, the description covers cost and auth well but says nothing about the outcome the agent should expect (returned localization object, processing time, or whether get_job_status is needed). Adequate but with a noticeable gap.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter (media_hashed_id, output_language, auto_enable, payload, payload_file, account, confirm) is already documented in the schema. The description adds no format, default, or mutual-exclusion detail beyond what structured fields provide, which is the baseline for this case.

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

Purpose4/5

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

The opening sentence gives a specific verb and resource ("Creates a new localization"), which is unambiguous. It does not, however, differentiate itself from nearby siblings such as translate_media, get_localization or list_localizations, so the agent must infer which localization-related tool applies.

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

Usage Guidelines3/5

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

The description supplies real prerequisites (required permission scope, confirm=true, billing implications) but never states when to reach for this tool instead of translate_media or the other media-mutation siblings. Usage is implied rather than routed.

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

create_media_from_trimsCreate Media from TrimsA

Destructive

Creates a new media that trims off parts of an existing media.

By default, the trims parameter specifies time ranges to remove from the media. When keep_trims is set to true, the trims parameter instead specifies time ranges to keep in the media.

NOTE: currently this endpoint only supports trimming video files.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`trims`	No	An array of strings matching the format of HH:MM:SS.mmm-HH:MM:SS.mmm where HH is hours, MM is minutes, SS is seconds and mmm is milliseconds. When keep_trims is false (default), the ranges specify parts of the media to remove. When keep_trims is true, the ranges specify parts of the media to keep.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`keep_trims`	No	When set to true, the trims parameter is treated as ranges to keep rather than ranges to remove. Defaults to false.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	The hashed ID of the media.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare destructive=true, idempotent=false and openWorld=true, and the description adds meaningful context beyond them: the required token permission, the confirm=true requirement, and the side-effect warning about sharing access, notifying people or incurring provider charges. The only gap is the video-only limitation is stated but the fate of the original media after trimming is not.

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

Conciseness4/5

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

The core behavior and the keep_trims inversion are front-loaded in the first two paragraphs, which is the right ordering. The trailing permission boilerplate is long but is standard auth context rather than filler.

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

Completeness4/5

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

For a destructive, non-idempotent, open-world mutation with 7 parameters and no output schema, the description covers auth requirements, the confirm gate, side effects, and the video-only restriction. It is nearly complete; only the post-trim state of the source media is unaddressed.

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

Parameters3/5

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 trims, keep_trims, confirm, account, and payload in detail. The description restates the trims/keep_trims relationship without adding format or edge-case detail (e.g., overlapping or out-of-range ranges) beyond the schema.

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

Purpose5/5

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

States a specific verb+resource ('Creates a new media that trims off parts of an existing media') and explains the trim semantics, which cleanly separates it from sibling mutations like copy_media, upload_media, and update_media. An agent can identify the operation 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.

Usage Guidelines3/5

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

The description implies when the tool applies (trimming video) and explains the keep_trims switch, but never states when to choose this over alternatives such as copy_media or upload_media, nor any prerequisites like media readiness. Usage is inferable but not spelled out.

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

create_review_bundleCreate Review BundleA

Destructive

Creates a review bundle from a set of existing media, producing a single link that can be shared for review. The media to include are specified by their hashed IDs and must already belong to the account. The media can come from any folder. Review Bundles are limited to 25 media.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`name`	No	The bundle display name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`allow_downloads`	No	Whether the videos in the bundle can be downloaded.
`media_hashed_ids`	No	The hashed ids of the media to include in the bundle. Limited to 25 media.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already flag destructive/openWorld/non-idempotent, so the description goes beyond them usefully: it discloses the required permission scopes, the delegation authorization behavior, the confirm=true requirement, and that it 'may share access, notify people or incur provider charges.' That is meaningful side-effect and auth context. It stops short of describing what happens on partial failure or duplicate bundles.

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

Conciseness4/5

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

Purpose and constraints are front-loaded in a tight opening paragraph, followed by limits and then the permission/confirm block. Most sentences earn their place; the multi-line permissions boilerplate is somewhat lengthy but is genuinely decision-relevant for a mutating tool.

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

Completeness5/5

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

For a complex nested-schema mutation with no output schema, the description covers purpose, input constraints, permission/scope requirements, the confirm gate, and side effects. It even hints at the return artifact (a shareable link), so an agent has everything needed to call it safely and correctly.

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

Parameters4/5

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 real constraints not in the schema: media 'must already belong to the account' and 'can come from any folder.' The 25-media cap and name/media_hashed_ids fields are largely restated from the schema, so it nudges above baseline rather than being fully additive.

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

Purpose4/5

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

States a specific verb+resource ('Creates a review bundle') plus the output ('a single link that can be shared for review'), so the agent knows exactly what it produces. The scope constraints (existing media, hashed IDs, 25 limit) sharpen it further. It does not, however, name the sibling tools (list_review_bundles / delete_review_bundle) to disambiguate the CRUD role, which keeps it from a 5.

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

Usage Guidelines3/5

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

Gives prerequisites ('media ... must already belong to the account', 'can come from any folder') and a hard limit (25 media), which implies when it is applicable. But it never states when to prefer this over alternatives such as create_share_link or the other review-bundle tools; usage is only implied.

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

create_subfolderCreate SubfolderA

Destructive

Creates a new subfolder within a folder. The subfolder will be created with the next available position.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`name`	No	The display name of the subfolder.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	Yes	The hashed ID of the folder
`description`	No	A description for the subfolder.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real context the annotations do not: the exact permission scopes needed, the delegation/expiring-token authorization model, the position-assignment behavior, and that confirm=true is required for the mutation.

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

Conciseness3/5

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

The position behavior is front-loaded correctly, but the long permission section with a duplicated block of OAuth scope prose is dense and repetitive. The final sentence about sharing, notifications and charges is useful but tacked on after the permission detail rather than integrated.

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

Completeness4/5

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

For a mutation tool with no output schema and a nested payload object, the definition covers the key gaps: required permission, confirm requirement, and position behavior. It would be stronger if it clarified how payload and payload_file interact with the body flags, but otherwise the agent has what it needs to call it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter including confirm, payload and payload_file is already documented. The description adds only the confirm=true requirement, which is also in the schema, so it does not materially extend parameter meaning beyond the structured fields.

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

Purpose5/5

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

The definition opens with a specific verb and resource: 'Creates a new subfolder within a folder,' and adds the scoping behavior that the subfolder receives 'the next available position.' An agent can tell this apart from create_folder, update_subfolder and delete_subfolder without opening the schemas.

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

Usage Guidelines2/5

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

There is no explicit when-to-use or when-not-to-use guidance. The description never says to prefer create_folder for top-level folders or which sibling to use for moving an existing subfolder, so the agent must infer the difference from names alone.

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

create_tagsCreate TagsA

Destructive

Creates a new tag.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`name`	No	The tag name. Stored lowercased with whitespace squished, 50 characters max, and must not already exist on the account.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare non-read-only, non-idempotent, open-world, destructive, so the safety bar is covered. The description adds real value beyond them: the exact permission scope required, the delegate-token authorization model, and an explicit side-effect warning ("May share access, notify people or incur provider charges"). It does not disclose the return shape, but the added authorization and side-effect context earns a 4.

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

Conciseness4/5

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

Purpose is front-loaded in the first line, followed by compact permission and safety notes. The markdown heading embedded mid-description is slightly awkward, but there is no filler sentence.

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

Completeness4/5

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

With 5 parameters including a nested payload object and no output schema, the description supplies the permission model, the confirm gate, and the side-effect caveat an agent needs before calling. Only the response/return behavior for a newly created tag is left unstated, a modest gap.

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

Parameters3/5

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 name, account, confirm, payload, and payload_file in detail. The description only restates the confirm=true requirement, adding nothing the schema doesn't already say. Baseline 3 applies.

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

Purpose4/5

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

Opens with a specific verb+resource: "Creates a new tag." That is unambiguous and distinguishable from siblings like list_tags, delete_tag, or bulk_tag. However, it does no explicit sibling differentiation, so it stops short of a 5.

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

Usage Guidelines3/5

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

The description states necessary prerequisites (required permission scope, delegate-token behavior, confirm=true for the mutation), which is genuine usage guidance. It never says when to reach for this tool versus bulk_tag or how tagging interacts with list_tags, so it is implied rather than explicit.

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

create_webinarCreate WebinarA

Destructive

Creates a new webinar.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`title`	No	The title of the webinar
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	Hashed ID of the folder to place this webinar in. Defaults to the account's default webinar folder if not provided.
`time_zone`	No	The IANA time zone identifier the webinar is scheduled in.
`description`	No	The description of the webinar
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`scheduled_for`	No	The scheduled start time as a UTC formatted ISO 8601 string (offset `Z` or `+00:00`).
`event_duration`	No	Duration of the event in minutes (minimum 15)

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already mark this as a non-read-only, non-idempotent, potentially destructive open-world mutation. The description meaningfully adds upstream context the annotations cannot convey: the required token scope, the delegate_to_contact_permissions path, the mandatory confirm=true, and warnings that the call may share access, notify people, or incur provider charges. It does not describe return shape or rate limits, keeping it below 5.

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

Conciseness4/5

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

Purpose is front-loaded in the first sentence, and the permission/confirm/side-effect notes follow in a compact block. The code-fenced permission list is slightly heavier than necessary, but every sentence carries information.

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

Completeness4/5

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

For a 10-parameter tool with nested objects and no output schema, the description covers purpose, authorization, mutation confirmation, and external side effects, which is most of what an agent needs. It leaves return-value expectations unaddressed, but the schema-rich parameters carry the rest.

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

Parameters3/5

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

Schema description coverage is 100% and the nested payload repeats the top-level fields with their own descriptions, so the schema fully documents parameters like scheduled_for, time_zone, and event_duration. The description adds no syntax or format detail beyond that, 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.

Purpose4/5

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

States a specific verb (Creates) and resource (webinar), so an agent immediately knows the outcome. It does not, however, differentiate this tool from the other create_* tools in the cluster (create_channel, create_brand, create_folder), so it stops short of a 5.

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

Usage Guidelines2/5

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

The description states preconditions (token permission, confirm=true) but gives no guidance on when to choose this tool over alternatives such as create_channel_episode or the update/webinar siblings. There are no explicit when-to-use or when-not-to-use statements.

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

create_webinar_collaboratorCreate Webinar CollaboratorA

Destructive

Invites a collaborator (producer) to a webinar by specifying their email address. Creates a new contact if one doesn't exist with that email. Note that viewers cannot be webinar collaborators.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`email`	No	Email address of the contact to invite. Creates a new contact if one doesn't exist. Note that viewers cannot be webinar collaborators.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`webinar_id`	Yes	Hashed ID of the webinar
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4/5.0

Behavior4/5

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

Annotations already flag destructive/openWorld/non-idempotent, but the description adds meaningful context beyond them: new contacts are created on the fly, a specific permission scope is required, confirm=true is mandatory, and the call may share access, notify people, or incur charges.

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

Conciseness3/5

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

Purpose is front-loaded in the first sentence, but the embedded multi-line permission code block is bulky and adds significant length relative to the core instruction. The essential routing and confirmation logic could be tighter.

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

Completeness4/5

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

For a mutation tool with no output schema and full annotation coverage, the description supplies the prerequisites (permissions, confirm) and side effects (contact creation, notifications, charges) an agent needs. Return format is undocumented but not critical for this write.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents email, confirm, account, payload, and payload_file. The description largely restates the email behavior already in the schema; it adds only the token-permission context, not param syntax. Baseline 3 is appropriate.

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

Purpose5/5

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

States a specific verb (invites), resource (collaborator/producer), and scope (to a webinar via email). Clearly distinguishes the write from siblings like list_webinar_collaborators and delete_webinar_collaborator.

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

Usage Guidelines4/5

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

Gives an explicit exclusion ('viewers cannot be webinar collaborators') and the confirm=true requirement, which tells the agent when this call is valid. It stops short of naming an alternative tool, but the context is clear.

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

create_webinar_registrationCreate Webinar RegistrationA

Destructive

This endpoint generates a unique visitor key and returns a personalized webinar URL for the registrant.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`email`	No	Email address of the registrant
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`last_name`	No	Last name of the registrant
`first_name`	No	First name of the registrant
`webinar_id`	Yes	Hashed ID of the webinar
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4/5.0

Behavior5/5

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

Even though annotations already flag this as a destructive, non-idempotent, open-world mutation, the description adds substantial context: it explains the return values (unique visitor key and personalized webinar URL), the required API permissions, the need for confirm=true, and potential side effects such as sharing access, notifying people, or incurring provider charges.

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

Conciseness4/5

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

The description is front-loaded with the core action and return value, followed by permission and confirm details. It is well-structured, though the permission callout block is slightly verbose and could be tightened without losing meaning.

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

Completeness5/5

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

For a mutation tool with 8 parameters, nested objects, no output schema, and rich annotations, the description covers the missing pieces: return value shape, authorization requirements, confirmation requirement, and side effects. An agent has everything needed to invoke it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so parameter semantics are fully documented in the schema. The description only repeats the registrant fields (email, first name, last name) and adds no extra syntax, format, or constraint information beyond what the schema already provides.

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

Purpose5/5

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

The description states a specific verb and resource: 'Register a person for a webinar'. It is clearly distinct from siblings like create_webinar, list_webinar_registrations, and update_webinar, leaving no ambiguity about what the tool does.

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

Usage Guidelines2/5

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

The description explains what to provide (email, first name, last name) but gives no explicit guidance on when to use this tool versus alternatives, nor any when-not conditions or prerequisites beyond the permission and confirm requirements that appear later.

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

delete_allowed_domainDelete Allowed DomainA

Destructive

Deletes an allowed domain from the account.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`domain`	Yes	The domain name to delete
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered; the description adds real beyond-annotation detail: the exact permission scopes required, delegated-token authorization semantics, and the confirm=true gate. The trailing 'May share access, notify people or incur provider charges' is generic boilerplate with less value.

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

Conciseness3/5

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

The purpose is front-loaded in one clean sentence, but the large fenced permission block and the generic trailing caveat inflate the text without adding tool-specific value.

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

Completeness4/5

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

For a destructive single-resource delete with full annotation coverage and no output schema, the description supplies the key missing operational facts (permissions, confirmation gate). Nothing critical is missing, though it could clarify where a deleted domain disappears from (e.g., the allowed-domains list).

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

Parameters3/5

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

Schema description coverage is 100%, so baseline is 3. The description restates the confirm=true requirement but adds no syntax, format, or edge-case meaning for domain/account beyond what the schema already documents.

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

Purpose4/5

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

The description states a specific verb and resource: 'Deletes an allowed domain from the account.' It is easily distinguished from siblings like create_allowed_domain, get_allowed_domain, and list_allowed_domains by the delete verb, though it never names them explicitly.

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

Usage Guidelines3/5

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

Usage context is implied and constrained by prerequisites: the required token permissions and the 'Requires confirm=true for the requested mutation' rule tell the agent when the call is permissible. However, there is no explicit when-to-use/when-not guidance or routing to alternative siblings.

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

delete_brandDelete BrandA

Destructive

Deletes a brand. Anything the brand was applied to falls back to the account-level default brand, unless sync_to_customizations is set, in which case the brand's values are written into each item's own customizations first so they keep their current look.

The account-level default brand (is_default: true) can't be deleted.

Requires api token with one of the following permissions

All data

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`brand_id`	Yes	The id of the brand
`sync_to_customizations`	No	When true, the brand's values are baked into the customizations of everything it was applied to before it is deleted, so those items keep their current appearance. Defaults to false.

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false), which only flag the operation as a non-idempotent write. The description discloses the actual fallout: applied items revert to the account default brand, or with sync_to_customizations are baked into each item's customizations first, plus token/permission and confirm requirements.

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

Conciseness4/5

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

Front-loads the core deletion behavior and its side effect in the first sentence, then places the constraint and permission requirements afterward. The permissions/confirm block is somewhat boilerplate-heavy, keeping it from a 5.

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

Completeness5/5

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

For a destructive mutation with no output schema, the description covers behavior, irreversible consequences, the default-brand exclusion, authorization scope and the confirm requirement. Nothing an agent needs before invoking it is missing.

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

Parameters4/5

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 real meaning by framing sync_to_customizations as the branch that decides the fate of the brand's applied items, and by documenting the built-in block on deleting the default brand. It stops short of 5 because the per-parameter text largely duplicates the schema.

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

Purpose5/5

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

States a specific verb and resource ('Deletes a brand') and immediately describes the consequences, which cleanly separates it from siblings like update_brand, apply_brand, get_brand and list_brands. An agent can identify the operation 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.

Usage Guidelines4/5

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

Gives a clear when-not condition (the account-level default brand with is_default: true can't be deleted) plus the required permission scope and confirm=true prerequisite. It doesn't route to a specific alternative operation (e.g. sync via update_brand instead of deleting), so it stops short of a full 5.

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

delete_captionsDelete CaptionsA

Destructive

Removes the captions file from a media for the specified language.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`language_code`	Yes	Language code conforming to ISO-639-2 for which the captions should be removed.
`media_hashed_id`	Yes	Unique identifier for the media.

TDQS

A4.2/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds important operational context: required API token permissions, delegated-contact token behavior, the confirm=true requirement, and possible side effects like sharing access, notifications, or provider charges.

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

Conciseness4/5

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

The purpose is front-loaded in one clear sentence, followed by structured permission and confirmation requirements. The permission block is somewhat long but relevant for safely invoking a destructive operation.

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

Completeness5/5

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

For a destructive mutation with no output schema, the description covers the action, required confirmation, authorization constraints, and possible side effects. Together with complete schema descriptions and annotations, it provides enough context to call the tool correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description reinforces the language scope and confirm requirement but does not add syntax or format details beyond the structured fields.

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

Purpose5/5

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

States a specific verb and resource: removes the captions file from a media for a specified language. An agent can distinguish this from sibling caption tools such as update_captions, get_captions, and list_captions 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.

Usage Guidelines3/5

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

The purpose implies usage, and the description states prerequisites like confirm=true and required token permissions. However, it does not explicitly say when to choose this tool over alternatives such as update_captions or edit_captions_text.

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

delete_channelDelete ChannelA

Destructive

Deletes a channel. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`channel_hashed_id`	Yes	The hashed id of the Channel

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered structurally. The description adds value beyond that by disclosing the confirm gate and concrete side effects (shared access changes, notifications, provider charges), which an agent cannot infer from the annotations alone.

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

Conciseness4/5

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

Two short sentences, front-loaded with the action and immediately followed by the hard requirement. The side-effect sentence is slightly generic but still earns its place by warning about charges and notifications.

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

Completeness4/5

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

With no output schema, the description does not need to describe returns, and annotations cover the read/write and destructiveness profile. It supplies the confirm requirement and side effects, leaving only minor gaps such as irreversibility of the deletion.

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

Parameters3/5

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 all three parameters including the confirm flag and hashed id. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

Purpose4/5

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

The description opens with a specific verb+resource ("Deletes a channel"), which is unambiguous and clearly distinct from the channel-episode or media deletion siblings. It stops short of explicitly naming which sibling to prefer in a given situation, so it lands at a clear-but-undifferentiated 4.

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

Usage Guidelines3/5

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

It states a prerequisite (confirm=true is required for the mutation), which is genuinely useful invocation guidance. However, there is no when-to-use vs. when-not-to-use framing and no comparison to alternatives such as update_channel, so usage is only implied.

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

delete_channel_collaboratorDelete Channel CollaboratorA

Destructive

Removes a collaborator's access to a channel.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Collaborator ID
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`channel_hashed_id`	Yes	Channel Hashed ID

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds valuable auth context (required token permissions, delegated token behavior) and a side-effect warning about sharing access, notifying people, or incurring provider charges. It does not describe reversibility or what happens to the collaborator's other access, but it goes beyond the annotations.

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

Conciseness4/5

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

The purpose is front-loaded in the first sentence, and the permission details, while lengthy, are relevant to a destructive mutation. The structure is logical and no clearly extraneous sentences appear, though the auth block could be tightened.

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

Completeness4/5

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

For a destructive, open-world deletion with no output schema, the description covers auth requirements, the confirm gate, and side effects. It lacks details on post-deletion state or re-invite behavior, but the annotations and schema provide the safety profile. It is complete enough for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description repeats the confirm=true requirement and adds no new syntax or semantics for id, account, or channel_hashed_id. Baseline 3 applies when the schema carries the parameter detail.

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

Purpose5/5

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

States a specific verb and resource: 'Removes a collaborator's access to a channel.' The resource is clearly a channel collaborator, distinguishing it from siblings like delete_channel or delete_webinar_collaborator. No ambiguity about what is being deleted.

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

Usage Guidelines3/5

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

Provides prerequisite permission scopes and the confirm=true gate, but does not state when to choose this tool over alternatives such as delete_channel, update_channel, or create_channel_collaborator. Usage is implied by the tool name and resource, but no explicit when-not or alternative routing is given.

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

delete_channel_episodeDelete Channel EpisodeA

Destructive

Deletes an existing channel episode in a channel.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`channel_episode_hashed_id`	Yes	The hashed id of the Channel Episode

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description goes beyond that with real added context: the required token scope, the delegate_to_contact authorization model, the mandatory confirm=true flag, and the warning that the operation may share access, notify people, or incur provider charges. It still doesn't say whether the deletion is reversible or soft-deleted.

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

Conciseness3/5

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

The opening sentence is front-loaded and clear, but the permissions section uses a code block and parenthetical scope names that add bulk for relatively little agent-facing value. It is not wasteful enough to be penalized heavily, but it is longer than the core instruction warrants.

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

Completeness3/5

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

For a destructive, non-idempotent tool with no output schema, the description covers auth and confirmation well but leaves the key operational question unanswered: whether the deletion is permanent or recoverable, especially given siblings like list_deleted_media and restore_deleted_media exist. Adequate but with a clear gap.

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

Parameters3/5

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

Schema description coverage is 100%, so all three parameters are already documented, giving a baseline of 3. The description restates the confirm=true requirement but adds no new syntax or meaning beyond what the schema provides.

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

Purpose4/5

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

States a specific verb and resource ('Deletes an existing channel episode'), which is specific enough to separate it from delete_channel, delete_webinar and delete_review_bundle in the sibling list. The trailing 'in a channel' adds no real information, and no sibling is named as an alternative, so it stops short of a 5.

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

Usage Guidelines3/5

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

The description gives invocation prerequisites (an api token with read/update/delete permission, confirm=true) but never says when to use this tool versus alternatives like un_publish_channel_episode or delete_channel. Usage is implied by the name rather than explained.

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

delete_customizationsDelete CustomizationsA

Destructive

Deletes all explicit customizations for a video, making it act as if it has never been customized.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`media_id`	Yes	The hashed ID of the media whose customizations are to be deleted.

TDQS

A4.2/5.0

Behavior5/5

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

Annotations already flag destructive/non-idempotent, but the description adds real context beyond them: required token permission tiers, the delegated-permission path, the confirm=true gating, and side-effect warnings about sharing access, notifying people, or incurring provider charges. This is exactly the kind of behavior detail 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.

Conciseness4/5

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

The core purpose sentence is front-loaded and efficient, and the mandatory confirm requirement is present. The permission block is fairly verbose boilerplate, which slightly dilutes the entry, but every line is functionally relevant.

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

Completeness5/5

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

For a destructive mutation with no output schema, the description covers the effect on the target, the required permission scope, the confirm gate, and possible side effects. An agent has everything needed to invoke it safely.

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

Parameters3/5

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 account, confirm, and media_id fully. The description reinforces the confirm=true requirement but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb (deletes), the resource (all explicit customizations for a video), and the resulting state (acts as if never customized). No sibling tool offers a per-category delete, so an agent can distinguish this bulk-delete from the various get_/update_ customization tools without ambiguity.

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

Usage Guidelines3/5

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

Usage is implied by the scope word 'all' and the effect on the video, and prerequisites (token scope, confirm=true) are stated. However, it never explicitly says when to choose this over, say, update_customizations to strip specific settings, nor does it name any alternative. Adequate but not explicit.

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

delete_folderDelete FolderA

Destructive

Deletes a folder (previously called project) and the media inside it.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the destroy permission on this folder can also be used. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Folder Hashed ID
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and non-idempotency, but the description adds real context beyond them: the cascade deletion of contained media, the exact permission scopes required, the confirm=true mandate, and a warning about sharing access/notifications/charges. The trailing warning is somewhat generic boilerplate, keeping it from 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.

Conciseness4/5

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

The core action and cascade scope are front-loaded in the first sentence, and the permission block is organized under a header. The token-scope prose is verbose but relevant for an irreversible operation.

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

Completeness4/5

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

For a destructive delete with annotations covering the safety profile, the description covers what is destroyed, the auth requirements, and the confirmation gate. No output schema exists but a delete tool needs no return-value explanation, so the definition is nearly complete.

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

Parameters3/5

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

Schema description coverage is 100%, so id, account, and confirm are all documented in the schema. The description's mention of confirm=true largely restates the schema constraint and adds no syntax or format detail beyond it; baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource plus the critical scope detail that it deletes 'the media inside it', which distinguishes it from delete_subfolder and the various delete_media tools. An agent can immediately tell what this removes.

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

Usage Guidelines3/5

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

The description supplies prerequisites (required token scopes, confirm=true for the mutation) but never states when to choose this over sibling alternatives like delete_subfolder or delete_media, or any exclusion conditions. Usage is implied rather than routed.

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

delete_folder_sharingDelete Folder SharingB

Destructive

Deletes a sharing on a folder.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`folder_id`	Yes	Hashed ID of the folder
`sharing_id`	Yes	ID of the sharing to be deleted

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the base safety profile is covered. The description adds genuinely useful behavioral context beyond that: the exact API token permission required, the delegated-token scope, and the mandatory confirm=true for the mutation. The trailing 'may share access, notify people or incur provider charges' warning is vague but adds some awareness of side effects.

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

Conciseness3/5

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

The core action is front-loaded in one short sentence, which is good. However, the multi-line permission block is lengthy boilerplate for a simple delete operation, and the final sentence mixes side-effect warnings awkwardly. Adequate but not tight.

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

Completeness4/5

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

For a destructive, non-idempotent mutation with no output schema, the description supplies the two things an agent most needs: authorization requirements and the confirm=true gate. It could say more about what happens to existing viewers when sharing is removed, but it is close to complete.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters including account, confirm, folder_id, and sharing_id are already documented in the schema. The description reinforces the confirm=true requirement but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

Purpose4/5

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

The first sentence states a specific verb and resource: 'Deletes a sharing on a folder.' That is unambiguous and distinguishes it from the broad delete_folder sibling. It does not, however, explicitly contrast itself with update_folder_sharing or the share-link deletion siblings, so it stops short of 5.

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

Usage Guidelines2/5

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named (e.g. update_folder_sharing to modify rather than remove access). The permission and confirm prerequisites are stated, but routing guidance is absent.

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

delete_localizationDelete LocalizationB

Destructive

Deletes a localization.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`media_hashed_id`	Yes	The hashed ID of the localization's media.
`localization_hashed_id`	Yes	The hashed ID of the localization to delete.

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond that: the required permission scopes, delegation semantics for team-member tokens, the mandatory confirm=true gate, and the side-effect warning that deletion may share access, notify people or incur provider charges.

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

Conciseness3/5

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

The single-sentence purpose is front-loaded and the confirm requirement is stated, but the bulk of the text is a large fenced permission block with boilerplate that inflates the definition. It is not padded arbitrarily, but the signal-to-length ratio is mediocre.

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

Completeness4/5

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

For a destructive tool with no output schema, the description covers permissions, the confirm gate, and side effects, and annotations cover reversibility and world scope. The main missing piece is any statement about whether a deleted localization can be recovered or what an error response looks like.

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

Parameters3/5

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

Schema description coverage is 100% and all four parameters (account, confirm, media_hashed_id, localization_hashed_id) are documented inline. The description restates that confirm=true is required but adds no format, ID-sourcing or edge-case detail beyond the schema, so the baseline 3 applies.

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

Purpose4/5

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

The description states a clear verb+resource ('Deletes a localization'), which cleanly separates it from the other delete_* siblings (delete_media, delete_captions, delete_folder) and from list_localization/get_localization/create_localization. It does not explicitly name those siblings, so it stops short of full differentiation, but the purpose is unambiguous.

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

Usage Guidelines2/5

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

The text says nothing about when to use this tool versus alternatives such as delete_media or delete_captions, nor when not to use it. It only provides authentication and confirm-token mechanics, which are prerequisites rather than usage guidance.

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

delete_mediaDelete MediaA

Destructive

Deletes a media. Deleted media moves to the account's Recently Deleted area, where it can be restored until the account's restore window ends, after which it is permanently purged.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the destroy permission on this media can also be used. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`media_hashed_id`	Yes	The hashed ID of the media.

TDQS

A3.9/5.0

Behavior5/5

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

Annotations already flag destructiveHint/openWorldHint/non-idempotent, but the description adds real substance: the delete is deferred (recoverable via Recently Deleted until a restore window closes), the exact permission scopes required, the confirm gate, and a side-effect warning about access sharing, notifications, and charges. This is far beyond what the annotations disclose.

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

Conciseness4/5

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

The purpose and destructive lifecycle are front-loaded in the first sentence, which is the highest-value content. The permission section is lengthy boilerplate with code blocks, but it is structured and arguably necessary for authorization correctness.

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

Completeness4/5

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

For a destructive mutation with no output schema, it covers the essentials: auth requirements, the confirm gate, recovery semantics, and side effects. Only minor gaps remain (error/not-found behavior, what the response returns).

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

Parameters3/5

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

Schema coverage is 100% and all three parameters are described in the schema, so the schema carries the load. The description only reinforces the confirm=true requirement already documented on the confirm property; it adds no syntax or format detail for media_hashed_id or account.

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

Purpose4/5

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

Specific verb+resource with the full lifecycle spelled out: delete, move to Recently Deleted, restore until the window ends, then permanent purge. This distinguishes it semantically from archive_media and restore_media, though it never names those siblings explicitly.

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

Usage Guidelines3/5

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

The description gives prerequisites (required permissions, confirm=true) but does not state when to choose this over archive_media, delete_media_extended_audio_description, or other adjacent delete/restore siblings. Usage is implied by the mutation name rather than explicitly routed.

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

delete_media_extended_audio_descriptionDelete Media Extended Audio DescriptionA

Destructive

Deletes an extended audio description by its hashed id. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The hashed id of the Media Extended Audio Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already flag destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description adds value beyond them by disclosing side effects ('may share access, notify people or incur provider charges') and restating the confirm gate, which tells the agent this write has external consequences.

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

Conciseness5/5

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

Two tight sentences, with the verb+resource front-loaded and the mutation precondition and side effects following. No filler or repetition.

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

Completeness4/5

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

With no output schema the description need not explain return values, and the annotations carry the safety profile. It covers the identifier, the confirmation gate and the blast radius, which is nearly everything needed to call a destructive delete correctly; only rollback/recovery context is absent.

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

Parameters3/5

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 id, account and confirm. The description only echoes the hashed-id and confirm semantics without adding format, resolution or side-effect meaning per parameter, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb (deletes) and resource (extended audio description) and names the identifier it operates on. It clearly separates itself from generic delete_media, though it does not explicitly differentiate from the closely related get_media_extended_audio_description / order_extended_audio_description siblings.

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

Usage Guidelines3/5

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

Supplies one real precondition (confirm=true must be set for the mutation), which is more than nothing. However, it gives no when-to-use / when-not guidance and does not point at the restore or list siblings for recovery or verification.

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

delete_review_bundleDelete Review BundleA

Destructive

Permanently deletes a review bundle, identified by its hashed id. This removes the bundle and its shared review link; the media it contained are not deleted. This action cannot be undone.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`review_bundle_hashed_id`	Yes	The hashed id of the review bundle.

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already mark this as destructive and non-idempotent, but the description goes beyond them: it discloses that the shared review link is removed, that contained media survive, that the operation is irreversible, that a specific permission scope and confirm=true are required, and that the call may share access, notify people, or incur provider charges.

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

Conciseness4/5

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

The core behavior (permanent delete, link removed, media preserved, irreversible) is front-loaded in the first two sentences. The permission block is boilerplate-heavy but structured, with only minor redundancy.

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

Completeness4/5

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

For a destructive tool with no output schema, the description covers consequences, side effects, and authorization requirements well. The one gap is not directing the agent to how the hashed id is obtained or what a successful/failed deletion returns.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3 and the schema already explains each parameter. The description adds value by emphasizing the confirm=true gating requirement and the significance of the hashed id as the deletion target, reinforcing semantics rather than restating raw types.

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

Purpose5/5

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

States a specific verb+resource ('Permanently deletes a review bundle') and identifies it by hashed id. It also draws a clear boundary against sibling delete tools by clarifying that the contained media are NOT deleted, letting an agent distinguish it from delete_media.

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

Usage Guidelines3/5

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

The destructive, irreversible nature implies when it is appropriate, but there is no explicit when-to-use statement or named prerequisite (e.g., call list_review_bundles to obtain the id, or a non-destructive alternative). Usage is inferable but not spelled out.

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

delete_share_linkDelete share linkA

Destructive

Deletes the share link for a media, revoking the URL. A new share link can be created later with a fresh URL by calling the show or update endpoint again.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`media_id`	Yes	The hashed ID of the media.

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare destructive and open-world behavior, but the description adds substantial context: exact permission requirements, delegate scope behavior, the confirm=true prerequisite, and consequences ('May share access, notify people or incur provider charges'). 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.

Conciseness4/5

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

Front-loads the purpose in the first sentence, then uses structured sections for permissions and requirements. The final sentence is somewhat vague boilerplate, but overall the information earns its place for a mutation tool with auth complexity.

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

Completeness5/5

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

For a destructive mutation tool with no output schema, the description covers the key needs: what it deletes, reversibility, permission requirements, confirm prerequisite, and side effects. Nothing critical is missing for correct invocation.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all three parameters. The description mentions confirm=true, but the schema already contains that requirement. No additional semantics are added for account or media_id beyond what the schema provides.

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

Purpose5/5

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

States a specific verb and resource ('Deletes the share link for a media') plus the effect ('revoking the URL'), and distinguishes from siblings like get_share_link and update_share_link by noting the link can be recreated via those endpoints.

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

Usage Guidelines4/5

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

Clearly describes the action and its reversibility, but does not explicitly state when to choose this over update_share_link or get_share_link. The context is clear enough for an agent to know this is the revocation operation.

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

delete_subfolderDelete SubfolderA

Destructive

Deletes one subfolder and moves its media to the folder's root level. The subfolder is soft-deleted and is no longer accessible via the API. To delete multiple subfolders and their media, use the Bulk Delete Subfolders endpoint.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`folder_id`	Yes	The hashed ID of the folder
`subfolder_id`	Yes	The hashed ID of the subfolder

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already flag destructive/not-idempotent, but the description adds real context beyond them: media is relocated to the root, the subfolder is soft-deleted and no longer API-accessible, and specific token/permission requirements apply. The closing 'May share access, notify people or incur provider charges' is generic boilerplate that slightly muddies the otherwise precise disclosure.

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

Conciseness4/5

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

The core behavior and the alternative-endpoint routing are front-loaded in the first two sentences, which is ideal. The subsequent multi-line permission block and the trailing charges/notification sentence are verbose and push the definition well past what an agent strictly needs.

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

Completeness4/5

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

For a destructive mutation with no output schema, it covers side effects, auth scope, and the confirm gate, which is most of what an agent needs. It stops short of stating whether the soft-deleted subfolder or its media can be restored (e.g., via a restore endpoint), leaving that ambiguity.

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

Parameters3/5

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

Schema description coverage is 100% and both required IDs plus 'confirm' are documented in the schema (confirm already states 'Must be true for the specific user-requested write'). The description only restates the confirm requirement without adding syntax or format meaning, so the schema does the heavy lifting.

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

Purpose5/5

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

Specific verb+resource ('Deletes one subfolder') with the key side effect spelled out ('moves its media to the folder's root level') and the soft-delete/API-inaccessibility consequence stated. It explicitly distinguishes itself from bulk_delete_subfolders, so an agent can route correctly 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.

Usage Guidelines5/5

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

States the exact single-vs-multiple condition and names the alternative ('To delete multiple subfolders and their media, use the Bulk Delete Subfolders endpoint'). It also surfaces the confirm=true prerequisite, so both routing and invocation conditions are covered.

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

delete_tagDelete TagB

Destructive

Deletes a tag

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Name of the tag to delete
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value on top: the specific permission scope required, the confirm=true gate for the mutation, and the side-effect warning that the action 'May share access, notify people or incur provider charges.'

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

Conciseness3/5

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

The core statement 'Deletes a tag' is front-loaded and clear, but the permission block is verbose boilerplate that consumes most of the text. It is organized with headers, though it could be trimmed without losing meaning.

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

Completeness4/5

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

For a destructive, non-idempotent tool, the description supplies the auth requirements and the confirm gate, complementing the safety annotations. With no output schema, nothing about return values is needed; the definition is close to complete for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so name, account, and confirm are fully documented in the schema. The description only restates the confirm requirement already captured by the confirm property, adding no syntax or format detail beyond the schema baseline.

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

Purpose4/5

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

States a specific verb and resource ('Deletes a tag'), which is unambiguous on its own. It does not, however, differentiate itself from tag-related siblings such as bulk_tag, create_tags, or list_tags, so an agent gets no routing help from the description.

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

Usage Guidelines2/5

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

The description never says when to use this versus bulk_tag or another deletion path, and offers no prerequisites beyond an auth/confirm requirement that is operational rather than usage-routing. There is no explicit when/when-not guidance.

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

delete_webinarDelete WebinarA

Destructive

Deletes an existing webinar.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The hashed ID of the webinar
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description still adds real value beyond that: the required token permission scopes, delegation behavior, the mandatory confirm=true, and the side-effect warning about sharing access, notifying people, or incurring charges.

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

Conciseness4/5

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

The core purpose is front-loaded in the first sentence, followed by the permission and confirmation requirements. The permission block is verbose but operationally relevant for a destructive call, and there is only minor duplication of the confirm rule.

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

Completeness4/5

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

For a destructive delete with no output schema and strong annotation coverage, the description supplies the missing pieces: required scopes, delegation semantics, the confirm gate, and side-effect warnings. What remains unstated (reversibility, whether the deletion is soft or hard) is a minor gap.

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

Parameters3/5

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

Schema coverage is 100%, with all three parameters (id, account, confirm) documented inline, so the schema does the heavy lifting. The description only reinforces the confirm requirement already stated in the schema; it adds nothing new about the id or account parameters.

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

Purpose4/5

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

States a specific verb and resource ('Deletes an existing webinar'), which is unambiguous and distinct from siblings like update_webinar or get_webinar. It does not explicitly contrast itself with alternatives, but the name/verb pairing leaves no room for confusion.

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

Usage Guidelines2/5

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

The description never says when to use this tool versus restoring via restore_deleted_media or archiving via archive_media, and offers no preconditions beyond the confirm flag. The confirm=true requirement is a gating rule rather than usage guidance, leaving the agent to infer the context.

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

delete_webinar_collaboratorDelete Webinar CollaboratorB

Destructive

Removes a collaborator's producer access to a webinar.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Collaborator ID
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`webinar_id`	Yes	Webinar Hashed ID

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already flag destructive/openWorld/non-idempotent, but the description adds real value beyond them: required token permission scopes, delegation authorization behavior, the confirm=true requirement, and side-effect warnings ('may share access, notify people or incur provider charges').

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

Conciseness3/5

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

The permission disclaimer block is boilerplate-heavy and partially redundant with annotations, though the core action sentence is front-loaded and the structure with headers aids scanning. The trailing side-effect sentence is generic filler.

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

Completeness4/5

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

For a destructive mutation with no output schema, the description supplies the needed authorization profile, the confirm gate, and side-effect expectations. Nothing critical to correct invocation is missing.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all four parameters including confirm and collaborator id. The description reinforces the confirm=true requirement but adds no syntax or format beyond what the schema provides.

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

Purpose4/5

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

The description states a specific verb+resource: removing a collaborator's producer access to a webinar. It is clear, though it does not explicitly name the sibling delete_channel_collaborator to distinguish webinar vs channel scope, which the agent must infer from the 'webinar' wording.

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

Usage Guidelines2/5

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

There is no explicit when-to-use or when-not guidance, nor a named alternative sibling (e.g., delete_channel_collaborator, update_webinar). The usage is only implied by the removal semantics and the permission block.

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

dismiss_desktop_install_promptDismiss Desktop Install PromptB

Destructive

Marks the current contact's macOS install-prompt modal as dismissed. Called by the SPA when a teammate invited via the Wistia desktop app closes the "Wistia is even better on your Mac" modal : the modal never shows again for that contact.

Idempotent: a repeat call returns the timestamp of the first dismissal.

Requires api token with one of the following permissions

Read, update & delete anything

Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

B3.4/5.0

Behavior1/5

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

The description asserts 'Idempotent: a repeat call returns the timestamp of the first dismissal', while the annotations declare idempotentHint=false. That is a direct contradiction of the declared behaviour. Credit is due for disclosing the permission requirement, the confirm=true gate, and side effects ('may share access, notify people or incur provider charges'), but the idempotency claim conflicts with structured metadata.

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

Conciseness4/5

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

Purpose and trigger are front-loaded in the first two sentences, followed by the idempotency note and the permission block. The permission/boilerplate section is somewhat verbose and repeated template text, but nothing is fatally misplaced.

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

Completeness3/5

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

For a mutation tool with no output schema, the description does cover the trigger, the idempotency claim, required permissions, the confirm gate, and side effects. However the return value is only hinted at in the contradictory idempotency sentence, and the annotation conflict leaves the agent with an unresolved behavioural question.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters (account, confirm) are already documented in the schema as credential selector and mutation gate. The description restates the confirm=true requirement but adds no syntax or format detail beyond that. Baseline 3 applies when the schema carries the semantics.

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

Purpose5/5

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

States a specific verb (marks as dismissed) and a precise resource (the current contact's macOS install-prompt modal), and names the exact UI moment that triggers it ('Wistia is even better on your Mac' modal close). No sibling tool overlaps this behaviour, so an agent can uniquely select it.

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

Usage Guidelines4/5

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

Gives clear invocation context ('Called by the SPA when a teammate invited via the Wistia desktop app closes the modal'), which is effectively the when-to-use condition. It stops short of stating when NOT to use it or naming any alternative, but no sibling is a plausible substitute, so the gap is minor.

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

edit_captions_textEdit Captions TextA

Destructive

Applies targeted find-and-replace corrections to a media's transcript for the specified language, preserving the timings of unchanged words. The whole batch is applied atomically against a specific caption version, or nothing is.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`edits`	No	The corrections to apply, all-or-nothing, in one new version.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`language_code`	Yes	The 3-character ISO 639-2 language code of the caption track to edit (e.g., `eng`, `fra`, `spa`). Some languages use extended IETF subtags (e.g., `zh-Hant`).
`media_hashed_id`	Yes	The hashed ID of the media whose transcript should be edited.
`expected_version`	No	The active caption version returned with the caption content used to prepare these edits. The edit applies only if that is still the active version; otherwise it returns 409 so you re-read and retry.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already flag destructive=true and non-idempotent, but the description adds meaningful behaviour: all-or-nothing batch semantics, optimistic-concurrency against expected_version with a 409 retry signal, and required token permission scopes plus confirm=true. The generic trailing boilerplate ('May share access, notify people or incur provider charges') is low-signal but the version/atomicity disclosure is genuinely useful.

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

Conciseness3/5

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

The opening sentence is well front-loaded and earns its place, but a lengthy markdown permission block and generic risk boilerplate ('May share access, notify people or incur provider charges') inflate the description with content that is largely boilerplate rather than tool-specific guidance.

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

Completeness4/5

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

For an 8-parameter mutation with nested objects and no output schema, the description covers the essentials an agent needs: atomicity, version pinning with the 409 retry path, permission requirements, and confirm=true. Return-shape details are absent but no output schema exists, and the concurrency contract is the main missing-behaviour risk that is actually addressed.

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

Parameters3/5

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 every parameter including the nested edit objects, expected_version, and confirm. The description adds essentially no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource ('applies targeted find-and-replace corrections to a media's transcript for the specified language') plus a distinguishing constraint ('preserving the timings of unchanged words'). An agent can differentiate this from update_captions (full replacement) and find_caption_matches (search only) without reading the schema.

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

Usage Guidelines3/5

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

Implies the use case (targeted corrections vs wholesale replacement) and states the atomic batch behaviour, but never explicitly names an alternative sibling tool or contrasts when to pick this over update_captions or find_caption_matches. The atomic/version guidance is usage-relevant but framed as mechanics rather than tool selection.

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

find_caption_matchesFind Caption MatchesA

Read-onlyIdempotent

Finds exact text in caption tracks without modifying them. Matching uses the same normalization, composite-media boundaries, and time coordinates as the targeted caption edit endpoint. Fuzzy alternatives are returned separately as suggestions and are never reported as exact matches. A resolved match means the wording was located; a later write can still fail authorization, version, or edit-boundary checks.

When more than 10 exact matches exist, use the one-based occurrence parameter to retrieve a specific later match.

Authentication and request validation failures apply to the whole request. Missing, inaccessible, or otherwise unreadable media are reported as per-media statuses without exposing whether an inaccessible ID exists.

Requires api token with one of the following permissions

Read all folder and media data

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Read-only account operation.

ParametersJSON Schema

Name	Required	Description
`end_ms`	No	Optional end of a time range used to disambiguate the match.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`start_ms`	No	Optional start of a time range used to disambiguate the match.
`media_ids`	No	Explicit hashed IDs of the media whose captions should be searched.
`occurrence`	No	One-based exact occurrence to return, including occurrences after the first 10.
`target_text`	No	Exact caption wording to locate.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`language_code`	No	Exact IETF language tag. Omit when each media has only one caption track.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description goes well beyond them: it discloses match normalization, composite-media boundaries, the 10-match occurrence ceiling, whole-request auth/validation failure behavior, and per-media status reporting that hides whether an inaccessible ID exists. It also warns that a resolved match does not guarantee a later write succeeds.

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

Conciseness4/5

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

Front-loads purpose, then behavior, then the occurrence rule, then permissions. Every sentence carries information, though the permissions block is verbose and the normalization reference is slightly dense.

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

Completeness5/5

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 characterizes return behavior (exact matches vs. fuzzy suggestions, per-media statuses) and the occurrence-based retrieval. Combined with the auth requirements, it gives an agent enough to call the tool correctly.

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

Parameters4/5

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 real meaning beyond the schema by explaining the one-based `occurrence` parameter's purpose (retrieving matches past the first 10) and tying start_ms/end_ms to match disambiguation.

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

Purpose5/5

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

States a specific verb and resource ('Finds exact text in caption tracks') and immediately scopes it as non-mutating. It distinguishes itself from the caption edit endpoint it shares normalization semantics with, so an agent can tell it apart from siblings like edit_captions_text.

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

Usage Guidelines4/5

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

Clearly frames the tool as the read/search counterpart to the targeted caption edit endpoint and explains the fuzzy-vs-exact split. However, it never explicitly routes the agent between this tool and other caption readers (list_captions, get_captions, list_all_captions), leaving that selection to inference.

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

find_media_by_embed_locationFind Media By Embed LocationA

Read-onlyIdempotent

Find the media embedded at a given URL. Returns the hashed IDs of the account's media that recorded activity at that embed location during the date range, ranked by plays. The resulting hashed IDs can be passed to other endpoints, such as Show Account Top Content's hashed_ids[] filter, to fetch analytics for those media.

The domain of embed_url is always matched exactly. Its path is matched exactly by default, or as a prefix with path_match=prefix (e.g. /pricing also matching /pricing/plans). A path that is empty or / is ignored, returning media across all paths on the domain.

Embed location data is retained for 6 months; a start_date older than that returns a 422 error. When start_date and end_date are omitted, the full 6-month queryable window is used.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	No	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date. Defaults to tomorrow, so today's activity is included.
`per_page`	No	Number of media hashed IDs to return (max 1000).
`embed_url`	Yes	The URL of the page to look up, e.g. `https://example.com/pricing`. The protocol is optional (https is assumed), so `example.com/pricing` also works.
`path_match`	No	How to match the path of `embed_url` against embed locations. `exact` requires the path to match exactly; `prefix` matches any embed path starting with it.	exact
`start_date`	No	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date. Must be within the last 6 months. Defaults to 6 months ago, the start of the queryable window.

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and idempotency are covered. The description adds valuable non-obvious behavior: exact domain matching, path matching rules, the empty-path special case, the 6-month retention window, and the 422 error for older start dates. It does not detail pagination or output ordering beyond 'ranked by plays'.

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

Conciseness4/5

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

The description is front-loaded with the core purpose, then organized into clear paragraphs covering matching rules and date constraints. It is slightly verbose in places (e.g., repeating the 6-month window) but every sentence contributes useful information.

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

Completeness4/5

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

Given the complexity of URL matching and date-range behavior, the description covers the essential semantics well, including retention limits and error conditions. It lacks details on return format (no output schema) and pagination, but annotations and schema fill some gaps.

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

Parameters4/5

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, but the description adds meaning beyond the schema by explaining exact vs prefix path matching with an example, the empty/root-path special case, and the 6-month date constraint. It omits details on per_page and account parameters, which the schema already covers.

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

Purpose5/5

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

States a specific verb (Find) and resource (media by embed location), and immediately clarifies that it returns hashed IDs of media that recorded activity at an embed URL, not the media objects themselves. This distinguishes it from siblings like get_media or get_media_embed_locations, which fetch analytics rather than media IDs.

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

Usage Guidelines4/5

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

Clearly indicates when to use it (looking up media tied to an embed URL) and points to a downstream use case (passing hashed IDs to Show Account Top Content's hashed_ids[] filter). However, it does not explicitly name or contrast with alternatives like get_media_embed_locations, which also covers embed location data.

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

get_access_customizationsShow Access CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set password-protection settings for the video, including the stored password.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real value beyond them: specific required permission scopes, the delegation-token behavior (requests authorized as the assigned contact), and the notable fact that the response includes the stored password. That sensitive-data disclosure is exactly the kind of context an agent should have.

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

Conciseness4/5

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

The purpose is front-loaded in a single tight sentence before the permissions detail, which is the right ordering. The permissions boilerplate is somewhat verbose but carries useful authorization detail rather than filler.

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

Completeness4/5

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

For a read tool with no output schema, the description does the heavy lifting: it says what is retrieved and flags that it exposes the stored password, plus documents the authorization requirements. Nothing critical to correct invocation is missing.

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

Parameters3/5

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

Schema description coverage is 100% and both parameters (account, media_id) are already documented in the schema. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

Purpose4/5

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

States a specific verb ("Fetches") and resource ("explicitly-set password-protection settings for the video"), sharpening the vague name 'access customizations' into a concrete concern. It distinguishes itself from the many other get_*_customizations siblings by naming password protection, though it never explicitly names update_access_customizations as the write counterpart.

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

Usage Guidelines3/5

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

Usage is only implied: the read-only framing and the word 'explicitly-set' hint at when this is useful, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer it pairs with update_access_customizations, but must do the inferring itself.

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

get_accessibility_customizationsShow Accessibility CustomizationsB

Read-onlyIdempotent

Fetches the explicitly-set accessibility customizations (caption display and styling, transcript display, and audio description) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: it specifies the exact permission scopes required and the delegate_to_contact_permissions authorization model, plus the important nuance that only 'explicitly-set' customizations are returned (i.e. defaults are not included). It could have said more about what happens when nothing is set, but this is solid added context beyond the 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.

Conciseness3/5

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

The opening sentence is front-loaded and efficient, but the trailing permission block is verbose and formatted in a way that competes with the core purpose statement, and the closing 'Read-only account operation.' merely restates the readOnlyHint annotation. Some economy is lost to redundancy.

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

Completeness4/5

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

With no output schema, the description helpfully enumerates the customization categories returned and covers authorization requirements thoroughly. The main gap is the absence of any indication of the response shape (e.g. whether defaults are returned as empty objects), but for a simple read tool it is largely complete.

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

Parameters3/5

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

Schema description coverage is 100% with only two parameters (account, media_id), both already documented in the schema. The description adds no parameter-level detail, so the schema does the heavy lifting and the baseline of 3 applies.

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

Purpose4/5

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

The description gives a specific verb (fetches) and resource (accessibility customizations) and enumerates the covered sub-areas: caption display/styling, transcript display, and audio description. It is clearly distinct from update_accessibility_customizations, but it never contrasts itself with the sibling read tools like get_customizations or get_appearance_customizations, so an agent must infer the boundary.

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

Usage Guidelines2/5

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

There is no guidance on when to call this versus the many other get_*_customizations siblings, nor any stated prerequisites beyond token permissions. The permission/auth section is the only context given, which is access requirements rather than usage selection.

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

get_accountGet Current AccountA

Read-onlyIdempotent

Retrieves a summary of the Wistia account including account name, description, URL and counts of records.

Requires api token with one of the following permissions

(any scope allowed)

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fixed. The description adds meaningful context beyond that: it specifies the required api token permissions, explains the delegated-permissions token behavior, and notes it is a read-only account operation. This goes beyond repeating the annotations, though it does not cover rate limits or error behavior.

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

Conciseness3/5

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

The first sentence is well front-loaded and concise. However, the permission block, while useful, is verbose and could be compressed; the description reads as a mix of concise summary and raw documentation text rather than a tightly structured brief.

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

Completeness4/5

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

Given no output schema, the description compensates by enumerating the returned summary fields (name, description, URL, counts). Combined with the permission requirements and read-only designation, an agent has enough to call the tool correctly. It does not explain what the record counts represent or how the summary relates to sibling analytics tools, but the core is complete.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents the single 'account' parameter fully, including the note that it selects credentials rather than a remote account ID. The description adds no parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

Purpose5/5

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

States a specific verb (Retrieves) and resource (summary of the Wistia account), and enumerates exactly what is returned: name, description, URL, and record counts. This distinguishes it clearly from siblings like get_account_stats or get_account_usage, which cover different aspects of the account.

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

Usage Guidelines3/5

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

The description implies usage (fetch the current account's summary) but does not explicitly state when to choose this tool over get_account_stats, get_account_usage, or list_accounts. Some routing is inferable from the enumerated fields, but no alternatives or exclusions are named.

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

get_account_analyticsShow Account AnalyticsA

Read-onlyIdempotent

Retrieve aggregate analytics for the entire account over a date range. This endpoint provides Bottler-powered analytics across all of the account's media including plays, loads, engagement rate, play rate, and conversion metrics.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the required permission ('Read detailed stats'), the delegation-scope behavior for 'Act with a team member's permissions' tokens, and the 2-year range cap — meaningful operational context not present in the annotations.

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

Conciseness4/5

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

Purpose and metrics are front-loaded in the first sentence, followed by the range limit and auth requirements. The permission block is verbose, and the trailing 'Read-only account operation.' repeats what the readOnlyHint annotation already states, so a small amount of the text does not earn its place.

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

Completeness4/5

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 results, and it does list the metric categories returned. It stops short of explaining aggregation granularity, pagination, or breakdowns, but for a read-only aggregate analytics endpoint whose safety profile is fully annotated, the coverage is largely sufficient.

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

Parameters4/5

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

Schema description coverage is 100%, so account/start_date/end_date semantics are already documented (including inclusivity/exclusivity). The description adds a constraint the schema lacks — the 2-year maximum span between start_date and end_date — which meaningfully narrows valid parameter combinations.

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

Purpose4/5

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

The description uses a specific verb+resource ('Retrieve aggregate analytics for the entire account over a date range') and enumerates the metrics returned (plays, loads, engagement rate, play rate, conversions). It clearly signals account-wide scope, which helps separate it from media-scoped siblings, but it never names or contrasts with obvious alternatives like get_account_analytics_timeseries or get_account_stats.

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

Usage Guidelines3/5

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

Usage is implied (call this for account-wide analytics over a date range) and one hard constraint is stated ('date range must not exceed 2 years'). However, there is no explicit when-to-use vs when-not guidance, and the many overlapping siblings (get_account_stats, get_account_stats_by_date, get_account_analytics_timeseries) are not addressed, forcing the agent to infer the distinction.

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

get_account_analytics_timeseriesShow Account Analytics TimeseriesA

Read-onlyIdempotent

Retrieve analytics timeseries data for the entire account over a date range with configurable granularity. Returns an array of timestamped metric buckets aggregated across all of the account's media.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`granularity`	Yes	The time granularity for the timeseries data.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds genuinely useful behavioral context they do not: the 2-year maximum on the date range and the required 'Read detailed stats' permission with delegation semantics. It also previews the return shape as timestamped buckets.

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

Conciseness4/5

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

Purpose and the return shape are front-loaded in the first two sentences, followed by the range constraint. The permissions block is verbose but carries real authorization information, so it earns most of its space.

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

Completeness4/5

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 as an array of timestamped metric buckets, and it discloses auth requirements and the range limit. Complete enough to invoke correctly, though it doesn't characterize pagination or which metrics are included.

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

Parameters4/5

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 a cross-parameter constraint absent from the schema: the span between start_date and end_date must not exceed 2 years. That meaningfully guides how the required date parameters must be set.

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

Purpose5/5

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

States a specific verb+resource (retrieve analytics timeseries data for the entire account) and pins the scope to account-wide aggregation across all media, which cleanly separates it from get_media_analytics_timeseries and the non-timeseries get_account_analytics in the sibling list. An agent can tell what it does 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.

Usage Guidelines3/5

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

The phrase 'for the entire account' and 'aggregated across all of the account's media' implies when this is appropriate, but the description never explicitly states when to choose it over get_media_analytics_timeseries or get_account_analytics. Usage context is only implied, not spelled out.

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

get_account_embed_locationsShow Account Embed LocationsA

Read-onlyIdempotent

Retrieve embed location analytics for the entire account. Returns a list of domains where the account's media are embedded, ranked by the chosen metric.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	The metric to sort embed locations by.	plays
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`per_page`	No	Number of results to return (max 100).
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`sort_direction`	No	The sort direction.	desc

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds behavior beyond annotations: the required permission ('Read detailed stats'), delegated-token behavior, and the 2-year maximum date span. It omits pagination or rate-limit behavior, so a 4 is appropriate rather than 5.

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

Conciseness4/5

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

The description is front-loaded: purpose and return are stated first, followed by the date-range constraint, then permissions. It is generally tight, though the delegated-token paragraph is boilerplate that goes beyond what an agent likely needs for tool selection, slightly diluting conciseness.

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

Completeness4/5

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

Given no output schema, the description does describe the return as a ranked list of domains, and it covers the key constraint and authorization requirements. It stops short of detailing per-domain response fields or pagination behavior, leaving minor gaps for an analytics-listing endpoint.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds a valuable cross-parameter constraint not present in the schema: the range between start_date and end_date must not exceed 2 years. It adds no further meaning for sort_by, sort_direction, account, or per_page, so it does not reach 5.

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

Purpose5/5

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

States a specific verb and resource ('Retrieve embed location analytics for the entire account') and clarifies the return ('list of domains where the account's media are embedded, ranked by the chosen metric'). The phrase 'entire account' distinguishes it from the sibling get_media_embed_locations, so an agent can route correctly without opening schemas.

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

Usage Guidelines4/5

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

The scope ('entire account') implicitly tells when to use this instead of a media-specific embed-location tool, and the 2-year date-range restriction is a concrete usage constraint. However, no alternative tool is named explicitly and there is no 'do not use when' statement, so it falls short of the explicit when/when-not/alternatives bar.

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

get_account_statsShow Current Account StatsA

Read-onlyIdempotent

Retrieve account-wide video stats. Get statistics like the number of video loads, plays, and hours watched for the entire account.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond that by spelling out the required token permission ('Read detailed stats') and the delegate_to_contact_permissions authorization path — real operational context the annotations do not provide.

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

Conciseness4/5

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

The first two sentences front-load what is returned and are tight. The permission block is verbose but is structured, scoped boilerplate tied to auth requirements rather than filler.

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

Completeness5/5

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

For a no-required-parameter read tool with no output schema, the definition covers what is returned (metrics list and scope), the auth prerequisites, and the read-only nature. An agent has everything needed to call it correctly.

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

Parameters3/5

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

There is a single optional parameter with 100% schema description coverage, so the schema already explains that 'account' selects named credentials rather than a remote ID. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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

Purpose4/5

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

States a specific verb and resource — 'Retrieve account-wide video stats' — and enumerates the actual metrics (video loads, plays, hours watched) for the entire account. It is clear about scope, but it never distinguishes itself from the close sibling get_account_stats_by_date, so an agent must infer the difference.

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

Usage Guidelines3/5

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

The phrase 'for the entire account' implies this is the unfiltered aggregate view, which conveys usage context. However, no explicit when-to-use rule or alternative is named against siblings like get_account_stats_by_date, get_project_stats, or get_media_stats, so routing must be inferred.

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

get_account_stats_by_dateShow Account Stats by DateA

Read-onlyIdempotent

Retrieve account-wide stats organized by day, between a start and end date parameter (inclusive). If start and end date are not provided, defaults to yesterday and today.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	No	The end date for the stats, formatted YYYY-MM-DD
`start_date`	No	The start date for the stats, formatted YYYY-MM-DD

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by specifying the required API token permission ('Read detailed stats') and the delegate_to_contact_permissions alternative, which the agent cannot learn from the annotations.

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

Conciseness4/5

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

The purpose and default behavior are front-loaded in the first two sentences, with permission requirements following. The permissions block is somewhat verbose but carries necessary auth information rather than filler.

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

Completeness4/5

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

For a read-only stats tool with no output schema, the definition covers scope, defaults, and auth requirements adequately. The main gap is the absence of guidance on which sibling stats/analytics tool to pick for a given need.

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

Parameters4/5

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, but the description adds meaning the schema lacks: date inclusivity and the concrete default window (yesterday/today) when start_date and end_date are omitted.

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

Purpose4/5

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

States a specific verb (Retrieve) and resource (account-wide stats organized by day) with a clear scope (date range, inclusive). This distinguishes it reasonably well from get_account_stats and get_media_stats_by_date, though it does not name the siblings explicitly.

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

Usage Guidelines3/5

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

It clarifies the default behavior (yesterday and today when dates are omitted), which is genuinely useful. However, it never states when to choose this tool over get_account_stats, get_account_analytics, or get_media_stats_by_date, leaving sibling selection to inference.

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

get_account_top_contentShow Account Top ContentA

Read-onlyIdempotent

Rank the account's content by a chosen metric over a date range. Returns the top media, channels, or folders (controlled by group_by) with their analytics, answering questions like "what were my most-played videos last month?".

Optionally pass hashed_ids to scope the ranking to a specific set of media instead of the whole account : useful for fetching analytics for a known list of videos, still sorted by sort_by.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	The metric to rank content by.	plays
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`group_by`	No	The type of content to rank.	media
`per_page`	No	Number of results to return. Defaults to the number of hashed_ids requested, or 10 when hashed_ids is not given.
`hashed_ids`	No	Scope the ranking to these specific media's hashed IDs, rather than the whole account. Only valid with group_by=media.
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`sort_direction`	No	The sort direction.	desc

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare the read-only, idempotent, non-destructive safety profile, and the description adds real behavioral context beyond that: the 2-year maximum date span and the required 'Read detailed stats' permission plus delegate_to_contact behavior. It does not address pagination/result-limit behavior, so it stops short of a full picture.

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

Conciseness4/5

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

Front-loaded with purpose, then example, then the optional parameter, then the hard constraint, then permissions — a logical order with little waste. The permission markdown block is somewhat boilerplate-heavy, but it is scannable and does not bury the core task.

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

Completeness5/5

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

With 8 parameters, full schema coverage, and no output schema, the description supplies everything an agent needs: the purpose, the return shape, the trade-off for `hashed_ids`, the 2-year constraint, and auth requirements. Nothing material is left implicit for correct invocation.

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

Parameters4/5

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 the schema lacks: it explains that `hashed_ids` changes the scope from the whole account and that results remain ordered by `sort_by`, and it states the 2-year range bound that applies to the date parameters. This is genuine added value over the enum/format docs.

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

Purpose4/5

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

The first sentence states a specific verb and resource ('Rank the account's content by a chosen metric over a date range') and clarifies the return shape ('top media, channels, or folders'). It is clear and concrete, but it never names a sibling analytics tool (e.g. get_account_stats, get_media_analytics) to sharpen the distinction from the many other analytics endpoints.

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

Usage Guidelines4/5

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

Offers a concrete use-case framing ('answering questions like "what were my most-played videos last month?"') and explains the specific scenario for `hashed_ids` (fetching analytics for a known list of videos). It lacks explicit when-not-to-use guidance or direct routing to the sibling analytics tools an agent would otherwise pick.

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

get_account_usageGet Account UsageA

Read-onlyIdempotent

Retrieves plan, usage, and limit information for the current account.

The response includes plan tier, upload eligibility, and links to billing pages. Usage and limit details (media counts, storage, seats, bandwidth) are only visible to account owners and managers : other contacts receive null for the limits field.

Requires api token with one of the following permissions

(any scope allowed)

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare the safe read-only/idempotent profile, yet the description adds substantial value beyond them: it discloses the response shape, the permission-dependent nulling of the `limits` field for non-owner contacts, and the delegated-token authorization behavior. This is real behavioral context not derivable from the structured hints.

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

Conciseness4/5

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

The core purpose and response contents are front-loaded efficiently in the first two sentences. The permissions block is somewhat boilerplate-heavy ('any scope allowed'), but it is clearly delimited and does not obscure the primary intent.

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

Completeness4/5

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 enumerating returned fields (plan tier, upload eligibility, billing links, usage/limit details) and the visibility caveat. For a single read-only parameter tool this is nearly complete; only the null-vs-value contract for non-owner callers could be stated more explicitly.

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

Parameters3/5

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

Schema description coverage is 100% and the single `account` parameter is documented in the schema as selecting local credentials rather than a remote ID. The description adds only the vague phrase 'current account' and no further syntax or format meaning, so the baseline 3 applies.

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

Purpose4/5

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

The description states a specific verb and resource ('Retrieves plan, usage, and limit information for the current account') and enumerates the concrete data involved (plan tier, upload eligibility, billing links, media counts, storage, seats, bandwidth). However, it never distinguishes itself from adjacent account-level siblings like get_account, get_account_stats, or get_credit_balance.

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

Usage Guidelines3/5

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

The description implies usage context through the permission requirements and the owner/manager visibility note, and states the required token scopes. But it never says when to reach for this tool versus get_account or get_account_stats, so the agent must infer the selection.

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

get_allowed_domainShow Allowed DomainB

Read-onlyIdempotent

Returns the details of an allowed domain.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`domain`	Yes	The domain name to retrieve
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

B3.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: the required token permission ('Read all data') and the delegated-permission scope behavior, which an agent needs to know before calling.

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

Conciseness3/5

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

The purpose sentence is front-loaded and tight, but the multi-line permission block with markdown headers is boilerplate-heavy, and the trailing 'Read-only account operation.' merely restates the readOnlyHint annotation.

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

Completeness3/5

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 should ideally say what 'details' are returned for a domain (e.g., name, verification state), but it does not. Auth and read-only semantics are well covered, leaving the return shape as the main gap.

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

Parameters3/5

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

Schema description coverage is 100% for both parameters, so the schema already documents 'domain' and the 'account' credential selector. The description adds no additional parameter meaning, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb ('Returns the details') and resource ('an allowed domain'), which clearly separates it from the sibling mutations create_allowed_domain and delete_allowed_domain. It does not explicitly distinguish itself from list_allowed_domains, leaving the singular-vs-collection distinction to be inferred from the wording.

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

Usage Guidelines2/5

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

No guidance on when to use this versus list_allowed_domains or the create/delete siblings, and no statement of prerequisites beyond the permission block. The agent must infer that this fetches one domain by name while the sibling lists many.

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

get_appearance_customizationsShow Appearance CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set appearance customizations (player color, gradient, rounded corners, control contrast, and customer logo) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover readOnly/idempotent/destructive/openWorld. The description adds genuine beyond-schema context: the required permission scope, the delegation-token alternative, and the 'explicitly-set' semantics (i.e., it excludes inherited/default values). It does not describe what happens when no customizations are set, which would push it higher.

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

Conciseness4/5

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

One tight sentence front-loads the purpose with the field list, but half the text is a boilerplate permissions block that repeats the annotation-supplied read-only nature. The permission details are useful; the trailing 'Read-only account operation' line is redundant with readOnlyHint.

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

Completeness4/5

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

No output schema exists, so the field enumeration compensates. Auth scope requirements are spelled out. Adequate for a simple 2-param read tool, though it could note the return shape and the unset-value behavior.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents media_id and account. The description adds no parameter-level detail (e.g., what a 'hashed ID' looks like or the account-selection semantics). Baseline 3 is appropriate when the schema does the heavy lifting.

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

Purpose4/5

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

States a specific verb ('Fetches'), resource ('explicitly-set appearance customizations'), and enumerates the fields (player color, gradient, rounded corners, control contrast, customer logo). This clearly distinguishes it from siblings like get_customizations, get_playback_customizations, and get_thumbnail_customizations, though it does not name those alternatives explicitly.

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

Usage Guidelines3/5

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

The 'explicitly-set' qualifier implies this returns only overridden values, but the description never states when to use this vs. other get_*_customizations siblings or the generic get_customizations. Usage is implied, not instructed.

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

get_brandShow BrandB

Read-onlyIdempotent

Returns the brand with the given id.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`brand_id`	Yes	The id of the brand.

TDQS

B3.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations do not: the required permission scope ('Read all data') and the delegated-permission mode via the all:delegate_to_contact_permissions scope, which dictates whether a call will be authorized at all.

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

Conciseness3/5

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

The core statement is front-loaded in one clean sentence, but it is followed by a large block of permission boilerplate whose last line ('Read-only account operation.') merely restates the readOnlyHint annotation. The permission detail earns its place; the trailing fragment does not.

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

Completeness3/5

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

For a read tool with full annotation coverage and a fully documented schema, the main remaining gap is that no output schema exists and the description says nothing about what a returned brand contains. Authorization is well covered, but return shape is left entirely to inference.

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

Parameters3/5

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

Schema description coverage is 100% and both parameters (brand_id, account) are documented in the schema, including the non-obvious note that account selects credentials rather than a remote ID. The description adds no parameter-level meaning, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Returns the brand with the given id'), so an agent knows exactly what the call does. It does not differentiate itself from the very similar siblings get_brand_preload, list_brands, or update_brand, which leaves the sibling-selection burden on the name alone.

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

Usage Guidelines2/5

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

There is no guidance on when to use this rather than list_brands (to enumerate) or update_brand/delete_brand. The description never states prerequisites, alternatives, or exclusions beyond the permission scopes.

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

get_brand_kit_colorsGet Brand Kit ColorsA

Read-onlyIdempotent

Retrieves the current account's brand colors for the Wistia desktop app's background picker.

colors lists solid colors: every brand kit's color tokens (the colors the web editor offers as "Brand colors"), then each brand's primary and page background color when it is solid, default brand first. Values are six-digit hex strings, and a repeated color is listed once. Tokens whose value isn't a hex color are left out. An account without a brand kit gets its player color in place of the kit, which is what its default brand kit would hold.

brand_gradients lists each brand's primary and page background color that is set to a gradient, as color stops sorted by position, default brand first. Stops whose color isn't a hex color are left out, and a gradient with fewer than two hex stops left isn't listed.

Requires api token with one of the following permissions

(any scope allowed)

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A4/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context the annotations do not: deduplication of repeated colors, omission of non-hex tokens, gradient stop sorting/omission rules, and the fallback to player color for accounts without a brand kit. This is substantive beyond-structured-fields disclosure.

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

Conciseness4/5

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

The purpose is front-loaded in the first sentence and the return-value details are organized into two labeled blocks (`colors` and `brand_gradients`). It is longer than typical, but since there is no output schema this detail earns its place; only the permission boilerplate is filler.

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

Completeness5/5

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

With no output schema, the description fully carries the burden of explaining return shape and edge cases: hex format, dedup, gradient stop ordering, and the no-brand-kit fallback are all covered. Nothing an agent would need to interpret the result is missing.

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

Parameters3/5

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

With 100% schema description coverage and a single parameter, the schema already documents `account` (including that it selects credentials, not a remote ID). The description adds no parameter-level detail, so the baseline 3 is appropriate.

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

Purpose5/5

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

The description states a specific verb+resource (retrieves the current account's brand colors) and even names the concrete consumer (the Wistia desktop app's background picker). An agent can distinguish this from get_brand, list_brands, and get_brand_preload 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.

Usage Guidelines3/5

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

It implies the usage context — feeding a background picker with brand colors and gradients — but never states when to use this tool versus siblings like get_brand or get_brand_preload, nor any exclusions. Usage is inferred rather than directed.

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

get_brand_preloadGet Brand PreloadA

Read-onlyIdempotent

Retrieves Brandfetch-derived brand info for the current account's contact domain, plus a boolean indicating whether the account already has any brand kits configured. Used by Glass onboarding to preload the brand kit for new signups on business-email domains.

Returns brandfetch_brand with nil primary_color/logo/domain for free-mail domains, Wistia's own domain, when the Brandfetch feature flag is off, or when Brandfetch has no data : the caller silently skips the preload in every such case. The object itself is always present; only its fields go nil.

Requires api token with one of the following permissions

(any scope allowed)

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A4/5.0

Behavior5/5

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), it discloses important behavioral nuances: nil primary_color/logo/domain for free-mail domains, Wistia's own domain, feature-flag off, or no Brandfetch data, and that the object is always present with only fields going nil. It also covers token/permission requirements and delegation behavior.

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

Conciseness4/5

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

The description is front-loaded with purpose, then return behavior, then auth requirements, with each block earning its place. The permission boilerplate is somewhat verbose but standard and useful for invocation.

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

Completeness5/5

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 explaining the returned object and its nil-field edge cases, and it documents the authorization requirements. An agent has what it needs to call this correctly and interpret the result.

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

Parameters3/5

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

Schema description coverage is 100% and the single 'account' parameter is already documented in the schema as selecting credentials. The description adds no further meaning to the parameter, so the baseline of 3 applies.

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

Purpose4/5

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

The description states a concrete verb and resource: it retrieves Brandfetch-derived brand info for the current account's contact domain plus a boolean about existing brand kits. The scope is narrow and specific (onboarding preload), which implicitly separates it from general brand tools like get_brand, though no sibling is named explicitly.

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

Usage Guidelines3/5

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

It gives a usage context ('Used by Glass onboarding to preload the brand kit for new signups on business-email domains'), which implies when the tool applies. However, there is no explicit guidance on when to prefer this over siblings such as get_brand or get_brand_kit_colors, and no stated exclusions beyond the internal skip cases.

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

get_captionsShow CaptionsA

Read-onlyIdempotent

Returns a media's captions in the specified language. Supports multiple formats: JSON (default), SRT, VTT, and TXT. Use file extensions (.srt, .vtt, .txt) or Accept headers to specify format.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`include`	No	Set to `segments` for time-coded caption cues or `diarized_segments` for speaker-turn segments in JSON responses.
`language_code`	Yes	The 3-character ISO 639-2 language code of the captions to be retrieved (e.g., `eng`, `fra`, `spa`). Some languages use extended IETF subtags (e.g., `zh-Hant`).
`media_hashed_id`	Yes	The hashed ID of the media from which captions are to be retrieved.
`include_speakers`	No	For TXT responses, set to true to group the transcript by speaker turns and include speaker labels. Ignored for other response formats.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds substantive behavior beyond that: the required API token permission, the delegation scope for team-member tokens, and that include_speakers is ignored outside TXT responses.

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

Conciseness5/5

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

Front-loaded with the core action, then format options, then permissions in a headed block. Sentences are compact and each carries distinct information with no filler.

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

Completeness4/5

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 explaining return shape, and it does so adequately by naming the four formats and the segment/diarized_segments options. Only minor gaps remain, such as pagination or size limits for large transcripts.

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

Parameters4/5

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

Schema coverage is 100%, which sets the baseline at 3. The description adds meaning the schema lacks, specifically the mechanism for selecting output format via extensions or Accept headers, a format control that has no corresponding entry in the input schema.

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

Purpose4/5

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

The description states a specific verb and resource ('Returns a media's captions') plus scope ('in the specified language'). It is clear what the tool does, though it never names or contrasts itself with near siblings such as list_captions, list_all_captions, or get_media_extended_audio_description.

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

Usage Guidelines3/5

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

It explains how to request formats (file extensions or Accept headers) and that is the default, which gives real invocation context. However, it offers no when-to-use guidance relative to the many other caption/transcript tools in the sibling list, so alternative selection 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.

get_channelShow ChannelA

Read-onlyIdempotent

Returns the Channel associated with the hashedId.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`channel_hashed_id`	Yes	The hashed ID of the channel.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful auth context beyond annotations: required permission scopes and delegated-token behavior. It also confirms 'Read-only account operation,' consistent with readOnlyHint. It does not describe error behavior or return format, but the auth detail is valuable.

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

Conciseness4/5

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

The core purpose is front-loaded in one sentence, followed by permission details. The permission block is somewhat heavy with code fences, but every part is relevant to invoking the tool. It is appropriately sized for a simple read operation, though the auth section could be tightened.

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

Completeness4/5

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

For a simple read-by-ID tool with full schema coverage and no output schema, the description covers purpose, required permissions, and read-only nature. It does not explain what a Channel contains or behavior when the hashedId is invalid, but these are minor gaps for a straightforward retrieval tool.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description mentions the hashedId as the identifier but adds no syntax, format, or validation detail beyond what the schema provides. Baseline 3 is appropriate when the schema carries parameter semantics.

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

Purpose4/5

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

The description states a specific verb and resource: returns the Channel associated with the hashedId. It clearly identifies a single-resource retrieval operation. However, it does not explicitly differentiate this tool from siblings like list_channels or get_channel_episode, so it falls short of a 5.

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

Usage Guidelines3/5

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

The description provides a prerequisite: an API token with the 'Read all folder and media data' permission, and mentions delegated token permissions. It does not state when to use this tool versus list_channels or other retrieval alternatives, leaving alternative selection to inference. This is implied usage context rather than explicit when-to-use guidance.

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

get_channel_episodeShow Channel EpisodeA

Read-onlyIdempotent

Returns the Channel Episode associated with a channel hashed id and channel episode hashed id.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`channel_hashed_id`	Yes	The hashed ID of the channel.
`channel_episode_id`	Yes	The hashed ID of the channel episode.

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds genuinely useful context beyond them: the specific required permission scope and the delegate-token authorization behavior. It does not describe error behavior for a missing episode, so it is strong but not exhaustive.

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

Conciseness4/5

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

The core purpose is front-loaded in the first sentence and is immediately actionable. The permission block that follows is more verbose than needed and mixes scope names with markdown, but it carries real auth information so it is not filler.

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

Completeness4/5

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

For a simple read-only resource fetch with full annotations and no output schema, the key operational detail an agent needs (required token permission) is present. What is missing is minor: no note on behavior when the id is invalid or not found.

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

Parameters3/5

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

Schema description coverage is 100%, so both required hashed-id parameters and the account selector are already documented in the schema. The description merely names the same ids without adding format, sourcing, or fallback semantics, so the baseline 3 is appropriate.

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

Purpose4/5

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

States a specific verb ('Returns') plus the exact resource ('Channel Episode') and the two identifiers that key it, which cleanly distinguishes it from siblings like list_channel_episodes or get_channel. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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

Usage Guidelines2/5

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

The description never says when to use this single-fetch tool versus list_channel_episodes, list_channel_episodes_by_channel, or get_channel, and gives no exclusions or prerequisites beyond the token scope. Usage is only implied by the verb 'Returns'.

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

get_chapters_customizationsShow Chapters CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set chapter customizations (the chapter list and its visibility) for the media.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the media.

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive/open-world safety, but the description adds meaningful context beyond them: the exact token scopes required and the delegate-token authorization behavior, plus the semantic that only 'explicitly-set' customizations are returned. No rate limits, pagination, or error behavior are mentioned.

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

Conciseness4/5

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

The purpose is front-loaded in a single clear sentence, and the permission block that follows is relevant to invocation. The closing 'Read-only account operation' is redundant with the readOnlyHint annotation and the block is somewhat boilerplate-heavy.

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

Completeness4/5

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

For a low-complexity read getter with rich annotations and a fully documented 2-parameter schema, the description covers purpose, returned content, and auth requirements adequately. No output schema exists, and the brief return description ('chapter list and its visibility') is sufficient at this complexity.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds no syntax, format, or constraint details for media_id or account, making the baseline 3 appropriate.

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

Purpose4/5

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

States a specific verb ('Fetches') and a precise resource ('explicitly-set chapter customizations (the chapter list and its visibility) for the media'), which separates it from the other get_*_customizations siblings. It never names or contrasts an alternative (e.g. update_chapters_customizations), so it stops short of full sibling differentiation.

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

Usage Guidelines2/5

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

The description provides permission prerequisites but no when-to-use guidance or routing to alternatives, despite many sibling getters (get_customizations, get_appearance_customizations, update_chapters_customizations). An agent must infer when this chapter-specific read applies.

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

get_credit_balanceGet Credit BalanceA

Read-onlyIdempotent

Retrieves the current account's available credit balance and expected next recurring credit grant time.

The balance is a near-real-time hint and can lag one in-flight metered operation. A 402 response from an operation is authoritative when deciding whether more credits are required. Negative ledger balances are returned as 0 available credits.

next_grant_at comes from the account's billing schedule, not an existing grant's expiration. It is null when no scheduled grant can be determined. Processing may occur later, and other grants may arrive sooner.

Requires api token with one of the following permissions

(any scope allowed)

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. The account is always derived from the authenticated token; this endpoint does not accept an account identifier. Read-only account operation.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations (readOnly/idempotent/openWorld) by disclosing the lag window versus in-flight metered operations, the authoritative 402 signal, that negative ledger balances are clamped to 0, and the source and null semantics of next_grant_at.

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

Conciseness4/5

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

Front-loads the core purpose and follows with behavioral caveats, then a permission block. The permission section is somewhat templated but relevant, and no sentence is wasted.

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

Completeness5/5

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

For a read-only balance tool with no output schema, the description covers interpretation of the value, edge cases (negative balances, null next_grant_at), and auth requirements, leaving nothing material an agent needs to call it correctly.

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

Parameters4/5

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 meaningful semantics by clarifying that the account is always derived from the authenticated token and that the endpoint accepts no account identifier, reinforcing what the 'account' parameter actually selects.

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

Purpose5/5

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

States a specific verb and resource ('Retrieves the current account's available credit balance') plus the secondary output ('expected next recurring credit grant time'). It is unambiguously distinct from siblings like get_account_usage or get_account_stats.

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

Usage Guidelines4/5

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

Gives clear interpretive context: the balance is a near-real-time hint that may lag, and a 402 is authoritative when deciding whether more credits are required. It does not explicitly name an alternative tool to use instead, but the when-to-trust guidance is strong.

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

get_current_tokenGet Current TokenA

Read-onlyIdempotent

Retrieves a summary of the token used to make the API request. This endpoint can primarily be used to debug permission issues with the API. Read-only account operation.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description's 'Read-only account operation' largely restates that. It adds the diagnostic purpose (permission debugging) but doesn't describe what the summary contains or whether the token value itself is exposed, which matters for a token tool.

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

Conciseness5/5

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

Three short sentences with no waste; the core action is front-loaded and the diagnostic purpose follows immediately. Every sentence contributes.

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

Completeness4/5

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

For a trivial debug endpoint with no output schema, the description conveys the essential shape of the return ('a summary of the token') and the reason to call it. It stops short of detailing the summary fields, but nothing critical to correct invocation is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the single 'account' parameter is documented in the schema as selecting credentials rather than a remote account ID, so the schema carries the semantic load. The description adds nothing about the parameter, 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.

Purpose5/5

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

States a specific verb and resource ('Retrieves a summary of the token used to make the API request'), which is unambiguous and cannot be confused with any sibling tool in the list. An agent knows exactly what will be returned 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.

Usage Guidelines4/5

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

Explicitly states the intended use case: 'primarily be used to debug permission issues with the API.' That gives clear context for when to reach for this tool, though it names no alternative or exclusion (there is no obvious sibling alternative for token introspection).

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

get_customizationsShow CustomizationsB

Read-onlyIdempotent

Fetches explicitly defined customizations for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

B3.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value by stating the required token permission ('Read all folder and media data') and the delegation scope behavior, but says nothing about what 'explicitly defined' means or what is returned.

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

Conciseness3/5

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

The one-sentence purpose is front-loaded and clear, but it is followed by a large fenced permission block that dominates the description's length. The permission text earns some place, yet the prose around it ('Read-only account operation') is redundant with the readOnlyHint annotation.

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

Completeness3/5

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

For a read-only tool with no output schema, the description does cover authentication requirements, which is the main non-obvious burden. It is still incomplete on the two things an agent most needs here: which customization scope this returns versus its many siblings, and what 'explicitly defined' excludes.

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

Parameters3/5

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

Schema description coverage is 100%: media_id ('hashed ID of the video') and account ('named private Wistia account') are already documented in the schema. The description adds no parameter meaning 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.

Purpose4/5

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

States a specific verb and resource ('Fetches ... customizations for the video'), so an agent knows it is a read of customization data. However, with ~10 sibling getters (get_appearance_customizations, get_playback_customizations, get_thumbnail_customizations, etc.) the bare 'customizations' resource is not disambiguated, and the qualifier 'explicitly defined' is never explained.

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

Usage Guidelines2/5

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

No when-to-use guidance, no conditions, and no routing to the numerous sibling customization getters (e.g. get_appearance_customizations vs get_playback_customizations). The only contextual text is authentication/permission boilerplate, which is not usage guidance.

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

get_engagement_customizationsShow Engagement CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set engagement customizations (the end/pause Call To Action and timed annotation links) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds real value beyond that: the exact permission scopes required and the delegation-token behavior (authorized as the assigned contact), which an agent cannot derive from annotations 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.

Conciseness3/5

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

The leading sentence is well front-loaded and efficient, but the description then spends most of its length on a fenced permission block plus delegation details. That content is legitimate auth guidance, yet its bulk outweighs the one-line functional summary and buries the actual behavior.

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

Completeness4/5

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

For a read-only getter with no output schema, the description covers purpose, the specific fields returned conceptually, and full authorization requirements. It is nearly complete, with the only gap being no indication of the response shape or what an empty/explicitly-unset result looks like.

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

Parameters3/5

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

Schema coverage is 100%, so media_id and account are already fully documented, and the description adds no per-parameter detail. The word 'explicitly-set' implies unset customizations are omitted from the result, which is a mild semantic addition, but it is not tied to any parameter. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb (Fetches), resource (engagement customizations), scope (explicitly-set), and even defines the two sub-resources involved (end/pause Call To Action and timed annotation links). It distinguishes this from the generic get_customizations, though it never names the paired write tool update_engagement_customizations explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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 read counterpart to update_engagement_customizations, but the description never states when to prefer it over get_customizations or the other per-category getters. It does give the required token permissions, which is genuine usage guidance of a sort.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_eventShow EventA

Read-onlyIdempotent

Retrieve information for a single event. Please note that due to our data retention policy, only events from the last 2 years are available.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`event_key`	Yes	The unique key of the event.

TDQS

A3.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, and non-destructive behavior, but the description adds significant context: a two-year retention limit, required permissions ('Read detailed stats' or delegated token scope), and how delegation authorizes requests. This meaningfully reduces ambiguity beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, followed by the retention note and required permissions in a logical order. The permissions block is somewhat lengthy but necessary, and the final 'Read-only account operation' slightly duplicates the readOnlyHint annotation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-single-event tool, the description covers purpose, retention limits, and authorization requirements well. It does not describe return fields, but given no output schema and the tool's simplicity, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents the two parameters. The description adds no additional meaning about event_key format or account selection, so it meets the baseline of 3 without adding value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Retrieve information for a single event.' This clearly distinguishes it from list-oriented siblings like list_events, though it does not name an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides important prerequisites (data retention window, required permissions) but does not explicitly say when to use this tool versus siblings such as list_events or search. Usage is implied by 'single event' and the event_key requirement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_folderShow FolderB

Read-onlyIdempotent

Retrieves a single folder (previously called project).

Requires api token with one of the following permissions

Read all folder and media data

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization for this folder can also be used; any permission granted on a folder allows showing it. Read-only account operation.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Folder Hashed ID
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

B3.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact permission scopes required, delegated-token semantics, and expiring access token support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in one good sentence, but the body repeats the same delegated-token point across three paragraphs (delegate_to_contact_permissions scope, then expiring tokens with that scope again) and ends with a dangling 'Read-only account operation.' fragment.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Auth requirements are thorough and the input schema is fully documented, but with no output schema the description never indicates what a folder object contains or how the id/account pair maps to a result. Adequate but incomplete for a retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with 'id' documented as 'Folder Hashed ID' and 'account' explained as a credential selector. The description adds nothing further about the parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieves a single folder') and notes the legacy alias 'project', which helps agents reconcile older terminology. It does not explicitly contrast with list_folders or get_subfolder, so sibling differentiation is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus list_folders, get_subfolder, or search. The only conditional content is about token types, which is authorization eligibility rather than usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_folder_sharingShow Folder SharingA

Read-onlyIdempotent

Retrieves the details of a specific sharing object for a given folder.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`folder_id`	Yes	Hashed ID for the folder for which you'd like to see sharings.
`sharing_id`	Yes	The ID of the specific sharing object that you want to see.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding auth context: the required 'Read all data' permission and the delegated 'all:delegate_to_contact_permissions' token path. This is real behavioral context not present in the structured fields, though it doesn't cover rate limits or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded and the permission block follows as supporting detail. It is somewhat boilerplate-heavy for a simple read tool but every section is relevant and no sentence is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, 3-parameter tool with full schema coverage and a complete annotation set, the description plus auth requirements cover what an agent needs. The lack of an output schema is acceptable since the return is a described 'sharing object', though its fields are not characterized.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so folder_id and sharing_id are already fully documented in the schema. The description only restates that a folder and a specific sharing object are involved, adding no format or constraint detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Retrieves the details of a specific sharing object for a given folder.' This clearly distinguishes it from a list operation, though it never names the closest siblings (list_folder_sharings, create/update/delete_folder_sharing) explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance. An agent must infer from 'specific sharing object' that this is the single-item counterpart to list_folder_sharings, and nothing addresses ordering, error cases, or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_job_statusShow Background Job StatusA

Read-onlyIdempotent

Retrieves the status of a background job.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`background_job_status_id`	Yes	The hashed ID or numeric ID of the background job

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable beyond-annotation context: the required API token permission ('Read all data') and delegate token behavior, which is exactly the kind of auth-need disclosure that helps an agent. The final 'Read-only account operation' line is redundant but harmless.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose in one sentence, then provides a clearly formatted permission requirement block. It is slightly verbose due to the markdown heading and a redundant final line, but overall well-structured and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read operation with a fully described schema and comprehensive annotations, the description covers purpose and authentication. It does not explain what the returned status looks like or any polling behavior, but no output schema exists and the omission is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no additional meaning about parameter syntax or format, leaving it at the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Retrieves the status of a background job.' This is clear and unambiguous, but it does not differentiate from similar status-retrieval siblings such as get_order_status or get_account.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (when you need the status of a background job) and provides explicit authentication prerequisites, but it offers no guidance on when to choose this tool over alternatives or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_lead_capture_customizationsShow Lead Capture CustomizationsB

Read-onlyIdempotent

Fetches the explicitly-set lead-capture plugins (Turnstile, Wistia Form, and HubSpot/Marketo/Pardot form embeds) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds substantive context: the exact auth permission required ('Read all folder and media data'), and that delegated tokens (all:delegate_to_contact_permissions) authorize via the assigned contact. The 'explicitly-set' distinction also discloses a scope nuance beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, which is good, but the auth block is verbose and restates the required scope in prose plus a bulleted heading, and 'Read-only account operation' duplicates the readOnlyHint annotation. Some redundancy dilutes efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-param read-only tool with no output schema, the description covers purpose, plugin scope, and the full auth model, which is more than most definitions provide. It is slightly short on output expectations and sibling differentiation, but the complexity is low so little is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters, giving a baseline of 3. The description adds no parameter-level detail (e.g., what happens with a missing/blank media_id) beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) and resource (explicitly-set lead-capture plugins) for the video, and even enumerates the plugin types (Turnstile, Wistia Form, HubSpot/Marketo/Pardot embeds). However, it does not explicitly distinguish itself from the sibling update_lead_capture_customizations, which an agent could confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use guidance beyond the auth requirement. The 'explicitly-set' qualifier implies a read of configured state rather than defaults, but nothing states when to call this vs. get_customizations or the update counterpart.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_localizationShow LocalizationB

Read-onlyIdempotent

Obtain detailed information about a localization.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_hashed_id`	Yes	The hashed ID of the localization's media.
`include_transcript`	No	Whether to include the transcript in the response.
`localization_hashed_id`	Yes	The hashed ID of the localization.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds genuinely useful context by spelling out the required token permission scopes ('Read all data' / delegated contact permissions), but says nothing about error behavior or response shape. Adds value beyond annotations without being rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is properly front-loaded and the auth requirements are relevant, but roughly two-thirds of the text is permission boilerplate restating scopes and the closing 'Read-only account operation' is redundant with readOnlyHint=true. Reasonably sized but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only getter with no output schema, the description plus annotations cover the essentials: what it returns (details of one localization), how to authenticate, and the safety profile. It lacks any hint about response contents (e.g., transcript flag implications), which is a minor gap rather than a blocker.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the optional include_transcript flag and the account credential selector. The description adds no additional parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Obtain detailed information about a localization.' This clearly signals single-item retrieval and, combined with the required media/localization IDs, distinguishes it from list_localizations and create/delete_localization. It does not explicitly name sibling alternatives, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance, no exclusions, and no routing to alternatives like list_localizations or get_media. An agent must infer that this is the single-localization read path purely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_mediaShow MediaA

Read-onlyIdempotent

Fetches a single media by its hashed id.

Requires api token with one of the following permissions

Read all folder and media data

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization for this media can also be used; any permission granted on a media allows showing it. Read-only account operation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`include`	No	Set to `speakers` to include active transcript speaker assignments used for diarization. Webinar hosts and panelists are not included.
`media_hashed_id`	Yes	The hashed ID of the media.
`description_format`	No	Format for media descriptions

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial context: required permissions, delegated token behavior, and expiring token support. This goes beyond annotations. Minor gap: no mention of error behavior or response format, but that's acceptable given annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly verbose and includes token permission details that are not directly about the tool's operation. The core purpose is front-loaded but then followed by a large block of authentication boilerplate that could be separated or summarized. It does not earn its place for a simple fetch tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and the tool is a simple read operation, the description covers necessary auth requirements and the basic action. It lacks details on what the returned media object contains, but that may be expected from the API. It is mostly complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all parameters, including the media_hashed_id, include enum, account, and description_format. The description adds no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Fetches a single media by its hashed id'. Clear and unambiguous. However, it does not differentiate from siblings like get_media_stats, get_media_analytics, or list_media, so it falls short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists required permissions and token types, which implicitly guide when the tool can be used, but does not explicitly say when to use this vs. alternatives like list_media or get_media_stats. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_analyticsShow Media AnalyticsA

Read-onlyIdempotent

Retrieve aggregate analytics for a video over a date range. This endpoint provides Bottler-powered analytics including plays, loads, engagement rate, play rate, and conversion metrics.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`media_id`	Yes	The hashed ID of the video.
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is to add context. It adds the 2-year date range ceiling and detailed auth requirements (required permission scope, delegate_to_contact_permissions behavior), which are genuinely useful beyond the annotations. It does not describe return shape or pagination behavior, keeping it out of the top band.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first two sentences are front-loaded and efficient, but the lengthy auth boilerplate (permission scope code block, delegate_to_contact explanation, read-only note) adds bulk that could be a single line or delegated to auth documentation. Structure is functional but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analytics tool with no output schema and full annotation coverage, the description supplies the essential missing pieces: metric scope, date-range constraint, and auth requirements. Return-value shape is undefined, but given annotations and the aggregate focus, an agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all four parameters including the exclusive/inclusive date semantics. The description only reinforces the date range constraint (2 years) already implied by the schema; it adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Retrieve) and resource (aggregate analytics for a video) with named metrics (plays, loads, engagement rate, play rate, conversions). This separates it clearly from siblings like get_media_stats, get_media_analytics_timeseries, and get_media_traffic_breakdown which cover different analytics surfaces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a constraint (date range must not exceed 2 years) but does not state when to use this tool versus the many adjacent analytics siblings (timeseries, traffic breakdown, engagement, account-level analytics). Usage is implied by the 'aggregate' framing but no explicit routing guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_analytics_timeseriesShow Media Analytics TimeseriesB

Read-onlyIdempotent

Retrieve analytics timeseries data for a video over a date range with configurable granularity. Returns an array of timestamped metric buckets.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`media_id`	Yes	The hashed ID of the video.
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`granularity`	Yes	The time granularity for the timeseries data.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds valuable behavioral constraints: the 2-year maximum date range and the required API token permission ('Read detailed stats') including delegation scope details. However, it does not disclose rate limits, pagination, or other operational traits beyond what is already in annotations and schema. With annotations covering basics, this added context earns a 3.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose in the first sentence, followed by return format and a key constraint. The second paragraph on permissions is somewhat verbose but necessary for authorization context. Overall efficient with little waste, though could be slightly more compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, 4 required), rich schema with 100% coverage, and comprehensive annotations, the description is largely complete. It covers purpose, return format, a critical constraint, and authorization. It lacks guidance on alternative tools, which would improve completeness for an agent selecting among many siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all parameters in detail (including date inclusivity/exclusivity and granularity enum). The description adds the 2-year range constraint, which is a valuable semantic detail not present in the schema. However, it still relies on the schema for most parameter meaning, warranting the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (retrieve), resource (analytics timeseries data for a video), and scope (over a date range with configurable granularity), and mentions the return format ('array of timestamped metric buckets'). It distinguishes itself from sibling tools like get_media_analytics (which likely returns aggregated analytics) and get_account_analytics_timeseries by specifying 'for a video'. However, without explicit naming of the sibling alternative, it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives such as get_media_analytics, get_account_analytics_timeseries, or get_media_stats. It only implies usage by describing the output. No when-not-to-use or alternative conditions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_embed_locationsShow Media Embed LocationsA

Read-onlyIdempotent

Retrieve embed location analytics for a video. Returns a list of pages where the video is embedded, ranked by the chosen metric.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	The metric to sort embed locations by.	plays
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`media_id`	Yes	The hashed ID of the video.
`per_page`	No	Number of results to return (max 100).
`embed_url`	No	Filter results to a single embed URL. When provided, only analytics for the page matching this URL are returned. The protocol is optional (https is assumed).
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`sort_direction`	No	The sort direction.	desc

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the safe read-only, idempotent profile. The description adds genuinely useful context beyond them: the 2-year maximum date span and the required token permission ('Read detailed stats', including delegation semantics). This is real behavioral disclosure, though it says nothing about pagination limits or result caps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return in the first two sentences, then the constraint, then permissions. The permissions block is lengthy but operationally relevant; the trailing 'Read-only account operation.' is slightly redundant with the annotations but harmless.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter analytics tool with no output schema, the description explains the return, the key date constraint, and the auth requirement, which covers what an agent needs to invoke it correctly. It lacks alternative-routing guidance against sibling analytics tools, keeping it short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for every parameter, including exclusion/inclusion date semantics and enum choices, so the schema does the heavy lifting. The description only adds 'ranked by the chosen metric,' which maps loosely to sort_by but contributes little beyond the enum already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Retrieve) and resource (embed location analytics for a video) plus the return shape (list of pages ranked by metric). This clearly distinguishes it from account-level (get_account_embed_locations) and timeseries (get_media_embed_locations_timeseries) siblings without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose implies when to use it, and the 2-year date-range constraint is stated, but there is no explicit guidance on when to choose this over the closely related get_account_embed_locations or get_media_embed_locations_timeseries tools. Usage is implied rather than directed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_embed_locations_timeseriesShow Media Embed Locations TimeseriesA

Read-onlyIdempotent

Retrieve timeseries analytics for a video broken down by embed location. Returns an array of timestamped buckets, each containing metrics for the top embed locations (ranked by the chosen metric) plus an "All other" entry aggregating the remaining locations.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	The metric used to rank and select the top embed locations.	plays
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`media_id`	Yes	The hashed ID of the video.
`per_page`	No	Number of top embed locations per time bucket (max 100). Remaining locations are aggregated into an "All other" entry.
`embed_url`	No	Filter results to a single embed URL. When provided, only analytics for the page matching this URL are returned. The protocol is optional (https is assumed).
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`granularity`	Yes	The time granularity for the timeseries data.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine operational context: the 2-year date-range ceiling, the required 'Read detailed stats' permission, delegated-token semantics, and the 'All other' aggregation behavior. It stops short of stating rate limits or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return shape, followed by the hard constraint and then the auth block. The permission/boilerplate section is somewhat verbose but each element is actionable; nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 compensates by describing the bucket structure and aggregation entry, and it covers auth and date constraints. For an 8-parameter analytics tool it is nearly complete, only missing explicit sibling routing and pagination/return-volume detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 real meaning beyond the schema by tying sort_by to how locations are ranked and per_page to the 'All other' bucket — a relationship the schema documents only piecemeal per property.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (timeseries analytics for a video broken down by embed location) and even sketches the return shape (timestamped buckets, top locations, 'All other'). This clearly distinguishes it from the non-timeseries sibling get_media_embed_locations, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the scope (timeseries by embed location) and the description supplies real prerequisites — the 2-year max date range and the required token permission. However it names no alternatives (e.g. get_media_embed_locations for totals, get_media_analytics_timeseries for non-embed breakdowns) or when-not conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_engagementShow Media EngagementB

Read-onlyIdempotent

Retrieve engagement data for a video. This endpoint provides engagement data for a specific video identified by its media-id.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID or ID of the video for which you want to retrieve engagement data.

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact permission scope required ("Read detailed stats") and the delegated-permission path via all:delegate_to_contact_permissions, which is real operational information an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded and tight, but it is followed by a bulky verbatim permission boilerplate block that consumes most of the text. The boilerplate is useful for auth but is not proportionate to a two-parameter read tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only, single-required-param tool with no output schema, auth and scope coverage are adequate. What is missing is any indication of what "engagement data" contains (plays, engagement rate, heatmap?), which the agent needs since no output schema defines the return shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, including the account parameter's non-obvious meaning ("selects credentials, not a remote account ID"). The description only restates that lookup is by media-id and adds nothing on format or ID variants, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ("Retrieve engagement data for a video") and specifies the identifying key (media-id). However, it does not distinguish itself from closely named siblings such as get_media_analytics, get_media_stats, or get_engagement_customizations, so an agent cannot tell which engagement-adjacent tool returns what.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description names the required permission but gives no when-to-use guidance, no exclusions, and no routing to alternatives among the many media/analytics siblings. The agent must infer that this is the per-video engagement endpoint rather than a customization or stats endpoint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_extended_audio_descriptionShow Media Extended Audio DescriptionA

Read-onlyIdempotent

Retrieves a single extended audio description by its hashed id, including download links. Read-only account operation.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	The hashed id of the Media Extended Audio Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so 'Read-only account operation' largely restates the structured data. The genuinely additive detail is that the response includes download links, which is useful but thin beyond what 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and lookup key, with no filler. Slightly tighter wording could fold the safety note in, but it is efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-resource read with no output schema, the description conveys the key, the payload (download links) and the safety profile. It is adequate, though it does not mention error behavior when the id is missing or invalid.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'id' and 'account' semantics are already documented in the schema, including the note that 'account' selects credentials rather than a remote ID. The description mentions only the hashed id and adds nothing the schema does not already carry.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (retrieves), a singular resource (a single extended audio description), the lookup key (hashed id), and the payload (download links). It clearly reads as the single-item fetch counterpart to the sibling list_media_extended_audio_descriptions, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by its hashed id' implies the tool is for fetching one known record, which implicitly distinguishes it from the list and delete siblings. However, it never states when to prefer this over list_media_extended_audio_descriptions or what to do if the id is unknown, so guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_form_conversionsShow Media Form ConversionsA

Read-onlyIdempotent

Retrieve form conversion data for a video. Returns a paginated list of form submissions with visitor details and timestamps.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`cursor`	No	Cursor for pagination. Use the value from the previous response's page_info.end_cursor.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`media_id`	Yes	The hashed ID of the video.
`per_page`	No	Number of results to return (max 100).
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this as a read-only, idempotent, open-world, non-destructive operation. The description goes beyond them by disclosing the authorization requirements (specific permission or delegated token) and the 2-year date-range limit, which are real behavioral constraints an agent must respect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and return shape in the first sentence, followed by the date constraint. The permission block is boilerplate-heavy but relevant to correct use; slightly more text than strictly needed but no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 shape (paginated submissions with visitor details and timestamps) and the auth/date constraints. For a read-only, six-parameter analytics tool this is nearly complete; only sibling differentiation would add value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 the cross-parameter constraint that start_date/end_date must span no more than 2 years — information not present in the schema. It also confirms the response is paginated, reinforcing the cursor parameter's purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Retrieve form conversion data for a video', plus the concrete return content (form submissions with visitor details and timestamps). It is clearly distinguishable from generic stat tools like get_media_stats, though it never explicitly contrasts itself with the analytics siblings in the list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful prerequisites (required permission, delegation scope) and a hard constraint (date range must not exceed 2 years), which guides correct invocation. However, it gives no explicit when-to-use/when-not guidance versus adjacent tools such as get_media_stats or get_media_analytics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_languagesShow Media LanguagesA

Read-onlyIdempotent

Retrieve language analytics for a video. Returns a breakdown of plays by viewer browser language, sorted by number of plays in descending order.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`media_id`	Yes	The hashed ID of the video.
`per_page`	No	Number of results to return (max 100).
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only safety, but the description adds substantial behavioral context beyond them: the 2-year maximum date range constraint and the specific auth requirement ('Read detailed stats' permission, delegated token support). These are non-obvious operational details that the annotations do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and date-range limit are front-loaded efficiently, but the token/permission boilerplate is verbose and partially redundant with the readOnly annotation. The structure is functional but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analytics tool with no output schema and full schema coverage, the description covers purpose, return shape, range limit, and auth requirements. It is nearly complete; only explicit sibling routing would push it higher.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all parameters including the exclusive end_date semantics. The description only reinforces the date-range constraint (2 years), which is the one parameter-related fact not in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Retrieve language analytics for a video') and describes the exact output breakdown (plays by viewer browser language, sorted descending). This distinguishes it from sibling analytics tools like get_media_stats and get_media_traffic_breakdown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is for language-specific analytics on a single video but names no alternative when a different dimension is needed (e.g., get_media_traffic_breakdown). Usage context is implied rather than explicit, which is the minimum viable level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_statsShow Media Aggregated StatsB

Read-onlyIdempotent

Aggregated tracking statistics for a video embedded on your site.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_hashed_id`	Yes	The hashed ID of the video.

TDQS

B3.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine value beyond that: the exact permission scopes required and the delegated-token behavior, which the agent cannot infer from structured fields. It stops short of a 5 because return/aggregation behavior is undocumented.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core sentence is front-loaded and efficient, but the bulk of the text is verbose boilerplate about token permissions and delegation. It is arguable whether all of that earns its place versus a terse 'requires Read access' note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

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 carries the burden of explaining what 'aggregated tracking statistics' actually returns (plays, engagement, heatmap?). It also fails to aid disambiguation among numerous stats siblings, leaving the agent under-informed for a stats call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, media_hashed_id) are already documented in the schema. The description adds no syntax, format, or meaning 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and scope: 'Aggregated tracking statistics for a video embedded on your site.' An agent can grasp what it returns. However, it offers no differentiation from the many stats siblings (get_media_stats_by_date, get_media_stats_stats_media, get_media_analytics), so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance and no mention of alternatives, despite a crowded set of stats siblings (by-date variant, stats_media variant, analytics tools). The agent is left to guess which stats tool to call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_stats_by_dateShow Media Stats by DateA

Read-onlyIdempotent

Retrieve stats for a media organized by day, between a start and end date paramater (inclusive). If start and end date are not provided, defaults to yesterday and today.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	No	The end date for the stats, formatted YYYY-MM-DD
`media_id`	Yes	The ID of the media
`start_date`	No	The start date for the stats, formatted YYYY-MM-DD

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the bar is lower. The description adds real value beyond them by disclosing the required API token permission ('Read detailed stats') and the delegation-scope alternative. It still omits return format and any pagination/limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior is front-loaded in the first sentence, then the auth requirements are grouped into a clearly demarcated block. There is minor redundancy (the 'Read-only account operation' trailing line) and a typo ('paramater'), but no wasted bulk.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no description of the returned stats shape (visitor counts, plays, engagement?), the agent cannot anticipate the response. Annotations and the auth block cover safety and permissions, but return-value context is the notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by documenting default semantics for start_date/end_date (defaults to yesterday and today) that the schema does not state. The 'account' parameter's credential-selection behavior is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource+scope: retrieve stats for a media, organized by day, within an inclusive start/end range. That is enough to distinguish it from aggregate siblings like get_media_stats, but it never names or contrasts with those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the 'by day' framing and the default window ('defaults to yesterday and today'), which tells the agent what happens when dates are omitted. However, there is no explicit when-to-use-this vs get_media_stats / get_media_stats_stats_media guidance despite many near-neighbor stats tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_stats_stats_mediaShow Media StatsB

Read-onlyIdempotent

Retrieve stats for a video. This endpoint provides statistics for a specific video identified by its media-id.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID or ID of the video for which you want to retrieve stats.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely useful context beyond them: the required "Read detailed stats" permission and the delegation behavior of the all:delegate_to_contact_permissions scope. It does not, however, say what the returned statistics contain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, which is good. The trailing "Read-only account operation." merely restates the readOnlyHint annotation and the permission block is rendered with stray blank lines and nested code fences, adding some noise without adding meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 carries the burden of telling the agent what comes back — it only says "statistics" without describing the shape of the return. Combined with the unresolved overlap against get_media_stats/get_media_stats_by_date, the definition is adequate but leaves real gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both media_id and account are already documented in the schema. The description merely restates that media-id identifies the video and adds no format, accepted-value, or fallback detail beyond what the schema provides — the baseline 3 for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource — "Retrieve stats for a video" — and clarifies that the video is identified by its media-id. However, it never distinguishes this tool from the near-identical siblings get_media_stats and get_media_stats_by_date, so an agent cannot tell which stats endpoint it actually wants from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this endpoint versus get_media_stats, get_media_stats_by_date, or get_media_analytics. The only conditional guidance is about token permissions, not about tool selection, so usage must be inferred entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_media_traffic_breakdownShow Media Traffic BreakdownA

Read-onlyIdempotent

Retrieve traffic breakdown analytics for a video, grouped by a specified dimension such as UTM campaign, UTM source, UTM medium, referrer domain, or viewer screen size.

The date range between start_date and end_date must not exceed 2 years.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	The metric to sort results by.	plays
`end_date`	Yes	End date for the analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date.
`group_by`	Yes	The dimension to group traffic data by.
`media_id`	Yes	The hashed ID of the video.
`per_page`	No	Number of results to return (max 100).
`start_date`	Yes	Start date for the analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date.
`sort_direction`	No	The sort direction.	desc

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the 2-year maximum date span, the specific 'Read detailed stats' permission requirement, and the delegation-token authorization behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by the key constraint and then the auth block. The permissions code block is somewhat verbose but relevant to correct invocation; little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Nominal completeness: purpose, constraint, and auth are covered, and annotations carry the safety profile. But with no output schema and no mention of return shape or pagination behavior for a paginated analytics query (per_page exists), the definition leaves observable behavior for the caller to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all 8 parameters are already documented and the baseline is 3. The description adds parameter-relevant meaning beyond the schema by enumerating valid group_by dimensions and imposing the 2-year window on start_date/end_date, which the schema does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Retrieve) and resource (traffic breakdown analytics for a video) and enumerates the grouping dimensions, so the agent knows exactly what it returns. It implicitly separates itself from get_webinar_traffic_breakdown via the 'for a video' scope, though it never names 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.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied through the date-range constraint and the required permission, giving the agent enough to know it's a read-only analytics call. However, there is no guidance on when to prefer this over get_media_analytics, get_media_stats, or get_webinar_traffic_breakdown, and no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_order_statusGet Order StatusA

Read-onlyIdempotent

Returns the current status of an extended audio description order. Use the order id returned from the order endpoint to poll for status updates. Read-only account operation.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	The hashed ID of the order returned from the order endpoint.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description mostly restates that ('Read-only account operation'). Its one additive behavior is the polling-a-status-update pattern, which is useful but modest against already-rich annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly packed sentences; the core behavior is front-loaded and the usage/lifecycle note follows immediately. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 carries the burden of explaining the return. It says it returns 'the current status' but never enumerates possible status values or terminating conditions, which an agent polling for completion would need. Adequate but with a real gap for a status-polling tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both the hashed id and the account credential selector are documented in the schema. The description only repeats that the id comes from the order endpoint, adding no syntax or format beyond structured data, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: returns the current status of an extended audio description order. This distinguishes it from the get_/list_media_extended_audio_description siblings, which retrieve the description asset rather than an order's status. Clear and specific, though it never explicitly names the alternative tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tells the agent when and how to use it: take the order id returned from the order endpoint and poll for status updates. That is clear actionable context including the polling lifecycle, but it offers no exclusions or named alternatives for cases where another tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_playback_customizationsShow Playback CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set playback customizations (autoplay, mute, controls visibility, player control buttons, end behavior, looping, quality bounds, and embed/runtime flags) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/destructive semantics, so the bar is lower. The description adds genuine context beyond them: the exact permission scopes required (including the delegate_to_contact token nuance) and the 'explicitly-set' vs default distinction, which is behaviorally important for interpreting the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The informative purpose sentence is front-loaded and dense but earns its place by enumerating returned fields. The permission block that follows is boilerplate-heavy and long, though clearly structured and separated so an agent can skip it. Slightly verbose overall but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so enumerating the returned field groups is valuable and present. Combined with the explicitly documented auth requirements and the read-only annotation profile, an agent has everything needed to call and interpret this getter correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, media_id) are already fully documented in the schema. The description adds nothing beyond 'for the video', which merely restates media_id. Baseline 3 is appropriate when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetches') and resource ('playback customizations') and enumerates the exact field group (autoplay, mute, controls visibility, end behavior, etc.). The 'playback' specificity clearly distinguishes it from siblings like get_appearance_customizations or get_sharing_customizations without needing to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'explicitly-set' hints that it returns only overrides rather than defaults, and it names the required permission. But it never states when to prefer this over get_customizations or the sibling customization getters, nor any when-not condition. Adequate but leaves routing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_statsShow Project StatsB

Read-onlyIdempotent

Retrieve stats for a project. This endpoint provides statistics for a specific project identified by its project-id.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`project_id`	Yes	The Hashed ID or ID of the project for which you want to retrieve stats.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description usefully adds the authorization requirements: a token with 'Read detailed stats' or the delegation scope (all:delegate_to_contact_permissions), which an agent cannot infer from annotations 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is front-loaded and efficient, but the bulk of the description is padded auth boilerplate with awkward line breaks ('Read-only account operation.'), which costs tokens without adding selection value for the agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, two-parameter tool with a full schema and no output schema, the description covers purpose and authorization adequately. It could say what the returned stats contain or their time scope, but that is a minor gap given annotations and schema richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, project_id) are already documented, and the description only restates that project-id identifies the project. It adds no extra meaning such as accepted ID formats or how the account selector interacts with credentials.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (retrieve) and resource (stats) scoped to a single project identified by project-id. This distinguishes it reasonably from sibling stats tools like get_media_stats and get_account_stats, though the description never names those siblings to sharpen the contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no routing to alternatives such as get_media_stats, get_account_stats, or get_account_stats_by_date, despite a crowded stats-tool family. The only selection context given is the required permission scope, which is authorization rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_related_media_customizationsShow Related Media CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set related-media ("discover more") customizations (which videos to recommend, when to show them, label and button text) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context by specifying the required permission scopes and the delegated-token authorization behavior, which the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, followed by the permission block. The trailing 'Read-only account operation' slightly duplicates the readOnlyHint annotation, and the fenced permission block is verbose, but the structure is clean and information-bearing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only getter with 100% schema coverage and full annotations, the description covers purpose, returned fields, and auth requirements. With no output schema present, it could hint at the response envelope, but nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents media_id and account. The description adds no parameter syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetches') and resource ('related-media customizations'), and the parenthetical elaborates exactly what those are (which videos to recommend, when to show them, label and button text). This clearly distinguishes it from the many sibling customization getters like get_appearance_customizations or get_playback_customizations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It says the customizations are 'explicitly-set,' which subtly implies defaults may apply, but there is no explicit when-to-use guidance and no reference to the sibling update_related_media_customizations as the write counterpart. Usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_share_linkShow share linkA

Read-onlyIdempotent

Fetches the share link for a single media. If the media does not have a share link yet, one is created on first request with a default visibility derived from the parent folder.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the media.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the bar is lower; the description adds real value on top by disclosing the get-or-create side effect and that default visibility is inherited from the parent folder. It also spells out the required token permission and the delegated-token authorization path. Note the create-on-first-request behavior sits in mild tension with readOnlyHint=true, though the description is candid about it rather than misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior is front-loaded in the first sentence, followed by the auth block, which is relevant for invocation. The permission section is somewhat long and the trailing 'Read-only account operation.' fragment reads like boilerplate, but nothing is egregiously wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read with no output schema, the description covers the essential invocation context: what it returns conceptually, the create-if-missing behavior, and the exact permission scope required. It lacks any description of the returned link payload or its URL shape, but that is a minor gap given the safety annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (media_id, account) are already documented in the schema. The description adds no format, ID-type, or account-selection detail 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetches the share link for a single media') and scopes it to one media, which is far clearer than a tautology. It does not contrast itself with the adjacent share-link siblings (resolve_share_link, update_share_link, delete_share_link), so the agent must infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no mention of the sibling operations that also touch share links. The only contextual cue is the conditional 'if the media does not have a share link yet', which describes behavior rather than selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sharing_customizationsShow Sharing CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set sharing customizations (the social/embed/download share bar: enabled channels, tweet text, download type, and page URL/title) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, yet the description adds real value: it discloses the required permission scope ('Read all folder and media data') and the delegation-token semantics with how authorization is resolved. The 'explicitly-set' caveat also warns that defaults are omitted, which annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence front-loads the purpose and contents efficiently. The permission block is boilerplate-heavy but genuinely relevant for a token-gated read, and it is visually separated from the purpose statement so it does not obscure the main point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 enumerating the returned fields (enabled channels, tweet text, download type, page URL/title). Auth requirements and token delegation are covered, leaving only minor gaps such as what happens when no customizations are set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters carry their own descriptions (including the subtle 'account selects credentials, not a remote account ID' note), so the schema does the heavy lifting. The description adds no parameter-level syntax or format detail beyond 'for the video', so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb (fetches) and resource (sharing customizations) and enumerates the concrete contents (channels, tweet text, download type, URL/title) tied to the share bar. It distinguishes this from the many other get_*_customizations siblings by naming the sharing domain, though it never names 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.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus the many adjacent tools (get_customizations, get_appearance_customizations, update_sharing_customizations). The word 'explicitly-set' hints that unset values are not returned, but the agent is left to infer both the use case and the read-only counterpart relationship.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_subfolderShow SubfolderA

Read-onlyIdempotent

Retrieves detailed information about a specific subfolder, including all media contained within it.

Requires api token with one of the following permissions

Read all folder and media data

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization naming this folder (any permission) can also be used. The embedded media are limited to those the token's authorizations name. Read-only account operation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`folder_id`	Yes	The hashed ID of the folder
`subfolder_id`	Yes	The hashed ID of the subfolder
`description_format`	No	Format for media descriptions

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/destructive/openWorld, but the description adds real context beyond them: the exact permission scope required, delegation behavior via all:delegate_to_contact_permissions, and the constraint that embedded media are limited to those the token's authorizations name. That last point is a genuine behavioral caveat an agent would otherwise miss.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The functional sentence is front-loaded and efficient, but roughly 80% of the text is an auth boilerplate block that reads as template copy, and it closes with a dangling fragment ("Read-only account operation.") that is not a complete thought. The useful opening is diluted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description does disclose the main return characteristic (subfolder details plus contained media) and all auth prerequisites. It omits pagination or result-size behavior for the embedded media, which is the only notable gap for a read tool of this kind.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (folder_id, subfolder_id, account, description_format are all documented in the schema), so the baseline is 3. The description adds nothing parameter-level beyond confirming that the returned payload includes media, so it neither compensates for nor extends the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ("Retrieves detailed information about a specific subfolder") and adds scope ("including all media contained within it"), which cleanly separates it from list_subfolders and get_folder. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the required subfolder_id and folder_id signal that this is for a known subfolder, and the media-inclusion note hints at when you'd prefer it over a plain listing. There is no explicit when-to-use, when-not-to-use, or named alternative (list_subfolders, get_media), so guidance is present but thin.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_thumbnail_customizationsShow Thumbnail CustomizationsA

Read-onlyIdempotent

Fetches the explicitly-set thumbnail customizations (still image URL, alt text, fit strategy, and the looping video thumbnail / text-overlay plugins) for the video.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_id`	Yes	The hashed ID of the video.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it spells out the exact token scopes required, explains the all:delegate_to_contact_permissions delegation semantics, and clarifies that only explicitly-set customizations are returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The useful content is front-loaded in the first sentence, and the permission requirements follow in a scannable block. The auth section is somewhat boilerplate-heavy (including the trailing fragment 'Read-only account operation'), but the information earns its place for an auth-gated read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with a complete input schema and annotations covering the safety profile, the description supplies the missing pieces: what fields are returned, and the auth/delegation model. Without an output schema, the field enumeration is particularly helpful; only the empty/absent-customization response behavior is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both params (account, media_id) fully documented in the schema, so the baseline is 3. The description only indirectly reinforces 'for the video' (media_id) and says nothing additional about the account selector.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('fetches') and resource ('thumbnail customizations') and even enumerates what the payload contains (still image URL, alt text, fit strategy, looping video thumbnail/text-overlay plugins), which cleanly separates it from the many sibling get_*_customizations tools. It stops short of explicitly naming its write counterpart update_thumbnail_customizations as the mutation path, so it is clear but not fully sibling-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than directed: 'explicitly-set' hints that unset/default customization values are not returned, and the permission block states prerequisites for calling it. However, it never says when to prefer this over get_media, get_customizations, or update_thumbnail_customizations, and gives no when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_visitorShow VisitorA

Read-onlyIdempotent

This endpoint provides detailed information about a specific visitor.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`visitor_key`	Yes	The unique key of the visitor.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: exact required permission scopes ('Read detailed stats') and the delegate-to-contact token path, which an agent needs before calling. It stops short of noting rate limits or return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the body is dominated by a verbose, oddly formatted permission block that ends with the dangling fragment 'Read-only account operation.' It is usable but not tightly written.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 would ideally say what 'detailed information' is returned; it does not. It is otherwise adequate, covering authentication fully, and is reasonable for a simple single-resource get.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already well documented in the schema. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: it returns detailed information about a specific visitor, and the required visitor_key reinforces single-record retrieval. It does not explicitly distinguish itself from the sibling list_visitors, but the singular 'a specific visitor' makes the scope reasonably clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: fetching details for one known visitor by key. There is no explicit 'use this instead of list_visitors when you already have a visitor_key' guidance, though the singular framing hints at it. The permission requirements give prerequisite context but not alternative-selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webinarShow WebinarB

Read-onlyIdempotent

Returns the webinar associated with the hashed id.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	The hashed ID of the webinar
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds permission requirements (the 'Read all data' scope and delegated token behavior), which is useful auth context beyond annotations. However it doesn't cover error behavior for missing ids or account scoping semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is efficient and front-loaded. But the permission block is verbose, including a full fenced code block and multi-sentence token explanation that could be more compact. The core purpose gets buried under auth boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-by-id tool with annotations covering safety and a fully-described schema, the definition is complete enough to call correctly. The permission details are a bonus. Missing only a note on what happens if the id doesn't exist, which is a minor gap for a read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% – both 'id' (hashed ID of the webinar) and 'account' (named private Wistia account) are documented in the schema. The description adds no additional parameter meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource: 'Returns the webinar associated with the hashed id.' This distinguishes it from list_webinars and create/update/delete_webinar. It doesn't explicitly contrast with get_webinar_analytics or other webinar retrieval siblings, but the singular-resource-by-id framing is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is provided. It doesn't say to use this instead of list_webinars when you have a specific hashed id, nor does it point to update_webinar for mutations. Usage is only implied by the verb choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webinar_analyticsShow Webinar AnalyticsA

Read-onlyIdempotent

Retrieve aggregate analytics for a webinar. This endpoint provides Bottler-powered analytics including registrations, attendance, engagement, chat activity, and poll results.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`webinar_id`	Yes	The hashed ID of the webinar.
`include_post_event`	No	Whether to include on-demand viewing data after the live event ended.
`post_event_end_date`	No	End date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date. Only used when include_post_event is true.
`post_event_start_date`	No	Start date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date. Only used when include_post_event is true.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description adds real value by disclosing the required token permission ('Read detailed stats') and the delegated-permission alternative. It doesn't describe response shape, pagination, or rate limits, which keeps it short of 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core sentence and metric list are front-loaded and waste-free. The permission block is somewhat verbose but carries genuinely useful auth information, so it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates what the analytics payload contains and states the auth requirements. For a read-only aggregate tool with fully documented parameters, this is nearly complete; only return-format details are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter (account, webinar_id, include_post_event, post_event dates) is documented in the schema, including the ISO date inclusivity/exclusivity semantics. The description adds no parameter-level meaning 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Retrieve aggregate analytics for a webinar') and enumerates the covered metrics (registrations, attendance, engagement, chat, poll results), which distinguishes it from narrower siblings like get_webinar_registration_timeseries, get_webinar_audience, or get_webinar_histograms. It stops short of naming those siblings explicitly, so a 5 isn't warranted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains authorization requirements but never says when to choose this aggregate endpoint over the neighboring webinar-analytics tools, nor does it state exclusions or prerequisites for use. Usage is only implied by the metric list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webinar_audienceShow Webinar AudienceA

Read-onlyIdempotent

Retrieve audience data for a webinar. Returns a paginated list of registrants with their attendance status, engagement metrics, attribution data, and per-attendee histograms.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`cursor`	No	Cursor for pagination. Use the value from the previous response's page_info.end_cursor.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`per_page`	No	Number of results to return (max 100).
`webinar_id`	Yes	The hashed ID of the webinar.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description adds real value on top: it discloses pagination (paginated list keyed to page_info.end_cursor per the schema), the shape of the returned payload, and the exact permission requirement including the delegation scope. It stops short of stating rate limits or whether the list is raw registrants vs. aggregated attendees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The functional sentence is front-loaded and dense with useful detail in a single sentence. The trailing permission block is longer and largely boilerplate, but it is genuinely required for a scoped read operation and does not bury the purpose statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 return content and does so concretely (attendance status, engagement metrics, attribution, histograms) while covering pagination and auth. Minor gaps remain around ordering, list size expectations, and which webinar-scoped read tool to prefer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (cursor, account, per_page, webinar_id) are already documented in the schema, including the max of 100 and the cursor source. The description adds no parameter-level semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Retrieve audience data for a webinar") and enumerates exactly what comes back: registrants with attendance status, engagement metrics, attribution data, and per-attendee histograms. That distinguishes it reasonably from list_webinar_registrations, get_webinar_histograms and get_webinar_analytics, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'for a webinar' and by the required permission block, which tells the agent this is an authorized read for a specific webinar. However, there is no explicit when-to-use/when-not guidance and no routing against the closely related sibling tools (list_webinar_registrations, get_webinar_histograms).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webinar_histogramsShow Webinar HistogramsA

Read-onlyIdempotent

Retrieve engagement histogram data for a webinar. Returns arrays of per-time-bucket counts for attendees, chat activity, and visual focus, useful for rendering engagement visualizations.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`webinar_id`	Yes	The hashed ID of the webinar.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, openWorld, and the description reinforces 'Read-only account operation.' It goes beyond them by naming the required permission scopes ('Read detailed stats', delegated-token behavior) and describing the return structure (arrays of per-time-bucket counts), which is genuine added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The payload sentence is front-loaded and dense with useful detail, and the permission block follows logically. It is somewhat verbose with the fenced permission boilerplate, but no sentence is truly wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only stats tool with no output schema, the description compensates by describing the return shape (per-time-bucket arrays) and the auth requirements. The main residual gap is the lack of sibling differentiation against other webinar analytics tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both 'account' and 'webinar_id' fully documented in the schema. The description adds no syntax, format, or semantics 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Retrieve') plus resource ('engagement histogram data for a webinar') and concrete contents (per-time-bucket counts for attendees, chat activity, visual focus). However, it does not distinguish itself from siblings like get_webinar_analytics, get_webinar_traffic_breakdown, or get_webinar_registration_timeseries, which an agent could easily confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'useful for rendering engagement visualizations' implies the intended usage context, and the permission requirements are spelled out. But there is no explicit when-to-use guidance and no mention of alternative webinar analytics tools an agent should pick instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webinar_registration_timeseriesShow Webinar Registration TimeseriesA

Read-onlyIdempotent

Retrieve registration timeseries data for a webinar with configurable granularity. Returns an array of timestamped registration metric buckets including impressions, registrations, and completion rates.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`webinar_id`	Yes	The hashed ID of the webinar.
`granularity`	Yes	The time granularity for the timeseries data.
`include_post_event`	No	Whether to include on-demand viewing data after the live event ended.
`post_event_end_date`	No	End date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Exclusive — the range ends before the beginning of this date. Only used when include_post_event is true.
`post_event_start_date`	No	Start date for the post-event analytics period in ISO 8601 format (YYYY-MM-DD). Inclusive — the range starts at the beginning of this date. Only used when include_post_event is true.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds real value beyond them: it discloses the return shape (timestamped registration metric buckets covering impressions, registrations, completion rates) and the required token permission ('Read detailed stats' or delegated permissions), which is a meaningful auth constraint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The two-sentence purpose and return summary is front-loaded and tight. The appended auth/permission block is somewhat verbose (including the delegation scope text) but is genuinely relevant to invoking the tool, so it earns most of its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully compensates by describing the return contents, and it covers the auth requirement. The missing piece is any guidance on choosing this tool over adjacent webinar analytics tools, but for correct invocation the definition is essentially complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents webinar_id, granularity, include_post_event, and the post-event date bounds including their inclusive/exclusive semantics. The description only echoes 'configurable granularity' and adds nothing the schema does not already carry, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (retrieve) and resource (registration timeseries for a webinar) with the configurable-granularity scope. It distinguishes itself from the many media/folder siblings, though it does not explicitly contrast with close webinar-analytics siblings like get_webinar_analytics or get_webinar_histograms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool returns but gives no when-to-use guidance, no exclusions, and no routing to alternatives such as get_webinar_analytics or get_webinar_audience. The agent must infer selection from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_webinar_traffic_breakdownShow Webinar Traffic BreakdownA

Read-onlyIdempotent

Retrieve traffic breakdown analytics for a webinar, grouped by a specified dimension such as UTM campaign, UTM source, UTM medium, or referrer domain.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	The metric to sort results by.	registrations
`group_by`	Yes	The dimension to group traffic data by.
`webinar_id`	Yes	The hashed ID of the webinar.
`sort_direction`	No	The sort direction.	desc

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds real value beyond that by spelling out the required 'Read detailed stats' permission and the delegated-token authorization model, which an agent needs to know before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, with the auth requirements separated afterward. The permission boilerplate is somewhat verbose but is genuinely actionable rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analytics endpoint with 100% schema coverage and no nested objects, the description plus annotations give enough to call it correctly. It does not describe the shape of the breakdown results or any pagination/limit behavior, which would be the only remaining gap given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (account, sort_by, group_by, webinar_id, sort_direction) are already documented in the schema, including enums and defaults. The description's list of grouping dimensions merely restates the group_by enum and adds no new syntax or format detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Retrieve traffic breakdown analytics for a webinar' — plus the grouping dimension, so the agent knows exactly what data comes back. It distinguishes itself from the media analog (get_media_traffic_breakdown) implicitly via 'for a webinar,' but never names or contrasts 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.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the purpose but there is no when-to-use/when-not guidance and no routing to alternatives such as get_media_traffic_breakdown or get_webinar_analytics. The dimension examples hint at appropriate cases but do not frame selection between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

import_media_from_urlImport Media from URLA

Destructive

This endpoint imports a media file from a given URL. The import is processed asynchronously and will return a background_job_status object rather than the typical Media response object. You can poll the background job status endpoint to check on the progress of the import.

If no folder_id is provided, a new folder called "Untitled Folder" will be created and the imported media will be placed there.

The URL must be publicly accessible : Wistia's servers need to be able to fetch the file directly.

Note: imports from certain domains (e.g. vimeo.com, wistia.com) are not permitted.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`url`	No	The publicly accessible URL of the media file to import.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	The hashed ID of the folder (project) to import the media into. If not provided, a new folder will be created.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing the async return shape (background_job_status instead of Media), the required polling, the auto-created 'Untitled Folder', the public-URL fetch requirement, blocked domains (vimeo/wistia), the confirm=true requirement, and permission/scope constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and async behavior, then constraints. Mostly earned, though the token-permission block is verbose boilerplate that slightly dilutes the operational content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, nested, destructive async tool with no output schema, the description covers return shape, polling, defaults, auth, and domain restrictions, leaving no critical gap for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 value: it names the auto-created folder ('Untitled Folder'), reinforces the publicly-accessible URL constraint, and clarifies the confirm=true mutation gate. The payload/body-flag distinction is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('imports a media file from a given URL') and distinguishes itself from the upload siblings (upload_media, upload_media_file) by making clear the source is a remote URL rather than a local file. An agent can immediately tell what this does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the async workflow and that you must poll the background job status endpoint, plus the fallback behavior when no folder_id is given. It does not explicitly name alternatives (e.g. 'use upload_media_file for local files'), so the sibling routing is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

invite_contactsInvite ContactsA

Destructive

Invites one or more people to the account by email. Accepts a comma/whitespace/newline-separated list; each entry becomes a new contact if one does not already exist for that email.

Requires api token with one of the following permissions

Read, update & delete anything

Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`contacts`	No	A comma-, whitespace-, or newline-separated list of email addresses to invite to the account. Each entry becomes a new contact if one does not already exist for that email.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the annotations by naming the side effects explicitly: access sharing, notifications to invitees, and possible provider charges, plus the confirm=true gate required for the mutation. Annotations already flag destructive/open-world, but the description adds real operational context about the consequences of inviting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action in the first sentence, then separates permissions and the confirm requirement into their own block. Slight redundancy in repeating the 'each entry becomes a new contact' rule that already appears in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter mutation tool with a nested payload and no output schema, the description covers permissions, the confirm gate, accepted input formats, and side effects. It leaves the account/payload/payload_file parameter relationships to the schema, which is acceptable given full coverage there.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented structurally. The description restates the separator format and contact-creation behavior, which duplicates the schema's own contacts description rather than adding new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Invites one or more people to the account by email') with the input format, so an agent knows exactly what the tool does. No sibling tool performs the same invite action, so explicit differentiation isn't needed, but it also isn't provided.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful prerequisites (required permission level and confirm=true), which implies when the tool is callable, but never states when to prefer it over alternatives or what conditions should prevent invocation. Usage context is inferred rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accountsList configured accountsA

Read-onlyIdempotent

List private account labels, default selection and configured token method. No credentials, token paths or account content; no network request.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it confirms no credentials, token paths, or account content are returned, and that no network request is made.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences front-load the core scope and then immediately clarify the negative behavior. Every phrase contributes useful information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with no output schema, the description adequately covers the returned concepts and explicitly rules out sensitive data and network activity. It stops short of describing result ordering, formatting, or pagination, but those may not apply or may be self-evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to clarify. Per the rubric, a zero-parameter tool has a baseline of 4, and the description does not need to compensate for undocumented inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource (list accounts) and enumerates the exact scope: private account labels, default selection, and configured token method. Its exclusions also implicitly distinguish it from broader siblings like get_account or get_current_token, which would expose account content or credentials.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating exactly what metadata the tool surfaces, but it never explicitly says when to call this instead of alternatives such as get_account or get_current_token. The 'No credentials...' clause scopes the tool, yet no named alternative or when-not condition is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_all_captionsList CaptionsA

Read-onlyIdempotent

Lists captions belonging to the account. Results can be narrowed to a specific media with media_id, or to several media and languages at once with media_ids[] and languages[]. Each caption includes its text, so combining these filters with pagination fetches transcripts for many media in a few requests. Pass include=metadata to omit transcript text when only track and language information is needed.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`include`	No	Set to `metadata` to omit caption text and return only track metadata. Omitting this parameter preserves the existing response, including SRT text.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id` is supported.	id
`media_id`	No	Find captions for a particular media by providing the media hashed ID
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`languages`	No	Find captions in any of these languages, using the codes returned in each caption's `language` field (for example `eng` or `spa`). When combined with `media_ids[]`, captions must match both.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`media_ids`	No	Find captions belonging to any of these media hashed IDs. IDs that don't match a media the token can access are ignored rather than returning an error.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's main added value is the auth context: the required token permission and the delegate_to_contact_permissions scope behavior. It does not disclose pagination or result-count behavior, but the schema does, so this is a solid addition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core behavior and filters in the first sentences and defers the auth boilerplate to a clear trailing block. Every substantive sentence earns its place, though the verbatim permission block is lengthy relative to the functional content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter read-only list tool with full schema coverage and no output schema, the description covers scope, filtering strategy, transcript-vs-metadata tradeoff, and auth requirements. It could be a 5 if it also addressed pagination interaction or listed-value behavior, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 earns an extra point by explaining how media_id, media_ids[] and languages[] interact (filters combine, non-matching IDs are ignored) and what include=metadata does to the payload. That is genuine semantic value beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists captions belonging to the account') and immediately scopes it with the available filters, so the agent knows exactly what it returns. It does not differentiate itself from the sibling list_captions, which is the one real ambiguity, keeping it just below a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance: combine media_ids[] and languages[] with pagination to fetch transcripts in bulk, and pass include=metadata when only track/language info is needed. It stops short of saying when to prefer this tool over list_captions or get_captions, so there is no explicit alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_allowed_domainsList Allowed DomainsA

Read-onlyIdempotent

Lists allowed domains belonging to the account.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id` and `domain` are supported.	id
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the description is not the primary safety signal. It goes beyond them, however, by disclosing the exact required token permission and the delegate-to-contact behavior of scoped tokens, which is real operational context an agent cannot derive from 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded and the permission block is clearly fenced under a heading. There is minor redundancy in that the permission section already implies read-only and the trailing 'Read-only account operation.' restates annotation data, but overall the text is well organized and not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 no output schema and exhaustive parameter documentation, the definition covers what an agent needs to call it correctly: purpose and authorization. It does not touch on the shape of returned records or pagination continuation, but the schema already carries pagination semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters (pagination, cursor, sort_by, sort_direction, all_pages, max_items) are already fully documented in the schema. The description adds no parameter meaning beyond that, which is the correct baseline for a tool whose schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists allowed domains') plus its scope ('belonging to the account'), so an agent can immediately tell what data is returned. It does not, however, name or distinguish itself from the closely named siblings create_allowed_domain, get_allowed_domain, and delete_allowed_domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this versus get_allowed_domain or the create/delete counterparts, nor when to prefer offset (page) vs cursor pagination. Usage is left entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_brandsList BrandsA

Read-onlyIdempotent

Lists the brands belonging to the account. A brand is a saved set of branding options (colors, fonts, logos, and layout) that can be applied to media, folders, and channels. The account-level default brand is flagged with is_default, and styles everything that has no brand of its own.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id`, `updated` and `created` are supported. All other sort_by options require offset pagination.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc)

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint. The description adds meaningful context beyond that: required token permissions and the behavior that the account-level default brand is flagged with is_default. It does not describe pagination behavior, but that is fully covered in 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose and brand definition, then places permission requirements under a clear heading. The permission block is somewhat long but standard and relevant, and every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, authentication, and the key return flag for a read-only list operation. Given there is no output schema, it could explain response structure more, but the schema fully documents the 8 optional parameters and the description gives enough to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 8 parameters including the nested cursor object are documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists the brands belonging to the account') and defines what a brand is. It does not explicitly differentiate this tool from siblings such as get_brand or list_brands variants, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides prerequisite permission scopes ('Read all data' or delegated permissions) and notes it is a read-only account operation. However, it gives no explicit when-to-use guidance versus alternatives like get_brand, so usage is only implied by the tool name and permission requirement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_captionsList Captions by MediaB

Read-onlyIdempotent

Lists captions belonging to a specific media.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_hashed_id`	Yes	The hashed ID of the media for which captions are to be retrieved.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only/idempotent/non-destructive and open-world behavior, but the description adds real value on top: the specific permission ('Read all folder and media data') and the delegated-token behavior. It still omits pagination and return-format behavior, which matters for a list endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in a single tight sentence. The permission block is verbose (code fences, multi-line scope text) but the information is relevant to correctly invoking the tool, so it earns most of its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 could helpfully state what a caption record contains or whether results paginate, and it does neither. Authorization requirements are well covered, but the return-side picture is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are fully documented in the schema itself, including the note that 'account' selects credentials rather than a remote account ID. The description adds no parameter-level detail 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Lists) plus resource (captions) scoped to 'belonging to a specific media', which implicitly separates it from the sibling list_all_captions. It is clear what the tool does, though it never names the alternative it is not, so the sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no when-to-use guidance or exclusion criteria. With siblings like list_all_captions, get_captions, and find_caption_matches, an agent gets no help deciding which one to invoke; only the required media_hashed_id implies a per-media scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_channel_collaboratorsList Channel CollaboratorsA

Read-onlyIdempotent

Lists the collaborators (contacts and contact groups) that have been granted access to a channel.

Results are scoped to what the authenticated user is allowed to see: account owners and managers see all collaborators, channel admins see all collaborators on their channels, and everyone else sees only the roles that grant them access.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id` is supported.	id
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)
`channel_hashed_id`	Yes	Channel Hashed ID

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful behavior beyond that: result scoping by account role and the token/permission and delegation requirements needed to call it. It stops short of describing return shape or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by scoping and permission requirements. It is reasonably sized, though the permissions block is somewhat boilerplate-heavy relative to the core behavior statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 a fully documented 9-parameter schema and complete annotations, the description covers what an agent needs: purpose, result scoping, and authorization requirements. No return-value explanation is required since annotations and schema carry the rest.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so pagination, sorting, and channel_hashed_id are already fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline-3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (lists) and resource (collaborators of a channel), and even clarifies the entity types involved (contacts and contact groups). The 'channel' scope implicitly distinguishes it from the sibling list_webinar_collaborators, so an agent can identify it 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context via required permissions ('Read all data' or the delegate_to_contact_permissions token) and explains which viewer sees which results. However, it never explicitly says when to choose this over related tools or when not to use it; the guidance is contextual rather than comparative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_channel_episodesList Channel EpisodesA

Read-onlyIdempotent

Lists Channel Episodes belonging to an account. This endpoint can also be used to do a batch fetch based off of the hashed id.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`title`	No	Filter by channel episode name/title.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. Default is ID ASC. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`position`, `title`, `updated`, `published_at`) require offset pagination.
`media_id`	No	Filter by media id. Accepts either the numeric id or the hashed id of a media.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`published`	No	Filter by published status.
`channel_id`	No	The hashed ID of the channel to grab channel episodes from.
`hashed_ids`	No	Filter by hashed id
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the exact permission scope needed ('Read all folder and media data') and the delegated-token authorization behavior, which is genuine operational context an agent needs before calling. It does not, however, address pagination semantics or quota behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, with the permission block clearly demarcated afterward. Slightly long due to the fenced permission text, but every section serves a function and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, zero-required list tool with no output schema, the description covers what it returns (channel episodes for an account, batch by hashed id) and the authorization requirements. Combined with the exhaustive schema, an agent has enough to invoke it correctly, though the sibling-routing ambiguity remains a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 13 parameters, including nested cursor object and enum constraints, so the schema carries the full burden. The description adds no parameter-level meaning beyond it, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ('Lists Channel Episodes belonging to an account') and adds a second capability (batch fetch by hashed id). It is clear what the tool does, though it never explicitly distinguishes itself from the near-identical sibling list_channel_episodes_by_channel, leaving the agent to infer the account-wide vs per-channel scoping from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states a second use case (batch fetch off hashed id) and spells out the required token permissions and the delegate-to-contact authorization path. However, it never says when to prefer this over list_channel_episodes_by_channel or get_channel_episode, so the routing decision among siblings is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_channel_episodes_by_channelList Channel Episodes by ChannelB

Read-onlyIdempotent

Lists Channel Episodes belonging to the channel passed in the path.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`title`	No	Filter by channel episode name/title.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. Default is ID ASC. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`position`, `title`, `updated`, `published_at`) require offset pagination.
`media_id`	No	Filter by media id. Accepts either the numeric id or the hashed id of a media.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`published`	No	Filter by published status.
`hashed_ids`	No	Filter by hashed id
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)
`channel_hashed_id`	Yes	The hashed ID of the channel to grab channel episodes from.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond that by documenting the required API token permission scope and the delegation behavior for 'act as contact' tokens, which an agent must know before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in one sentence, followed by a clearly delineated permission section. The permission block is somewhat verbose but is genuinely functional information, not filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a list tool: the schema fully documents the 13 pagination/filter/sort parameters and annotations carry the safety profile. However, with no output schema and no mention of pagination or return shape in the description, an agent gets no narrative on how results are paged back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 13 parameters are already documented in the schema. The description adds only that the channel identifier is passed 'in the path'; otherwise it does not clarify filtering or pagination semantics beyond what the schema provides. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists Channel Episodes') and clarifies the scope is limited to the channel in the path. However, it does not distinguish itself from the sibling 'list_channel_episodes', so an agent cannot tell which of the two near-identical listers to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus 'list_channel_episodes' or 'get_channel_episode'. The permission block tells you what credentials are needed, but not the selection context or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_channelsList ChannelsA

Read-onlyIdempotent

Lists all Channels belonging to an account. This endpoint can also be used to do a batch fetch based off of the hashed id.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`page`	No	Page number to retrieve
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. Default is ID ASC. Note: Only 'id' and 'created' are supported when using cursor pagination.
`per_page`	No	Number of channels per page
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Find all of the channels limited to these hashed_ids.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds meaningful context beyond them: the exact permission scopes required and the delegated-permission behavior for tokens. It does not describe pagination or result-shape behavior, but the auth disclosure is genuinely useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The functional purpose and the batch-fetch capability are front-loaded in the first two sentences. The permission block that follows is lengthy boilerplate, but it is scoped, formatted with a header, and relevant to actually calling the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter read-only list endpoint with no output schema, the description covers purpose, a second use case, and authorization fully, while the schema handles pagination and sorting semantics. Return values are not explained, but no output schema exists and the listing intent is self-evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all 9 parameters including pagination, sort, and hashed_ids. The description only gestures at hashed_ids ('batch fetch based off of the hashed id') without adding syntax or format detail, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists all Channels belonging to an account') and adds a second capability (batch fetch by hashed id). Scope of 'belonging to an account' distinguishes it from a single-record fetch like get_channel, though it never names the sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the scope statement and the batch-fetch hint, but there is no explicit when-to-use guidance (e.g., list_channels vs get_channel vs list_channel_episodes). The bulk of the text is authorization boilerplate rather than selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_deleted_mediaList Deleted MediaA

Read-onlyIdempotent

Lists media that has been soft-deleted and is still inside the account's restore window. Media is listed only while it can still be restored : 30 days on most plans, 14 on free plans. After which it is permanently purged.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Field to order by. When omitted, results are ordered most-recently-deleted first.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Restrict the results to the deleted media with these hashed IDs.
`sort_direction`	No	Direction to order by. (0 = desc, 1 = asc; default is 1)

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds genuine context beyond them: the time-bounded lifecycle of the listed items and the permanent purge that follows the window. It also spells out the required token permissions and the delegate_to_contact_permissions path, which annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the restore-window constraint are front-loaded in the opening sentence, which is the most important information. The permission block adds length and has minor formatting artifacts (stray space before the colon, trailing 'Read-only account operation'), but each section is relevant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 no output schema and zero required parameters, the definition supplies purpose, lifecycle timing, and auth requirements, while the schema fully documents pagination and filtering. Nothing critical an agent needs 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 9 parameters, including pagination, sorting, and the hashed_ids filter, so the schema carries the full burden. The description adds no parameter-level meaning (no interaction between page and cursor, no all_pages semantics), so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with a precise scope qualifier: media that is 'soft-deleted and is still inside the account's restore window.' The 'soft-deleted / restorable' framing implicitly separates it from list_media, but no sibling is named explicitly, so an agent must infer the routing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the restore window (30 days most plans, 14 free) and that purging follows, which implies this is the pre-restore inspection step before restore_deleted_media. However, it never states when to use this versus list_media, restore_media, or the other restore/delete siblings, leaving selection to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_eventsList EventsB

Read-onlyIdempotent

Retrieve a list of events. Please note that due to our data retention policy, only events from the last 2 years are available.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`page`	No	The page of events to get data from.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`end_date`	No	End date in the format 'YYYY-MM-DD'.
`media_id`	No	An optional identifier for a specific video.
`per_page`	No	Maximum number of events to retrieve (capped at 100).
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`start_date`	No	Start date in the format 'YYYY-MM-DD'.
`visitor_key`	No	An optional identifier for a specific visitor.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: a 2-year retention window and the exact token permissions required, including the delegate-to-contact scope. It stops short of describing return shape or pagination semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the retention caveat are front-loaded, which is good. The embedded permission block with a fenced code snippet is somewhat bulky, but each element (purpose, retention, auth) is distinct information rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With nine parameters, no output schema, and openWorldHint, the description covers auth and retention but omits what an event record contains and how the all_pages/max_items continuation state surfaces in results. Adequate but leaves real gaps for a paginated list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all nine parameters (page, per_page, all_pages, max_items, date filters, media_id, visitor_key) are already documented in the schema, including the per-request quota note on all_pages. The description adds nothing about parameter semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb and resource ('Retrieve a list of events'), so an agent knows this is a list operation. However, it never disambiguates from the sibling get_event, nor clarifies what kind of 'events' these are (analytics/visitor events), which matters in a large sibling set full of list_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no exclusions, and does not mention any alternative such as get_event or the visitor/media-scoped list tools. The only conditional content is auth prerequisites and retention, which are constraints rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_foldersList FoldersA

Read-onlyIdempotent

Lists folders (previously called projects) belonging to the account. My Library folders are not included.

For tokens scoped to a specific user (all:delegate_to_contact_permissions), results are limited to folders that user can see in their content library: folders shared with them directly, through a contact group, or with the whole account (owners and managers see every folder). Public (unlocked) folders the user has no sharing on remain viewable by link but are not listed.

Requires api token with one of the following permissions

Read all folder and media data

An expiring access token created with the all:delegate_to_contact_permissions scope can also be used. Results are limited to the folders its authorizations name (any permission granted on a folder qualifies it), filtered as they would be for the contact the token was created for. Read-only account operation.

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id`, `updated` and `created` are supported. All other sort_by options require offset pagination.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	A collection of hashed ids belonging to folders to fetch
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

A3.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavior beyond them: My Library folders are excluded, delegated tokens are filtered to folders the contact can see (direct share, contact group, whole-account, public-by-link-but-unlisted), and expiring access tokens are scoped by their authorizations. This is exactly the auth/filtering context an agent needs and cannot get from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and scope are correctly front-loaded, but the text is padded: the all:delegate_to_contact_permissions scope is explained three separate times across the permissions, token, and expiring-token paragraphs. Two of those paragraphs could be merged without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, no-required-arg listing tool with no output schema, the description covers authorization and result-scoping thoroughly, and the schema carries pagination/sorting. It stops short of describing the shape of returned folder records or how hashed_ids interacts with listing, a minor gap given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so pagination (page, cursor, per_page, sort_by, sort_direction), the all_pages/max_items quota notes, and hashed_ids are already fully documented in the schema. The description adds no parameter-level meaning (e.g., it never mentions hashed_ids filtering or pagination interaction), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists folders'), clarifies legacy naming ('previously called projects'), and scopes it ('belonging to the account', 'My Library folders are not included'). It does not, however, distinguish itself from the sibling list_subfolders, so an agent gets no explicit routing signal between the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives detailed authorization context (required permission scope, delegated-token behavior) and labels it a 'Read-only account operation', which implies when it is appropriate. But it names no alternative tool and no exclusion criteria versus list_subfolders/get_folder, so usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_folder_sharingsList Folder SharingsB

Read-onlyIdempotent

Lists the sharings of contacts and contact groups on a folder.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id` is supported.	id
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`folder_id`	Yes	Folder Hashed ID
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Filter sharings by their hashed IDs
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the required token permission and the delegation scope that changes whose permissions authorize the request. It does not disclose return shape or the pagination model, which keeps it from 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in a single sentence, followed by a compact permission block that is relevant to calling the tool correctly. The permission boilerplate is somewhat verbose but each part earns its place; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, a nested cursor object, and no output schema, the description covers the 'what' and the auth prerequisites but says nothing about what a sharing record contains or how pagination/continuation is returned. The schema carries the parameter burden, but for a list endpoint with no output schema a brief note on return contents would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 10 parameters, including the nested cursor object, enum values, and limits, is already documented in the schema. The description adds no parameter-level meaning 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it 'Lists the sharings of contacts and contact groups on a folder.' An agent can distinguish it from the singular get_folder_sharing and the mutating create/update/delete_folder_sharing siblings by the 'List' verb and the folder-scoped resource. It stops short of explicitly naming those alternatives, so it is clear but not sibling-differentiating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only contextual guidance is an authorization requirement ('Requires api token with Read all data') and a delegation note. There is no statement of when to use this tool versus get_folder_sharing, list_folders, or the other sharing endpoints, and no exclusions. Usage must be inferred from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_localizationsList LocalizationsA

Read-onlyIdempotent

Lists all the localizations for a media.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`media_hashed_id`	Yes	The hashed ID of the media to list localizations for.
`include_transcript`	No	Whether to include the transcript in the response.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds meaningful context beyond them: the required permission scopes and the delegated-token authorization model. It adds little on rate limits or result size, so not 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The operational sentence is front-loaded and zero-waste. The permission block is boilerplate repeated across the API surface, which adds bulk but is at least clearly separated from the core statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list operation whose annotations carry safety and whose schema carries parameters, the description is mostly sufficient. With no output schema, it never characterizes the returned localization list or the effect of include_transcript, leaving a mild gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so media_hashed_id, account, and include_transcript are already fully documented in the schema. The description adds no additional parameter meaning, which matches the baseline 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists all the localizations for a media'), which is clearly distinguishable from create_localization/get_localization/delete_localization. It does not, however, explicitly contrast itself with the singular get_localization sibling, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose sentence implies the use case (enumerate every localization attached to a media), but there is no explicit when-to-use vs when-not, no named alternative such as get_localization for a single item, and no stated prerequisites beyond the auth block.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_mediaList MediaA

Read-onlyIdempotent

Lists the media belonging to the account. This endpoint can also be used to do a batch fetch based off of the hashed id.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`name`	No	Find a media or medias whose name exactly matches this parameter.
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`tags`	No	Find all of the medias that match all of these tag names.
`type`	No	A string specifying which type of media you would like to get.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`include`	No	Set to `speakers` to include active transcript speaker assignments used for diarization. Webinar hosts and panelists are not included.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`name`, `updated`, `position`) require offset pagination.
`archived`	No	Filter by archived status. True will return only archived medias, while false will return only active medias.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`folder_id`	No	A hashed ID specifying the folder from which you would like to get results.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Find all of the medias by these hashed_ids.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)
`description_format`	No	Format for media descriptions

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description adds genuinely useful context beyond those: the required token permission scopes and the delegation behavior for team-member-permission tokens. It still says nothing about rate limits or pagination semantics, so it is not fully complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, which is good, but the auth boilerplate consumes most of the text and the trailing "Read-only account operation" fragment is redundant with the readOnlyHint annotation. Some trimming would help.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter, zero-required list tool with no output schema, the description covers purpose and authorization but leaves pagination behavior (offset vs cursor), the all_pages/max_items semantics, and return shape to the schema. Adequate but not rich; an agent has to lean entirely on the schema for invocation detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 16 parameters are already documented in the schema. The description's reference to hashed-id batch fetching maps to the hashed_ids parameter but adds no syntax or constraint detail beyond what the schema provides; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ("Lists the media belonging to the account") and adds a second mode (batch fetch by hashed id). It does not, however, distinguish itself from nearby siblings like list_deleted_media or get_media, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The mention of batch fetching by hashed id implies one usage context, but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as list_deleted_media or get_media. Usage is only loosely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_media_extended_audio_descriptionsList Media Extended Audio DescriptionsC

Read-onlyIdempotent

Lists all extended audio descriptions belonging to the account. Supports pagination and sorting. Read-only account operation.

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Field to order by. The default is id.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Filter extended audio descriptions to only those matching these hashed ids.
`sort_direction`	No	Direction to order by. (0 = desc, 1 = asc; default is 1)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, and the sentence "Read-only account operation" merely restates them without adding context. Nothing is disclosed about quota consumption during paginated reads, behavior of all_pages/max_items, or rate limits, so the description adds essentially nothing behavioral beyond the 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what the tool lists, and zero filler. The final "Read-only account operation" sentence is largely redundant with the readOnlyHint annotation, a minor waste in an otherwise tight definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required, nine-parameter list tool with a nested cursor object and no output schema, the description is minimally adequate: schema covers parameters thoroughly, but it omits the mutual exclusivity of page vs cursor, the default sort field and direction, and the quota cost of all_pages that an agent calling this repeatedly would want flagged. Nothing essential is missing, but the guidance layer is thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all nine parameters including the nested cursor object, sort_by/sort_direction enums, hashed_ids filter, and the all_pages/max_items quota semantics are already documented in the schema. The description's "supports pagination and sorting" adds no syntax or meaning 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Lists all extended audio descriptions belonging to the account" gives a clear verb plus resource and scope, which distinguishes it from the singular get_/delete_ extended-audio-description siblings. It does not name any sibling or contrast itself with list_captions, but an agent can infer the resource 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.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never states when to choose this tool over get_media_extended_audio_description, delete_media_extended_audio_description, or order_extended_audio_description. Beyond the implied list-vs-retrieve distinction, no conditions, prerequisites, or alternatives are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_review_bundlesList Review BundlesA

Read-onlyIdempotent

Lists review bundles belonging to an account. This endpoint can also be used to do a batch fetch based off of the hashed id, or to find the bundles that include a given media or any media from a folder.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description
`name`	No	Restrict the results to review bundles whose name contains this value (case-insensitive).
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Field to order by. The default is id.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Restrict the results to the review bundles with these hashed IDs.
`sort_direction`	No	Direction to order by. (0 = desc, 1 = asc; default is 1)
`media_hashed_id`	No	Restrict the results to review bundles that include the media with this hashed ID.
`folder_hashed_id`	No	Restrict the results to review bundles that include any media from the folder with this hashed ID.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the required token permission ("Read all folder and media data"), the delegated-permission scope, and confirmation that it is a read-only account operation. It stops short of describing pagination limits or return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and modes are front-loaded in the first two sentences with no waste. The trailing permission block is verbose boilerplate but functionally necessary auth information, not filler that obscures the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter read tool with rich schema coverage and no output schema, the description covers purpose, the three usage modes, and authorization requirements. Return shape is not described, but pagination/cursor semantics live in the schema and annotations carry the safety profile, leaving only minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so pagination, sort, cursor, name, hashed_ids, media_hashed_id and folder_hashed_id are all fully documented in the schema. The description's mention of batch fetch and media/folder lookup aligns with those params but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Lists review bundles belonging to an account") and then enumerates three distinct operating modes: listing, batch fetch by hashed id, and lookup by media or folder. This is far more specific than the bare title and lets an agent understand the tool's reach versus generic listing siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when each mode applies (batch fetch via hashed id, find bundles containing a given media or any media from a folder), which implicitly guides parameter selection. It does not name a sibling alternative to defer to, so it falls short of a full when/when-not comparison, but the usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_speakersList SpeakersA

Read-onlyIdempotent

Lists reusable speaker profiles belonging to the account.

Requires api token with one of the following permissions

Read all data

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. View-only contacts cannot list speaker profiles. Read-only account operation.

ParametersJSON Schema

Name	Required	Description
`name`	No	Restrict the results to speaker profiles whose name contains this value (case-insensitive).
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Field to order by. The default is id.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`sort_direction`	No	Direction to order by. (0 = desc, 1 = asc; default is 1)

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations do not: the required token permission, the delegation scope, and the view-only contact restriction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose sentence is concise and front-loaded, but it is followed by a bulky, boilerplate-looking permissions block with markdown headers that is not tailored to this tool and inflates the size of the definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 100% schema coverage and no output schema, the critical missing piece an agent would want is authorization, and the description supplies it. Pagination and sort behavior are fully documented in the schema, so the description is close to complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and covers all nine parameters, including the nested cursor object and pagination semantics. The description adds no parameter meaning beyond the schema, which is the baseline-3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource ('Lists reusable speaker profiles') and scopes it to 'belonging to the account'. No sibling tool in the list handles speakers, so no differentiation is needed, but the description stops short of the specificity a 5 would require.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the opening sentence, and the auth paragraph states a concrete exclusion ('View-only contacts cannot list speaker profiles'), but there is no explicit when-to-use framing and no alternatives exist among siblings to route against.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_subfoldersList SubfoldersB

Read-onlyIdempotent

Lists subfolders in a specific folder.

Requires api token with one of the following permissions

Read all folder and media data

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization naming this folder (any permission) can also be used; it lists the folder's subfolders. Read-only account operation.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Field to sort by. When using cursor pagination (see cursor param), only `id` is supported.	position
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`folder_id`	Yes	The hashed ID of the folder
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Filter subfolders by their hashed IDs
`sort_direction`	No	Sort direction (0 = desc, 1 = asc; default is 1)

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful authorization context — required permissions, delegation scope, and expiring token support — which goes beyond the annotations. It also states 'Read-only account operation,' reinforcing the annotation. It doesn't cover rate limits or pagination behavior, but with annotations carrying the core behavioral traits, this is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, but the subsequent authentication block is lengthy and verbose with boilerplate about token scopes. It's not wasteful per se, but the structure buries the simple purpose under a wall of auth details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 a rich input schema (10 params, 100% coverage) and annotations covering safety, the description is nearly complete. The main missing piece is guidance on when to choose this over sibling tools like list_folders, but for a straightforward list operation, that's a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all 10 parameters, including pagination, sorting, and filtering. The description adds no parameter-specific information beyond the schema. Baseline 3 is appropriate when the schema does all the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Lists subfolders in a specific folder.' This is clear and distinguishable from siblings like list_folders (which lists top-level folders) and get_subfolder (which retrieves a single subfolder). However, it doesn't explicitly differentiate itself from those siblings in the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides detailed authentication and permission requirements, but gives no guidance on WHEN to use this tool versus alternatives such as list_folders or get_subfolder. There are no exclusions, prerequisites, or routing cues for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tagsList TagsB

Read-onlyIdempotent

Lists tags belonging to the account.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id`, `updated` and `created` are supported. All other sort_by options require offset pagination.
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc)

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuine context the annotations lack — the required API token permissions and the delegate-to-contact authorization behavior. It stops at 'Read-only account operation,' which restates the annotation rather than adding return/pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The substantive sentence is front-loaded and tight, but the body is largely a repeated permissions boilerplate block, and the closing 'Read-only account operation' duplicates the readOnlyHint annotation. Some of the length is not earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 optional pagination parameters fully described in the schema and no output schema, the description need not explain return values. It usefully fills the auth gap, but gives no guidance on choosing between offset and cursor pagination or on the meaning of all_pages/max_items quota consumption, leaving real gaps for a paginated list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 8 parameters, including nested cursor pagination and the sort_by/cursor interaction constraint, so the schema carries the full burden. The description contributes nothing about pagination mode selection or defaults, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

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: 'Lists tags belonging to the account.' That is unambiguous. It does not, however, distinguish this from siblings like create_tags, delete_tag, or bulk_tag, so an agent gets no routing help.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives, no mention of filtering, and no note about how it relates to the tag mutation siblings. The only guidance is an authorization precondition, not usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_visitorsList VisitorsB

Read-onlyIdempotent

This endpoint provides a list of visitors that have watched videos in your account.

Requires api token with one of the following permissions

Read detailed stats

ParametersJSON Schema

Name	Required	Description
`page`	No	The page of results based on the per_page parameter.
`filter`	No	Filtering parameter to narrow down the list of visitors.
`search`	No	Search for visitors based on name or email address.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`per_page`	No	The maximum number of results to return, capped at 100.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered structurally. The description usefully adds the required token scope ('Read detailed stats') and delegation behavior, but 'Read-only account operation' merely restates the annotation and it says nothing about rate limits or result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence, and the remaining lines are structured permission boilerplate. It is a bit verbose relative to what it conveys, but nothing is truly wasted and the ordering is sensible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list endpoint with full annotation coverage, complete schema descriptions and no output schema, the definition supplies purpose plus the auth requirements an agent needs. The one real gap is the absence of any routing between this and get_visitor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 page, filter, search, per_page, all_pages and max_items thoroughly. The description adds no parameter-level meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource with scope: 'list of visitors that have watched videos in your account.' This tells an agent exactly what is returned and is distinguishable from the singular get_visitor sibling by the plural resource. It does not explicitly name or contrast the alternative, so it stays at 4.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains required token permissions but gives no when-to-use vs when-not guidance and never mentions the sibling get_visitor for single-visitor lookups. The only 'guidance' is an auth prerequisite, not a selection criterion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_webinar_collaboratorsList Webinar CollaboratorsA

Read-onlyIdempotent

Lists the collaborators (contacts and contact groups) that have been granted producer access to a webinar.

Results are scoped to what the authenticated user is allowed to see: account owners, managers, and the webinar's producers see all collaborators; everyone else sees an empty list.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Ordering. When using cursor pagination (see cursor param), only `id` is supported.	id
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`webinar_id`	Yes	Webinar Hashed ID
`sort_direction`	No	Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so credit is for added context: the description discloses the permission requirements and, importantly, that non-privileged users receive an empty list rather than an error. Return format/pagination behavior is left unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by the scoping caveat and permission block. Efficient overall, though the trailing 'Read-only account operation' line is redundant and the permission boilerplate is verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with full schema coverage and no output schema, the description covers purpose, access semantics, and permissions adequately. It could note return shape/pagination results, but what's needed to call it correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all 9 parameters including the nested cursor object and pagination options. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists the collaborators ... granted producer access to a webinar') and narrows scope to producer-access contacts and contact groups. This clearly distinguishes it from siblings like list_webinar_registrations or list_channel_collaborators.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for use: it specifies the required API token permissions and the delegate_to_contact scope, plus the visibility scoping (who sees all vs empty). It does not explicitly say when to prefer an alternative sibling, so it stops short of the 5 tier.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_webinar_registrationsList Webinar RegistrationsA

Read-onlyIdempotent

Retrieve a paginated list of registrations for a webinar. Returns contact information, attendance status, engagement metrics, and attribution data for each registrant.

Pagination uses cursor-based pagination with a page_info object in the response rather than per-record cursors. Use page_info.end_cursor as the cursor parameter to fetch the next page.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Cursor for pagination. Use the value from the previous response's `page_info.end_cursor` or `page_info.start_cursor`.
`emails`	No	Filter registrations by email addresses.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`per_page`	No	Number of results to return per page (max 100).
`attendance`	No	Filter registrations by attendance status.	all
`webinar_id`	Yes	Hashed ID of the webinar.
`restriction`	No	Filter registrations by restriction status.	all
`sort_direction`	No	Sort direction (0 = desc/previous page, 1 = asc/next page; default is 1)

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral value beyond annotations: the required permission scopes, the read-only nature of the operation, and the cursor-based pagination contract via page_info.end_cursor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and return shape are front-loaded, followed by pagination and permission details. The permission block is somewhat verbose but each section is relevant; nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 naming the return fields, and it covers the pagination and auth requirements. An agent has enough to invoke the tool correctly; only explicit sibling routing is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 earns extra credit by explaining the pagination mechanism in a way the schema alone does not: the cursor comes from the response's page_info.end_cursor rather than per-record cursors.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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: 'Retrieve a paginated list of registrations for a webinar.' It further enumerates what each record contains (contact info, attendance, engagement, attribution), distinguishing it from sibling analytics tools like get_webinar_audience or get_webinar_registration_timeseries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the required token permissions and the delegate-to-contact scope, which is genuine usage context. However, it never states when to prefer this tool over alternatives such as get_webinar_audience, so selection guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_webinarsList WebinarsA

Read-onlyIdempotent

Lists webinars belonging to the account. This endpoint can also be used to do a batch fetch based off of the hashed id.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number to retrieve. This cannot be combined with `cursor`, pagination.
`cursor`	No	If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch. For example, you cannot fetch using `sort_by` id and then pass that cursor value to a `sort_by` name.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`sort_by`	No	Field to sort by. When using cursor pagination (see cursor param), only `id` and `scheduled_for` are supported. All other sort_by options (`title`, `created`, `updated`) require offset pagination.
`started`	No	Filter by whether the webinar has started. Use "true" for webinars that have started, "false" for webinars that have not started yet
`per_page`	No	The number of medias per page. Use this for both offset pagination and cursor pagination.
`all_pages`	No	Read bounded page/per_page pages; each request consumes API quota. Not a snapshot or guaranteed complete backup.
`max_items`	No	Maximum returned records with all_pages=true, default 1000. At most 100 requests; output includes continuation state.
`hashed_ids`	No	Filter by specific webinars IDs
`sort_direction`	No	Sort direction (0 = desc, 1 = asc; default is 1)

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuinely useful non-annotation context: the exact permission scopes required ("Read all data") and the delegate_to_contact_permissions behavior that re-authorizes requests under the assigned contact. That is meaningful auth context rather than a restatement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is well front-loaded, but the permission block is bulky boilerplate and the closing "Read-only account operation." merely repeats the readOnlyHint annotation, so not every sentence earns its place. Acceptable but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Ten parameters with nested cursor objects and three enums, but full schema coverage and a description that supplies the auth/quota context the schema does not. With no output schema, the omission of return-shape detail is only a minor gap given the schema's richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains page, cursor, sort_by, per_page, all_pages, max_items and hashed_ids in detail. The description only gestures at the hashed-id batch fetch, adding no syntax or behavioral nuance beyond what is already documented. Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Lists webinars belonging to the account") and adds a secondary capability (batch fetch by hashed id). It distinguishes itself adequately from write siblings like create_webinar/update_webinar, though it never explicitly contrasts with get_webinar, which is the closest alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by naming the batch-fetch path via hashed ids, and it documents auth prerequisites. However, it gives no explicit guidance on when to use this list tool versus get_webinar for a single record, nor on pagination strategy choice (offset vs cursor), which is a real decision the agent must make.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_mediaMove MediaA

Destructive

Moves up to 100 media to a folder and optional subfolder. The subfolder must belong to the specified folder.

This endpoint allows 10 requests per 5 minutes, separate from the general API rate limit. Returns a Background Job because the move is asynchronous.

For more than 100 media, multiple destinations, or mixed actions, use the Create Bulk Actions endpoint with move actions.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and authorizations granting the update permission on every media being moved and on the destination folder can also be used. subfolder_id is not available to expiring access tokens. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	The hashed ID of the folder where you want the media moved.
`hashed_ids`	No	An array of the media hashed IDs to be moved.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`subfolder_id`	No	Optional. The hashed ID of the subfolder where you want the media moved. If not provided, media will be moved to the folder's default subfolder. The subfolder must belong to the specified folder.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing a dedicated rate limit (10 requests per 5 minutes, separate from the general limit), that the move is asynchronous and returns a Background Job, and detailed permission/token scope requirements (including expiring access token caveats where subfolder_id is unavailable). This is exactly the extra behavioral context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and scope, then organizes secondary concerns (rate limit, async behavior, bulk alternative, permissions) under headers, which is easy to scan. Some of the token/permission boilerplate is lengthy, keeping it from a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 noting the return is a Background Job, and it covers rate limits, permissions, and the confirm requirement. For a 7-parameter mutation with nested payload it gives an agent everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 folder_id, hashed_ids and subfolder_id. The description reinforces the folder/subfolder relationship constraint but adds no new syntax, format, or default details beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Moves media to a folder and optional subfolder') with an explicit scope cap ('up to 100 media') and a constraint ('subfolder must belong to the specified folder'). It also differentiates itself from the sibling create_bulk_actions for larger or mixed operations, so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the alternative ('For more than 100 media, multiple destinations, or mixed actions, use the Create Bulk Actions endpoint with `move` actions') and states the selection condition. It also notes confirm=true is required for the mutation, giving the agent a clear precondition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

order_extended_audio_descriptionOrder Extended Audio DescriptionA

Destructive

Orders an extended audio description for a media. The request will charge the credit card on the account when the order is ready. Only accounts on paid plans with the order_audio_descriptions feature can use this endpoint. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`enabled`	No	Whether the extended audio description should be automatically enabled once the order is complete.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	No	The hashed id of the media to order the extended audio description for.
`ai_enabled`	No	Whether to use AI-generated audio descriptions (cheaper) or human-generated (higher quality). AI is only available for English orders.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`ietf_language_tag`	No	IETF language tag for the audio description. Defaults to `eng` (English). Non-English orders must set `ai_enabled: false` — AI-generated audio descriptions are only available in English. Spanish (`es-419`) orders are only accepted when the source media is tagged as a Spanish-language variant or has no detected language (e.g. silent videos). Spanish orders against a media in another language return `400`.	eng
`order_instructions`	No	Optional instructions for the audio description provider.

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=false? No — they declare destructiveHint=true and openWorldHint=true, but the description adds the critical financial behavior ('will charge the credit card on the account when the order is ready'), the feature entitlement gate, the confirm requirement, and side effects (share access, notify people, incur provider charges). This is exactly the kind of beyond-schema disclosure that matters for an agent deciding whether to invoke.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and its consequence (card charge), followed by eligibility and confirmation requirements. No filler, and the most decision-relevant fact (billing) comes first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object mutation with no output schema, the description covers the prerequisites and consequences an agent needs before calling: entitlement, confirmation, side effects, and charge timing. It omits nothing critical, though it could note the order is asynchronous and trackable via get_order_status.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 every parameter including the language/AI constraints and payload nesting. The description adds no parameter-level meaning, which is acceptable at full coverage but earns no bonus.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Orders an extended audio description for a media') and distinguishes this write path from the sibling read/delete variants by the order/charge framing. It does not explicitly name list/get/delete_media_extended_audio_description, but the name-plus-verb combination makes selection unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real eligibility context: paid plans with the `order_audio_descriptions` feature, and a hard `confirm=true` gate for the mutation. It stops short of naming when to choose this over alternatives such as purchase_captions or create_localization, so it is context-rich but not fully routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

publish_channel_episodePublish Channel EpisodeA

Destructive

Publishes an existing channel episode in a channel.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`publish_at`	No	The date and time when the episode is scheduled to be published in UTC timezone.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`channel_episode_hashed_id`	Yes	The hashed id of the Channel Episode

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive/openWorld/non-idempotent, and the description goes well beyond them by naming the exact permission scopes required, the confirm=true gate, and the side effects (may share access, notify people, incur provider charges). That is exactly the extra context an agent needs before firing a publish mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, followed by structured permission and confirmation requirements. The permission block is slightly verbose but every clause carries actionable constraint information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description covers auth, confirmation, and side effects well. It omits what publishing actually changes about episode visibility and how publish_at scheduling interacts with the action, which would complete the picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters including confirm and publish_at are already documented in the schema. The description adds no format, default, or interaction detail beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Publishes) and resource (channel episode) and the qualifier 'existing' distinguishes it from create_channel_episode. It does not name the obvious inverse sibling un_publish_channel_episode, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete prerequisites: a required token permission set, an alternative delegation scope, and the mandatory confirm=true flag for the write. It never states when to choose this over un_publish_channel_episode or how it relates to scheduling, so exclusions are absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

purchase_captionsPurchase CaptionsA

Destructive

This method is for purchasing English captions for a media. The request will charge the credit card on the account if successful. A saved credit card is required to use this endpoint.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`rush`	No	Enable rush order for one business day turnaround instead of the standard four, for human-reviewed captions only. Rush bills at the account's higher per-minute rate.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`automated`	No	Order computer-generated captions or human-reviewed ones. What each costs depends on the account's plan and billing settings; computer-generated captions are included at no cost on some plans and billed per minute on others.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	Unique identifier for the media.
`automatically_enable`	No	Automatically enable captions for the media once the order is ready or hold the captions for review before manually enabling.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, openWorld=true, and non-idempotent behavior, but the description adds substantive context beyond them: it charges the account's credit card on success, requires a saved card, and specifies token permission scopes. It stops short of 5 because it doesn't cover failure/refund behavior or what the confirmation response returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the billing side-effect are front-loaded in the first two sentences, which is exactly right for a purchase tool. The permission block is templated boilerplate and somewhat long, but it is relevant auth information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, charge-incurring mutation with a rich nested schema and no output schema, the description covers purpose, side effects, prerequisites, and auth. The main gap is that it doesn't note how to track the resulting order (e.g. via get_order_status), but nothing critical for invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (rush, automated, automatically_enable, payload, confirm, etc.) is already documented in the schema. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'purchasing English captions for a media,' with the additional 'English' scope qualifier. An agent can tell this is a paid caption order rather than a caption-track edit. It never names or distinguishes itself from siblings like create_captions or create_bulk_purchase, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a real prerequisite (a saved credit card is required) and a required flag (confirm=true), which frame when this tool will work. However, it never says when to choose this over create_captions or how it relates to create_bulk_purchase, leaving the key routing decision to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_resource_urlsResolve Resource URLsA

Read-onlyIdempotent

Resolves a resource's hashed ID and type to its canonical app URL(s) : deep links an authorized user can open in the Wistia UI. The URL is only returned when the authenticated user is allowed to view the resource.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`type`	Yes	The kind of resource the hashed ID refers to.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`hashed_id`	Yes	The hashed ID of the resource.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description adds genuinely new context beyond them: the required permission scope ('Read all data'), the delegate-to-contact token variant, and the conditional behavior that the URL is suppressed when the caller lacks view access. The trailing 'Read-only account operation.' restates the annotations rather than adding value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Core purpose is front-loaded in the first sentence, which is good. But the pasted permission block is bulky boilerplate and the trailing fragment 'Read-only account operation.' is redundant with the annotations and reads as an artifact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does explain the return (canonical app URL(s)) and its conditional nature, and it covers auth requirements that the schema cannot. It is nearly complete; only the sibling boundary and the 'account' parameter behavior are left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 maps loosely to two of the three params ('hashed ID and type') but adds nothing about the 'account' parameter or the meaning of the type enum values beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (resolves) and resource (a resource's hashed ID and type) with a concrete outcome (canonical app URL / deep link openable in the Wistia UI). It does not name or differentiate itself from the nearby 'resolve_share_link' sibling, so an agent must infer the boundary between the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the stated input and output, and the description notes the precondition that the URL is only returned when the authenticated user can view the resource. However, it offers no explicit when-to-use guidance or comparison against alternatives such as resolve_share_link or get_media.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_share_linkResolve share linkA

Read-onlyIdempotent

Resolves a share link URL segment : the part after /s/ in a share link like https://example.wistia.com/s/summer-sale : to the share link and the media it points to, including the media's hashed ID.

The identifier may be the share link's hashed ID or its custom slug. Historical slugs that were later changed still resolve to the link.

Requires api token with one of the following permissions

Read all folder and media data

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`identifier`	Yes	The share link's URL segment — its hashed ID or custom slug.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real value beyond them: the exact required permission set, delegation behavior for `all:delegate_to_contact_permissions` tokens, and the notable trait that superseded slugs still resolve.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is front-loaded with the essential mechanics and there is little filler. The permission block is boilerplate but useful, and the trailing 'Read-only account operation.' merely restates the readOnlyHint annotation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 by naming the share link and the pointed-to media plus its hashed ID. Combined with explicit auth/permission requirements, an agent has enough to invoke it correctly; a note on error/not-found behavior would complete it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters, making 3 the baseline. The description adds minor meaning by framing `identifier` as the URL segment and enumerating its two accepted forms, but does not go beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (resolves) and resource (a share link URL segment), and precisely defines the input as the part after `/s/` plus what it returns (the link and the media, including its hashed ID). It never differentiates itself from close siblings like get_share_link or resolve_resource_urls, so it falls short of the 5 bar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: it says the identifier can be a hashed ID or custom slug and that historical slugs still resolve, which helps an agent know this tool accepts things get_share_link may not. But there is no explicit when-to-use/when-not or a named alternative, so it remains minimum-viable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

restore_deleted_mediaRestore Deleted MediaA

Destructive

Restores one or more soft-deleted media. By default each media returns to the folder it was deleted from; pass folder_id to restore them into a specific folder instead. Only media still inside the restore window can be recovered. The restore runs asynchronously and the response includes a background job status.

Requires api token with one of the following permissions

Upload and view media

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	Optional hashed id of the folder to restore the media into. If omitted, each media returns to the folder it was deleted from.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_ids`	No	The hashed ids of the soft-deleted media to restore. Up to 1000 at a time.

TDQS

A3.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond the annotations: the restore window limit, asynchronous execution with a background job status in the response, the required API token permission (and delegated-token behavior), and the confirm=true mutation requirement. Annotations cover the safety profile, but these operational traits are genuinely new information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Core behavior is front-loaded in one dense sentence, then defaults, constraints, and async behavior. The trailing permissions/confirm block is boilerplate but relevant to correct invocation; overall it is reasonably sized and every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter mutation with nested payload and no output schema, the description covers permissions, confirmation, async behavior, and return-shape ('background job status'). It is close to complete, with the only real gap being how it relates to the sibling restore_media.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 folder_id, media_hashed_ids, confirm, payload, and payload_file. The description restates folder_id semantics (default original folder vs. explicit target) but adds no format, ordering, or error-handling detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Restores one or more soft-deleted media') and narrows scope with the restore-window constraint. It does not, however, distinguish itself from the similarly named sibling restore_media, which an agent could easily confuse with restore_deleted_media.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the constraint 'Only media still inside the restore window can be recovered' and the folder_id default behavior, but it never says when to choose this over restore_media or explicitly recommends list_deleted_media to obtain the hashed ids. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

restore_mediaRestore MediaA

Destructive

Restores archived medias to your account. This method accepts a list of up to 100 medias to restore per request. It processes requests asynchronously and will return a background_job_status object rather than the typical Media response object. Your account must have access to the Archiving feature to use this method.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	No	The hashed ID of the folder to restore the medias to.
`hashed_ids`	No	An array of the media hashed IDs to be restored.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond annotations: the operation is asynchronous, returns a background_job_status object instead of a Media object, needs confirm=true, needs specific token permissions, and may share access, notify people or incur provider charges. These are real behavioral traits an agent must know before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior, async return type, and prerequisite are front-loaded in the first few sentences. The permission/token block is verbose boilerplate but standard for this API surface, so it costs some conciseness without obscuring the essentials.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and a nested payload, the description covers what it does, the async return shape (background_job_status), the prerequisite feature, and the confirm requirement. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 the 100-media batch constraint on hashed_ids and reiterates the confirm=true requirement, both of which add meaning beyond the schema fields themselves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (restores archived medias) and clarifies scope with the 100-item batch limit. However it never names the closely related siblings archive_media or restore_deleted_media, so the archived-vs-deleted distinction must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: requires Archiving feature access, requires confirm=true, and specifies batch size. It does not name alternative tools (e.g. restore_deleted_media) or state when this should not be used, so it falls short of explicit when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

searchSearchA

Read-onlyIdempotent

Searches across folders, subfolders, medias, channels, channel episodes, and webinars. Also searches through video transcripts, so media results may include transcript matches with timestamps when the query matches spoken content.

Requires api token with one of the following permissions

Read all data

ParametersJSON Schema

Name	Required	Description
`q`	Yes	The search query string
`tags`	No	Filter results by one or more tag names. When multiple tags are provided, results matching any of the specified tags are returned (OR logic).
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`include`	No	Pass `custom_metadata` to include each media result's custom metadata field values (same shape as the Get Custom Metadata Field Values endpoint). Only available on accounts with access to custom metadata (other accounts receive a 403 when this parameter is passed).
`created_after`	No	Filter results created on or after this datetime. Must be a valid ISO8601 timestamp in UTC (ending with 'Z').
`resource_type`	No	Filter results by one or more resource types.
`created_before`	No	Filter results created on or before this datetime. Must be a valid ISO8601 timestamp in UTC (ending with 'Z').
`custom_metadata`	No	Filter media by custom metadata field value, keyed by field key: `custom_metadata[<field_key>]=<value>`. Only available on accounts with access to custom metadata (other accounts receive a 403 when this parameter is passed). Custom metadata only exists on media, so results contain media only and `resource_type` must include `media`. Use an empty `q` to match all media. The value shape depends on the field's type: - Select, text, url, and email fields take a value (`custom_metadata[region]=emea`) or an array of values matched as OR (`custom_metadata[region][]=emea&custom_metadata[region][]=amer`). Select fields match on option keys. - Boolean fields take `true` or `false`. - Number, money, and time fields take an exact number (`custom_metadata[year]=2026`) or a range object (`custom_metadata[budget][min]=100&custom_metadata[budget][max]=500`; either bound may be omitted). - Date and datetime fields take a `YYYY-MM-DD` date matching that UTC day, or a range object with ISO8601 bounds (`custom_metadata[shoot_date][after]=2026-01-01`, `custom_metadata[shoot_date][before]=2026-02-01T00:00:00Z`). A bare-date bound covers its whole UTC day: `after` starts at the day's beginning and `before` runs through the day's end. - Contact fields (`contact_ref`, `contact_multi_ref`) only support the presence filter below; a value filter on them is rejected. - Any field type accepts a presence filter: `custom_metadata[region][exists]=false` returns media missing the field entirely (useful for metadata coverage audits), and `exists=true` returns media that have any value for it. Unknown or archived field keys return a 400, as do select option keys that don't exist on the field. The primary match set holds at most 100 media with no pagination; a non-blank `q` can add up to 100 more transcript-only matches, and an empty-`q` audit returns at most 100. Narrow large audits (e.g. with `created_after`/`created_before`) to complete full coverage.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds genuinely new behavioral context: the required permission scope ('Read all data'), the delegation scope behavior ('Act with a team member's permissions'), and that results can include transcript matches with timestamps. This exceeds what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, with transcript behavior immediately after and auth requirements last. The permission block is somewhat verbose but each part (scope name, delegation semantics) carries information an agent needs to call successfully.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-param tool with a nested object and no output schema, the description covers purpose and auth while the schema fully documents parameters and result limits. The main gap is that return shape (result ordering, mixing of transcript vs primary matches) is not described, though no output schema exists to carry it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including a richly documented custom_metadata parameter with value shapes, error behavior, and 100-result limits. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (searches) and enumerates the exact resource types covered (folders, subfolders, media, channels, channel episodes, webinars), plus transcript content. This clearly distinguishes it as the unified cross-resource search entry point, though it never names the sibling list_*/find_* tools it overlaps with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the enumerated searchable domains and the note that transcript matches carry timestamps, so an agent can infer when this applies. However, there is no explicit when-to-use vs alternatives guidance (e.g., versus list_media or find_caption_matches), and no exclusions or prerequisites beyond auth.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_account_trialStart Account TrialA

Destructive

Starts a business-tier trial on the current account. The plan tier is hardcoded : the only caller is the Wistia desktop app's "Invite and start trial" onboarding CTA.

Requires the current contact to be authorized to start the trial via the account's AccountPolicy : otherwise returns 403.

Requires api token with one of the following permissions

Read, update & delete anything

Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true) by disclosing the AccountPolicy authorization gate, the 403 failure mode, the hardcoded tier, the required confirm=true flag, and the side effects of sharing access, notifying people, and incurring provider charges. This is exactly the extra operational context the flags alone 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by caller scope, precondition, permissions, and the confirm requirement. The permissions block is boilerplate but functional; a couple of trailing clauses could be tightened without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-required-param mutation with no output schema, the description covers the critical concerns: authorization gate, error behavior (403), confirmation requirement, and side effects. It doesn't describe the success response shape, but with no output schema that omission is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both 'account' (credential selector) and 'confirm'. The description reinforces that confirm=true is mandatory for the mutation but adds no new syntax or format detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Starts a business-tier trial on the current account') and pins the exact plan tier (hardcoded business-tier). No sibling performs anything comparable, so an agent can identify it unambiguously from the name and first sentence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description scopes usage tightly by naming the sole caller (the desktop app's 'Invite and start trial' onboarding CTA) and the authorization precondition (current contact must be permitted via AccountPolicy, else 403). There are no alternate tools to compare against, so no explicit 'use X instead' is needed, but it never states when-not to call it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

swap_mediaSwap MediaA

Destructive

Swap one media with another media. This operation queues a background job to replace the original media with the replacement media while preserving the original media's hashed ID and URLs.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope can also be used when its authorizations grant the update permission on both the media being replaced and the replacement media. A replacement media the token does not name is treated as not found. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	The hashed ID of the media to be replaced.
`replacement_media_id`	No	The hashed ID of the media that will replace the original media. Must be the same media type as the original.

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that a background job is queued, that confirm=true is mandatory, the exact permission scopes required, expiring-token authorization semantics, and that the operation 'may share access, notify people or incur provider charges.' This is rich mutation context layered on top of destructiveHint/openWorldHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core operation and side-effect warning are front-loaded, and the auth block is clearly delineated in its own section. The permission prose is somewhat verbose and repetitive for a tool that mostly needs the when-to-use framing, but every part is relevant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, nested-object mutation with no output schema, the description covers the queued-job behavior, auth requirements, confirm gate, and side effects. It omits what happens on failure and whether the background job's progress can be tracked (e.g., via get_job_status), leaving a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 media_hashed_id, replacement_media_id, confirm, account, payload, and payload_file. The description adds little parameter-level detail beyond restating the confirm requirement and the same-media-type constraint, which the schema already states. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (swap one media with another), plus the key scoping fact that the original media's hashed ID and URLs are preserved. This distinguishes it clearly from siblings like copy_media, update_media, and upload_media, which do not retain the original identity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete preconditions (confirm=true, required permission scopes, delegated/expiring token behavior) and describes the outcome (background replacement preserving identity). It does not explicitly contrast when to use this versus copy_media or upload_media, so the agent must infer the 'replace in place' scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

translate_mediaTranslate MediaA

Destructive

Translates the transcript for a media.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`media_hashed_id`	Yes	The hashed ID of the media.
`source_language`	No	The language of the source transcript. Use the bibliographic ISO 639-2 form or a supported regional or script IETF tag. If not provided, the media's default transcript language will be used.
`target_language`	No	The language to translate the transcript to. Use the bibliographic ISO 639-2 form or a supported regional or script IETF tag.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructive/openWorld annotations, the description discloses real operational behavior: the required permission tier, the delegated-scope alternative, the mandatory confirm=true gate, and side effects (sharing access, notifying people, provider charges). It stops short of describing reversibility or whether translation is asynchronous/job-based.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in one line and the requirement block is header-structured, but the permission boilerplate is lengthy and largely templated across sibling tools, diluting the signal. It is organized but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, no-output-schema mutation with 7 params and a nested payload, the definition covers auth, confirmation, and side effects well. Remaining gaps (reversibility of the translation, sync vs. async execution) are minor since output values need not be explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 account, confirm, payload, source/target language, etc. The description adds no syntax, format, or default detail beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (translates) and resource (transcript for a media), so the operation is unambiguous. It does not, however, distinguish itself from adjacent localization/caption tools such as create_localization or update_captions, leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description supplies concrete prerequisites (token permissions, delegate scope, confirm=true), which implies usage conditions, but it never says when to prefer this tool over create_localization or get_media_languages, nor when-not to use it. Guidance is present but indirect.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

un_publish_channel_episodeUn-publish Channel EpisodeA

Destructive

Un-publishes an existing channel episode in a channel.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`channel_episode_hashed_id`	Yes	The hashed id of the Channel Episode

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, openWorldHint=true and idempotentHint=false, so safety is partly covered. The description adds genuinely useful context beyond annotations: required permission scopes, delegation-token behavior, the confirm=true gate, and side effects (may share access, notify people, incur charges).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence and the requirements follow in logical order. The permission boilerplate is lengthy but information-dense rather than redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description covers auth scopes, the confirm gate, and side effects adequately. Only the when-to-use distinction against sibling episode operations is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 account, confirm and channel_episode_hashed_id. The description adds no additional parameter meaning (e.g., format of the hashed id or account selection nuance) beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Un-publishes an existing channel episode'), clearly distinct from create/publish/delete siblings in action. It doesn't explicitly contrast with publish_channel_episode or delete_channel_episode, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to un-publish versus deleting the episode or updating it; the agent must infer intent from the name. The only operational condition given is the confirm=true requirement, which is a prerequisite rather than a use-case discriminator.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_access_customizationsUpdate Access CustomizationsA

Destructive

Applies a partial update to a video's password-protection settings. Only the fields supplied are changed; sending a field as null deletes it.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`private`	No
`media_id`	Yes	The hashed ID of the video to be customized.
`encrypted`	No
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description goes well beyond them: it explains the null-deletes-field partial-update semantics, spells out the authorization model including delegated tokens, requires confirm=true, and warns that the call may share access, notify people, or incur provider charges.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior is front-loaded in two sentences, followed by clearly delineated permission and warning blocks. Every sentence is actionable and nothing is redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, nested-object mutation with no output schema, the description covers mutation semantics, auth, and side effects adequately. It is slightly thin on how the payload/payload_file alternatives interact with the individual body flags, which an agent must infer from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 63%, so the description must carry weight, and it does: the null-deletes semantics is a critical parameter behavior not stated in the schema. It still leaves the relationship between payload, payload_file, and the individual body flags implicit, which the schema only partially documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb (partial update), the resource (a video's password-protection settings), and the scope (access customizations). This effectively disambiguates it from the many sibling customization tools such as update_sharing_customizations or update_playback_customizations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states concrete preconditions — the required permission set, the delegate-to-contact token variant, and the confirm=true requirement for the write. It does not, however, mention when to prefer this over get_access_customizations or the sibling update_*_customizations tools, so the routing guidance is incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_accessibility_customizationsUpdate Accessibility CustomizationsA

Destructive

Applies a partial update to a video's accessibility customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the video to be customized.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`captionsTextSize`	No	Size of the captions text in pixels.
`captionsTextColor`	No	Color of the captions text as a hexadecimal RGB string (no leading '#').
`transcriptEnabled`	No	If true, the interactive transcript is shown alongside the video.
`captionsFontFamily`	No	Font family used for the captions text.
`captionsBorderRadius`	No	Corner radius of the captions background in pixels.
`showTranscriptSpeakers`	No	If true, speaker labels are displayed in the transcript.
`audioDescriptionControl`	No	If true, the audio description control is available to viewers.
`captionsBackgroundColor`	No	Background color of the captions as a hexadecimal RGB string (no leading '#').

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and idempotentHint=false, and the description meaningfully extends these by explaining that omitted fields are preserved, that null values delete a field and revert it to default (the concrete form of the destructive behavior), and that the call may share access, notify people, or incur provider charges. The token-permission and confirm requirements are also spelled out, adding real value beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior is front-loaded in the first sentence, followed by the null-deletion rule, then the permission block. The markdown permission section is somewhat verbose, but it is structured and relevant to a mutation tool, so it earns its place despite some length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, nested-object mutation tool with no output schema, the description covers partial-update semantics, destructive null handling, auth scopes, the confirm gate, and side effects. It does not clarify the relationship between the body-flag parameters, the payload object, and payload_file, a minor gap given the 93% schema coverage and rich annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 93%, so the schema already documents most parameters (baseline 3). The description adds the important semantic that any field sent as null is deleted rather than ignored, which is behavior the schema's per-property descriptions do not convey, warranting an increment above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Applies a partial update') and resource ('a video's accessibility customizations'), which cleanly maps to the tool name and separates it from get_accessibility_customizations. It does not, however, explicitly distinguish itself from the many sibling update_*_customizations tools, so an agent must infer from the resource noun alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains partial-update mechanics and null-deletion, which tells the agent how to call it, and it mentions the confirm=true requirement. But it never says when to choose this over get_accessibility_customizations or the other customizations updaters, leaving usage context implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_appearance_customizationsUpdate Appearance CustomizationsA

Destructive

Applies a partial update to a video's appearance customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`branding`	No	If false, Wistia branding is hidden on the player.
`media_id`	Yes	The hashed ID of the video to be customized.
`playerColor`	No	Base color of the player as a hexadecimal RGB string (no leading '#').
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`contrastIcons`	No	If true, control icons use a higher-contrast treatment.
`roundedPlayer`	No	Corner radius of the player in pixels. 0 disables rounding.
`opaqueControls`	No	If true, player controls render on an opaque background.
`showCustomerLogo`	No	If true, your customer logo is shown on the player.
`playerColorGradient`	No	Optional gradient applied to the player color.
`customerLogoImageUrl`	No	URL of the customer logo image to display on the player.
`customerLogoPlacement`	No	Placement of the customer logo on the player (e.g. top-right).
`customerLogoTargetUrl`	No	URL the customer logo links to when clicked.
`customerLogoSizePercent`	No	Size of the customer logo as a percentage of the player.

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: the null-equals-delete/revert behavior, the required permission set, the all:delegate_to_contact_permissions token scope, the confirm=true gate, and possible side effects (sharing access, notifications, provider charges). This is rich disclosure 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core update semantics and null-deletion rule before the auth block, which is the right ordering. The permission section is somewhat verbose and could be tightened, but every block is relevant to correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter mutation tool with no output schema, the description covers auth, confirmation, partial-update behavior and side effects well. It omits any error/failure behavior and does not clarify the payload-vs-flags precedence, but with 100% schema coverage these are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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, but the description adds a semantic that the schema does not: that sending a payload field as null deletes it. That meaningfully informs how the payload fields behave on use, pushing it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Applies a partial update to a video's appearance customizations.' The resource name ('appearance customizations') inherently distinguishes it from the many sibling customization tools (playback, thumbnail, accessibility, sharing, etc.), so an agent can select it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides partial-update semantics (only supplied fields change; null deletes and reverts to default), which is real operational guidance. However, it never states when to choose this tool over the parallel update_*_customizations siblings or when to prefer payload vs. body flags vs. payload_file; usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_brandUpdate BrandA

Destructive

Updates a brand. Only the fields you send are changed; send an explicit null to unset one. Renaming the account-level default brand is ignored : its name is managed by Wistia.

Changes propagate to everything the brand is applied to.

Requires api token with one of the following permissions

All data

ParametersJSON Schema

Name	Required	Description
`name`	No	The brand's display name. Renaming the account-level default brand is ignored; its name is managed by Wistia.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`brand_id`	Yes	The id of the brand
`page_logo`	No	The brand logo used for pages. `url` must be a Wistia delivery URL — see the note on uploading below. On accounts without custom branding the player logo is ignored, but the page logo is always applied.
`player_logo`	No	The brand logo used for the player. `url` must be a Wistia delivery URL — see the note on uploading below. Ignored on accounts whose plan doesn't include custom branding.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`border_radius`	No	The border radius in pixels for rounded corners.
`primary_color`	No	The primary brand color, used for primary buttons and the player playbar. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples.
`contrast_icons`	No	Controls whether the player icon color is always white or uses an accessible contrast color when necessary.
`opaque_controls`	No	Controls the opacity of the video player control bar and big play button.
`body_font_family`	No	The brand font family for body text.
`button_font_family`	No	The brand font family for buttons.
`headline_font_family`	No	The brand font family for headlines.
`page_background_color`	No	The brand color used for page backgrounds. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/non-idempotent/open-world, so the description is not carrying the safety burden alone. It adds real value beyond them: partial-update semantics, null-to-unset behavior, the ignored default-brand rename, propagation of changes to everything the brand is applied to, and the confirm=true gate. The trailing 'may share access, notify people or incur provider charges' is generic boilerplate that dilutes it slightly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the operation and its key semantics in the first two sentences, then moves to permissions. The permissions block and the generic action-caveat sentence add bulk but the useful information is not buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema but full schema description coverage and annotations, the description covers the mutation contract, the ignored-field edge case, propagation, auth requirements, and the confirm gate. Only an explicit note on return value/response shape is absent, which is minor given the annotation profile.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 rises above it by explaining the cross-cutting mutation contract (only sent fields change, explicit null unsets) that governs all 16 parameters and is not spelled out per-field. Field-specific meaning is left entirely to the schema, which is acceptable at full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Updates a brand') and immediately narrows scope with partial-update semantics ('Only the fields you send are changed'). An agent can distinguish it from get_brand, delete_brand, create_brand and apply_brand from the name plus first sentence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful conditional rules (send explicit null to unset; renaming the default brand is ignored) and a prerequisite (confirm=true), but never states when to choose this tool over siblings like apply_brand, update_brand_preload, or update_customizations. Usage is implied rather than routed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_brand_preloadUpdate Brand PreloadA

Destructive

Persists the account's default page logo (by Bakery hashed_id) and default player color. Both fields are optional independently : omit a field to leave that account setting untouched. Passing an empty string for selected_logo_hashed_id clears the logo.

Requires the OAuth contact to be an owner or manager of the account (or a Wistia admin) : mirrors the auth check on the underlying updateWtwBrandKitAccountSettings GraphQL mutation.

Deliberately narrower than the mutation: this endpoint does not create/update BrandKits or set body font family. Glass's onboarding customize step writes only these two fields; broader brand-kit editing continues to happen through the WTW web UI + GraphQL.

Requires api token with one of the following permissions

(any scope allowed)

Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`selected_player_color`	No	Hex color string (e.g. "#3366FF") for the account's default player color — 6 hex digits, with or without the leading `#`. Omit or send an empty string to leave the current color untouched (there is no clear operation — color always has a value). Malformed values are rejected at the API boundary; without this check, the model's sanitize step would return nil and silently reset the account color to the global default.
`selected_logo_hashed_id`	No	Bakery hashed_id of an uploaded logo image, which will become the account's default page logo. Omit to leave the current logo untouched. Pass an empty string to clear the logo.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/non-idempotent/open-world, and the description adds material context beyond them: owner/manager-or-Wistia-admin auth requirement mirroring updateWtwBrandKitAccountSettings, the confirm=true gate, the empty-string clear semantics, and the silent-reset failure mode when the color sanitize step returns nil. These are real behavioral disclosures, not restatements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what the tool writes, followed by optionality rules, auth, and scope limits in descending priority. The appended permissions block and minor repetition of the clear/omit rule cost some tightness, but every core sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation with 100% schema coverage and no output schema, the description covers the remaining gaps an agent needs: exactly which two fields are written, auth requirements, confirmation requirements, clearing behavior, and the deliberate scope ceiling. 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.

Parameters4/5

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 usefully consolidates the omit-vs-clear rule across both the top-level and nested duplicate parameters and notes there is no clear operation for color. This adds modest meaning over the schema, which already carries most of the field detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (persists the account default page logo and default player color) and names exactly what is written. It explicitly distinguishes itself from the broader underlying mutation and from the rest of the brand-kit tooling, so an agent can separate it from siblings like update_brand, create_brand, and get_brand_preload 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage conditions: both fields optional independently, omit to leave untouched, empty string clears the logo, and broader brand-kit editing should go through the WTW web UI + GraphQL. It stops short of naming a specific sibling tool as the alternative, but the when/when-not boundary is well drawn.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_captionsUpdate CaptionsA

Destructive

This method is for replacing the captions on a video or audio media for the specified language.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`caption_file`	No	Either an attached SRT file or a string parameter with the contents of an SRT file.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`language_code`	Yes	Language code conforming to ISO-639-2 for which the captions should be updated.
`media_hashed_id`	Yes	Unique identifier for the media.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive=true, idempotent=false, openWorld=true, but the description goes further by naming the required token scopes, the delegation scope option, the confirm=true gate, and the warning that the call 'may share access, notify people or incur provider charges.' That extends well beyond the structured safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in one sentence, followed by scoped permission and side-effect blocks. The code-fenced permission text is somewhat bulky, but each section carries distinct operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the definition covers purpose, auth requirements, the confirm gate, and side-effect risk. There is no output schema to explain return values, and the schema fully documents the seven parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so media_hashed_id, language_code (ISO-639-2), caption_file format, account, and confirm are all documented in the schema itself. The description adds nothing about parameter format or interaction (e.g., payload vs caption_file vs payload_file exclusivity), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('replacing the captions') and resource scope (video/audio media, specified language), so the agent knows this is an overwrite rather than an append. It does not, however, distinguish itself from siblings like edit_captions_text or create_captions, leaving the boundary between 'update' and 'edit' unclear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides auth prerequisites and the confirm=true requirement, which is real operational guidance. But it never says when to choose this over edit_captions_text, create_captions, or delete_captions, nor what happens if captions for the language don't already exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_channelUpdate ChannelB

Destructive

Updates a channel. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`name`	No	The display name for the channel
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`custom_url`	No	Use if embedding the channel on your own site. The custom URL ensures links always direct to your page and not Wistia's.
`description`	No	The channel's description.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`podcast_enabled`	No	Whether podcasting is enabled for this channel.
`podcast_settings`	No	Podcast specific settings for a channel. These settings only take effect if podcasting is enabled for the channel. These values appear in the channel's publicly accessible podcast RSS feed.
`channel_hashed_id`	Yes	The hashed id of the Channel
`auto_publish_enabled`	No	Whether the episodes are automatically published when added to the channel. Cannot be enabled if podcasting is on.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation profile is known. The description adds genuinely new context: the confirm=true precondition and side effects (sharing access, notifying people, incurring provider charges). The hedge 'May' leaves these effects unquantified, keeping it below 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and then the precondition and side effects. No filler, though the second sentence is a vague catch-all that could be sharpened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter mutation with nested podcast objects and no output schema, the description covers the mutation gate and side effects but says nothing about the payload vs. payload_file vs. body-flags alternatives, which the schema notes are mutually exclusive. Adequate but with a notable routing gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all 11 parameters including the confirm semantics. The description merely restates the confirm requirement and adds no syntax, format, or interaction details beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource ('Updates a channel'), so the operation is unambiguous. However, it offers no differentiation from adjacent siblings such as update_channel_episode, update_brand, or update_webinar, which an agent must distinguish. Clear but not distinctive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives (e.g. update_channel_episode for episode-level edits, or create_channel). The only conditional given is the confirm=true requirement, which is a gate, not a when-to-use rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_channel_episodeUpdate Channel EpisodeA

Destructive

Updates an existing channel episode in a channel.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`title`	No	The episode's title. If not provided, the channel episode uses the title of the media used to create it.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`summary`	No	A short summary of the episode that is displayed when space is limited.
`publish_at`	No	The date and time when the episode is scheduled to be published in UTC timezone.
`description`	No	The episode's description or episode notes.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`episode_notes`	No	Additional notes for the episode.
`publish_status`	No	The status of whether or not the episode has been published to your channel.
`media_hashed_id`	No	The unique alphanumeric identifier for the media associated with this channel episode.
`podcast_settings`	No	Podcast specific settings for a channel episode. These settings only take effect if podcasting is enabled for the channel.
`channel_episode_hashed_id`	Yes	The hashed id of the Channel Episode
`live_stream_event_hashed_id`	No	The unique alphanumeric identifier for the live stream event associated with this channel episode.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false. The description adds valuable context beyond annotations: required token permissions, the need for confirm=true, and warnings that it may share access, notify people, or incur provider charges. This is meaningful behavioral disclosure 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, then details permissions and requirements in a structured way. It includes some repetitive phrasing (e.g., 'Requires api token' and code block) but overall it's efficient and each sentence serves a purpose. Minor verbosity but not distracting.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (14 params, nested objects, no output schema), the description covers required permissions, mutation confirmation, and side effects, which are critical for safe invocation. However, it doesn't explicitly state what happens when required parameters are missing or how updates are applied (e.g., partial update semantics), leaving some gaps for a destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 14 parameters including nested payload fields. The description mentions confirm=true but adds no other parameter semantics beyond what the schema provides. Baseline 3 is appropriate when schema does all the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states a specific verb (updates) and resource (channel episode), which distinguishes it from create_channel_episode and delete_channel_episode. It doesn't explicitly mention siblings, but the verb+resource combination is unambiguous in context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions the required permission scope and that confirm=true is needed, which gives some prerequisites for use. However, it offers no guidance on when to use this tool versus alternatives like publish_channel_episode or create_channel_episode, nor does it state exclusions. Usage is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_chapters_customizationsUpdate Chapters CustomizationsA

Destructive

Applies a partial update to a media's chapter customizations. Only the fields supplied are changed; sending a field as null deletes it.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the media to be customized.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: it discloses partial-update semantics (only supplied fields change), null-deletes-field behavior (the destructive mechanism behind destructiveHint), token/permission prerequisites including delegated tokens, the mandatory confirm=true, and side effects (may share access, notify people, incur charges). This is rich behavioral context beyond what readOnlyHint/destructiveHint declare.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the crucial behavior (partial update, null deletion) in the first two sentences, then layers auth and confirm requirements. The permission block is somewhat verbose but each element is actionable; the trailing side-effect sentence is broad but relevant for a destructive write.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex nested mutation with no output schema, the description covers the essential operational facts an agent needs (partial semantics, deletion, auth, confirmation). It omits how chapterList merges/replaces or the meaning of the "deleted" string field, leaving minor gaps for a tool this complex.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (83%), so the nested plugin/chapters/chapterList fields are already documented. The description adds conceptual meaning for the payload (partial update, null deletes) but does not explain the payload-vs-body-flags-vs-payload_file routing or per-field behavior beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Applies a partial update to a media's chapter customizations"), scoping to chapters specifically and distinguishing it from the many sibling update_*_customizations tools. An agent can identify the target resource 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.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides meaningful operational context (confirm=true required, permission/token requirements, delegate scope) but never explicitly states when to prefer this over siblings like get_chapters_customizations or the generic update_customizations. Usage is implied rather than stated, and no exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_customizationsUpdate CustomizationsA

Destructive

Allows for partial updates on a video’s customizations. If a value is null, then that key will be deleted from the saved customizations. If it is not null, that value will be set.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`seo`	No	If set to true, the video’s metadata will be injected into the page’s markup for SEO.
`time`	No	Sets the starting time of the video.
`email`	No	Associate a specific email address with this video’s viewing sessions.
`muted`	No	If set to true, the video will start in a muted state.
`wmode`	No	If set to transparent, the background behind the player will be transparent instead of black.
`plugin`	No
`volume`	No	Sets the volume of the video.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`playbar`	No	If set to true, the playbar will be available. If set to false, it will be hidden.
`preload`	No	Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.
`autoPlay`	No	If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers.
`media_id`	Yes	The hashed ID of the video to be customized.
`stillUrl`	No	Overrides the thumbnail image that appears before the video plays.
`resumable`	No	Determines if the video should resume from where the viewer left off. Options are true, false, and auto.
`videoFoam`	No	When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height.
`doNotTrack`	No	If set to true, data for each viewing session will not be tracked.
`keyMoments`	No	If set to false, the key moments feature will be disabled.
`playButton`	No	Indicates if the play button is visible.
`qualityMax`	No	Specifies the maximum quality the video will play at.
`qualityMin`	No	Specifies the minimum quality the video will play at.
`fitStrategy`	No	Resizes the video when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none.
`playerColor`	No	Changes the base color of the player. Expects a hexadecimal rgb string.
`playsinline`	No	If set to false, videos will play within the native mobile player.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`playlistLoop`	No	If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.
`playlistLinks`	No	Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.
`volumeControl`	No	When set to true, a volume control is available over the video.
`fakeFullscreen`	No	If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.
`qualityControl`	No	If set to false, the video quality selector in the settings menu will be hidden.
`silentAutoPlay`	No	Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are true, allow, and false.
`settingsControl`	No	If set to true, the settings control will be available.
`smallPlayButton`	No
`endVideoBehavior`	No	Determines what happens when the video ends. Options are default (stays on the last frame), reset (shows thumbnail and controls), and loop (plays again from the start).
`fullscreenButton`	No	If set to true, the fullscreen button will be available as a video control.
`thumbnailAltText`	No	Sets the Thumbnail Alt Text for the media.
`playPauseNotifier`	No	If set to false, animations for the Pause and Play symbols will be removed.
`playbackRateControl`	No	If set to false, the playback speed controls in the settings menu will be hidden.
`controlsVisibleOnLoad`	No	If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.
`playSuspendedOffScreen`	No	If set to false for a muted autoplay video, the video won't pause when out of view.
`copyLinkAndThumbnailEnabled`	No	If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.
`fullscreenOnRotateToLandscape`	No	If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.

TDQS

A3.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds crucial behavior beyond them: passing null DELETES a key from saved customizations (a non-obvious data-destroying rule), a confirm=true requirement, specific token permission scopes including delegation, and side effects ('share access, notify people or incur provider charges'). This is rich, high-value disclosure that goes well past the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior (partial update plus the null-deletes rule) is front-loaded in the first sentences, and the permission block that follows is dense but operationally necessary. Nothing is obviously wasted, though the permission prose is somewhat verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 43-parameter destructive mutation tool with nested objects and no output schema, the description covers the critical behaviors: the null-delete rule, required permissions, and the confirm requirement. It does not address the mutually exclusive body-flag vs payload/payload_file input modes (left to the schema), so it is slightly short of fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 95%, so the per-parameter documentation is already in the schema (baseline 3). The description adds cross-cutting semantics the schema does not encode: null deletes a key while a non-null value sets it, which governs how every one of the 43 parameters behaves. That is meaningful added meaning over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('partial updates on a video's customizations'), so an agent knows exactly what operation is performed. However, it never distinguishes this general tool from the many granular siblings (update_appearance_customizations, update_playback_customizations, update_chapters_customizations, etc.), leaving the agent to guess which one to call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use vs alternative guidance despite ~15 sibling customization updaters in the set. The null-semantics rule hints at how the call behaves, but the description never says when to prefer this general tool over the category-specific update_*_customizations tools, nor does it name any alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_engagement_customizationsUpdate Engagement CustomizationsA

Destructive

Applies a partial update to a video's engagement customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No	Container for engagement plugin configurations.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the video to be customized.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/openWorld/non-idempotent, and the description adds substantially: partial-update semantics, null-as-delete (revert to default), token-permission requirements including the delegate_to_contact scope, the confirm=true gate, and an explicit side-effect warning about sharing access, notifying people, and provider charges.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Core behavior is front-loaded in the first two sentences, followed by structured permission blocks. The permission boilerplate is somewhat verbose, but every block earns its place by carrying auth and side-effect constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, deeply nested mutation with no output schema, the description covers the essential invocation constraints (confirm gate, permissions, partial/null semantics, side effects). It does not clarify how the top-level plugin/flags relate to the payload/payload_file alternatives, though the schema descriptions do cover that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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, but the description adds meaningful semantics beyond the schema by defining how field values behave (null deletes a field, absent fields are untouched), which is the key invocation rule for this deeply nested payload.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (applies a partial update), resource (a video's engagement customizations), and scope (only supplied fields change). The 'engagement customizations' resource is named, but the description never distinguishes this from the similarly named sibling update_customizations, leaving some room for confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides prerequisite conditions (required permissions, delegate scope, confirm=true), which implicitly frame when the call can succeed. However, it names no alternatives and gives no explicit when-to-use/when-not-to-use guidance relative to update_customizations or get_engagement_customizations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_folderUpdate FolderB

Destructive

Updates a folder (previously called project)

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the update permission on this folder can also be used. The update permission also allows creating, renaming and deleting the folder's subfolders and using the folder as the destination when moving or bulk-copying media the token may update. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Folder Hashed ID
`name`	No	The folder’s new name.
`public`	No	A flag indicating whether or not the folder is enabled for public access.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`description`	No	The folder’s new description.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`anonymousCanUpload`	No	Whether anonymous users can upload media to the folder.
`anonymousCanDownload`	No	Whether anonymous users can download media from the folder.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true and openWorld=true, but the description adds valuable context: required token permissions, a mandatory confirm=true, and a warning that the call 'May share access, notify people or incur provider charges.' This goes beyond the annotations and helps an agent anticipate side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, but the lengthy auth permission block and markdown code fences are verbose and only partly relevant to tool selection. A leaner summary of the auth requirement would improve signal-to-noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with a nested payload and no output schema, the description covers critical behavioral gaps: permissions, confirm, and side effects. It could say more about mutually exclusive body styles (payload vs. payload_file vs. flags), but the schema documents those.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameter meanings are fully documented in the schema itself. The description only repeats the confirm requirement and adds no syntax or field-level semantics beyond what structured data provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ('Updates a folder') and notes the former name, so the action is clear. However, it does not differentiate from sibling tools like update_subfolder or update_folder_sharing, and the rest of the description drifts into auth details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to choose this tool over update_subfolder, update_folder_sharing, or other folder-related siblings. The auth and confirm requirements are prerequisites, not selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_folder_sharingUpdate Folder SharingC

Destructive

Updates a sharing on a folder.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`sharing`	No
`folder_id`	Yes	ID of the folder
`sharing_id`	Yes	ID of the sharing to be updated
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the description's 'Requires confirm=true' and permission notes add some value. But it repeats destructive behavior rather than explaining what specifically gets overwritten, whether untouched sharing flags reset, or reversibility. With annotations carrying the safety profile, the description adds modest context only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description leads with a single short sentence, then piles on a permissions block and confirm requirement that could be more tightly structured. The permission fence block is verbose relative to the low-value behavioral information it conveys, and the ordering buries the mutation scope behind auth boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested-object mutation tool with 7 params and no output schema, the description covers permissions and confirm but does not explain the payload/sharing structure or the interaction between payload, sharing, and payload_file. It is minimally adequate given the rich schema, but an agent still has gaps about response shape and idempotency semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 86%, so the schema already documents account, confirm, payload, sharing, folder_id, sharing_id, and payload_file. The description adds no syntax or format hints beyond the schema (e.g., payload vs payload_file vs body flags precedence is only in the schema). Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Updates a sharing on a folder'), which is adequate but thin. It does not distinguish this tool from the many sibling sharing tools (create_folder_sharing, delete_folder_sharing, get_folder_sharing) beyond the verb 'update'. An agent must read the name to know the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use vs. when-not, and no named alternatives among the large set of folder-sharing siblings. The permission and confirm requirements are prerequisites, not usage guidance. The agent is left to infer that this is the mutation path after get_folder_sharing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_lead_capture_customizationsUpdate Lead Capture CustomizationsA

Destructive

Configures a single lead-capture provider for the video, mapping it to the appropriate underlying plugin. Only the selected provider is changed.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`enabled`	No	Whether the selected provider is turned on. Defaults to true.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the video to be customized.
`provider`	No	Which lead-capture mechanism to configure.
`settings`	No	Provider-specific settings. Only the fields relevant to the chosen provider are used.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description adds material context beyond them: the required token permission, the delegated-permission scope, that confirm=true is mandatory for the write, and that the call may share access, notify people, or incur provider charges. That is meaningful behavioral disclosure, though it stops short of explaining reversibility or provider-specific failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first two sentences with zero waste. The permissions/confirm block is verbose boilerplate but is clearly sectioned and load-bearing for correct invocation, so it earns its place without harming readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a non-idempotent, destructive mutation with no output schema and a nested payload, the description supplies the auth requirements, confirm requirement, and side-effect warnings an agent needs. It could go further on how the flat provider/settings params interact with the nested payload, but the rich schema covers that gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 8 parameters including the nested payload/settings objects. The description adds only the general note that a single provider is configured, which is marginal beyond the enum and field docs already present; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (configures/updates) and resource (a single lead-capture provider on a video), and clarifies scope with 'Only the selected provider is changed,' which distinguishes it from the broader update_customizations siblings. It does not name the read counterpart get_lead_capture_customizations, so it falls just short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context ('single lead-capture provider,' 'only the selected provider is changed') but gives no explicit when-to-use-vs-alternative routing among the many update_*_customizations siblings. The permissions and confirm=gating are present but that is prerequisite information, not selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_mediaUpdate MediaA

Destructive

Updates the attributes on a media.

Requires api token with one of the following permissions

Read, update & delete anything

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the update permission on this media can also be used. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`name`	No	The media’s new name.
`tags`	No	An array of tag names to apply to the media. This replaces any existing tags. To add tags without replacing existing tags, use bulk-tag-media.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`description`	No	A new description for this media. Accepts plain text or markdown.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`custom_metadata`	No	Custom metadata field values to set, keyed by field key. Values take the same shapes as the Set Custom Metadata Field Value endpoint; a null value clears that field and omitted fields are untouched. Requires the custom metadata feature on the account.
`media_hashed_id`	Yes	The hashed ID of the media.
`new_still_media_id`	No	The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description goes beyond them by naming the exact permission scopes needed, explaining the delegate_to_contact_permissions authorization model, and warning that a mutation may "share access, notify people or incur provider charges" — concrete consequences an agent can reason about. It stops short of explaining reversibility or what happens to fields left unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in a single clear sentence, but the three-paragraph access-token boilerplate is heavy relative to the operational content and consumes most of the text. It is not padded so much as unbalanced: authorization detail dominates while the actual update semantics get nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, nested-object mutation with no output schema, the description supplies the auth model and the confirm gate, which are the highest-risk unknowns, and annotations cover the destructive/idempotency profile. It is incomplete in not stating which attributes are updatable or what an unspecified field does, but an agent can call it correctly from schema plus description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 10 parameters, including nested payload properties, so the schema already carries parameter meaning (e.g., tags replacing existing tags, null clearing custom metadata, payload vs payload_file mutual exclusion). The description adds no parameter-level detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Updates the attributes on a media"), so the intent is unambiguous. However, "attributes" is generic and the description never enumerates what can be changed (name, tags, description, custom metadata, still image), so it does not distinguish itself from siblings like update_channel or update_thumbnail_customizations beyond the resource noun.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description covers authorization prerequisites well (which permission sets permit the call, delegation tokens, and the confirm=true requirement), which is usage-relevant. It gives no guidance on when to choose this tool over alternatives — nothing tells the agent when to use bulk_tag instead of setting tags here, or when to prefer update_customizations. Usage is implied only by the resource.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_playback_customizationsUpdate Playback CustomizationsA

Destructive

Applies a partial update to a video's playback customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`hls`	No	If set to true, HLS adaptive bitrate streaming is enabled.
`seo`	No	If set to true, the video’s metadata will be injected into the page’s markup for SEO.
`time`	No	Sets the starting time of the video.
`email`	No	Associate a specific email address with this video’s viewing sessions.
`muted`	No	If set to true, the video will start in a muted state.
`wmode`	No	If set to transparent, the background behind the player will be transparent instead of black.
`volume`	No	Sets the volume of the video.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`bpbTime`	No	Controls when the big play button appears, expressed as a string.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`playbar`	No	If set to true, the playbar will be available. If set to false, it will be hidden.
`preload`	No	Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.
`autoPlay`	No	If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers.
`media_id`	Yes	The hashed ID of the video to be customized.
`resumable`	No	Determines if the video should resume from where the viewer left off. Options are "true", "false", and "auto".
`spherical`	No	If set to true, the video is rendered as a spherical (360-degree) video.
`videoFoam`	No	When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height.
`doNotTrack`	No	If set to true, data for each viewing session will not be tracked.
`keyMoments`	No	If set to false, the key moments feature will be disabled.
`playButton`	No	Indicates if the play button is visible.
`qualityMax`	No	Specifies the maximum quality the video will play at.
`qualityMin`	No	Specifies the minimum quality the video will play at.
`playsinline`	No	If set to false, videos will play within the native mobile player.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`playlistLoop`	No	If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.
`videoQuality`	No	Sets the default video quality the video will play at.
`clickForSound`	No	If set to true, viewers can click to enable sound on a muted video.
`playlistLinks`	No	Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.
`volumeControl`	No	When set to true, a volume control is available over the video.
`fakeFullScreen`	No	If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.
`qualityControl`	No	If set to false, the video quality selector in the settings menu will be hidden.
`silentAutoPlay`	No	Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are "true", "allow", and "false".
`googleAnalytics`	No	Google Analytics tracking configuration to associate with this video’s viewing sessions.
`settingsControl`	No	If set to true, the settings control will be available.
`smallPlayButton`	No	If set to true, the small play button control is shown.
`endVideoBehavior`	No	Determines what happens when the video ends. Options are "default" (stays on the last frame), "reset" (shows thumbnail and controls), and "loop" (plays again from the start).
`fullscreenButton`	No	If set to true, the fullscreen button will be available as a video control.
`playPauseNotifier`	No	If set to false, animations for the Pause and Play symbols will be removed.
`playbackRateControl`	No	If set to false, the playback speed controls in the settings menu will be hidden.
`controlsVisibleOnLoad`	No	If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.
`playSuspendedOffScreen`	No	If set to false for a muted autoplay video, the video won’t pause when out of view.
`copyLinkAndThumbnailEnabled`	No	If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.
`fullscreenOnRotateToLandscape`	No	If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses several high-value behavioral traits: partial-update semantics, that sending a field as null deletes it and reverts to default, the exact permission scopes needed, the confirm=true requirement, and the side effects ('May share access, notify people or incur provider charges'). This substantially exceeds what destructiveHint/idempotentHint already convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and null-deletion behavior are front-loaded in the first sentence, with the permission/auth details kept in a separate structured block. It is appropriately sized for a 44-parameter tool, though the permissions section is somewhat bulky.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with 44 parameters, nested objects, and no output schema, the description covers purpose, mutation semantics, auth, confirmation, and side effects well. Return-value/response behavior is not addressed, but with no output schema this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 the schema does not: null values delete a field and revert to default, which is critical semantics for any of the 44 parameters. This is meaningful added value beyond the per-field schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Applies a partial update') and resource ('a video's playback customizations'), and the 'playback' qualifier clearly separates it from the many sibling customization tools (update_customizations, update_thumbnail_customizations, etc.). It is clear but does not explicitly name or contrast 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.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool's context through its mutation semantics and permission requirements, and requires confirm=true, but it never states when to prefer this over update_customizations or the other customization updaters, nor when not to use it. Usage is implied rather than prescribed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_related_media_customizationsUpdate Related Media CustomizationsA

Destructive

Applies a partial update to a video's related-media customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the video to be customized.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations that already flag destructive and non-idempotent behavior, the description discloses that only supplied fields change, null deletes a field, confirm=true is required, specific token permissions are needed, and the operation may share access, notify people, or incur provider charges. This adds substantial behavioral context an agent needs before invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear purpose sentence and partial-update behavior, followed by structured permission requirements. It is reasonably concise, though the token-permission section is somewhat verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the mutation is annotated as destructive and the schema documents most parameters, the description completes the picture by covering authorization, confirmation, partial update behavior, null deletion, and possible side effects. It does not describe the return value, but no output schema exists and this is a write operation where that is less critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high at 83%, so the schema already documents most parameters. The description still adds meaningful semantics by explaining that sending a field as null deletes it and reverts to the default, which is not captured in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Applies a partial update to a video's related-media customizations.' It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as get_related_media_customizations or update_customizations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides important invocation details: partial update semantics, null field deletion, required permissions, and confirm=true. However, it does not explicitly state when to use this tool versus alternatives like update_customizations or create_customizations, leaving that comparison implicit from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_share_linkUpdate share linkA

Destructive

Updates the share link for a single media. If the media does not have a share link yet, one is created with the supplied visibility.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the media.
`visibility`	No	Controls who can view the media via this share link. - `unlocked`: anyone with the link can view the media. - `account`: only signed-in members of the media's account can view. - `locked`: only contacts with access to the media's folder can view. - `domain_verified`: only viewers signed in with an email address at a domain verified on the media's account can view. Requires the account to be enrolled in the domain validation gate; otherwise setting this value returns 400.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false) by stating the exact permission scope required, the delegate-to-contact authorization model, the mandatory confirm=true gate, and the side effects ('May share access, notify people or incur provider charges'). This is exactly the mutation context an agent needs before invoking a destructive write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and upsert semantics in the first two sentences, then appends auth and safety constraints. The permission section is verbose boilerplate but directly relevant to a destructive write, so it earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with a nested payload and no output schema, the description covers auth, confirmation, and side effects adequately. It is silent on the response shape or what the resulting share link contains, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the visibility enum is documented in rich detail inside the schema, so the description adds little parameter meaning beyond noting that the supplied visibility is used when creating a missing link. Baseline 3 is appropriate when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Updates the share link for a single media') and adds the crucial upsert behavior: if no share link exists, one is created. This clearly separates it from get_share_link, delete_share_link and resolve_share_link, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The upsert sentence implicitly tells the agent that a separate create call is unnecessary, and the permission block spells out the auth conditions required to call it. It does not, however, name alternative tools or state when not to use this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_sharing_customizationsUpdate Sharing CustomizationsA

Destructive

Applies a partial update to a video's sharing customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the video to be customized.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive/non-idempotent/openWorld, but the description adds substantial context beyond them: required API token permissions, the delegate_to_contact_permissions scope, the confirm=true gate, and side effects like sharing access, notifying people, or incurring provider charges. This is exactly the extra behavioral detail annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence front-loads purpose and mutation semantics, followed by auth and confirmation requirements; every element is relevant. The fenced permission block is slightly verbose but functional, not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive nested-payload mutation with no output schema, the description covers authorization, confirmation, and mutation semantics well. Return behavior is not described, but with no output schema that is a minor gap and the safety-critical context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83% (baseline 3), and the description adds meaning on top: it clarifies partial mutation semantics and that null values delete fields, which governs how the nested payload/share fields must be sent. It does not explain media_id, account, or the payload vs payload_file vs body-flag exclusivity, so it falls short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('applies a partial update to a video's sharing customizations') and the paired sibling get_sharing_customizations makes the scope unambiguous versus broader update_customizations. An agent can identify the resource and the update semantics immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the partial-update contract and the null-deletes-field behavior, which is the key decision information for how to call it. It does not explicitly contrast with update_customizations or other customization updaters, so sibling routing is left to inference rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_subfolderUpdate SubfolderA

Destructive

Updates a subfolder's name and/or description.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`name`	No	The new name for the subfolder
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`folder_id`	Yes	The hashed ID of the folder
`description`	No	The new description for the subfolder
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`subfolder_id`	Yes	The hashed ID of the subfolder

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description goes beyond them by disclosing the confirm=true gate, the token/permission requirements, and side-effect potential ("May share access, notify people or incur provider charges"), which is genuinely useful for a mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded and efficient, but the multi-paragraph permission block, fenced code sample and token-scope discussion consume most of the length for a simple two-field update, and the trailing side-effect sentence is generic boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering the safety profile and the schema fully documenting all eight parameters, the description need only add auth and side-effect context, which it does. The lack of content about return behavior is acceptable since no output schema is needed for an update, though sibling routing remains unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every field including confirm, payload, and payload_file is already documented in the schema. The description only restates the name/description targets and does not add syntax or precedence detail beyond the structured fields, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource with the exact mutable fields ("Updates a subfolder's name and/or description"). It is clear and unambiguous, though it does not differentiate itself from nearby siblings like update_folder or create_subfolder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The bulk of the description documents authorization prerequisites (required scopes, delegation, expiring tokens) and the confirm=true requirement, which implicitly frames when the call will succeed. However, it offers no guidance on when to prefer this over siblings such as update_folder or when not to use it at all.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_thumbnail_customizationsUpdate Thumbnail CustomizationsA

Destructive

Applies a partial update to a video's thumbnail customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`plugin`	No	Container for thumbnail-related player plugin configurations.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`media_id`	Yes	The hashed ID of the video to be customized.
`stillUrl`	No	Overrides the thumbnail image that appears before the video plays.
`fitStrategy`	No	Resizes the thumbnail when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`thumbnailAltText`	No	Alt text for the thumbnail image, used for accessibility.
`unalteredStillImageAsset`	No	Reference to the original, unaltered still image asset.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag this as destructive, non-idempotent and open-world, so the bar is lower; the description adds genuinely non-obvious behavior: only supplied fields change and nulling a field reverts it to the default. It also discloses auth/delegation requirements and the confirm requirement, plus side-effect warnings about sharing/notifying/charges, though that last line is generic boilerplate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and update semantics are front-loaded in the first sentence, followed by the permission block. The triple-backtick permission snippet and delegation paragraph are somewhat verbose, but every section is scannable and nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation with no output schema but annotations covering the safety profile, the description covers purpose, partial-update mechanics, auth requirements, confirm gating and side effects. Return-value behavior is not described, but no output schema exists to lean on, so a small gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 real value by defining how a null value is interpreted (delete/revert to default) for supplied fields - a semantic the schema does not convey. It does not otherwise elaborate on individual parameters like stillUrl or fitStrategy, which is acceptable given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Applies a partial update to a video's thumbnail customizations'), which clearly distinguishes it from the read sibling get_thumbnail_customizations and the broader update_customizations. It does not explicitly name alternatives, but the resource is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete preconditions (required permissions, confirm=true) and explains partial-update semantics, but never states when to reach for this tool versus update_customizations or update_appearance_customizations. Usage context is implied by the name rather than reasoned in the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_webinarUpdate WebinarA

Destructive

Updates an existing webinar.

Requires api token with one of the following permissions

Read, update & delete anything

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The hashed ID of the webinar
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`webinar`	No
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it destructive, openWorld, and non-idempotent. The description adds meaningful context beyond those: required token permissions, delegated permissions, confirm=true, and potential side effects like sharing access, notifying people, or incurring charges.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, followed by authorization and safety details. The permission block is somewhat verbose but relevant to correct invocation. Overall structure is clear and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive update with nested objects and no output schema, the description covers auth requirements, confirm=true, and side effects well. It leaves payload vs body-flag mechanics to the schema, which is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema documents most parameters. The description only reinforces confirm=true and does not add meaning for id, account, payload, webinar, or payload_file. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Updates an existing webinar.' This distinguishes it from create/delete/list siblings, but it does not name alternative tools or clarify scope beyond 'existing'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides prerequisites (permissions, confirm=true) but no explicit when-to-use, when-not-to-use, or alternative selection guidance. It implies updating an existing webinar, but does not help an agent choose between this and related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upload_mediaUpload or Import MediaA

Destructive

Endpoint to upload media files from a local system or import from a web URL.

Use multipart/form-data with a file parameter to upload from local system
Use application/x-www-form-urlencoded with a url parameter to import from web URL Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`url`	No	The publicly accessible web location of the media file to import.
`name`	No	A display name to use for the media in Wistia.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`contact_id`	No	A Wistia contact id.
`project_id`	No	The hashed id of the project to upload media into.
`description`	No	A description to use for the media in Wistia.
`low_priority`	No	Inform the encoding service that this upload can be considered lower priority than others. This is especially useful for platform customers doing bulk uploads or migrations. Setting this to "false" has no effect.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is largely covered. The description adds valuable context beyond annotations: it states that confirm=true is required for the mutation and warns that the action 'may share access, notify people or incur provider charges.' These side-effect disclosures go beyond what the annotations provide, though it does not cover permission requirements or encoding behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then uses two concise bullets to differentiate the upload and import modes. The final sentence about confirm and side effects is also compact. There is a small amount of redundancy in restating 'upload from local system' and 'import from web URL' after the first clause, but overall the structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 parameters, nested objects, no output schema) and the presence of near-identical sibling tools, the description is only partially complete. It covers content types, confirm requirements, and side effects, but it omits any guidance on how this tool differs from upload_media_file and import_media_from_url, and does not address the relationship between the mutually exclusive `payload`, `payload_file`, and body flags. The schema descriptions help, but the description should do more for a tool this complex.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 meaning by specifying content-type requirements that route the agent to either the `file` parameter (multipart/form-data) or the `url` parameter (application/x-www-form-urlencoded), which are not expressed in the schema itself. It does not, however, clarify the interaction between `payload`, `payload_file`, and body flags.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'upload media files from a local system or import from a web URL.' An agent can tell what the tool does, but the description does not differentiate it from the sibling tools upload_media_file and import_media_from_url, which appear to cover the same two modes. No explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides implied usage: use multipart/form-data for local uploads and application/x-www-form-urlencoded for web imports, and notes confirm=true is required for the mutation. However, it does not say when to use this tool versus the dedicated siblings upload_media_file or import_media_from_url, nor does it offer any when-not guidance. The context is useful but incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upload_media_fileUpload or Import Media from a local fileA

Destructive

Endpoint to upload media files from a local system or import from a web URL.

Use multipart/form-data with a file parameter to upload from local system
Use application/x-www-form-urlencoded with a url parameter to import from web URL Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

ParametersJSON Schema

Name	Required	Description
`file`	No	Absolute regular local file, no symlinks, at most 250 MiB locally. Bytes are sent after explicit confirmation.
`name`	No	A display name to use for the media in Wistia.
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Must be true for the specific user-requested write.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`contact_id`	No	A Wistia contact id.
`project_id`	No	The hashed id of the project to upload media into.
`description`	No	A description to use for the media in Wistia.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=false... rather destructiveHint=true, openWorldHint=true and idempotentHint=false. The description adds genuinely non-obvious context on top: the mandatory confirm=true, and that the action may share access, notify people, or incur provider charges. It stops short of describing limits or failure modes, but the added disclosure is substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then two clean bullets for the two modes, then the confirm requirement and risk note. No filler sentences; every line carries information. Only minor redundancy between the intro sentence and the bullets.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object, no-output-schema mutation tool, the description covers modes, confirmation, and side effects but omits sibling differentiation and size/format constraints (e.g. the 250 MiB limit) that matter for correct invocation. Adequate but with visible gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 every parameter; baseline is 3. The description adds a mode-to-parameter mapping (file for local, url for web), which is helpful, but it references a `url` parameter that does not exist anywhere in the input schema, slightly muddying rather than clarifying semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('upload media files from a local system or import from a web URL') that an agent can act on. However, it does not distinguish itself from the near-identical siblings 'upload_media' and 'import_media_from_url', leaving real ambiguity about when this tool is the right one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Offers useful in-tool guidance on which transport/parameter mode to use (multipart/form-data with `file` vs form-urlencoded with `url`), which is more than nothing. But it gives no guidance on when to choose this tool over the sibling upload/import tools, so the selection decision between siblings 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

169 tool updatesv2.0.0Oct 2, 2026
- First observedapply_brand
- First observedarchive_media
- First observedbulk_copy_media
- First observedbulk_delete_subfolders
- First observedbulk_tag
- First observedcopy_folder
- First observedcopy_media
- First observedcreate_allowed_domain
- First observedcreate_brand
- First observedcreate_bulk_actions
- First observedcreate_bulk_purchase
- First observedcreate_captions
- First observedcreate_channel
- First observedcreate_channel_collaborator
- First observedcreate_channel_episode
- First observedcreate_customizations
- First observedcreate_expiring_access_token
- First observedcreate_folder
- First observedcreate_folder_sharing
- First observedcreate_localization
- First observedcreate_media_from_trims
- First observedcreate_review_bundle
- First observedcreate_subfolder
- First observedcreate_tags
- First observedcreate_webinar
- First observedcreate_webinar_collaborator
- First observedcreate_webinar_registration
- First observeddelete_allowed_domain
- First observeddelete_brand
- First observeddelete_captions
- First observeddelete_channel
- First observeddelete_channel_collaborator
- First observeddelete_channel_episode
- First observeddelete_customizations
- First observeddelete_folder
- First observeddelete_folder_sharing
- First observeddelete_localization
- First observeddelete_media
- First observeddelete_media_extended_audio_description
- First observeddelete_review_bundle
- First observeddelete_share_link
- First observeddelete_subfolder
- First observeddelete_tag
- First observeddelete_webinar
- First observeddelete_webinar_collaborator
- First observeddismiss_desktop_install_prompt
- First observededit_captions_text
- First observedfind_caption_matches
- First observedfind_media_by_embed_location
- First observedget_access_customizations
- First observedget_accessibility_customizations
- First observedget_account
- First observedget_account_analytics
- First observedget_account_analytics_timeseries
- First observedget_account_embed_locations
- First observedget_account_stats
- First observedget_account_stats_by_date
- First observedget_account_top_content
- First observedget_account_usage
- First observedget_allowed_domain
- First observedget_appearance_customizations
- First observedget_brand
- First observedget_brand_kit_colors
- First observedget_brand_preload
- First observedget_captions
- First observedget_channel
- First observedget_channel_episode
- First observedget_chapters_customizations
- First observedget_credit_balance
- First observedget_current_token
- First observedget_customizations
- First observedget_engagement_customizations
- First observedget_event
- First observedget_folder
- First observedget_folder_sharing
- First observedget_job_status
- First observedget_lead_capture_customizations
- First observedget_localization
- First observedget_media
- First observedget_media_analytics
- First observedget_media_analytics_timeseries
- First observedget_media_embed_locations
- First observedget_media_embed_locations_timeseries
- First observedget_media_engagement
- First observedget_media_extended_audio_description
- First observedget_media_form_conversions
- First observedget_media_languages
- First observedget_media_stats
- First observedget_media_stats_by_date
- First observedget_media_stats_stats_media
- First observedget_media_traffic_breakdown
- First observedget_order_status
- First observedget_playback_customizations
- First observedget_project_stats
- First observedget_related_media_customizations
- First observedget_share_link
- First observedget_sharing_customizations
- First observedget_subfolder
- First observedget_thumbnail_customizations
- First observedget_visitor
- First observedget_webinar
- First observedget_webinar_analytics
- First observedget_webinar_audience
- First observedget_webinar_histograms
- First observedget_webinar_registration_timeseries
- First observedget_webinar_traffic_breakdown
- First observedimport_media_from_url
- First observedinvite_contacts
- First observedlist_accounts
- First observedlist_all_captions
- First observedlist_allowed_domains
- First observedlist_brands
- First observedlist_captions
- First observedlist_channel_collaborators
- First observedlist_channel_episodes
- First observedlist_channel_episodes_by_channel
- First observedlist_channels
- First observedlist_deleted_media
- First observedlist_events
- First observedlist_folder_sharings
- First observedlist_folders
- First observedlist_localizations
- First observedlist_media
- First observedlist_media_extended_audio_descriptions
- First observedlist_review_bundles
- First observedlist_speakers
- First observedlist_subfolders
- First observedlist_tags
- First observedlist_visitors
- First observedlist_webinar_collaborators
- First observedlist_webinar_registrations
- First observedlist_webinars
- First observedmove_media
- First observedorder_extended_audio_description
- First observedpublish_channel_episode
- First observedpurchase_captions
- First observedresolve_resource_urls
- First observedresolve_share_link
- First observedrestore_deleted_media
- First observedrestore_media
- First observedsearch
- First observedstart_account_trial
- First observedswap_media
- First observedtranslate_media
- First observedun_publish_channel_episode
- First observedupdate_access_customizations
- First observedupdate_accessibility_customizations
- First observedupdate_appearance_customizations
- First observedupdate_brand
- First observedupdate_brand_preload
- First observedupdate_captions
- First observedupdate_channel
- First observedupdate_channel_episode
- First observedupdate_chapters_customizations
- First observedupdate_customizations
- First observedupdate_engagement_customizations
- First observedupdate_folder
- First observedupdate_folder_sharing
- First observedupdate_lead_capture_customizations
- First observedupdate_media
- First observedupdate_playback_customizations
- First observedupdate_related_media_customizations
- First observedupdate_share_link
- First observedupdate_sharing_customizations
- First observedupdate_subfolder
- First observedupdate_thumbnail_customizations
- First observedupdate_webinar
- First observedupload_media
- First observedupload_media_file

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-10-02 21:55 across 169 tools

Disambiguation2/5

There are clear duplicates and near-duplicates: upload_media and upload_media_file have identical descriptions, get_media_stats and get_media_stats_stats_media appear to do the same thing, and get_media_analytics/get_media_stats/get_media_stats_by_date/get_media_engagement overlap heavily. With 169 tools across media stats, analytics, and customization concerns, an agent faces many ambiguous choices between similarly-purposed endpoints.

Naming Consistency3/5

Most tools follow a snake_case verb_noun pattern (list_media, create_folder, update_channel), but there are deviations like 'bulk_tag' (verb omitted), 'un_publish_channel_episode' (underscore variant), 'get_media_stats_stats_media' (garbled), and inconsistent list_captions vs list_all_captions vs list_all_captions/list_channel_episodes vs list_channel_episodes_by_channel. Readable but not fully predictable.

Tool Count1/5

169 tools is far beyond any reasonable scope for effective tool selection, and the surface is bloated with redundant variants (multiple stats endpoints, duplicated customizations get/update pairs, upload_media vs upload_media_file). The count creates selection burden that defeats the purpose of a coherent toolset.

Completeness4/5

Coverage is extensive: full CRUD across media, folders, subfolders, channels, episodes, webinars, captions, localizations, brands, shares, tags, and collaborators, plus rich analytics. Minor gaps exist (e.g., no media creation via bulk actions, some resources lack full lifecycle), but the domain surface is essentially complete.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

YouTube Transcript & Search MCP Server A
com.transcriptout
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Entertainment & Media Search
141
mcp A
online.editclips
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Multimedia Processing Audio Processing Image & Video Processing
51
agent-media-toolkit B
io.github.krakonjac300-pixel
15 media & data tools for AI agents: search, transcribe, subtitles, voiceover, translate & more.
Multimedia Processing Audio Processing Language Translation
1521
BulkTranscripts YouTube AOAuth
co.bulktranscripts
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Entertainment & Media
101

Related MCP Servers

Appwrite MCP
Cloud Platforms Developer Tools Databases
Song-JunHyeong
A
license
Not graded
quality
Not graded
maintenance
Enables AI agents to fully automate Appwrite backend operations with 143 tools covering databases, users, storage, functions, messaging, and more. Supports advanced features like GeoJSON attributes, file uploads, function deployment, and bulk operations.
Updated 9 months ago (2025-12-24 15:33 UTC)
3 npm
-
mux-mcp
Entertainment & Media Multimedia Processing AI & Machine Learning
NoBanks
A
license
Not graded
quality
D
maintenance
Enables AI agents to interact with Mux video infrastructure, providing tools for fetching video assets, clipping videos into shorts, monitoring live streams, pulling viewer analytics, and generating auto-captions.
Updated 4 months ago (2026-05-29 00:45 UTC)
MIT
YouTube MCP Server
Social Media Entertainment & Media
mrchevyceleb
A
license
Not graded
quality
C
maintenance
Gives AI coding agents full control over a YouTube channel with 22 tools for channel management, videos, playlists, comments, search, analytics, thumbnails, and captions.
Updated 2 months ago (2026-08-14 14:56 UTC)
12 npm
3
MIT
@indica-facil/mcp-chatwoot
Customer Support Communication
indicafacil-ai
A
license
Not graded
quality
B
maintenance
Exposes the full Chatwoot API as 129 tools for AI assistants, enabling account, contact, conversation, message, inbox, team, report, help center, automation, and custom attribute management, plus exclusive Kanban and scheduled message features.
Updated 2 months ago (2026-08-20 01:08 UTC)
9 npm
MIT

Wistia MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up Wistia access

Get a narrowly scoped private token

Permissions and feature eligibility

Modern routes and dated API version

Shared quota

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

upload_media

upload_media_file

list_review_bundles

create_review_bundle

delete_review_bundle

list_deleted_media

restore_deleted_media

list_media

get_media

update_media

delete_media

copy_media

swap_media

get_media_stats

translate_media

import_media_from_url

archive_media

move_media

restore_media

bulk_copy_media

get_customizations

create_customizations

update_customizations

delete_customizations

get_appearance_customizations

update_appearance_customizations

get_playback_customizations

update_playback_customizations

get_thumbnail_customizations

update_thumbnail_customizations

get_accessibility_customizations

update_accessibility_customizations

get_chapters_customizations

update_chapters_customizations

get_engagement_customizations

update_engagement_customizations

get_related_media_customizations

update_related_media_customizations

get_sharing_customizations

update_sharing_customizations

get_lead_capture_customizations

update_lead_capture_customizations

get_access_customizations

update_access_customizations

resolve_share_link

get_share_link

update_share_link

delete_share_link

list_captions

create_captions

list_all_captions

find_caption_matches

purchase_captions

get_captions

update_captions

delete_captions

edit_captions_text

list_localizations

create_localization

get_localization

delete_localization