CueFrame

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

Goes well beyond the annotations: disposable staging, immutable original/transformed bytes with dependency/installer provenance, explicit non-actions ('does not execute source, convert arbitrary HTML or mark it CueFrame compatible'), and the 'never force-overwrite authored work' safety rule. The commandId retry-identity note nuances idempotentHint=false rather than contradicting it, since dedupe only applies to a repeated identical commandId.

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 and every sentence is topical, but the prose is dense and jargon-heavy across roughly eight clauses, with some material (e.g., 'Changed source versions remain provenance-pending until exact adaptation bytes are captured') that reads as implementation trivia an agent must parse to extract the actionable rules.

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 no explanation, and the description still covers what the receipt owns and the follow-up inspection step. For a nested-object, open-world mutation the main residual gap is the lack of explicit routing against the sibling search/select/get tools.

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 50% schema coverage, the description compensates by enumerating the body fields and giving real semantics: 'Keep the snapshot and manifest digest exactly as observed' and 'native author sessions supply their replay-stable top-level commandId automatically.' The 'variables' object remains opaque, but the schema explicitly delegates it to describe_tool_input.

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 ('acquire a selected external candidate') and pins the mechanism ('pinned maintained installer in disposable staging'), which separates it from get_registry_item and search_registry_items. It never explicitly names a sibling, but the acquisition framing makes the operation distinct.

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

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

The description gives sequencing ('Inspect the receipt with get_registry_acquisition, then author through existing admitted component/template operations'), which implies use after selection and before authoring. It never says when NOT to use it or how it differs from select_candidate / get_registry_item, so the selection logic 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?

Annotations only declare readOnly=false, idempotent=false, destructive=false; the description adds the substance: all-or-nothing semantics, 428 precondition_required, 409 stale_etag recovery procedure ('never copy the error's currentEtag'), brand-drift refusal, unsupported_concurrency on non-guarded endpoints, dry_run validation-only behavior, and that captions do not auto-update after edits. This is behavior no annotation or schema field 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?

The content is valuable but heavily bloated and repetitive: the negotiated-execution rule is stated twice, if_match/precondition requirements are restated three times, and the card-token warning runs several sentences. Section headers ('CAPTIONS FOR EDITED TIMELINES:', 'CARDS:', 'SCENE SHOTS:') help, but a multi-screen wall of prose for a 4-param tool buries the two or three facts most calls need.

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 high-complexity, deeply nested batch-mutation tool with an output schema present, the description covers preconditions, failure modes, dry-run, target selection, and the major op families (captions, cards, scene), and points to cueframe://scene-shot for the one area it deliberately does not inline. Nothing an agent needs to call it safely 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 already 100%, but the description adds inter-parameter semantics the schema cannot express: composition_id is mutually exclusive with session_id and targets a non-active composition, componentExecutionVersions must be paired with the exact observed expectedBrandIdentity, builtinSources pins must be referenced by the final composition, and concurrency requires a guardedCompositionV1-capable endpoint. These relational constraints go well beyond per-field descriptions.

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

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

Opens with a specific verb+resource+unit of work: 'Atomically apply an array of CompositionOps to a project composition,' immediately qualified as transactional. That distinguishes it from validate_composition (non-persisting check), derive_composition and new_composition (creation), and get_composition (read) without the agent needing to open 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: call describe_composition_ops for the op list/schema, get_composition with componentExecutionVersions for the negotiated path, new_composition then composition_id for A/B variants, and explicitly excludes brand work ('Brand is NOT set here — it lives on the project'). It also states when-not: committing calls with neither if_match nor concurrency are refused with 428, and only legacy dry-runs may omit preconditions.

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?

Well beyond the annotations, the description discloses preservation semantics ('preserves existing timeline content and package source offsets'), refusal conditions (missing media, stale revision, stale pin, brand mismatch), and the no-silent-witness-refresh rule. The mutation is non-destructive by design and the description explains why, consistent with destructiveHint=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 and information-dense, but it is packed with unexplained jargon ('witness', 'package source offsets', 'pin') and the final sentence — 'For ordinary templates, this operation retains its existing apply behavior' — is near-vacuous and adds ambiguity rather than information.

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

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

For a mutating tool with an output schema (so return values need no explanation) and only thin annotations, the description covers prerequisites, refusal behavior, and binding semantics adequately. Remaining gaps are the unexplained 'preset'/'brandKitId' parameters and the absence of any degraded-recovery path when a refusal occurs.

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 67%, and the description compensates on the parts the schema cannot convey: it maps 'template' to the selected builtin id, spells out the required body fields, disambiguates the cryptic componentExecutionVersions consts as [3,4], and explains the two media binding modes. It omits any explanation of 'preset' and 'brandKitId', and does not mention the url media variant the schema permits.

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 — 'Insert a resolved builtin component package into an existing project' — and 'resolved' usefully signals the dependency on resolve_builtin_component. It stops short of differentiating this from close siblings like apply_composition or start_template, and the closing line about 'ordinary templates... existing apply behavior' blurs the boundary rather than sharpening it.

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

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

The description explicitly imposes a prerequisite workflow ('Read get_composition first and retain expectedRevision, commandId, componentExecutionVersions:[3,4] and expectedBrandIdentity') and states selection rules for media bindings. It lacks an explicit 'use this instead of X' routing statement against apply_composition/start_template, which keeps it from a 5.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true, so the safety profile is covered. The description adds real value beyond that: the director cancel is confirmed before the row flips, linked charges are released, and an already-terminal job returns 422 rather than silently succeeding — behavior an agent could not infer from annotations.

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

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

Four short sentences, front-loaded with the action and the motivating scenario, then prerequisites, then side effects, then the failure mode. Nothing is redundant with the schema or the title.

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

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

For a cancel mutation with no output schema, the description covers prerequisites, side effects (charge release), and the terminal-state error. It does not say what state the job ends in or how to confirm the cancellation afterward, a minor gap given there is no return-value 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, but the description adds provenance the schema lacks ('composeJobId from compose'), which directly helps an agent source the required ID. commandId's retry semantics are 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 and resource ('Cancel an in-flight compose job') and glosses the intent ('stop a runaway/mis-priced ensemble'). The resource is unambiguous against siblings like cancel_export, cancel_render, and cancel_job, which operate on different object types.

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 clear use condition (stopping a runaway or mis-priced job) and notes the terminal-state case that will be rejected with 422. It stops short of naming an explicit alternative or explaining what to do instead when the job is already terminal, so it falls short of a 5.

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

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

Annotations already cover safety (non-read-only, non-destructive, idempotent), but the description adds the terminal-state 422 rejection, which is behavior not encoded anywhere in the structured fields. It omits what a successful cancel returns, though with no output schema that is a small gap.

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

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

Three short clauses, no filler: action+scope first, required inputs second, failure mode last. Every sentence carries information the agent needs.

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

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

For a low-complexity, 3-parameter mutation tool with a fully-described schema and no output schema, this covers the action, prerequisites, and the one surprising error case. Only the success response shape is unaddressed, which is minor here.

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 slightly beyond by naming exactly which two ids are required and where exportId comes from ('from the export enqueue'), giving the agent provenance the bare 'exportId (path)' schema description lacks.

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: 'Cancel an in-flight NLE export (fcpxml/premiere)'. The scope qualifier 'in-flight' and the format parenthetical distinguish it from the many sibling cancel_* tools (cancel_compose, cancel_job, cancel_render) without the agent 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?

The 'in-flight' qualifier plus 'No-op-reject (422) if already terminal' tells the agent the precondition for calling and what happens if it guesses wrong. It does not explicitly point at the sibling alternatives (cancel_render vs cancel_job), so the routing is inferred rather than 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?

Goes well beyond the annotations: discloses billing behavior ('cancel never meters'), side effects on infrastructure ('warm box is reaped best-effort'), and the exact failure mode with status code ('422 if already terminal'). This is exactly the context the idempotentHint/destructiveHint flags 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?

Two sentences, zero filler, with the core action and job types front-loaded before the billing and error semantics. Every clause contributes new information.

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

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

Covers the mutation's side effects, billing and error behavior, which is more than enough for a two-parameter tool with full schema coverage. The only gap is that no output schema exists and the description does not say what a successful cancel returns.

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

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

Schema coverage is 100% and commandId already carries a clear retry-identity explanation, so the structured data does the heavy lifting. The description adds no argument-level detail such as where to obtain jobId or how commandId interacts with cancellation, so baseline 3 applies.

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

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

States a specific verb+resource ('Cancel a running async job') and enumerates exactly which job kinds qualify (verify / preview / brand-kit-extract) while anchoring the resource to 'returned by an enqueue call'. An agent can distinguish this from wait_job purely from the description.

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

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

Gives a concrete when-to-use motive ('abort a mis-priced job instead of waiting out its TTL') and a when-not condition ('No-op-reject (422) if already terminal'). It implies the alternative (wait_job) through 'instead of waiting out its TTL' but never names it, so routing is slightly inferential.

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 and destructiveHint=false, so the bar is lower; the description still adds real context by explaining that terminal-state calls are a no-op and by naming the origin of renderId. It stops short of saying what the render's resulting state or artifacts look like after cancellation.

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 sentences, front-loaded with the action, then prerequisites, then the edge-case behavior. No filler or restatement of the tool name.

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

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

For a three-parameter, no-output-schema cancellation tool with rich annotations, the description covers action, required inputs, provenance, and terminal-state behavior. 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 both required params and commandId are already documented in the schema. The description adds only the provenance note that renderId comes from create_render, and says nothing about commandId's retry semantics — baseline 3 applies.

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

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

States a specific verb and resource ('Cancel an in-flight render') plus the scope of what qualifies (runaway/queued job). The resource noun 'render' implicitly separates it from cancel_compose, cancel_export, and cancel_job, though no sibling is named explicitly.

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

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

'Cancel an in-flight render (stop a runaway/queued job)' gives a clear condition for use, and 'No-op if already terminal' tells the agent it is safe to call without first checking state. It does not, however, mention alternatives such as retry_render for jobs that failed rather than need stopping.

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, and the description reinforces this by ruling out rerender/edit side effects. It adds that outputs are unaligned and that views/crop affect only diagnostic evidence, not the underlying composition. It does not cover failure modes (e.g., mismatched resolutions or stale identities), which keeps it below a 5.

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

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

Five tight sentences with the core action and return shape front-loaded, followed by prerequisites and caveats. Dense terminology ('certified representation', 'explicit event correspondence') costs some readability but no sentence is filler.

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

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

For a nested-object comparison tool with an output schema (so return values needn't be spelled out), the description covers inputs' provenance, side-effect guarantees, and the retiming caveat. The main remaining gap is what the caller should do when comparison preconditions fail.

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 only 50% schema description coverage and nested objects, the description does real work: it tells the agent where reference.mediaItemId/representationIdentity and candidate.jobId/artifactId come from, and clarifies that views are optional and that crop uses identical coordinates across both frames. It still leaves the required/optional status of views and the crop bounds 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?

States a specific verb and two specific resources (a certified reference frame vs. an existing full-resolution PNG preview) and names the exact output artifacts. It is clearly distinguishable from preview_frame (which produces the candidate) and editorial_run_source (which supplies the reference identity).

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 prerequisite chain: read editorial_run_source for the reference identity, then preview_frame + wait_job for the candidate artifact. It also states the exclusion ('never rerenders or edits the composition') and the retiming caveat that selects a different correspondence strategy.

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 readOnly=false, destructive=false, idempotent=false, openWorld=false; the description adds the async-job model, ensemble verification, the refusal-loudly behavior, and the returned { composeJobId, status, streamUrl }. However, its claim that fromComposition carries authored graphics 'VERBATIM as locked clips ... never re-authors or drops' conflicts with the schema's statement that client-authored graphic clips cause a validation_error refusal (only the Director's own critique-retry output is exempt), which could lead an agent into a guaranteed 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?

Front-loaded with the core action and the return/follow-up contract, with no filler sentences. It is dense and heavily parenthesized — the three source paths in one long sentence with backticked labels — which is efficient but slightly harder to scan than a bulleted breakdown would be.

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 names the returned fields and the blocking follow-up, and annotations plus schema cover the remaining safety/budget/hold semantics. The one substantive hole is the missing caveat that fromComposition is refused for client-authored graphic clips, which is exactly the kind of failure mode a caller needs pre-warned.

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 giving the source-selection semantics and the exact mutual-exclusivity rule ('EXACTLY ONE source'), which is the highest-risk parameter decision. Other body fields (maxCandidates, holdAt, critique, budgetUsd, qualityThreshold, seed, clientNonce) are left entirely to the schema, so it is 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?

States a specific verb and resource ('Start an async Director compose job') and immediately explains the pipeline: authors an ensemble of candidates, verifies each, saves the winner. It also distinguishes itself from siblings by naming apply_composition, create_brief, suggest_briefs and wait_job as the surrounding steps.

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 enumerates the three mutually exclusive entry paths and their prerequisites: briefId requires create_brief first (PLANNED), fromComposition requires apply_composition first (GENERAL), suggestionId pairs with suggest_briefs (CLIPPING). It also gives the mandatory follow-up (wait_job with kind="compose"), so an agent knows both when to call it and what to do next.

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 beyond-annotation context: async job semantics, a returned consultJobId, per-mode latency estimates (~30s-2min vs minutes), and the etag/409 binding on ifMatch. However, it never reconciles readOnlyHint=false with the framing that the tool 'never writes' — the agent gets the composition-safety story but not an explicit statement that calling consult itself creates a job and consumes compute. Useful context, but the mutation profile is left implicit.

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 purpose and the 'never writes' guarantee come first. But the body is a dense block of parentheticals and backticked mode names that duplicates the schema's enum documentation (mode semantics are explained twice), and the advise/amend distinction is split across two separated sentences rather than stated once. Informative, but over-packed.

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 a nested body, an output schema, and an async continuation, the description covers the full round trip: intent, mode selection, focus, etag conflict behavior, the job id, and how to poll and adopt the result. Nothing material is missing; commandId retry semantics are already documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns a bump by adding meaning the schema lacks: 'explore is coming soon → use amend' steers the enum choice, and per-mode latency and output shape (plan vs graded assessment + candidateIndex) tell the agent what each mode actually yields. It largely restates intent/focus/ifMatch, however.

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: 'Ask the Director for editing advice on the project's CURRENT composition', and immediately negates the most likely confusion ('it NEVER writes your composition'). That distinguishes it cleanly from apply_composition, compose, and score_composition without requiring the agent to open their 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 routing: use 'advise' for a fast directional nudge, 'amend' for a grounded adoptable fix, and pins 'explore' as unavailable ('coming soon → use amend'). It also names the follow-up call (wait_job with kind="consult") and the adoption path (select_candidate), so the agent knows both when to call this and what to do next.

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 annotations by disclosing upsert semantics (re-POSTing same kitId updates in place), tenant scoping (no project arg), and the cross-tool effect on rendering. There is a mild tension with idempotentHint=false, though that hint concerns environment no-ops while the description describes an in-place update, so it is not a clear contradiction.

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 verb+resource, then workflow, then consequences—logical ordering. It's dense with parentheticals and all-caps emphasis that could be tightened, but each sentence carries real information.

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

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

Output schema exists, so return values aren't needed. Description covers the important context: upsert behavior, workflow step, binding path, and tenant scoping—enough to call it correctly. It leaves out how the tool relates to extract_brand_kit and the many optional body fields.

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 the body fields; the description only names kitId, fonts, colors, and logo. This adds the meaningful kitId upsert semantic, but says nothing about the many other body fields, so 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+resource: 'Create or UPSERT a brand kit' and clarifies it also serves as the UPDATE path. Distinctly scoped as the authoring entry point ('brand step 0'). Minor gap: it doesn't disambiguate from the sibling extract_brand_kit, which is another way to obtain a brand kit.

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

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

Explicitly tells the agent when and how to use it: author the kit, then bind it via create_project (kitId as brandKitId) or update_project. It names the concrete alternative consumers and warns that without binding, create_render produces UNBRANDED output. This is exactly the when/alternatives/consequence guidance the dimension wants.

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

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

Annotations only declare the safety profile (not read-only, not idempotent, not destructive); the description goes well beyond that. It discloses that seededGraphics are carried VERBATIM as locked clips and never re-authored, that exclusions are hard negatives the Director must never author, that moment pinning is 'honored to-the-frame or refused', and that the response carries a quote which must be relayed before composing. These are non-obvious contract behaviors an agent could not infer from annotations.

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

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

Purpose and the compose handoff are front-loaded, which is good, but the middle is a single sprawling field dump with heavy CAPS emphasis and parentheticals that is hard to parse in one pass. Every clause is informative, yet the delivery is less structured than it could be (no grouping, one giant sentence for all fields).

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 complex nested mutation tool this covers the contract well: intent, exclusions, seeded graphics locking, gates, and the mandatory quote relay. An output schema exists so return values needn't be explained, and the description still notes what the response carries. The remaining gap is the unmentioned root-level params (projectId, commandId retry identity) that the description never touches.

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

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

With schema coverage at only 50% and several nested objects deferred to describe_tool_input, this description does real compensatory work: it names goal as required, clarifies locale drives ALL on-screen copy + captions, explains beats carry editorial intent plus moment pinning, and defines captions.emphasisPhrases as the big-serif treatment. It omits projectId, commandId, name, references, and audio, so it does not fully close the coverage gap.

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

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

Opens with a specific verb+resource: 'Persist the video's INTENT as a Brief — the Director's rich input contract'. That is far more than a restatement of the name and explains where the artifact comes from (the storyboard skill's output). It does not explicitly differentiate itself from siblings like update_brief, editorial_create_brief, or suggest_briefs, which keeps it at 4.

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 next-step workflow: 'Then compose it: compose with {briefId}' and an explicit human-in-the-loop precondition ('relay it to your human BEFORE composing'). That is real usage guidance. What is missing is when NOT to use it — no mention of update_brief for revisions or the editorial_* brief variants.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds genuinely new facts: an existing saved card is NEVER charged silently, the human confirms on Stripe, the org is resolved from the API key and not the body, and billing:write scope is required. It stops short of covering idempotency/retry behavior (commandId) even though idempotentHint=false, which is the one behavioral gap.

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

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

The core action and return value are front-loaded in the first sentence, and every subsequent sentence adds a real constraint. It is somewhat run-on with several em-dash asides and could be trimmed, but there is no filler.

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

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

For a mutating, payment-adjacent tool it covers what an agent needs: what is created, that the output is a { url } to hand to a human, that no charge happens server-side, the required scope, and where to look before calling. An output schema exists, so the terse return-value mention is sufficient.

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 50% schema coverage the description must compensate, and it partially does: it enumerates the three plan values and warns that the org is never in the body. But it silently omits the `interval` and `commandId` parameters entirely, and the schema's own `interval` description (monthly/annual, '~2 months free') and `plan` description ('Plan tier to subscribe to') actively conflict with the description's insistence that no subscription exists.

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 ('Top up the CURRENT org's credit wallet') and immediately clarifies the concept against the nearest confusion ('There are no subscription tiers — a pack is a one-off top-up'), which no sibling tool covers. An agent can distinguish this from get_account, get_usage, and list_plans 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?

Explicitly gates invocation: 'Only send a user here when get_account shows the relevant `balance` at or near zero' and routes discovery to 'list_plans'. That is a when-to-use, a when-not-to-use, and named alternatives in one place — the highest bar.

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

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

Goes well past the annotations: it discloses that the source is admitted before storage (template lint, determinism rules banning timers/Date/network/CSS animation, declaration checks), that refusals name the violated rule, that version-3 sources are rejected as component_source_retired, and that the response is ComponentResponse (id + metadata). Annotations only say non-read-only/non-destructive/non-idempotent; the description supplies the mutation's actual risk profile and failure modes.

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

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

Front-loaded correctly — the tool's purpose is the first clause — but the rest is a single dense block of jargon-heavy prose with no line breaks or bullet structure, forcing the reader to parse a schema contract inline. For this complexity some length is warranted, yet the informativity-per-sentence varies and the pointer to "the server instructions' Component Contract" partially duplicates what is restated here.

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

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

With an output schema present, the description needn't explain return shape, and it correctly limits itself to id+metadata context. It covers the admission pipeline, versioning, scoping, and placement contract. It omits what happens on a duplicate or colliding componentId (create vs. overwrite, conflict status), which is the main remaining gap for a create 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 100%, so baseline is 3, but the description earns more: the `source` field is opaque in the schema (just a pointer to describe_tool_input with required keys), and the description spells out the four sub-objects, the required template DOM skeleton, the __cfScene.mount call, the data-composition-variables projection rule, the manifest fields, and the slot constraint ("slots never travel in params"). That is meaning the schema does not carry.

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?

A concrete verb+resource ("Create and store a custom component for the tenant") plus a one-line explanation of what a component actually is (a native 3D scene tiling declared media). The tenant-scoping note ("No project arg") narrows scope, but no sibling is named, so a caller has to infer the boundary with update_component, preview_component, and resolve_builtin_component.

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 lays out the downstream workflow explicitly — the returned ComponentResponse id is referenced from a composition, and placement uses execution {version:4,...} plus placement {version:3, kind:'clip'}. It never states when NOT to use this tool or which sibling to pick instead (e.g. preview_component before creating, update_component for edits), so it stops short of full routing guidance.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds genuinely useful behavior — brandKitId propagates colors/fonts/motion theme to every render of the project, and omitting it yields unbranded output — plus the return type. However, it is silent on the deprecated width/height fields and on what happens if format conflicts with them, which is the main behavioral risk here.

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 prerequisite role, then parameters, then return value — a sensible order with no filler sentences. The parenthetical '(PATCH /projects/:id over REST)' is slightly extraneous transport detail for an MCP caller, but it does not obscure the guidance.

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

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

An output schema exists and the description still names ProjectResponse (id + metadata), so return semantics are covered; creation effects and the brand-kit binding are explained. The remaining gap is the undocumented deprecated width/height pair, which an agent could plausibly pick from the schema without knowing the description's preferred format 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 description coverage is 100%, so the schema already documents both top-level parameters and the nested format object; baseline is 3. The description does add real value for brandKitId by tying it to create_brand_kit's kitId and spelling out the consequence of omission, but it never mentions the deprecated width/height fields or the free-form description field.

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 a new project') and immediately defines what a project is ('the unit you compose and render into'), which distinguishes it from compose, create_render, and the preview siblings that consume a projectId rather than mint one.

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 tools that require a projectId (compose / apply_composition / create_render / the preview family) and states this tool mints one, so the prerequisite relationship is unambiguous. It also routes the agent to update_project for later brand-kit changes, covering the obvious follow-up case.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, so the call's mutation profile is known. The description adds real value beyond that: it is asynchronous ('queue'), returns { id, status, warnings? } with warnings semantics, and states that an unknown/foreign/scratch-less session is a 404 rather than silently falling back to the active composition. It stops short of describing failure/rate-limit behaviour beyond the 404 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?

The core action and the follow-up wait_job call are front-loaded; the branding caveat and webhook alternative come after. It is dense but nearly every clause carries information, with only mild redundancy (return shape is also covered by the 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?

This is an async creation tool with nested body objects, and the description covers the full lifecycle an agent needs: what is queued, what comes back, how branding is resolved, how errors on the session target surface, and how to await completion. Nothing essential is missing despite the nested 'format' field delegating to describe_tool_input.

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 a 3 is the baseline. The description compensates on the highest-value ambiguity: brandKitId determines whether the output is branded or unbranded, and how to bind one (create_project/update_project or PATCH /projects/:id). It also clarifies the session_id vs compositionId exclusivity, though that is largely duplicated from 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+output type: 'Queue an MP4 render of a project's composition' with the compose-session scratch variant. This clearly separates it from get_render, retry_render, cancel_render, and wait_job in the sibling list.

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

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

Explicitly routes the agent to the two follow-up paths: wait_job(kind="render", id=renderId, projectId=...) to block for the URL, or create_webhook on render.completed. It also names the alternative target (compose session scratch vs active composition) and calls them mutually exclusive.

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 that uploadUrl is short-lived and single-PUT, the exact content type required, the SHA256 must be exact lowercase, the archive size window, and the auth restriction. These details materially shape correct invocation of a non-readOnly, non-idempotent operation.

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

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

Four dense sentences, front-loaded with the reservation action and followed by the exact call sequence. Every sentence carries needed operational detail, though the density of constraints makes it slightly heavier than an ideally lean definition.

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

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

For a multi-step upload-reservation tool with an output schema present, the description still explains the return values' purpose and the follow-up call, plus auth and content-type constraints. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 50%, with commandId documented in-schema and the nested body fields only named. The description compensates by humanizing archiveBytes as 1..128MiB and clarifying the lowercase hex SHA256 format, adding meaning beyond the raw pattern/max. It does not explain idempotencyKey semantics beyond naming it.

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

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

States a specific verb (Reserve) and resource (LOCAL portable CueFrame template package ZIP) targeted at the organization library, distinguishing it explicitly from import_template_package and media items. An agent can separate it from export_template_package and create_upload 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?

Lays out the full sequence: supply idempotencyKey/archiveSha256/archiveBytes, receive uploadId and uploadUrl, PUT raw bytes with Content-Type application/zip, then call import_template_package with uploadId. It also names the exclusion condition (project-bound editor credentials are refused) and clarifies a reservation is not an import.

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 (which only say it is a non-read-only, non-destructive, non-idempotent, closed-world write): it discloses that the tool returns a short-lived PUT URL with an expiry, the ~5 GB per-PUT ceiling, the required Content-Type declaration, and that processing is asynchronous afterwards. It also names the exact follow-up call (finalize_upload with mediaItemId) needed to actually trigger processing — critical, non-obvious 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?

Dense but front-loaded and ordered as a procedure: routing rule, then step 1, step 2, then async follow-up. The 'Body: filename, contentType, size' sentence partially restates the schema and is the only borderline 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 names the key returned fields ({ id, uploadUrl, expiresAt }), covers the out-of-band HTTPS PUT that no schema can express, and points to downstream consumers (get_media_context, suggest_briefs, composition source). Everything an agent needs to complete the workflow is present.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by stating that contentType is an allowed enum, that size is in bytes and bound by the ~5 GB PUT limit (matching the schema maximum), and that filename identifies the object. The optional projectId is never explained, which keeps this from 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?

Opens with a specific verb+resource ('Ingest a LOCAL file') and immediately scopes it against the sibling import_media, so an agent knows exactly what this does and what it is not. The two-step reserve/PUT+finalize flow is stated up front rather than buried.

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 selection rule: use this only when the bytes are local and there is no public URL; 'prefer import_media whenever the bytes already sit at an https URL'. It also tells the agent what to do after (finalize_upload, then poll list_media or create_webhook on media.completed), 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?

Goes far beyond the annotations: documents delivery payload shape, Standard-Webhooks headers, that the secret is returned once, the synchronous activation challenge with status:"pending" on failure, and non-idempotent-but-recoverable behavior. This is exactly the mutation-lifecycle context annotations don't carry.

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

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

Front-loaded with purpose and the wait_job contrast, and every clause carries operational substance. It is dense and runs long with stacked parentheticals, which slightly hurts scanability but little is wasted.

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

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

Covers the full contract an agent needs for a webhook-creation mutation: event set semantics, delivery format, secret handling, activation handshake, failure mode, and recovery path. Output schema exists, so return values are correctly not belabored.

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 description still adds meaning: it clarifies that events are one terminal event per job kind with status inside the payload, plus checkpoint.ready semantics. It does not explain settleMs, which the schema leaves undocumented, so not 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 ('Register a webhook') and immediately frames its role against the sibling wait_job. An agent can distinguish it from wait_job, verify_webhook, and update_webhook 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?

Explicitly says when to use it ('the right pattern for fan-out/async agents', 'instead of blocking on wait_job') and names the recovery alternative (verify_webhook, 'no delete/recreate'). It also directs the agent to read a resource before building the receiver.

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, idempotentHint=true, and readOnlyHint=false. The description adds meaningful behavioral context beyond annotations by explaining that compose jobs already run from the brief are unaffected because they snapshot. It does not cover permissions or return behavior, but the key side-effect nuance is disclosed.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the most relevant side-effect caveat. Every sentence earns its place with no redundancy.

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

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

For a simple two-parameter destructive tool with full annotation coverage and full schema coverage, the description is nearly complete. It explains the snapshot behavior of dependent compose jobs, which is the main non-obvious consequence. It could still mention irreversibility or authorization expectations, but annotations already flag destructiveness.

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 briefId and commandId are already documented in the schema. The description does not add syntax, format, or semantic detail for either parameter. Baseline 3 is appropriate when the schema fully carries parameter documentation.

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: 'Delete a brief.' That is clear and unambiguous. It does not explicitly differentiate this from sibling deletion tools such as delete_composition or delete_project, but the resource is named.

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 implies usage by naming the action and noting that previously run compose jobs are unaffected. However, it does not state when to use this tool versus update_brief, delete_composition, or other alternatives, nor does it describe prerequisites or when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description goes further by disclosing the cascade (version history is deleted), the 409 refusal condition, and remediation steps. Those are behavioral facts an agent cannot derive from the annotations.

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

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

Three short sentences, front-loaded with the destructive action and its blast radius before the refusal rule. No filler and no restatement of the title.

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

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

For a 3-parameter destructive tool with no output schema, the description covers what is destroyed, when the call will fail, and how to avoid that failure. 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 description coverage is 100%, so projectId, compositionId and the commandId retry-identity semantics are already documented in the schema. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a composition') and adds scope that a name alone cannot convey: the version history is destroyed too. That distinguishes it cleanly from delete_project, delete_brief and delete_media in the sibling list.

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

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

Explicitly names the exclusion — the ACTIVE composition is refused with 409 — and gives two concrete paths forward (activate another composition, or delete the project). It also routes the agent to list_compositions to determine active state before calling, which is exactly the pre-call check 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description earns credit for adding the downstream consequence — the critic stops firing in Director gates and score_composition immediately — which is real context beyond the structured fields, though it omits reversibility and behavior when the criticId does not exist.

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

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

Two sentences, no filler, with the identifier requirement front-loaded and the effect second. Every clause carries information.

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

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

For a two-parameter delete with full annotation coverage and no output schema, this covers the essential action and its consequence. It leaves open whether deletion is permanent, how to restore a critic, and what happens on an unknown criticId — minor gaps rather than blocking ones.

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%: criticId is documented as a path parameter and commandId explains its retry-identity semantics in full. The description adds no meaning beyond naming criticId, 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 ('Delete a registered critic') plus the identifier it acts on ('by its criticId'), which cleanly separates it from register_critic and list_critics among the 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?

The intended use (removing a critic you no longer want in the pipeline) is implied rather than stated. There is no mention of when not to use it, no alternative such as disabling or re-registering, and no prerequisite for obtaining a criticId.

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 and idempotentHint=true, so the safety profile is known; the description still adds real value with "Irreversible" and the downstream consequence that referencing compositions will fail to render. It does not clarify whether the call errors out when references exist or whether it silently succeeds, which is the one behavior an agent still needs.

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 sentences, all load-bearing: action, irreversibility, and consequence plus precondition. The destructive warning is front-loaded before the caveat.

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 tool with a fully documented 2-parameter schema and annotations covering safety, this covers the essential decision inputs: permanence and render breakage. The remaining gap is whether deletion is blocked or merely harmful when a composition still references the item.

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%, with mediaItemId documented and commandId carrying a full retry-semantics explanation, so the baseline is 3. The description adds no meaning about either parameter 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 ("Permanently delete a media item from your library") and scopes the intent as cleanup. An agent can distinguish it from siblings like delete_composition, delete_brief, or delete_project 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 a clear precondition for use: "only delete media no composition still needs," which functions as an explicit when-not rule. It stops short of naming alternatives (e.g., delete_composition for derived assets), but the usage context is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the lower bar applies; the description still adds the cascade targets (composition plus render history) and the ownership requirement, neither of which is in the annotations. It does not say whether active renders or jobs block deletion, which is the main remaining gap.

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

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

Three short sentences, front-loaded with the irreversible action and cascade scope before the safety caveat. No filler, and the destructive nature is stated immediately.

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 two-parameter tool with strong annotations and full schema coverage, the description supplies the cascade semantics and ownership precondition an agent needs before acting. Missing only the interaction with in-flight work (active renders or jobs) and whether deletion is blocked or forced.

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 commandId is documented as retry identity, so the schema carries the parameter burden. The description adds nothing about projectId format or how to obtain it, leaving this at 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+resource ('Permanently delete a project') with the cascade scope spelled out ('Removes its composition and render history'), which distinguishes it from sibling deleters such as delete_composition and delete_brief. The parenthetical '(cleanup)' further signals intent.

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 and gating condition: 'only call on a project you own and no longer need,' which prevents casual or speculative deletion. It stops short of naming a sibling alternative (e.g., update_project, or deleting only a composition), so it is clear context without full routing.

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 destructiveHint=true and idempotentHint=true; the description adds meaningful context beyond that by naming the irreversibility and the specific casualty (the signing secret is invalidated). It doesn't say whether delivery history is retained or what error occurs for a missing ID, so not a 5.

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

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

Two short sentences, zero filler, with the destructive consequence front-loaded right after the purpose statement.

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 destructive mutation whose safety profile is already covered by annotations, this is nearly sufficient. Minor gaps remain around post-deletion state (delivery history, secret invalidation side effects) but nothing blocks correct invocation.

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

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

Schema description coverage is 100% and the commandId retry semantics are documented in the schema itself. The description adds nothing about either parameter, 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 (delete a webhook subscription) and clarifies the effect with 'stop receiving its deliveries'. Siblings like create_webhook/update_webhook/verify_webhook are self-evidently different, but it never names them, so it falls just short of full differentiation.

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 parenthetical implies when you'd want this (to stop deliveries), but there is no explicit when-to-use guidance, no mention of alternatives such as updating/pausing a webhook, and no note on what happens for an unknown webhookId.

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 disclosing what actually happens internally (copies authored intent, content-aware reframes each clip with point/face/active-speaker focus) and what is created (a new independent composition, source preserved). Annotations already mark it as a non-read-only, non-destructive, non-idempotent write; the description supplies the missing 'what does it materialize' context. Minor gaps: it doesn't mention the commandId retry contract or any latency/async behavior for the reframing pass.

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

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

Front-loads the verb and resource in the first clause, then the call shape, then behavior, then the sibling-routing note — a good information ordering. The two trailing parentheticals are dense but both earn their place by preventing misuse; the sentence is slightly overpacked, with a dangling parenthetical after the comma.

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?

Output schema exists and the description still names the return ({ compositionId }) and routes to create_render/apply_composition for next steps. With annotations, full schema coverage, and an output schema all present, nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by spelling out the nesting shape inline (projectId + body { fromCompositionId, targetFormat: { aspectRatio, fps?, resolution? } }), which makes the optionality of fps/resolution readable before opening the schema. The if_match and commandId semantics are 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 (derive) and specific resource (a reframed SIBLING composition) with scope (different aspect ratio) and product terminology (Auto-Reframe / Magic-Resize). The word 'sibling' plus 'independent composition in the same project' distinguishes it from new_composition, create_render, and apply_composition without needing the 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 use case ('make 9:16 + 1:1 + 4:5 cuts from one 16:9 edit'), an explicit exclusion ('to only change resolution within the SAME aspect, pass create_render.format instead — that is a scale-only export override, not a new composition'), and names downstream alternatives (create_render, apply_composition). This is exactly the routing information an agent needs to pick between near-duplicate tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile needs no restating. The description earns credit by disclosing that the return payload differs by mode — a name/description list when type is omitted versus a JSON Schema for one op when supplied — which the annotations cannot convey.

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

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

Three short clauses, zero filler: purpose first, mode behavior second, call-site guidance last. Nothing could be removed without losing information.

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

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

With one optional parameter, full schema coverage, and no output schema, the description covers everything an agent needs: what the tool returns in each mode and when to invoke it. No output schema means return-shape disclosure falls to the description, and it delivers exactly that.

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 parameter's description already says 'Omit for the operation list', so the description largely restates schema content. It clarifies the consequence of each mode, which is mildly additive, but under the high-coverage rule 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 ('Discover the exact CompositionOp vocabulary') and ties it directly to the sibling that consumes it (apply_composition). An agent can immediately separate this discovery tool from apply_composition or validate_composition 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 an explicit trigger ('Read this before authoring edits or captions') and explains mode selection: omit type for the compact list, pass type for a single schema. It stops short of stating when not to call it or naming alternatives beyond apply_composition, so it is strong but not exhaustive.

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/closed-world, so the safety profile is covered. The description adds the non-obvious mechanism: this tool exists because the tool list abbreviates schemas, and it resolves one field at a time. It doesn't say what a failure looks like for an unknown tool/field.

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 sentences, front-loaded with the return value and followed by the reason and the call instructions. Nothing redundant for a meta-tool of this scope.

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 does cover what is returned (the exact JSON Schema for the field). The only gap is error behavior for unknown tool/field names, which is minor for an idempotent read-only resolver.

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 both parameters carry their own descriptions with examples (validate_composition, tracks). The description's 'pass that tool and field' adds no syntax or constraints beyond what the schema already documents, 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: return the exact JSON Schema for an abbreviated body field. No sibling tool does anything similar, and the description makes the abbreviation-expansion role unmistakable.

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 clear trigger condition — an abbreviated field names this tool in its description — and says what to pass (that tool and field). It doesn't state what to do if the field is not actually abbreviated or what happens on a wrong tool/field pair, but the positive routing rule is explicit.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses that the URL requires no auth header, expires at expiresAt in about an hour, must be re-fetched rather than cached, is free with nothing persisted, and works as soon as the upload/import is stored before processing completes. These are non-obvious operational facts an agent would otherwise get wrong.

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

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

Front-loads the core definition, then usage, then behavioral caveats, with every sentence carrying information. It is dense but slightly long; the parenthetical about 'raw upload or conformed transcode' and the 'read-only and free' clause could be trimmed since annotations already imply safety.

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 no explanation, and the description still flags the expiresAt field the agent will encounter. For a two-parameter read tool, the expiry, auth, and sibling-routing information covers everything needed to invoke it correctly.

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

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

Schema coverage is only 50%, so the description must compensate — and it partly does, clarifying that mediaItemId selects the media item whose source file is returned and tying the result to expiresAt. However, projectId is never mentioned in either the schema or the description, leaving one of two parameters undocumented.

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 (presigned download URL for a media item) and narrows it precisely to the stored SOURCE file, explicitly contrasting it with a render's MP4. An agent can distinguish it from refresh_render_url and list_media 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-to-use context ('this is how you copy media OUT of a library'), names the concrete downstream flows (fetch and PUT with create_upload, or import_media on another account), and names the alternative for a different case ('For a render's MP4 use refresh_render_url instead'). 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?

Annotations already declare the tool is mutating, non-read-only, non-destructive, and not idempotent. The description adds important behavioral context about concurrency guards, revision basis, journal identity, and the distinction between session command identity and HTTP request identity.

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 commit action and uses only three dense sentences. Each sentence carries useful identity or concurrency information, though the phrase 'guarded composition fields' is slightly vague.

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 nested mutation with no output schema, the description supplies the key concurrency and identity constraints needed to call it correctly. It does not fully explain the composition operations or sibling routing, but annotations cover safety and the schema covers required fields.

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 67%, and the nested composition schema is only a pointer to describe_tool_input. The description compensates by explaining the critical relationship composition.commandId = composition.clientId + ':' + composition.sequence and by distinguishing the top-level commandId as a separate request identity.

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: committing an integrated editorial edit to a saved project composition. It is clearly not a read or listing tool, but it does not explicitly differentiate itself from the similar sibling apply_composition.

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

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

The description gives no explicit when-to-use guidance, prerequisites, or alternatives. It implies this is a commit step after editorial integration, but never says when to choose it over apply_composition or related editorial tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that the call persists data and yields a briefId; it says nothing about retry semantics (the commandId behavior lives only in the schema) or what happens when a brief already exists for the project.

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

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

Two tight sentences with zero filler: the action comes first, then the parameter-placement hint, then the return-value handoff. Nothing could be removed without losing information.

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

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

There is no output schema, and the description does at least name the returned briefId, which is the key detail. For a nested-object write tool, though, it omits the required `goal` field, validation/failure behavior, and any distinction from the non-editorial brief tools, leaving the agent to call describe_tool_input to proceed 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 description coverage is 50% and the nested `brief` object's own description just redirects to describe_tool_input, so the note that "the projectId belongs in body.brief" genuinely resolves a real nesting ambiguity. However, the other required brief field (goal) and commandId's retry semantics are left entirely to the schema, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource: "Persist an authored brief for the selected project." That is clear, but it does not differentiate this from the sibling `create_brief`, and an agent has no way to tell which one to reach for without guessing at the "editorial" prefix.

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 second sentence implies a downstream workflow ("use the returned briefId to start an editorial run"), which hints at sequencing, but there is no explicit when-to-use vs `create_brief`/`update_brief`, and no stated preconditions beyond needing a 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 this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds a genuine guardrail ('never invent a source pin or infer inspection from an index'), but says nothing about the side effect of creating a run, what allowanceUsdMicros spends, or how the run behaves on retry. The commandId retry semantics live in the schema, not the description.

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 sentences, front-loaded with the action and scope, then the prerequisite, then the prohibition. No repetition of the title or annotations. The final sentence is slightly cryptic ('infer inspection from an index') but is not padding.

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, nested-object tool with no output schema, the description covers source-pin fidelity but omits what a successful call returns (run id/handle), what 'certified' means, and how budget allowance is enforced. An agent could call it, but would need to probe siblings to know what to do with the result.

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

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

Schema description coverage is 50% and the description compensates for part of it by naming the fields required in a source pin (identity, revision, frame count, fps ratio). It says nothing about briefId, outline, or allowanceUsdMicros, and the nested inputs/outline schemas are deferred to describe_tool_input. Marginal value over the structured fields, so baseline 3.

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 editorial run from a persisted brief and explicitly selected certified source ranges.' That clearly separates it from read-side siblings like editorial_get_run and editorial_list_runs. It does not name a sibling alternative it might be confused with (editorial_apply / editorial_integrate), so it stops short of a 5.

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

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

Gives an explicit prerequisite workflow: 'Read editorial_run_source for each project media source first; use its exact identity, revision, frame count and fps ratio.' That tells the agent what must happen before calling. It gives no exclusion condition or alternative path for when a run should not be started.

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 disclose the write/non-destructive/non-idempotent safety profile, so the description's main added value is the evidence-coverage caveat: nothing_useful may only cover inspected evidence and sparse stills do not certify unsampled intervals. That is useful domain behavior beyond annotations, though it does not cover return behavior.

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

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

Two compact sentences with the core action front-loaded and a relevant caveat second. Every sentence earns its place.

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

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

The nested schema and examples supply most structural detail, and annotations cover the safety profile. Still, with no output schema, the description does not explain what append returns or how findings relate to the run and evidence beyond the one outcome caveat.

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 67%, with top-level descriptions for runId and commandId and a detailed nested body schema with examples. The description adds meaning to outcome/evidenceIds via the evidence-backed and nothing_useful caveat, but leaves range, timebase, and other nested fields 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: "Persist one evidence-backed observation." It is clear this appends a finding, but it does not explicitly differentiate from siblings like editorial_findings_list or editorial_integrate.

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 second sentence gives a rule for when a nothing_useful outcome is valid, which implies usage after inspecting cited evidence. However, it does not state when to use this instead of alternatives or mention prerequisites such as existing evidence/run.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing pagination behavior and a response field ('nextCursor') that has no output schema, plus a warning to retain evidence IDs, supersession and uncertainty when recovering decisions. It does not state ordering, page size behavior, or what an empty page means.

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

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

Two sentences, front-loaded with the read operation and then the pagination/retention instructions; nothing is obviously redundant. It is somewhat dense with internal jargon, but the information per sentence is high.

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, three-parameter paged list with no output schema, the description covers pagination and key result concepts (evidence IDs, supersession, uncertainty) but omits the run scoping, limit semantics, and ordering. An agent can call it, but must infer what defines the result set.

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 only 33%: runId is documented merely as 'runId (path)' and limit/cursor are undocumented in the schema. The description partially compensates by explaining cursor semantics ('pass nextCursor as cursor until done'), but it says nothing about the runId scoping requirement or the limit bounds (1-100).

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 says it reads 'durable observations ... in bounded pages', which conveys a list/read operation but substitutes jargon ('observations', 'useful/nothing-useful/uncertain outcomes') for the resource name 'findings', and never states that results are scoped to a run. It gives no differentiation from close siblings such as editorial_list_evidence, editorial_get_run, or editorial_findings_append.

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 pagination instruction ('Pass nextCursor as cursor until done') is a concrete procedural usage cue, which is more than most list tools offer. However, there is no guidance on when to choose this tool over editorial_list_evidence or editorial_get_run, and no stated preconditions or exclusions.

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 and non-destructive, so safety is covered. The description adds real value by disclosing the exact payload shape and, importantly, what is excluded (findings and evidence), which prevents an agent from assuming full coverage.

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

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

Two sentences, no filler, and the returned-contents list is front-loaded before the caveat about separate findings/evidence reads. Every clause earns its place.

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

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

With no output schema, the description must convey return values, and it does so by enumerating the run's fields plus the notable omissions. It falls short only on failure behavior (missing/unknown runId) and identifier format.

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

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

Schema coverage is 100% and there is a single required parameter, so the schema carries the burden. The description adds nothing about runId format, whether it is a UUID versus a path-like identifier, or behavior when the run does not exist — 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 ('Read') and resource ('a persisted editorial run') and enumerates the contents returned (revision, state, inputs, outline, selected finding IDs, omitted reasons, integration gaps). It implicitly distinguishes itself from editorial_list_runs and from the findings/evidence readers, though it never names those siblings directly.

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

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

The second sentence ('Read findings and evidence separately for complete coverage') signals that this tool is partial and that other tools fill the gap, which is useful routing. However, it never names editorial_findings_list or editorial_list_evidence, nor does it say when to prefer this over editorial_list_runs or editorial_apply.

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 indicate this is a non-destructive, non-read-only operation, and the description correctly adds that it saves an audio evidence receipt. However, it does not explain what is persisted, whether the receipt is durable, permission requirements, or failure behavior beyond the certified-run constraint.

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

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

Two tightly written sentences with no waste. The core action is front-loaded, and the certified-run constraint follows immediately.

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?

This is a complex nested mutation with no output schema and only two sentences of description. It leaves critical gaps around what a certified run input is, how the saved evidence receipt is returned or identified, and how the nested range parameters interact.

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 67%, so the description should compensate for undocumented nested fields such as frames, timebaseNum, timebaseDen, mediaId, and representationIdentity. It adds only the vague constraint that the interval must lie inside a certified run input and does not explain the parameters' roles or format.

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

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

The description gives a specific verb-and-resource: deliver a bounded 16 kHz source audio interval and save an audio evidence receipt. It is clear what the tool does, though it does not explicitly distinguish itself from sibling inspection tools such as editorial_inspect_source or editorial_inspect_transcript.

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 only usage context is the precondition that the interval must lie inside a certified run input. There is no guidance on when to choose this tool over editorial_inspect_source, editorial_inspect_transcript, or editorial_sample_motion, and no exclusions or workflow context.

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 readOnly=false and destructive=false, and the description adds useful behavioral context: it saves an evidence receipt, returns a JPEG, inspects only that sampled frame, and says to preserve the returned evidenceId and coverage. It does not explain retry/idempotency behavior, though the schema's commandId description does.

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 two tight sentences with no wasted wording. The core action is front-loaded, followed by the scoping constraint and the evidence fields to preserve.

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

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

There is no output schema, so the description must carry some return-value information; it names the JPEG artifact and the returned evidenceId and coverage. It still does not describe the full response shape or receipt format, but it covers the essential behavior for invoking the tool.

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

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

Schema description coverage is 67%, with runId and top-level commandId partially documented and an example for the nested body. The description adds that a single exact decoded frame is involved, loosely mapping to the frame parameter, but it does not explain mediaId, the body-level commandId, or frame indexing beyond 'one exact sampled frame'.

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

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

The description gives a specific verb and resource: deliver one exact decoded source frame as JPEG and save its evidence receipt. That is clear on its own, but it does not explicitly differentiate this tool from nearby siblings such as preview_frame, compare_frames, editorial_sample_motion, or editorial_inspect_audio/transcript.

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?

There is no explicit guidance on when to use this tool versus alternatives in the large sibling set. The statement that only the sampled frame is visually inspected implies a narrow scope, but it does not tell the agent when this tool is the right choice over preview_frame, compare_frames, or editorial_sample_motion.

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

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

With readOnlyHint=false and destructiveHint=false, the annotations already flag this as a non-destructive but state-changing operation, and the description usefully confirms that by naming the receipt that gets written. The 100-word cap is a genuine disclosure not present in any structured field. It stops short of explaining what the 'certified decode interval' is, what happens if the word span exceeds 100 words, or how the commandId retry semantics interact with 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?

A single sentence with no filler, front-loading the deliverable before the side effect. It is dense with domain jargon but structurally efficient rather than padded.

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?

This is a state-mutating tool taking a nested range/wordSpan body with no output schema to explain the result, and the description leaves the return shape, the meaning of 'certified decode interval', and the range-identity requirements unspecified. For a nested-object mutation with only 67% schema coverage, more disclosure is needed to call it correctly.

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

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

Schema coverage is 67% and the gaps are exactly the ones that matter: body.wordSpan's [start, exclusive-end] semantics, the frames/timebase/representationIdentity bundle for range, and what runId must refer to. The description only echoes the word cap and says nothing about any of these three parameters, so it fails to compensate for the coverage shortfall.

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

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

The description gives a concrete verb and resource ('Deliver ... verified transcript words with their mapped certified decode interval') plus a side effect ('save a transcript evidence receipt'), so the agent knows roughly what comes out. It does not distinguish this from adjacent siblings like get_transcript or editorial_inspect_audio, so an agent cannot tell from the description alone why it would pick this over those.

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?

There is no when-to-use, when-not-to-use, or prerequisite guidance. Nothing says whether a run must already exist (the required runId implies it, but that is inference), nor when to prefer this over get_transcript or editorial_inspect_audio. Usage must be guessed entirely from the name and siblings.

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

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

Annotations already declare not read-only, not idempotent, not destructive. The description adds the useful detail that a revision is 'observed' (optimistic concurrency against expectedRevision), but it doesn't say what happens on a revision mismatch, whether the save is rejected or overwrites, or what state results.

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

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

Two short sentences with the payload contents front-loaded before the prerequisite. No wasted clauses, though the second sentence reads as an instruction rather than definitional content.

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

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

For a nested, multi-object mutation with no output schema and only partial schema coverage, the description leaves the response shape, revision-conflict behavior and the role of compositionId/transitionIntent unstated. Adequate to attempt a call, not to predict its outcome.

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 67% and the description maps its prose onto selectedFindingIds, omittedReasons, unresolvedGaps and the observed revision, which helps. However compositionId, compositionVersion and transitionIntent are documented nowhere, and the body/runId duplication is unexplained.

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

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

States a specific verb (save) and enumerates the resources being persisted: selected finding IDs, omitted reasons, unresolved gaps, tied to an observed run revision. That is distinguishable from editorial_findings_append and editorial_apply, though it never explicitly names those siblings.

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

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

'Read the run and findings before deciding' gives a prerequisite ordering, which implies the editorial workflow, but it never says when to pick this over editorial_apply or editorial_findings_append, nor what conditions make integration appropriate.

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, closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the bounded-page pagination model and that brief IDs link to editorial runs. It stops short of saying what a brief record contains or what happens at the end of the cursor chain.

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 sentences, zero filler, with the core purpose front-loaded and the pagination mechanic immediately after. Every sentence carries information an agent needs.

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

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

For a three-parameter read-only list tool with no output schema, the description covers purpose and pagination adequately, and 'Brief IDs link to editorial runs' hints at the return shape. It remains incomplete on the required projectId parameter and on how this list differs from the generic list_briefs sibling.

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

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

Schema description coverage is 0%, so the description carries the burden. It does explain cursor semantics ('pass nextCursor as cursor') and gestures at limit ('bounded pages'), which is meaningful compensation, but projectId — the only required parameter — is never explained, and no defaults or bounds are given for limit.

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 — 'Recover persisted authored briefs for a project' — which is more concrete than a bare 'list'. It does not, however, explicitly distinguish itself from sibling list_briefs or suggest_briefs, so the agent must infer that 'editorial' scoping is the differentiator.

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

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

Provides procedural guidance for pagination ('pass nextCursor as cursor until done'), which is genuinely useful. But it never says when to choose this over list_briefs or editorial_list_runs, and states no prerequisites or exclusions.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral caveat that annotations cannot express: an empty page does not mean the source was fully inspected, which prevents premature conclusion. It stops short of describing ordering or page-size 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?

Two tight sentences with the core action first and the pagination caveat second. No filler and nothing redundant with the schema.

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

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

With no output schema, the description partially compensates by naming nextCursor, but it does not describe what an evidence record or coverage entry contains, nor any ordering. Adequate for calling the tool, thin for interpreting 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 only 33% and the single documented parameter ('runId (path)') is essentially a restatement. The description does add real meaning for cursor by tying it to a 'nextCursor' value and implying bounded page sizes, but 'limit' and its 1-100 range are never explained in prose.

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 (Read) and resource (delivered evidence and inspection coverage) scoped to a run, and adds the bounded-paging qualifier. It is reasonably distinguishable from editorial_findings_list and editorial_get_run, though it does not name those siblings directly.

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

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

The description gives operational guidance for pagination ('Pass nextCursor as cursor until done') and a caveat about empty pages. However, it never says when to prefer this over editorial_findings_list, editorial_get_run, or editorial_inspect_source, so tool 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?

Annotations already declare safety (readOnly, idempotent, non-destructive, closed-world), and the description adds useful behavioral context: results are persisted, pagination is bounded, and cursor iteration continues until done. It does not contradict annotations and clarifies the follow-up reading pattern, though it does not describe return shape.

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

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

The description is two sentences, front-loaded with the core operation and pagination instruction, followed by the natural next step. Every sentence carries actionable meaning with no filler.

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

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

For a paginated read tool with no output schema and three parameters, the description covers pagination mechanics and the subsequent read action needed to get integration decisions and unresolved gaps. It stops short of describing the list items' fields, but that is reasonable given the instruction to read individual runs for details.

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 0% schema description coverage, the description compensates well for cursor by explaining that nextCursor should be passed as cursor until done, and it implies project scoping and bounded pages. It does not explicitly name the limit parameter or clarify its maximum (the schema already declares maximum 20), so the coverage is strong but not complete.

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

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

The description clearly states a specific verb and resource: recovering persisted editorial runs for a project in bounded pages. It distinguishes itself from a single-run read via the follow-up instruction to 'read each relevant run' afterward, though it does not explicitly name the sibling tool for that follow-up.

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 provides concrete pagination guidance: pass nextCursor as cursor until done, then inspect each relevant run for decisions and gaps. This is clear procedural context, but it does not state when to prefer this tool over alternatives such as editorial_list_briefs or editorial_get_run.

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 genuine behavior beyond that: a null representation signals the source cannot be pinned, the response omits internal storage paths, and it returns frameCount and an exact fps ratio. That tells the agent what to expect on failure and what data comes back, which annotations alone would not.

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

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

Three tight sentences, front-loaded with the action and precondition, followed by output semantics and a guardrail. Dense jargon ('certified decode representation', 'pinned') costs a point but nothing is wasted or 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 with no output schema, the description covers purpose, precondition, failure signal, and what the response surfaces (frameCount, fps). Only the provenance of the identifiers and how this differs from the inspect_* siblings are 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 0% for both required parameters, so the description must carry the load. It names projectId and mediaId and implies mediaId must belong to the given project, but does not say where those identifiers come from (e.g., list_media/list_projects) or what form they take; the guidance is only partially compensating.

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?

A specific verb ('Read') and resource ('certified decode representation for media selected in this project') make the intent clear, and the phrase 'before starting an editorial run' anchors it to the editorial workflow. It does not differentiate itself from close siblings such as editorial_inspect_source or editorial_inspect_audio, which an agent could easily confuse with this 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?

The first sentence gives a clear timing precondition ('before starting an editorial run'), and 'do not invent a source identity' is an explicit negative instruction telling the agent to derive values rather than guess. There are no named alternatives or exclusions, so a 4 is the correct ceiling.

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 safety profile (non-destructive, non-open-world, non-read-only), and the description adds two things beyond that: the call persists an evidence receipt as a side effect, and the returned frames do not certify continuous coverage. That coverage caveat is genuinely non-obvious and prevents an agent from over-claiming completeness of a visual inspection.

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

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

Two tight sentences, front-loaded with the action and followed by a distinct caveat that earns its own sentence. Nothing is wasted, though the whole description is thin for a tool with a six-field nested body and a persistence side effect.

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

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

There is no output schema, so the description must describe what comes back, and it does not: no indication whether the result is frame data, a receipt identifier, or both, and no pointer to how the saved receipt is later retrieved (e.g. editorial_list_evidence). For a tool that writes state and has a nested object parameter, this leaves the agent guessing on the return and follow-up path.

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 67% and the description adds essentially no parameter meaning beyond the word 'bounded', which loosely maps to the two-frame cap enforced structurally. The nested body object (mediaId, representationIdentity/Revision, timebaseNum/Den) carries only structural constraints with an example, and runId is documented as 'runId (path).' only, so the hardest parameters are left to the token names.

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 specific verbs and resources: it samples motion frames over a bounded range and persists an evidence receipt. That is materially more informative than the title alone. However, it does not distinguish this from nearby frame-inspection siblings such as preview_frame, compare_frames, or editorial_inspect_source, so the agent cannot tell from the description alone which one to reach for.

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

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

There is no when-to-use guidance, no exclusions, and no named alternative among the many sibling tools. The second sentence is a scope caveat about the accuracy of the output, not a usage condition. An agent must infer entirely from the name when this is the right call versus compare_frames or preview_frame.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it discloses that the operation is durable/asynchronous, requires expectedRevision concurrency control, surfaces slug conflicts as errors, and enforces editor scoping. It also clarifies that data is read via the maintained extractor rather than from caller input, which is exactly the kind of behavior an agent cannot infer from the schema.

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

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

Front-loaded with the core action and inputs, then workflow, then constraints — no filler sentences. Some clauses are dense and run long (the mediaParams/textParams sentence), but every sentence carries operational information.

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

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

For a nested-body mutation with an output schema, the description covers the async job lifecycle, the downstream retrieval step, conflict behavior, and authorization scoping. An agent can complete the full export flow without consulting anything else except the schema for field shapes.

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 67% schema coverage, the description still adds real meaning: expectedRevision is framed as a revision guard, mediaParams/textParams are "optional bounded ... selectors for existing clip/leaf sites" (max 128), and slug conflicts are called out. The role enum (project-template vs component-package) and the commandId retry parameter are left to the schema, so it does not fully cover the surface.

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

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

"Export an exact SAVED project snapshot as a portable template package" states a specific verb and resource plus the source of truth (saved composition, not caller-supplied documents). It is clearly separable from siblings such as import_template_package, create_template_package_upload, and get_template_package_download.

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

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

The description gives the full call chain: submit, poll get_template_job until ready, then pass receiptId to get_template_package_download. It also states exclusions ("Does not render or create a new project") and preconditions (existing slug conflicts; a project-bound editor may export only its bound 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?

Adds substantial context beyond annotations: async job semantics, the 20s timeout, SSRF/private-URL blocking, non-2xx and non-HTML handling, and the crucial non-obvious behavior that all these degrade to empty token arrays on a *succeeded* job rather than an error. That failure mode is exactly what an agent would otherwise misread as success with real data. Consistent with readOnlyHint=false (a job record is queued) and idempotentHint=true.

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 ASYNC warning, and every clause carries load-bearing information (job polling, no-persistence, degradation behavior). The long em-dash-and-parenthetical sentences are dense but not padded; slightly heavier parsing than necessary.

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?

Output schema exists so return shape needn't be explained, yet the description still tells the agent the immediate return is a jobId. Combined with the async polling instruction and the empty-tokens caveat, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so both url and commandId (including retry-replay semantics) are already documented in the schema. The description adds the nature of the URL (a website to parse, not an asset) but says nothing about commandId, so it adds only marginal meaning over the structured fields. Baseline 3.

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 ('Queue brand-token extraction from a website URL') and pins the exact scope: HTML/CSS regex parsing of colors/fonts/title/description, explicitly 'NOT a screenshot/vision pass'. It also distinguishes itself from the nearest sibling by name, noting it does not persist and that create_brand_kit does.

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

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

Gives the full workflow: call this, then wait_job(kind="brand_kit_extract", id=jobId), then create_brand_kit to persist. It also names the when-not case ('JS-rendered SPAs typically extract empty; author the kit manually from the compiled CSS').

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 context annotations cannot carry: image/asset complete immediately vs audio/video entering 'processing', the returned fields, the 400 conditions, and ownership checks. The idempotency-via-commandId note clarifies the opt-in retry semantics rather than contradicting 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-loads the action and precondition in the first sentence, then layers outcomes, return shape, errors, and next steps in a logical order with no redundant restatement of the name or 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?

Even though an output schema exists, the description briefly states the return shape and, more importantly, tells the agent exactly what to do next and what errors to expect — everything needed to invoke this correctly in the upload lifecycle.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references mediaItemId only implicitly through the wait_job example and does not mention audioRole or commandId, so it adds little 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 ('Finalize a direct upload') and explicitly anchors it to the two-step flow with create_upload, so it is clearly distinguishable from siblings like create_upload, import_media, and prepare_media.

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

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

Gives explicit preconditions (after PUTting bytes to the uploadUrl from create_upload), explains the failure mode when that has not happened (400), and names the follow-up paths: wait_job(kind="media", id=mediaItemId) or a media.completed webhook.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds useful framing (org-scoped, an undo of a learned preference, so low blast radius), but says nothing about what happens with an unknown or already-deleted id, or whether the removal is permanent versus soft.

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

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

Two short sentences, zero padding, with the core action and id source front-loaded and the undo framing used as a closing hook 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 two-parameter, single-required delete with full annotation coverage and no output schema, the description supplies what an agent needs: what it deletes, how to obtain the id, and why a user would invoke it. Only edge-case behavior (missing id, repeat with a different commandId) is left to the schema and annotations.

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 commandId's retry semantics are documented in the schema, so the baseline is 3. The description earns a step up by documenting the provenance of tasteId (get_profile `taste` or remember_taste), which the schema does not say.

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 cardinality ('Delete one entry'), the exact resource ('the org's learned taste'), and the keying parameter ('by its id'). It also implicitly distinguishes itself from remember_taste and list_taste by naming where the id comes from, so an agent can separate 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 the trigger context explicitly: 'This is how the user's "undo" works,' which tells the agent when to reach for it, and points to get_profile `taste` / remember_taste as the id source. It stops short of naming an alternative or a when-not condition, but the use case is unambiguous.

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

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

With annotations silent on cost and async semantics, the description carries that load well: it discloses the return shape ({ id, status:"generating", estimateUsd? }), the 402 behavior when the estimate exceeds the per-call ceiling, and that the operation is async with two completion paths. It also tells the agent the returned id is a normal media item id, which prevents follow-on misuse.

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?

Five short sentences, front-loaded with the verb and generator list, then effects, then async guidance. No filler; even the return-shape parenthetical is compressed to a single fragment.

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 nested-schema, async, paid generation tool, the description covers selection, input placement, error condition, return shape, and both completion mechanisms. An output schema exists, so restating the payload is optional and the description already does the essential part.

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 routing value for the nested objects: style holds presentation controls and refs holds first/last/image references. It omits any mention of commandId, the retry-identity parameter, which is a meaningful gap for a non-idempotent generation call.

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

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

States a specific verb and resource ('Generate one first-class Library media item from a prompt') and immediately enumerates the seven mutually exclusive generator modes, so the agent knows exactly what the tool produces. It is clearly distinguishable from siblings like import_media, prepare_media, and compose.

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

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

Gives concrete routing: pick a generator, place presentation controls in body.style and references in body.refs, then handle the async result via wait_job(kind="media", id=mediaItemId) or a media.completed webhook. It does not explicitly say when NOT to use this versus alternatives such as import_media or preview_clip, which keeps it from a 5.

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

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

Annotations only declare readOnly/idempotent/non-destructive; the description adds the entire funding model (one shared credit wallet via `fundedBy`, per-feature balances as alternative views of the same money), the `listUsdPerUnit` quoting semantics including 0 and null cases, and specific error behavior (billing_required with reason free_generation_cap). It also discloses that free accounts start with a grant and can still spend, which is exactly the kind of non-obvious trait 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?

The action directive is correctly front-loaded, but the middle is a dense wall of field-level documentation for `balance`, `included`, `fundedBy`, `creditCost`, `listUsdPerUnit`, and `costCeilings` that largely duplicates the output schema. Several sentences (e.g. the full enumeration of which features spend the shared wallet) could be compressed without losing the decision rule.

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

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

Given an output schema exists, the definition is more than complete — it covers funding semantics, error reasons, free-tier caveats, and the per-call cap name. The only shortfall is that it pours return-value documentation into the description rather than letting the output schema carry it, which is a completeness-by-volume rather than completeness-by-gap.

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?

Zero parameters, so the baseline is 4; it earns a 5 by explicitly stating 'No args — identity is resolved from your key (never echoed from input)', which prevents an agent from inventing an account_id argument. That is meaningful semantics for an otherwise empty 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 opening clause names a specific verb and resource ('show THIS key's account') and enumerates exactly what is returned: bound org, current plan, entitlements map, cost ceilings. It is clearly distinguishable from get_usage and list_plans, which sit alongside it as 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?

It gives an explicit ordering rule ('ORIENT FIRST ... before you spend a metered call') plus a concrete read rule ('READ `balance`, NOT `included`') and an explicit pre-call check pattern against cost. The agent is told not just when to call it but what to do with the result before calling metered siblings like generate_media or compose.

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