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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds real operational context beyond them: account is null under an API key, limits/plan/generationLimits/features are omitted when lookup fails, and an expired sign-in raises an error. It also explains organizationChoice provenance and the capabilities field, and closes by confirming it grants no permissions and mutates nothing.

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

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

The paragraph is front-loaded with purpose, then usage routing, then failure modes, which is the right order for an agent. It is dense and long for a zero-parameter read, and the closing restatement of the no-side-effects guarantee partly duplicates the readOnly/destructive annotations.

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

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

For a parameterless read with an output schema, the description covers everything an agent needs: when to call it, what it returns, which fields may be absent, and how failures surface. Nothing material is left unstated.

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

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

With zero input parameters there is nothing for the description to disambiguate, so the baseline applies. It instead spends its detail on response-field semantics (organizationChoice, capabilities, omitted-on-failure fields), which is useful but belongs to the output side rather than parameter meaning.

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

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

The description opens with a concrete verb and resource: "Read who is signed in and which sync. organization this session runs in," then enumerates the payload (plan, generation limits, feature flags, team seat and voice-clone limits). It explicitly separates itself from account_get-usage and organizations_list/organizations_select, so an agent can distinguish it from siblings without opening any schema.

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

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

It states the two motivating cases ("name the organization before paid work," "check limits before planning a job") and routes the agent elsewhere for credits/balance/spend and for listing or switching organizations. Both the when-to-use and the when-not-to-use alternatives are named explicitly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them by explaining the polymorphic response: credits when credit-billed, freeMonthlyLimits when free-tier, usage only when both are null and only when totals are not reported as incomplete. It also discloses the authorization rule for canManageBilling (billing must allow it and caller must be owner or admin), which is behavior an agent cannot get from the schema. Nothing here contradicts the readOnlyHint.

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

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

Front-loaded with the primary purpose, then the response-shape rules, then a compact 'not for' list. Dense but every clause carries information an agent needs, since the output schema alone does not tell you which branch is populated. It is long for a zero-parameter read, and the conditional-field sentence is packed tightly enough that it requires careful reading.

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

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

An output schema exists, so return values need not be enumerated, yet the description supplies the missing interpretive layer: which of credits/freeMonthlyLimits/usage is populated under which billing mode and when usage stays null. For a zero-param read with rich conditional output, this is exactly the context needed to interpret results correctly.

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

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

The tool takes zero parameters (additionalProperties: false, empty properties), so there is no parameter meaning to add and the baseline of 4 applies. The description compensates by describing how the response shape varies, which is the only input-adjacent ambiguity (which billing mode the org is in).

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

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

States a specific verb and resource ('Read what the connected sync. organization has left to spend in the current billing period') and immediately distinguishes itself from three named siblings with different scope. An agent can tell this apart from account_get-context or generations_get-costs without opening a schema.

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

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

Contains an explicit exclusion block naming the alternative for each adjacent need: past generation cost → generations_get-costs, new-work quote → generations_estimate-cost, plan limits and org → account_get-context. It also closes off side-effect expectations (buys no credits, changes no plan, starts no generation), leaving nothing to infer.

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

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

Annotations already establish a safe read operation, but the description adds real behavioral context: deleted assets are excluded from the count, filters combine conjunctively, and passing a limit outside 1-100 causes a validation failure. That last point is a genuine trap the annotations don't reveal. It doesn't discuss permission scoping beyond 'you can access', which keeps it just under a 5.

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

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

Three sentences, front-loaded with purpose, then the alternative, then the return type and the parameter trap. Nothing is wasted and the ordering mirrors what an agent needs to decide before calling.

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

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

There is no output schema, and the description compensates by saying it returns a bare number rather than records. All seven parameters are documented in the schema, no parameters are required, and the description covers the non-obvious validated-but-ignored behavior, so an agent can call this correctly without further inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the combination rule (multiple filters AND together) and the no-effect/validated distinction for sortBy, limit and cursor, which the schema states per-parameter but never as a coherent rule. That is useful meaning beyond the schema's field-by-field text.

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

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

Opens with a specific verb and resource ('Count the assets you can access in the current organization') and scopes it to the same filter set as assets_list. It states the return type ('a bare number, not asset records'), which removes any ambiguity about whether this is a listing tool.

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

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

Explicitly routes between the two siblings: 'Use it when you only need how many; use assets_list to see, pick or page through assets.' It also gives a when-not rule for pagination/sort parameters, warning that they are validated even though they have no effect.

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

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

Adds substantial behavior beyond the annotations: non-idempotency is spelled out operationally ('every call saves another one, so do not repeat a call that succeeded'), plus the 422 size-limit condition, the 409 import_in_progress retry contract with retryAfterMs fallback, and a stop-don't-retry list of terminal import errors. The warning that 'The importJobId in the 409 is not an asset id' preempts a concrete agent mistake, and nothing contradicts destructiveHint=false/idempotentHint=false.

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

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

Front-loaded with the two-sentence purpose and the sibling exclusions, then cleanly sectioned into Direct URL / Social link / Projects blocks that map onto real decision branches. It is long, and a few clauses (e.g. the full enum of inputType behavior) could be trimmed, but almost every sentence disambiguates a genuine failure mode.

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

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

For a 15-parameter mutating tool with no output schema, the description supplies the return shape inline (id, type, name, url, visibility, thumbnailUrl, projectId), the follow-on usage ('pass its id as an asset input to generation tools, or as videoAssetId in dubbing_create'), and the async import contract. An agent could invoke and recover from this tool using the description alone.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns above that by adding conditional semantics the schema only implies — that name, visibility and metadata fields are ignored for social links, and that projectId is only valid alongside projectIntent=explicit and never inferred from a matching workflow or open editor. It stops short of 5 because per-parameter detail (size, thumbnailUrl, contentSha256) is left entirely to the schema.

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

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

States a specific verb+resource pair ('Register a media file at a URL', 'import a ... video link into a saved VIDEO asset') and explicitly names what it is not for, citing the sibling tools assets_create-upload-url, assets_list and assets_update. An agent can distinguish this from every nearby asset tool without opening a schema.

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

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

Gives explicit routing: local file → assets_create-upload-url first, existing asset → assets_list, rename → assets_update, social link → this tool with type=VIDEO. It also specifies the sequencing prerequisite ('Import first, then estimate and confirm translation') and the projectId/projectIntent gating rule with a default ('Default new work to a new project').

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

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

The annotations only say the call is non-read-only, non-idempotent, open-world and destructive; the description supplies everything else of consequence: that nothing is registered until assets_create runs, that the returned url (not uploadUrl) is what gets passed on, that expiresIn is a lifetime in seconds after which a new URL must be requested, that no credits are spent, and that each call mints a fresh random-prefix path so it can never collide. It also discloses failure modes (422 from this tool vs 422 from assets_create when nothing was uploaded).

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

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

Front-loaded with the verb and the 'step 1 of 2' framing, and nearly every clause carries non-redundant information (alternatives, return fields, expiry, error codes). It is a single dense block of roughly 150 words, which is justified by the two-step workflow but costs some scannability.

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

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

With no output schema, the description carries the return contract itself ({uploadUrl, url, expiresIn} with each field's meaning) and adds the downstream hand-off and the 422 conditions. For a non-idempotent, non-read-only tool operating in an open-world storage flow, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so fileName, contentType and size are already fully documented, including the 5GB bound, extension normalization and the Content-Type header requirement. The description restates the Content-Type and byte-size constraint in the PUT step but adds no new parameter semantics beyond what the schema already carries, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a presigned upload URL for a local audio, video or image file') and immediately frames it as 'step 1 of 2' of a named workflow, so an agent knows exactly what it produces and that no asset exists yet. It also draws the boundary against assets_create and dialogue_upload-source in the same paragraph, which is stronger differentiation than most siblings in this list provide.

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

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

Explicitly names the when-not cases: not for a public https:// file or social video link (pass those straight to assets_create) and not for re-hosting an already saved video as an Edit Dialogue source (use dialogue_upload-source). It also gives the positive condition — local file, one upload URL per file — so both branches of the decision are covered.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), and the description still adds real behavior: 404 semantics for deleted or cross-organization ids, proxyPath being null unless generated, and a mandated rendering fallback when thumbnailUrl is missing. That is materially more than the annotations provide.

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

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

Front-loaded with purpose, then alternatives, then error behavior, then display policy — a sensible ordering. The preview paragraph is long and somewhat repetitive (restating what must NOT be shown in several ways), costing a point on tightness.

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

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

There is no output schema, and the description compensates by enumerating the returned fields (type, name, media url, durationSeconds, size, format, dimensions, visibility, timestamps, thumbnailUrl, proxyPath). Combined with 404 semantics and the null-handling note, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented in the schema, including the note that generation or project ids return 404. The description restates the same constraint ('by its id') without adding format or sourcing 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.

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

States a specific verb and resource (get one asset) plus the exact scope ('in the current organization by its id') and enumerates the returned fields. It explicitly separates itself from assets_list, assets_get-download-url and assets_get-playback-metadata, so an agent can pick it without opening sibling schemas.

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

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

Gives an explicit precondition ('Use it when you already hold an id') and routes to alternatives for the other intents: assets_list for lookup by name/type/project, assets_get-download-url for signed links, assets_get-playback-metadata for fps/frame count/codec. It also names the failure cases (deleted id, other organization, no visibility) that should not be retried here.

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

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

Goes well beyond the readOnly/openWorld/destructive annotations: signed-link lifetime (up to 7 days), the filename behavior on download, the passthrough case for externally registered assets, and the 404 conditions including a permission-based invisibility case. It also gives operational guidance not to reuse or alter the link, which annotations could never convey.

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

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

Front-loads purpose, then alternatives, then behavior, then return/usage rules – a sensible order. It is somewhat dense at four sentences, but each carries distinct operational information; no filler or restatement of the title.

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

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

With no output schema, the description covers the return value (plain string URL), the external-URL edge case, and the 404 failure modes, plus a caution against link reuse. Nothing needed to call this single-parameter tool correctly is missing.

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

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

Schema coverage is 100% and the id description already distinguishes asset ids from generation ids and points to outputMediaUrl. The description adds only 'by id' with no further syntax, format, or example, so it neither repeats harmfully nor compensates meaningfully.

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

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

States a specific verb and resource with scope: 'Get a download link for one asset's original media file, by id.' The 'original media file' qualifier and 'by id' scoping separate it cleanly from assets_get, which returns details and a media url.

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

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

Explicitly states the selecting condition ('use it when the user wants to download or save the file') and names the two adjacent alternatives with their purposes: assets_get for details/media url, assets_get-playback-metadata for frame timing. An agent can route without opening other schemas.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavior the annotations cannot: the signed-in-user requirement and the exact API-key degradation payload ({supported: false, metadata: null}), plus null/omitted field semantics and an instruction never to guess unmeasured values. The only minor gap is that it does not describe pagination/caching or error behavior, but for a single-object read this is close to complete.

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

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

Front-loaded with the core action and the returned-field list, then use case, then alternatives, then caveats — a logical progression with no filler. The long inline field enumeration is somewhat redundant given an output schema exists, which keeps it below a 5.

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

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

For a one-parameter, read-only tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, the frame-conversion use case, sibling routing, auth/degradation behavior, and null semantics. Nothing material is missing.

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

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

There is a single assetId parameter with 100% schema description coverage (UUID, sourced from assets_list or assets_get), so the schema already carries the semantics. The description only implies single-asset scoping via 'Read one asset's' and adds no format or sourcing detail 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.

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

Starts with a specific verb+resource ('Read one asset's measured playback metadata') and enumerates exactly what comes back (duration, fps, frameCount, dimensions, codec, proxy fields, thumbnailsManifestUrl). It also carves itself apart from siblings assets_get and assets_get-download-url, so an agent can pick it without opening a schema.

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

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

Gives a concrete positive use case ('convert between seconds and frames for frame-accurate edits such as lipsync_create-timeline clips') and explicitly routes the agent elsewhere for name/media url (assets_get) and file download (assets_get-download-url). It also states negative scope: it does not analyze media, read transcripts, or change the asset.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, but the description adds real semantics the annotations cannot: filters are AND-combined, deleted assets are never returned, totalCount spans all pages while nextCursor is absent on the last page. It also documents the item field set in lieu of an output schema. The remaining gap is minor — no note on rate limits or whether access scope varies by role.

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

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

Purpose, exclusions and filter/pagination semantics are front-loaded and tight, but the preview block is disproportionately long and partly redundant: "Never ... substitute another asset, a stock image, a voice portrait, or the asset's url or proxyPath" is restated by the fallback sentence about a placeholder image. That content is operationally useful but could be roughly halved without losing meaning.

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

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

There is no output schema, and the description compensates fully by enumerating the response envelope {items, nextCursor, totalCount} and every item field, plus pagination and sort tie-breaking behavior. For a 7-parameter, zero-required list tool with annotations covering safety, nothing an agent needs to call or render results is missing.

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

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

Schema coverage is 100%, so the schema baseline is 3; the description earns above that by adding cross-parameter semantics absent from the schema — "Filters combine, so an asset must match all of them" — and by restating the id-lookup use case that motivates searchQuery/types/userId/projectId. It does not add format or syntax detail for the UUID parameters, so it stops short of 5.

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

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

States a specific verb and resource ("List the media assets (VIDEO, AUDIO, IMAGE)") plus the scope ("you can access in the current organization") and the user goal ("find an asset id by name, type, creator or project"). It also names the siblings it is not — assets_get, assets_count, generations_list, projects_list-generations — so an agent can discriminate without opening any schema.

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

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

Explicit when-not conditions are given with the correct alternative for each: "Not for an id you already hold (use assets_get), a total alone (use assets_count) or generation results (use generations_list...)". This is the full when/when-not/alternative triad with no inference required.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety bar is partly cleared; the description nonetheless adds substantial context: omitted fields are preserved while sent fields overwrite, metadata rewrites the record and not the media file, downstream duration checks read durationSeconds, and 403/404/422 error meanings. The only gap is that the overwrite semantics read like a PUT-style idempotent operation while the annotation says idempotentHint=false, which is not a contradiction but is left unexplained.

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

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

Purpose is front-loaded in the first clause, followed by the write-semantics rule, then auth, then error codes, then return shape — a sensible order. It is dense and long for a single paragraph, and the return-value inventory (including the proxyPath caveat) is somewhat padded given there is no output schema to contrast against.

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

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

For a destructive mutation with no output schema, the description covers what changes, what is preserved, permission requirements per field group, API-key limitations, distinguishing 403 vs 404 vs 422, and the returned record's contents. An agent has everything needed to invoke it safely without further lookups.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, and the description mostly restates that grouping (name/visibility vs. the media metadata set). It does add one piece of cross-field meaning the schema lacks: that durationSeconds is consumed later by plan-length limits and dubbing intervals, which justifies the caution not to guess. That is a modest addition over an already-complete schema, so the baseline 3 holds.

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

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

States a specific verb and resource plus the exact editable surface: name, visibility, and stored media metadata fields, all keyed by id. It explicitly distinguishes itself from assets_create (adding media), projects_rename (renaming projects), and assets_get (reading proxyPath), so an agent can route without opening sibling schemas.

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

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

Gives explicit when-to-use and when-not-to-use guidance with named alternatives, plus a prerequisite workflow: read with assets_get first if old values may be needed. It also sets a consent rule ('change those only on the user's explicit request') for metadata-only edits on other members' assets, which is a real branching decision an agent needs.

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

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

Goes well beyond the annotations: it declares the operation never generates video, spends credits, or consumes a free generation, and it specifies idempotency semantics (persist the key first, reuse only after an uncertain response, new attempt after failure). The annotations say idempotentHint=true and readOnlyHint=false; the description explains how to realize that idempotency, which the annotation cannot.

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

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

Front-loaded with purpose, then usage, then behavior, then parameter rules, in a logical order that lets an agent stop reading early. It is long and restates a few schema facts (assetId/audioAssetId aliasing, the 3600 cap is left to the schema), so a little overlap keeps it from a 5.

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

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

For a mutating job-creating tool it covers what an agent needs: confirmation of the partial duration before calling, idempotency recovery, the poll target, and the follow-up step of re-quoting with the actual duration. Because an output schema exists, it correctly avoids restating the full return shape, mentioning only the state semantics (null until completed, errorCode, retryAfterMs).

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds rule-level meaning: pass assetId rather than the deprecated audioAssetId, the call fails when neither is present or the two disagree, and projectId requires projectIntent=explicit which is only allowed for an explicit user choice or a newly created project. That paves the semantic cliff the schema alone only states tersely.

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

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

"Save the first durationSeconds of an authorized audio asset (assetId) as a new, reusable audio asset" gives a precise verb, resource, and output. It also scopes itself against siblings by naming lipsync_create and distinguishing the audio-only trim from the cut_off sync mode path.

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

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

States the positive condition (audio longer than lipsync can take and only its beginning is needed) and the exclusion with a concrete alternative (partial video lipsync → leave video and draft unchanged, set options.sync_mode to cut_off on lipsync_create). It also routes polling to audio-trims_get and explicitly says jobs_get and jobs_wait do not read trims, closing the most likely wrong-path.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses the retryAfterMs pacing contract, the null-before-completion field semantics, the errorCode on failure, the {error: {message, status, code}} shape for API errors, and that it never starts video generation or spends credits.

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

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

Front-loaded with the purpose and the sibling exclusion, then a procedural paragraph that maps one-to-one onto agent decisions. Some return-field enumeration duplicates the output schema and could be trimmed, but every sentence carries an actionable instruction rather than filler.

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

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

For a single-parameter async polling tool with an output schema, the description covers origin of the id, polling cadence, terminal states, failure handling, error envelope, and side-effect boundaries. Nothing an agent needs in order to call it correctly and act on the result is missing.

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

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

Schema coverage is 100%, so the id semantics are already documented; the description reinforces rather than adds new syntax. It does add meaningful usage semantics for the parameter — reuse the same id across polls until completed or failed — which is slightly more than the schema's own wording.

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

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

States a specific verb and resource ("Read one audio trim") plus the id provenance, and explicitly rules out sibling tools: "jobs_get and jobs_wait do not read audio trims." An agent can distinguish it from audio-trims_create and the generic jobs pollers without opening a schema.

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

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

Gives explicit when-to-use behavior: poll again after retryAfterMs while queued/processing, never create another trim, and on failure escalate to an explicit new audio-trims_create attempt. It also names the alternatives (jobs_get, jobs_wait) and states what to do with each outcome, leaving nothing to inference.

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

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

Annotations already declare the mutating, non-idempotent, open-world profile, and the description adds material context beyond them: queueing that bypasses the per-generation concurrency limit, results taking up to a day, plan-gated availability with a 402 carrying requiredPlan and billingUrl, and per-item billing as a paid action. The slack below Scale (each row still consumes a concurrent slot) and the 'up to a day' latency are exactly the operational traits an agent needs 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.

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

Purpose and scale limits are front-loaded, then alternatives, then safety steps, then return/next-step. Every sentence carries information, though the paragraph is dense and could be split into short scannable clauses; nothing is filler, but the single block makes the dryRun and projectIntent rules easy to miss.

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

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

Despite the tool's complexity — nested array items, billing, plan gating, non-idempotency, and a downstream polling step — the description covers prerequisites, cost confirmation, recovery after an ambiguous response, and the handoff to batches_get with wait: true. An output schema exists, yet the one-line note about returned batch id and per-item requestId still usefully names the handle needed for the next call.

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

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

Schema coverage is 100%, so the schema already documents items, dryRun, webhookUrl, projectIntent, and organizationId, and a baseline of 3 would apply to no added meaning. The description does add cross-parameter workflow meaning: the payload.projectId / projectIntent=explicit coupling, the rule that projectId must come from explicit user selection and never inference, and the dryRun-validates-without-spending semantics that ties to the cost-confirmation guidance.

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

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

Opens with a specific verb and resource: 'Submit many independent lipsync generations at once as one Sync batch', and immediately names the sibling patterns it supersedes (jobs_create-many, lipsync_create, dubbing_create). An agent can distinguish this from every other generation tool in the sibling list without opening any schema.

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

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

Explicit when-to-use with concrete scenarios (localizing one campaign video into many languages, syncing many videos to their own audio), volume and plan thresholds (20-500, Scale and above), and named alternatives for the 2+ immediate-jobs case and for chained/sequential work. It also prescribes a dryRun-first step, a cost-estimate-and-confirm step, and a recovery path via batches_list if the response is uncertain.

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

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

Beyond the readOnly/idempotent annotations it discloses concrete timing behavior: wait polls ~50 seconds, reading a finished result file can add up to 30 seconds, and batches may run for hours. It also describes degradation behavior (resultsError with reason, batch fields still current) and advises downloading outputUrl or using generations_list as fallbacks.

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

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

Three short paragraphs, front-loaded with purpose and return shape, then polling behavior, then the results filter edge cases. Nearly every sentence carries information, though the wait/results paragraphs partly restate schema text, costing a bit of density.

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

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

For a polling read tool with an output schema, this covers everything an agent needs: conditional return shape, timeout semantics, retry guidance, and fallback paths when the result file cannot be read. Nothing material about correct invocation is left to inference.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by tying results: failed to FAILED/REJECTED rows, explaining that none skips reading the result file (a performance hint the schema omits), and pairing the 30-second read cost with finished-batch reads. Much of the wait/results wording overlaps the schema descriptions, keeping it below a 5.

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

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

States a specific verb and resource ("Read one sync. batch by id") and enumerates what is returned: status, metrics, outputUrl, and per-item result rows once the batch is COMPLETED or FAILED. It explicitly distinguishes itself from batches_list and generations_get, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use ("follow a batch you created"), when-to-use-an-alternative (batches_list to find an id or check running batches, generations_get for one item's full details via generationId), and a negative instruction ("never create the batch again"). It also prescribes the polling loop ("call again while it runs") rather than sleeping.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds non-obvious traits: strict organization scoping with no cross-org reads, absence of paging/limit parameters, pass-through of the API's list, and single-value status matching. The only gap is that it does not hint at ordering or result-size expectations, which matters given the explicit no-pagination stance.

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

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

Purpose and the sibling routing come first, followed by scope and parameter semantics, so the definition is front-loaded and every sentence carries information. It is dense and slightly long for a three-parameter list call, with the second paragraph doing several jobs at once.

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

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

For a filtered list tool with an output schema, everything an agent needs is present: org scope and the remedy (organizations_select), no-pagination behavior, status enum grouping, and time-window semantics. Return-field detail is deferred appropriately to the output schema while still summarized in the first line.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that status matches one value per call and that omitting it shows running and finished batches together, and that createdAfter/createdBefore together bound a time window. That is useful operational framing rather than restatement.

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

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

Opens with a specific verb and resource ("List the batches in this session's organization") and immediately states the returned fields (id, status, metrics, outputUrl). It explicitly separates itself from batches_get (per-item results) and generations_list (single generations), so an agent can choose without opening a schema.

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

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

Gives three concrete when-to-use triggers: finding a batch id, verifying existence after an uncertain batches_create response before retrying, and diagnosing concurrency_limit_reached. It also names the alternatives (batches_get, generations_list, organizations_select) with the condition that selects each.

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

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

Annotations already declare readOnly/openWorld=false, so the safety profile is covered; the description adds genuinely new behavior: the answer comes from the loaded API spec, no HTTP request is sent, it costs nothing, and it is identical for every organization regardless of plan, credits or project access. It also discloses the failure mode behind keyedPreview ('sending one when it is false fails'), which is exactly the kind of consequence 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.

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

Strongly front-loaded: return shape first, then the meaning of each boolean, then the operational caveats, then the exclusions. It is denser and longer than most definitions, but nearly every clause carries distinct information; a minor trim would still leave all three boolean semantics, the free/no-request note and the alternatives.

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

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

With no output schema, the description fully compensates by spelling out all three returned booleans and their conditions, plus the absence of side effects and the recommended call timing. Nothing an agent needs in order to decide whether and when to invoke it is missing.

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

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

There are zero parameters, so the schema baseline applies and no parameter meaning needs explaining. The description instead documents the response fields, which is the relevant semantics for a no-arg call.

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

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

The description opens with a specific verb and resource: 'Report which Edit Dialogue features this connection supports', and immediately enumerates the exact return shape { available, keyedPreview, sourceUpload }. It also names what it is not (lipsync models, dubbing/voice options), so an agent can distinguish it from the neighbouring *_get-options siblings without opening a schema.

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

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

It gives an explicit trigger ('Call it once before the first dialogue-previews_create to decide whether to persist an idempotencyKey') plus explicit exclusions that route to named alternatives (models_list, dubbing_get-options, speech-previews_get-options). Both when-to-use and when-not-to-use are present, which is the top of the scale.

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

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

Goes well past the annotations: it discloses voice cloning and synthesis charges, the requirement to confirm edits and voice-use permission, the validation that fails if the source video doesn't match, and that it 'adds a preview job and never overwrites the source.' It also spells out the non-idempotent recovery protocol (persist idempotencyKey when dialogue_get-options reports keyedPreview, retry only with identical input and the same key, never auto-retry an ambiguous creation), which the idempotentHint=false annotation alone would 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.

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

Purpose and exclusions are front-loaded and every sentence carries distinct operational content (preconditions, cost, polling, idempotency, project rules). It is dense, however — a few long multi-clause sentences (the keyedPreview/retry sentence especially) pack several independent rules together and would read faster if split.

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

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

For a costly, non-idempotent mutation with 9 parameters and no output schema, the description covers preconditions, side effects, failure modes, required follow-up polling, and the retry contract. An agent has everything needed to call it safely without consulting other documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by tying idempotencyKey to a runtime signal (keyedPreview, 'sending one otherwise fails'), stating projectIntent=explicit is required with projectId, and defaulting new work to a new project. It does not restate the edits/wordId semantics, which the schema already covers in depth.

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

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

States a specific verb and resource ('Start an Edit Dialogue audio preview: re-synthesize user-approved word changes and removals... in the original speaker voice') and names what it returns (preview job id, status). It explicitly differentiates from siblings by naming dubbing_create, lipsync_create, speech-previews_create, and dialogue-videos_create with the condition that selects each.

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

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

Gives explicit when-not routing ('Not for translation... another voice or new full script... or the final video') and an ordered follow-up path: poll dialogue-previews_get, disclose COMPLETED_PARTIAL shortfall, then quote with dialogue-videos_estimate after user approval. Prerequisites (COMPLETED transcription or COMPLETED/COMPLETED_PARTIAL prior preview) and the projectIntent=explicit rule are stated as gating conditions.

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

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

Although the annotations already declare this as a safe read-only operation, the description adds substantial behavioral context: status lifecycle values, partial-completion semantics, failure-code retry implications, and how to interpret background_bed_missing and EDIT_TOO_LONG. This is unusually rich and directly useful for handling the tool's output correctly.

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

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

The description is long but dense and front-loaded: it states the core read action first, then status behavior, polling guidance, partial/failed handling, and downstream routing. The density is justified by the tool's stateful preview workflow, though a few clauses could be tightened.

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

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

There is no output schema, so the description carries the full burden of explaining return values and states, which it does thoroughly: status values, previewAudioUrl, resultTranscript, resultSlots, sourceTranscript, edits, voiceId, partialDetail, and error. It also explains what to do in each terminal state, making the definition complete for this tool.

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

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

Schema coverage is already 100%, and all three parameters are documented in the schema itself, including the rejection behavior for a mismatched videoAssetId. The description reinforces that the preview must come from the given source video and that the id comes from dialogue-previews_create, but it does not add much parameter meaning beyond the schema.

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

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

The description starts with a specific verb and resource: read one Edit Dialogue audio preview by id. It also explicitly distinguishes this from rendered-video retrieval by saying it is not for generations_get, so an agent can select it confidently.

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

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

It gives explicit polling guidance while the preview runs and forbids creating another preview just to check progress. It also names the alternative workflows: pass the approved id to dialogue-videos_estimate and dialogue-videos_create, revise via dialogue-previews_create with previousPreviewId, and use generations_get for rendered videos.

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

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

Rich behavioral disclosure well beyond the annotations: it explains that destructiveHint is conservative ("overwrites nothing"), describes reuse/dedup semantics (returns an existing COMPLETED job or one running within the last hour), the 600-second SOURCE_TOO_LONG ceiling checked post-extraction, and HTTP 429/402 failure modes with rate-limit numbers. The copy-fallback path and its videoAssetId propagation are also spelled out, so an agent knows exactly what side effects can occur.

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

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

Front-loaded and organized under clear labels (Returns, Effects, Limits, Copy fallback, Project), with no filler sentences. The opening sentence is packed with stacked clauses and the paragraph is very dense, but for a tool with this many fail modes and fallbacks the length is largely earned.

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

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

No output schema exists, yet the description documents the return shape (id, status, transcript, speakerCount once COMPLETED) and the async polling path. For a complex mutation with dedup, a copy fallback, a hard duration cap and project-permission rules, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions already carry the projectIntent=explicit rule and the videoAssetId copy-replacement rule, so the description largely restates structured data. It adds marginal value by reinforcing the "default new work to a new project" policy and never treating a matching name/workflow/editor as permission, but no new format or syntax detail.

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

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

Opens with a specific verb and resource ("Start the unbilled timed-word transcription") and scopes it precisely to Edit Dialogue: correcting/removing spoken words in a saved single-speaker video while preserving the voice. It explicitly names the siblings it is not (transcriptions_create, dubbing_create, lipsync_create), so an agent can differentiate without opening any schema.

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

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

Gives explicit when-not conditions ("Not for general transcription or speaker analysis... translation... a new full script or different voice") with the correct alternative tool for each. It also supplies the follow-on routing: poll dialogue-transcriptions_get with the id, then send edits to dialogue-previews_create when speakerCount is 1.

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

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

Annotations already establish a safe read operation (readOnlyHint=true, destructiveHint=false), and the description adds substantial context beyond them: access confirmation for projectId, source-video matching rejection, the PENDING/PROCESSING/COMPLETED/FAILED lifecycle, null-before-completion fields, non-retryable error codes, and the absence of a wait option. The one gap is that it does not discuss rate limits or polling cadence, but for a read-only status tool the disclosure is rich.

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

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

The description is dense and front-loaded, starting with the read operation and placing workflow and polling guidance after the return-value details. It is long for a single paragraph and repeats some schema-level parameter semantics, but nearly every sentence carries operational value for a tool with a state machine and strict source validation.

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

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

There is no output schema, so the description carries the return contract and does so thoroughly: status values, transcript.segments with word timing in milliseconds from source start, speakerCount nullability, and error codes. Combined with the polling guidance and preview gating rule, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100% and the schema already explains that id comes from dialogue-transcriptions_create, that projectId is only for access confirmation, and that videoAssetId must be a VIDEO asset compared against the job's source. The description largely restates those semantics, adding only the workflow link that word ids feed dialogue-previews_create edits; with the schema doing most of the work, baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Read one Edit Dialogue transcription job by id.' It also positions the tool in the workflow between dialogue-transcriptions_create and dialogue-previews_create, and explicitly excludes jobs from the general transcriptions_create, so an agent can distinguish it from siblings 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.

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

Gives explicit when-to-use guidance and alternatives: poll again while running, or use jobs_wait with kind transcription; 'never start another transcription to check progress'; and 'do not create a preview when speakerCount is above 1.' The exclusion for general transcriptions_create is named with its alternative, transcriptions_get.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description explains exactly why — each call writes another new asset with no deduplication, the original is untouched, and no generation credits are spent. It adds operational facts not in the annotations: the server downloads and re-uploads the whole video, with 512 MiB / 15 minute defaults, and fails if the source is unavailable or too large.

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

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

Content is front-loaded (what it does, then the usually-unnecessary warning) and every clause carries operational weight. It loses a point because the closing projectIntent sentence largely restates the schema's own const/description, which is already fully documented.

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

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

For a destructive, non-idempotent, open-world copy operation it covers prerequisites, failure modes, size/time limits, idempotency, cost, and the return shape, and even with an output schema present it names the fields returned and their downstream use. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning: the returned asset.id must be passed as videoAssetId to every later dialogue tool, and projectIntent=explicit is required only for a just-created or explicitly chosen project, never inferred. That is semantic guidance the schema documents only locally.

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

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

States a precise verb and transformation: copy a saved VIDEO asset into sync. storage as a new VIDEO asset in a given project, with the reason (Edit Dialogue source URL rejected as not hosted in sync. storage). It also distinguishes itself from dialogue-transcriptions_create, assets_create-upload-url and assets_create, so an agent can select it without opening siblings.

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

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

Explicit when-not guidance: "Usually unnecessary: dialogue-transcriptions_create makes this copy itself... call this only when you need the hosted copy before or without transcribing." It also rules out local files and social links and points to the correct alternatives for each.

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

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

Strong beyond-annotation disclosure: it flags a paid action that consumes sync credits and starts an async generation job, and explicitly reconciles the destructiveHint=true by stating it only adds a generation and never overwrites the source video. It also explains the asynchronous return (generation id and status, not a video) with concrete polling paths (generations_get, jobs_wait, then outputMediaUrl when COMPLETED) and idempotency-key recovery behavior. Slightly marked down only because the polling guidance is worded loosely ("when available,,") and doesn't address retry/rate-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.

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

Front-loaded with purpose, then exclusions, then cost/behavior, then prerequisites and retry rules – a sensible ordering for a paid async action. It is dense with zero filler sentences, but it runs long, and minor editing artifacts ("kind generation when available,,") slightly hurt readability.

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

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

For a 9-parameter, nested-object, paid, asynchronous mutation, the description covers everything an agent needs: prerequisites, cost and approval gates, what the call returns versus what it does not, how to retrieve the finished asset, and how to safely retry. Return-value detail is legitimately light because an output schema exists, and no dangerous ambiguity remains.

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

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

Schema description coverage is 100%, so the parameters are already documented in detail (model matching the estimate, dialogueEditId must be a preview id not a transcription/generation id, idempotencyKey reuse, continuation.workflow must be edit_dialogue). The description restates rather than extends that: the only added nuance is the estimate-then-approve sequencing and reusing the key with identical inputs, both of which are largely workflow rather than parameter semantics. Baseline 3 is appropriate.

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

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

"Render the final Edit Dialogue video: lip-sync the saved single-speaker source video to a finished, user-approved preview's audio, creating a new generation" gives a precise verb-plus-resource plus the input/output identity of the operation. It then names the exact siblings it is not (dubbing_create, lipsync_create, dialogue-previews_create), so an agent can separate it from them without opening a schema.

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

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

Explicit when-not-to-use list routes the agent to the right alternative for translation, whole-script replacement, alternate voices, and preview generation. It also prescribes the required pre-call sequence (dialogue-videos_estimate with identical source/preview/model, then explicit user approval of preview, config and cost), plus continuation and projectId/projectIntent rules. Nothing about 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.

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

Beyond the readOnly/destructive annotations, it discloses that no job is created, no credits are reserved, no charge is incurred, and admission is not guaranteed. It also reports access checks, the COMPLETED/COMPLETED_PARTIAL precondition, and the specific 422 cost_estimate_unavailable failure mode — behavior an agent could not infer from annotations alone.

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

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

Front-loaded with purpose and value, then usage, then exclusions, then failure modes — a sensible order. It is dense but nearly every clause carries information; the enumerations of return fields and parameters make the first two sentences longer than ideal, though not wasteful.

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

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

With no output schema, the description carries the burden of describing returns and does so (estimatedGenerationCost, estimatedCredits with unit and null semantics, estimatedFrameCount, durationCheck). Preconditions, side-effect guarantees, and error behavior are all covered for a six-parameter tool with a nested options object.

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

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

Schema coverage is 100%, so the schema already documents each field and the tool sits at the baseline 3. The description adds real meaning by requiring the parameters to match the subsequent dialogue-videos_create call and by noting the quote is valid only for the supplied model and options.

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

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

The description opens with a specific verb and resource ('Quote the final lipsynced Edit Dialogue video for a finished preview') and immediately clarifies the operation is free and non-committal. It also names the sibling tools it is not (generations_estimate-cost, generations_get-costs), so an agent can distinguish 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.

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

It states exactly when to call it ('before dialogue-videos_create with the same projectId, videoAssetId, dialogueEditId, model, options and organizationId') and adds the operative instruction to show the user the quote. It gives explicit exclusions for other workflows and past-generation costs, and notes the quote only holds for that model and options.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false; the description adds real context beyond them: this is a paid action requiring user confirmation of language, configuration and estimated cost, that external provider charges may be excluded from a lip-sync-only quote, and the full async lifecycle (poll generations_get or jobs_wait until COMPLETED, then read outputMediaUrl). It does not explain the destructive implication flagged by annotations, so it stops short of full disclosure.

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

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

Content is front-loaded: purpose and sibling exclusions come first, then prerequisites, cost gate, project rules, and return/polling. It is dense and every section is useful, but retry/idempotency guidance is stated both in the body and repeated in the idempotencyKey, projectCreationKey and continuation parameter descriptions, adding some redundancy for a 12-parameter tool.

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

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

Given 12 parameters, nested options, enums and an output schema, the description covers the workflow end to end: sourcing the asset, estimating cost, project creation, and polling to outputMediaUrl. Return-value explanation is largely redundant with the output schema, and the destructive/idempotency implications of the annotations are left unaddressed, so it is strong but not exhaustive.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding cross-tool ordering meaning (model must match the generations_estimate-cost quote; targetLang comes from dubbing_get-options) and by clarifying that projectId requires projectIntent=explicit and must not be inferred from a name or an open editor. Most remaining parameter detail is already in the schema, limiting it to a 4.

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

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

The description names a specific compound verb and resource — translate a saved video's speech, lip-sync it, render one finished paid generation — and explicitly delimits scope against siblings: 'Not for subtitles only or translating a text document', 'to lip-sync audio you already have, use lipsync_create', and names translation-previews_create for audio-only review. An agent can route correctly without opening any schema.

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

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

It gives explicit when-to-use and when-not-to-use rules plus named alternatives with the selecting condition (previewAvailable from dubbing_get-options), prerequisites for social URLs (import via assets_create, wait for the saved asset), a mandatory confirmation step before the paid call, and clear projectId vs projectCreationKey vs omit semantics including what is NOT valid grounds for passing projectId.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description restates the no-side-effect/no-cost profile while adding real context beyond the annotations: the previews tools only exist when previewAvailable is true, and codes follow es / pt-BR / zh-TW shapes. It doesn't describe the response shape in detail, but that is largely covered by the output schema.

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

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

Front-loaded with what is returned, then usage, then the anti-use case, then a clarifying format note. Dense but nearly every sentence carries information; the 'Takes no input ... creates nothing and costs nothing' clause is somewhat redundant with the readOnly annotation.

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

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

For a zero-parameter lookup with an output schema and full annotations, nothing an agent needs is missing: it knows what is returned, what the codes look like, which siblings to feed them into, and which tools to avoid for pricing.

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

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

There are zero input parameters, so the baseline is 4; the description correctly says it takes no input. It adds useful semantics about the returned values (sourceLanguages includes 'auto' for detection) and the code format, though the output schema already carries much of that.

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

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

States a specific verb and resource: it lists the language codes accepted for translation (targetLanguages, sourceLanguages with 'auto') plus the previewAvailable flag. That is distinguishable from every sibling, including the create/estimate tools it names.

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

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

Gives explicit when-to-use ('pick a valid targetLang or sourceLang for dubbing_create or translation-previews_create'), a concrete edge case (translation-previews_create takes free text, so check codes here first), and an explicit when-not ('Not for prices: use generations_estimate-cost or translation-previews_estimate').

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

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

Beyond the annotations it discloses the return shape ("returns only a receipt id"), the review cadence ("the team reviews reports daily"), server-side enrichment ("the server adds the client name and MCP version"), and a strong non-interference guarantee ("Does not change, retry or cancel any job") that pairs with destructiveHint=false. The "once per problem" instruction usefully compensates for idempotentHint=false by discouraging duplicate submissions, though it does not state whether a duplicate report errors or is quietly accepted.

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

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

It is front-loaded with purpose, then timing, then exclusions, then parameter advice, then the non-interference guarantee — a sensible priority order with no filler sentences. It is a single dense paragraph, so the behavioral guarantee at the end is easier to miss than it would be as a separate sentence or bullet.

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

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

For a seven-parameter reporting tool with an output schema and full annotation coverage, nothing an agent needs is missing: what qualifies, when to send, when not to, which optional fields to populate, what comes back, and what side effects will not occur. Return values are correctly left to the output schema rather than duplicated.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further by adding cross-parameter guidance the schema cannot express: "Put the exact error text in message and fill tool, errorCode, and generationId or jobId whenever they apply." That resolves which optional identifier to use for which situation, a decision the per-field descriptions leave implicit.

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

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

The opening sentence names a specific verb ("Report friction") and resource ("these sync. tools to the sync. team") and then enumerates concrete triggering categories (confusing error, wrong result, missing capability, extra steps, misleading description). No sibling tool is a feedback channel, so the definition is unmistakably distinct from the surrounding generations/transcriptions/assets tools.

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

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

It states explicit timing ("once per problem after you have finished or stopped the task"), an explicit authorization rule ("without asking the user for approval"), and explicit exclusions ("Not for user support requests, success notes or questions that need an answer"). The alternative behaviors are named with the reason they are excluded (it returns only a receipt id), which is stronger than most definitions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes well beyond them: it asserts no job is created and no credits are reserved, warns that durationCheck does not guarantee admission ('a price does not guarantee admission'), and discloses that speech synthesis and external provider charges are excluded from the quote. That is exactly the kind of side-effect and trust-boundary context an agent needs before quoting a price to a user.

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

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

Front-loaded correctly: the price-before-create purpose and the no-side-effects guarantee come first, then routing, then return shape. Every sentence carries information, but the long run-on paragraph and the trailing presentation directives ('label script quotes approximate, show the breakdown') make it denser than it needs to be for a single paragraph.

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

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

There is no output schema and eleven parameters, so the description compensates by enumerating the return fields (estimatedGenerationCost, estimatedCredits with the credit-billed null case, estimatedFrameCount, durationCheck, breakdown, durationEstimate). Combined with the mutual-exclusivity rules for the length parameters, an agent has enough to call this correctly and present results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning the schema documents only per-field: 'Give one length: duration, or for replacement speech script or measured audioDuration, which replace duration' and 'never quote the full source video length for a shorter replacement script'. The workflow/lipsync-only default is also stated at description level. It stops short of restating the syncMode/visualType interactions, which remain schema-only.

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

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

States a specific verb and resource ('Quote the price of a lipsync, image-to-video or translate-and-dub generation') and immediately scopes it with 'before creating it; creates no job and reserves no credits'. It also explicitly excludes itself from three named siblings, so an agent can distinguish it from generations_get-costs, dialogue-videos_estimate and translation-previews_estimate without opening a schema.

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

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

Gives explicit when-to-use routing ('Use it before lipsync_create or dubbing_create, and price one representative item before batches_create') and explicit when-not-to-use by naming the three alternative tools for past costs, Edit Dialogue video and translated-audio previews. The workflow caveat ('Without workflow=translate-and-dub the quote covers lip sync only') further tells the agent which mode is the default before it calls.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false), but the description adds substantial behavior the annotations cannot: the waiting contract of roughly 50 seconds, the instruction to re-call with the same id rather than resubmit, and the billing consequence that a new create starts a separate billed generation. It also warns that outputMediaUrl is signed and must be copied verbatim. The only minor gap is that it does not state whether reads are rate limited under repeated polling.

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

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

Front-loaded with the purpose and the returned fields, then segmented into labeled blocks (usage, Not for, Waiting, Result) that each carry distinct information. It is long, but the length is justified by a polling tool with resubmission and signed-URL pitfalls; the deprecated outputUrl alias note is the one line that could be trimmed.

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

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

Although an output schema exists and return values need not be re-explained, the description adds the status transitions, the verbatim-copy requirement for the signed URL, and the failure-path instruction to report error and errorCode. For a read/polling tool with four parameters, nothing an agent needs in order to call it or handle its result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above baseline by specifying the interaction rule between two parameters: pass wait: true and leave timeout out, and call again rather than sleeping. That combination rule is not spelled out as such in the schema, and the warning about never resubmitting adds meaning to the id parameter.

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

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

States a specific verb and resource ('Read one sync. generation by id') and immediately enumerates what is returned: status lifecycle values, outputMediaUrl, error and errorCode. It explicitly differentiates itself from jobs_get/jobs_wait, which read the same generation in a generic job shape, so an agent can choose correctly without inspecting schemas.

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

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

Gives the positive trigger (follow a generation by the id a create call returned, naming lipsync_create, dubbing_create, lipsync_create-timeline, dialogue-videos_create), a 'Not for' exclusion block routing to generations_list, projects_list-generations, generations_get-costs and generations_get-continuation, and an explicit alternative (jobs_get/jobs_wait). This is the when/when-not/alternatives triad in full.

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

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

Beyond the readOnly and idempotent annotations, the description discloses that it returns the generation regardless of status after checking project and asset access. It also states concrete failure conditions: the generation must belong to the supplied project, and every referenced asset must still be accessible.

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

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

The description is front-loaded with the core purpose and then proceeds logically through usage, parameter sourcing, downstream continuation, and return behavior. It is dense and has a long parenthetical field list, but nearly every clause adds useful operational detail.

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

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

For a read-only continuation utility with an output schema, the description covers the key missing context: access checks, failure conditions, status-independent returns, and which downstream create tools can consume the continuation. Nothing essential for correct invocation appears to be omitted.

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

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

Schema coverage is already 100%, so the schema defines both parameters. The description adds important operational meaning by explaining that projectId must be the generation's own project and by naming valid sources for id, such as generations_list, projects_list-generations, or a create response.

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

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

The description states a specific verb and resource: reading one existing generation together with the inputs it was made from. It explicitly distinguishes this from generations_get by saying it is not for polling status or getting the result URL, so an agent can select it confidently.

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

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

It gives explicit when-to-use guidance: only when the user explicitly continues an existing generation. It also names the alternative generations_get for status and result URL, and lists exactly which create tools accept the returned continuation payload and for which workflows.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses non-obvious response behavior: totalCostUsd is null unless availability is complete, knownSubtotalUsd must be presented as partial, retryAfterSeconds requires a re-read, and excludedCosts (tax, subscription fees, external charges) are not counted. It also states error behavior for unknown or inaccessible ids, 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.

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

Purpose and exclusions are front-loaded, and the later sentences are dense but each carries operational content (nullability, retry loop, presentation rules, error case). It is slightly overlong for a one-parameter read tool, and the output-presentation directives could be tightened, but there is little pure filler.

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

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

An output schema exists, yet the description still supplies the semantic contract the schema cannot express: when totals are null, how to poll, and which costs are excluded. Combined with recovery guidance for a missing id, an agent has everything needed to call and interpret this correctly.

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

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

The single parameter is fully documented in the schema (100% coverage), so the schema carries the format burden. The description still adds sourcing guidance absent from the schema — where to obtain the id and what to do when multiple candidates match.

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

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

The first sentence gives a specific verb and resource (read the recorded cost of one past generation) and names the exact component breakdown (lipsync, dubbing, speech_synthesis). It is immediately distinguishable from generations_estimate-cost and account_get-usage, which are named explicitly.

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

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

The description states when to use it (answering what a generation actually cost) and when not to (pre-generation pricing, remaining credits), and explicitly forbids substituting an estimate or triggering a paid generation. It also covers the prerequisite path: look up generationId via generations_list or projects_list-generations and ask the user when several match.

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

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

Annotations only declare a safe read; the description adds real behavioral context beyond them: default behavior without limit is an unpaged, unordered full result set, paging requires cursor plus the same limit, and the accessible-project case degrades to an empty list rather than an error. It also enumerates the shape of each returned entry including conditional fields (outputMediaUrl only once COMPLETED, error/errorCode on failure).

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

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

Dense but front-loaded: purpose first, then routing, then parameter behavior, then return shape. Every sentence carries information, though the single long paragraph could be split for scanability and there is a typo ('sync. organization').

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

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

With no output schema, the description compensates by describing the per-entry fields and their conditional presence, and it covers the paging contract and the project-scoping edge case. Nothing an agent needs to call this correctly and interpret the response is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining the consequence of omitting limit (unordered, unpaged) and the coupling between cursor and limit. It does not restate the status enum values, leaving that correctly to the schema.

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

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

States a specific verb and resource (list generations) plus the scope (across the current organization, every member and API key) and the two concrete reasons to call it: find a generation id or see which are still running. It explicitly names the sibling generations_get for the single-id case, so an agent can route without opening either schema.

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

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

Covers when to use it (browse/search ids, check running work), when not to (one known id → generations_get), and how it differs from the sibling projects_list-generations, including the important failure-mode difference (empty list vs. error on inaccessible project). It also gives prescriptive operational guidance: always pass limit, page with the last returned id plus the same limit.

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

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

Goes well beyond the annotations: paid action billed per item, same API/limits as single calls, respects the account concurrency limit with keyed resends, ~50 second ceiling and never waiting for completion, per-item started/failed/not_started states, and error.outcomeUnknown semantics for ambiguous server errors. The idempotencyKey reuse rule resolves the apparent tension with idempotentHint=false by explaining that derivation is per item rather than per tool call.

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

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

Front-loaded with purpose, then eligibility, then cost/confirmation, then control flow, then return values — a logical order with no filler. It is dense and long (one unbroken block of prose), and a few sentences such as the concurrent-limit/resend one could be split for easier scanning, but the complexity of a paid multi-job batch justifies most of the length.

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

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

Covers confirmation workflow, cost estimation via the matching estimate tools, projectId/projectIntent handling for keeping a set together, partial-result interpretation and the resume contract. Even though an output schema exists, the description still supplies the decision rules an agent needs (when to resend, when to poll), leaving no obvious gap for a paid, partially-failing batch operation.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: items are 'that tool's own arguments' validated as a direct call would be, must differ from one another, and a single-item set is reserved for resending 'remaining'. It also explains that a reused idempotencyKey pairs with the same items. The tool enum itself is left to the schema, so not quite maximal.

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

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

Opens with a specific verb, resource and scale bound: 'Start up to 50 independent Sync jobs at once by running one create tool once per item', then enumerates the seven eligible tools. It explicitly distinguishes itself from the batch API ('it is not the batch API') and from single-call creation, so an agent can place it precisely against siblings like batches_create and lipsync_create.

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

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

States the trigger condition plainly ('whenever the user wants 2 or more jobs that do not depend on each other') and gives three concrete worked scenarios (one video to several audios, one video dubbed per language, preview-then-video per variant). It also names the follow-up tool (jobs_get-many) and the resend path with 'remaining', and warns that items must differ and at least two are needed for a new set.

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

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

Annotations declare destructiveHint=false and idempotentHint=true, but the description adds crucial context the annotations cannot: why readOnlyHint is false ('Reading an import resends the identical assets_create request... and starts the import if none exists'). It also defines the status lifecycle, explains REJECTED semantics, describes result shapes per kind, and flags the recoveryRequired uncertainty case.

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

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

Front-loaded and organized into scannable sections (usage, ids by kind, statuses, caveats). It is long but nearly every clause carries operational value. Minor deductions for the stray typo 'sync. job' and some density that could be tightened.

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

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

For a tool with six kinds, an output schema, and partial annotation coverage, the description supplies the missing pieces: id provenance per kind, status vocabulary, result shape per kind, non-read-only caveat, and error conditions ('An unknown id, an auth failure or a translation_preview without projectId returns a tool error, not a status'). Nothing an agent needs to call it correctly appears to be missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds meaning the schema cannot express: what 'id' actually is for each of the six kinds (e.g. the social video link for import, the transcription id for speaker_analysis) and when projectId/projectIntent are required. This materially reduces wrong-parameter calls.

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

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

Opens with a specific verb+resource: 'Read any sync job once, by kind and id, with one status vocabulary for all six kinds.' It immediately distinguishes itself from siblings jobs_wait (waiting) and jobs_get-many, and the per-kind id list makes the scope concrete.

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

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

Explicit exclusions and alternatives: 'Not for waiting: use jobs_wait instead of calling this in a loop' and 'For a kind's extra read options... call that tool directly', naming generations_get and batches_get. It also tells the agent never to re-create a job on PENDING/PROCESSING, which is usage guidance in practice.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, yet the description still adds a lot: exact return shape per job in input order, error entries for unreadable jobs, aggregate counts, the full status lifecycle, progress notifications, and the ~50 second server-side cap on wait. It does not explain why readOnlyHint is false for a tool framed as 'Read', which is the one behavioural loose end.

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

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

Purpose is front-loaded in the first clause and every block earns its place, but the per-kind id rules are crammed into one long parenthetical bullet list inside a single paragraph, which makes the definition dense to scan. Structuring the kind-to-id mapping as its own listed block would improve it without adding words.

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

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

Despite having only two parameters, this tool has a non-trivial contract (batched heterogeneous ids, partial failures, polling). The description covers id sourcing, batching limits, error entries, counts, status transitions, and wait/retry semantics, so an agent can call it correctly without further context.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description carries information the schema explicitly defers to it ('see the tool description per kind'): the source of each kind's id, and which kinds additionally require projectId, projectIntent, or videoAssetId. That mapping is the whole difficulty of using this tool and exists nowhere else.

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

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

The opening clause gives a specific verb, resource, and bounded scope: 'Read up to 50 Sync jobs of any kind at once ... by kind and id'. It also anchors the tool to the producer that creates these jobs (jobs_create-many), which is exactly what distinguishes it from the single-job jobs_get and the blocking jobs_wait.

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

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

Usage is spelled out concretely: pass jobs_create-many's jobs list as-is, per-kind id derivation rules, 'never create it again' while status is PENDING/PROCESSING, and 'call again with wait: true instead of sleeping'. The only gap is that it never names jobs_get or jobs_wait as the alternatives for a single job or a pure blocking wait.

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

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

Goes well beyond the annotations by explaining the ~50s server-side wait, early return on result.recoveryRequired, progress notifications when a progressToken is present, and the {error} shape for non-job-status failures. Critically, it explains why readOnlyHint=false: an import read re-issues the identical assets_create request and can start a new import for an unseen link, which an agent could not 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.

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

Front-loaded with the core behavior, then cleanly sectioned into ids-by-kind, statuses, results, and errors, so an agent can scan to the part it needs. It is long and occasionally repetitive (the projectId rule appears in both description and schema), but the density is justified by a six-kind, multi-status tool.

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

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

An output schema exists, yet the description still supplies the one thing the schema cannot: how result varies per kind (saved asset id, batch item statuses, uncertain translation_preview acceptance). Error semantics and the non-read-only warning complete the picture for a complex polling tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by mapping each 'kind' enum value to the specific sibling create tool that produced the id, and by clarifying that the import id is the social video link plus the assets_create projectId. The schema already states most of the projectId rules, so this is reinforcement plus genuine per-kind routing detail rather than wholly new information.

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

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

The opening sentence names a specific verb (wait), the resource (any job), the timing bound (~50 seconds), the termination condition (final status), and the return shape (same as jobs_get). It is immediately distinguishable from jobs_get, jobs_get-many, and the various create tools.

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

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

Explicit when-to-use (after a create tool returns an id), explicit when-not (instead of sleeping or polling jobs_get in a loop), an explicit fallback (call again with the same input if still PENDING/PROCESSING), and an explicit alternative for a single non-blocking check (jobs_get). Nothing is left to inference.

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

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

The description adds substantial behavior beyond annotations: it is a paid generation billed to an organization, returns an id plus status to be polled via generations_get, and silently creates a new project when projectId is absent, with API rejections occurring after project creation. That said, the annotations already declare destructiveHint=true and idempotentHint=false, and the description does not explicitly discuss irreversibility or cost magnitude, so it complements rather than fully carries the burden.

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

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

Front-loaded with the core action and alternatives first, then asset upload, then project and idempotency mechanics — a sensible ordering. It is dense and some sentences pack multiple constraints, but nearly every clause carries operational meaning.

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

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

For a 20-parameter, high-consequence generation tool with nested options and sibling alternatives, the description covers input combination rules, asset upload flow, billing scope, project side effects, retry/idempotency protocol and follow-up polling. Combined with the existing output schema, an agent has what it needs to invoke and recover safely.

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

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

Schema coverage is 100%, so baseline would be 3; the description earns more by explaining cross-parameter rules the schema only implies: exactly one visual and one driver, script+voiceId pairing, and that provider, stability and similarityBoost apply only to script. It also clarifies the projectId/projectCreationKey/projectIntent coupling.

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

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

States a specific verb and resource (create one lipsync video) and immediately constrains inputs to exactly one visual and one driver, naming the concrete fields. It explicitly differentiates from siblings like lipsync_create-timeline, batches_create, dubbing_create and the Edit Dialogue tools.

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

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

Gives explicit when-to-use-other guidance for four alternatives with the conditions that select them (several audio clips, 20+ generations, translation, editing existing speech). It also states when to pass projectId versus projectName, and when continuation is warranted, leaving little to inference.

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

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

Annotations flag it as destructive, non-idempotent and open-world, and the description goes well beyond them: it discloses that generation is paid, defaults to sync-3, launches asynchronously and must be polled with generations_get wait:true, that validation happens pre-creation but API-side failures can occur after a project exists, and the exact idempotency/retry contract including the warning never to resend a request lacking an idempotencyKey.

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

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

The core purpose, the sibling boundary and the paid/async warning are front-loaded, and the dense paragraphing is largely earned by a genuinely complex operation. It is still a long description with some restatement of schema content (the seconds-or-frames rule appears twice), which keeps it from a 5.

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

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

For an 11-parameter, deeply nested, destructive, paid, asynchronous tool, the description covers prerequisites (fps from assets_get-playback-metadata), the dub workflow, error surfacing, and the post-creation polling step. With an output schema present it correctly avoids describing return values while still naming the returned id and status.

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

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

Schema coverage is 100%, so the schema already explains every field; the description still adds interaction semantics the schema cannot express, such as exactly-one-of audioAssetId/audioUrl per clip, no mixing seconds and frames, and non-overlap only being checked within one unit. It does not explain every options field (sync_mode, model_mode are left to the schema), so it is strong but not exhaustive.

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

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

The opening sentence gives a specific verb and resource with scope: lipsync one saved video against several audio clips, each on its own stretch. It immediately distinguishes itself from siblings by naming lipsync_create for single-audio work and dubbing_create for full-video dubbing.

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

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

Explicit routing rules are given throughout: which sibling to use for one audio vs. many, when to pass outputAudio, when to mark clips lipsync:false, when to use frames vs. seconds, and when projectId is legitimate ('only when the user explicitly asks... never permission to modify it'). Alternatives and exclusions are both stated.

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

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

Annotations already mark this read-only and non-destructive, yet the description adds real behavioral context: no pagination, newest-first ordering, deprecated models excluded, feature-flagged models only shown where enabled, and the caveat that a listed model can still be refused at creation (react-1 without a paid plan). It also warns that some listed models serve other workflows, so lip sync should pick a lipsync model.

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

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

The return shape and the routing to sibling tools come first, which is the right order, and there is no filler. The later sentences are long and compound, packing eligibility caveats and the voices exclusion into dense clauses, which costs a little readability.

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

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

For a zero-parameter, non-destructive list tool with no output schema, the description covers what comes back (fields and ordering), what is omitted, and which downstream tools depend on the result. Nothing an agent needs to call and use this correctly is missing.

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

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

The tool takes no parameters, so there is no schema semantics to supplement; the description instead constrains how the output is consumed ("Pass a returned name exactly as listed and never invent one"). That is useful, but it is guidance about output usage rather than parameter meaning, so it stays at the zero-parameter baseline.

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

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

"List the sync. models this account can see, newest first, in one unpaged array" gives a specific verb, resource, ordering, and shape, and then enumerates the returned fields (name, type, version, description, feature tags). It explicitly separates itself from the nearest sibling with "Not for voices; use voices_list."

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

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

Names the exact consumers of the returned value (dubbing_create, dialogue-videos_create, dialogue-videos_estimate, generations_estimate-cost) and the override case for lipsync_create / lipsync_create-timeline. It also states a when-not condition: "it is not needed when the user has not asked for a model on those two."

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

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

Beyond the readOnly/idempotent annotations, it discloses that results depend on credential type: a Sync app connection lists only the organizations ticked at connect time, while an API key returns only the key's own organization. That tells the agent how to explain an unexpectedly short list, which annotations cannot convey.

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

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

Three sentences, front-loaded with purpose, then usage, then credential caveats — well ordered with no filler. A couple of phrases ('pass organizationId on one paid create') are slightly compressed but still parseable.

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

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

With zero parameters, an output schema already present, and read-only annotations, this description covers everything an agent needs: what comes back, when to call it, which sibling to use next, and why results may be limited.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing the description could add about inputs. It does clarify the meaning of the isCurrent output marker, but that belongs more to output documentation than parameter semantics.

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

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

The description opens with a specific verb and resource ('List the Sync organizations this connection can act in') and states what each entry carries (role, plan) plus the isCurrent marker. This is clearly distinguishable from siblings like organizations_select or projects_list.

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

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

It gives the triggering conditions ('when the user names an organization or team, or asks where work is created') and names the follow-up alternatives: organizations_select, or passing organizationId on a paid create. It also states the out-of-band fix (reconnect Sync and tick the organization) when the desired org is missing.

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

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

Annotations only say it is non-read-only, idempotent, non-destructive and closed-world; the description adds the crucial session-persistence behavior, that paid generations are affected, and that the switch lasts until session end or another switch. It also discloses the access model (Sync app connections limited to organizations ticked at connect time, reconnect error message, API keys bound to one organization and unable to switch), which is exactly the failure mode an agent needs to anticipate.

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

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

Front-loaded with the core action and its persistent scope, then the id source, then the access caveats, then the single-generation alternative. It is dense with four clauses of caveats, but each sentence carries distinct information; minor trimming of the reconnect wording would make it tighter.

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

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

An output schema exists so return values need not be detailed, and the description still previews them briefly (plan, generation limits, feature flags). Combined with the session-scope and auth constraints, an agent has everything needed to decide to call it and to interpret a refusal.

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

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

Schema description coverage is 100% and the schema already says the id comes from organizations_list, so the description largely restates that. It does reinforce that the value must originate from organizations_list rather than being constructed, but adds no format or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Switch this session to another Sync organization') plus the exact scope of the effect ('every later call runs there'). This clearly separates it from organizations_list (read-only enumeration) and from per-call organizationId overrides, which are named explicitly.

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

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

Gives an explicit when: only when the user asks to work in that organization, and requires an id sourced from organizations_list. It also gives the when-not and the alternative: 'To run a single generation elsewhere, pass organizationId on that create instead.'

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

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

Annotations already flag a non-readonly, idempotent=false, openWorld write, but the description adds facts they cannot convey: creation is not billed, ownership semantics ('you own it (for an API key, its owner)'), and that every call without an id produces another project. It also explains the retry contract (reuse the same UUID only for the same creation) and which fields come back, which is substantive disclosure 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.

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

A single front-loaded paragraph that leads with what is created and moves to defaults, exclusions, id semantics and return fields in a useful order. It is dense but long, and the id-reuse sentence partially duplicates the schema's id description.

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

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

Covers everything an agent needs for a mutation tool with no output schema: billing, ownership, defaulting behavior, the destructive/idempotency nuance, downstream propagation of the returned id, and the returned fields. Nothing essential is left unstated.

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

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

Schema coverage is 100% and already documents each field, yet the description adds cross-tool meaning the schema cannot: pass the returned id as projectId with projectIntent=explicit, omit projectId and use a fresh projectCreationKey for lipsync/dubbing with saved assets. The id retry/collision advice is restated but framed in workflow terms.

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

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

States a specific verb+resource ('Create a new, empty sync. project in the current organization') and its purpose (grouping assets and generations of one workflow request). It also distinguishes itself from siblings by naming projects_list for finding an existing project and by describing when the call should be skipped in favor of lipsync_create/dubbing_create.

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

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

Gives explicit when-to-use guidance ('Use it by default for every new workflow request, even when a project with the same name exists'), explicit when-not ('Skip it for a new lipsync_create or dubbing_create with saved assets') and a named alternative ('find that one with projects_list') for continuing a user-named project. No inference is required.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description goes beyond them with the 404 contract: missing, deleted, and another user's USER-visibility projects all fail the same way — a genuinely useful disclosure about both error behavior and access scoping. It also flags the failure mode when projectId and id disagree. It stops short of describing response shape beyond the field list, which keeps it at 4 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.

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

Front-loaded with purpose, then usage, then alternatives, then error behavior — a sensible ordering with no filler sentences. It is dense and slightly run-on ("sync." and stacked clauses in the last sentence), which costs a point but nothing is redundant.

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

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

For a two-parameter read tool with no output schema, the description supplies the returned fields, the access/error contract, the id-sourcing path, and the deprecated-alias rule. An agent has everything needed to call it correctly and interpret a 404.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real meaning by declaring projectId the canonical input, id a deprecated alias, and specifying that passing both with conflicting values is an error — behavior the schema only hints at. It doesn't add id format or sourcing detail beyond what the schema's "from projects_list, projects_create" note already says.

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

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

Opens with a specific verb+resource+scope: "Read one sync. project you can access by its id", then enumerates the returned fields (name, description, visibility, mode, defaultWorkflow, owner userId, organizationId, timestamps). It explicitly distinguishes itself from projects_list and projects_list-generations, so an agent can pick it out of the large sibling set without opening the schema.

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

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

Gives an explicit when-to-use rule ("check a project the user explicitly named or selected before working in it") and routes to alternatives by name: projects_list to obtain an id, projects_list-generations for history. Exclusions are concrete rather than implied.

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

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

Annotations already declare readOnly/no-destructive/closed-world, and the description still adds real behavior: visibility scope of results, page size defaults, sort order, the presence/absence of nextCursor on the last page, and the composition of each item. It also flags a misuse pattern (destination selection) that no annotation conveys.

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

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

Purpose comes first, then routing guidance, then pagination details — a sensible order with no filler sentences. There is mild redundancy (the default page size and cursor mechanics repeat the schema) and a stray fragment ('sync.'), which keeps it off a 5.

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

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

With no output schema, the description compensates by describing the return shape (items plus nextCursor) and the per-item fields including generationsCount, latest generation and thumbnail. Combined with the routing guidance, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so limit, cursor, sortBy and searchQuery are already fully documented, including the enum values and defaults. The description largely restates the pagination default and cursor mechanism rather than adding new semantics, so it sits at the baseline.

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

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

States a specific verb and resource with scope: 'List the ... projects you can access in the current organization (your own plus organization-visible ones)'. It also names the siblings it is not (projects_get, projects_list-generations, projects_create), so an agent can route without opening any schema.

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

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

Explicitly covers when to use ('to find the projectId of a project the user explicitly refers to'), which alternatives to use for adjacent needs (projects_get for a known id, projects_list-generations for history), and a hard when-not ('Never use it to choose a destination for a new workflow request'). It even disambiguates workflow names like Translate and Dub from project names.

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

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

Beyond the readOnly/non-destructive annotations, the description discloses that a missing or inaccessible project fails with an error rather than an empty list, and that omitting limit returns everything unpaged in no guaranteed order — non-obvious behaviors an agent must plan around. It also enumerates the return shape, which matters since there is no output schema. It stops short of noting rate limits or maximum page behavior beyond what the schema states.

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

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

Front-loaded with purpose and sibling routing, then paging rules, then return shape — a sensible priority order. It is dense and the final field enumeration runs long, but each clause carries information the agent needs given no output schema.

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

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

Covers purpose, alternatives, failure mode, ordering, pagination contract, and the per-entry fields including the deprecated outputUrl alias — everything an agent needs for a 4-parameter read tool with no output schema. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the consequence of omitting limit (unpaged, unordered, full result set) and the cursor contract (last returned id, paired with the same limit). It does not explain the status filter, though the schema already enumerates its values.

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

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

States a specific verb and resource ('List the generations in one sync. project') scoped to a single project, and immediately names the two siblings it must not be confused with (generations_list for org-wide/without projectId, generations_get for a known id). An agent can distinguish all three without opening a schema.

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

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

Explicit routing: use this for a project's history, generations_list for the whole organization or when no projectId is available, generations_get for a single known id. It also gives operational guidance to always pass limit for newest-first ordering and to page by passing the last returned id as cursor with the same limit.

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

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

Beyond the annotations (which only say non-read-only, idempotent, non-destructive), it discloses the blast radius ("visibility, owner, media and generations stay as they are"), the failure mode (404 for missing, deleted or inaccessible project), and the pre-condition gate that can reject the call. Those are exactly the behavioral facts 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.

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

Three tight sentences: scope first, then the selection rule, then the operational gotcha. No filler. Minor deduction because the projectIntent guidance tracks the schema's own wording closely enough that it partly repeats structured data rather than adding new signal.

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

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

For a low-complexity, flat 3-parameter mutation with an output schema present, everything an agent needs is covered: what changes, what does not, when to call it, when not to, the rejection condition, and the error case. Return values are mentioned but the real detail lives in the output schema, which is the right division of labor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a consequence the schema does not state: omitting or guessing projectIntent "can be refused with PROJECT_INTENT_REQUIRED." That turns a const field into an actionable requirement. The remaining content largely restates the schema's own projectId and projectIntent text, so it stops short of 5.

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

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

States a specific verb and resource ("Rename one existing project") plus precise scope ("you can access in the current organization") and the exact field affected ("only the name changes"). It distinguishes itself from the sibling projects_create by naming it as the destination for new work, so an agent can route without opening either schema.

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

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

Gives an explicit when ("only when the user explicitly asks to rename that project") and an explicit when-not ("never because its name or workflow matches the request or its editor is open"), and names the alternative tool (projects_create) for the excluded case. This is about as complete a selection rule as a description can carry.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description justifies both by calling this a 'potentially paid action' whose only deduplication is the supplied idempotencyKey. It additionally discloses the return lifecycle (PENDING/PROCESSING/SUCCESS/FAILED, url and duration only on SUCCESS) and pre-synthesis failures. It does not contradict the annotations — a new key can bill again, which is consistent with idempotentHint=false — but it could have been a touch more explicit about the billing trigger.

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

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

The purpose and the paid-action warning are front-loaded, and nearly every sentence carries an operational rule. It is a single dense paragraph, though, and the polling/retry/anti-duplicate rules would scan faster as discrete lines; a few clauses restate the schema descriptions for projectId and idempotencyKey.

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

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

For a paid, open-world, job-creating mutation with seven parameters and an output schema, the definition covers selection, prerequisites, side effects, failure modes, polling, retry semantics and sibling routing. Nothing an agent needs in order to call it safely is missing, and the return-shape note is a bonus rather than filler.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by prescribing how projectIntent=explicit must be reasoned about (only explicit user selection or a just-created project, never name matching) and by treating idempotencyKey as a persisted artifact rather than a plain UUID. The stability and similarityBoost knobs get no prose treatment, which keeps it at 4 rather than 5.

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

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

States a specific verb and resource: 'Synthesize a confirmed script in a voice from voices_list into one standalone speech audio job (ElevenLabs)', and explicitly names the three siblings it is not (lipsync_create, dialogue-previews_create, translation-previews_create). An agent can choose between them without opening any schema.

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

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

Gives explicit preconditions (check speech-previews_get-options first, persist idempotencyKey before calling, verify projectId access) and explicit exclusions routing to the three alternative tools. It also states the recovery procedure after an uncertain response and forbids re-creating after an attach failure, which is exactly the when/when-not guidance this dimension rewards.

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