CueFrame

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

With annotations declaring only the safety profile, the description carries the rest: transactionality, dry_run validation, if_match/409 stale_etag semantics, unsupported_concurrency refusal, brand-change refusal, caption regeneration requirements after timeline edits, and the warnings[] return signal. This is far richer behavioral context than the annotations provide. (Minor tension: the ops include clip.remove/removeTrack deletions while destructiveHint is false, but the edits are described as undoable, so this is not a hard 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?

The core purpose is front-loaded, but the body is an unstructured wall that sprawls through captions, cards and scene shots in a single block. Substantial portions (SCENE SHOTS schema, CARDS var() mechanics, caption op variants) restate what the nested op and scene schemas already document in full, so many sentences do not earn their place at the tool-description level.

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 partially compensates by disclosing return signals (warnings[], dry_run returns {valid, errors}) and the failure modes (stale_etag, unsupported_concurrency, brand refusal, caption errors). It does not describe the success response shape or the resulting etag, which a mutation of this complexity would ideally include.

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, but the description adds operational meaning: composition_id vs session_id mutual exclusivity and the A/B authoring workflow, if_match's OCC role, dry_run's behavior, and the concurrency envelope's endpoint requirement. These semantics go beyond field definitions, though many are also restated in the schema descriptions.

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

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

The opening states a specific verb and resource ('Atomically apply an array of CompositionOps to a project composition') plus the transactional contract ('All ops succeed or none do'). It distinguishes itself from siblings by pointing at describe_composition_ops for the op list and get_composition for reading, so an agent can place it without opening any schema.

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

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

It gives explicit when-to-use guidance ('seed a composition' vs 'make targeted edits'), names the alternative sources (describe_composition_ops, get_composition), and states prerequisites and contingencies (componentExecutionVersions negotiation, brand refusal, guarded concurrency requiring an enforcing endpoint). Exclusions and alternatives are covered in detail.

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?

Despite annotations already declaring the non-idempotent, non-destructive write profile, the description adds substantial context: it preserves existing timeline content and package source offsets, refuses missing required media, never selects samples implicitly, and refuses (rather than silently refreshing) on stale revision/pin/brand. These are exactly the operational behaviors an agent needs before mutating a 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?

It is front-loaded with purpose, then parameters, then refusal semantics, and most sentences carry real information. The closing line ("For ordinary templates, this operation retains its existing apply behavior") is vague filler and the prose is dense/choppy, keeping it from a 5.

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

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

An output schema exists so return values needn't be explained, and the description covers prerequisites, the parameter contract, and failure modes — a lot for a complex nested tool. It still leans on undefined references ("the contract", "the witness"), leaving minor ambiguity about the revision/pin protocol.

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% and the body is a deep nested object, so the description must compensate. It does: it explains that template is the selected builtin id, enumerates body fields (projectId, documentSha256, insert:{startTime,idPrefix}, values, media bindings), and clarifies the media convention media:{slot:{sample:true}} vs real media IDs.

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

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

The description opens with a specific verb and resource: "Insert a resolved builtin component package into an existing project." This is far more precise than the name alone and implicitly separates it from apply_composition and start_template. It stops short of naming a sibling explicitly, so it lands at 4 rather than 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?

It gives a clear precondition — "Read get_composition first and retain expectedRevision, commandId, componentExecutionVersions:[3,4] and expectedBrandIdentity" — which tells the agent how to prepare the call. However, it never states when to prefer this over apply_composition/start_template or when not to use it, so it lacks explicit 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?

Goes well beyond the annotations by disclosing side effects: the cancel is confirmed before the row flips, any linked charge is released, and a terminal job yields a 422 no-op-reject. The 422-on-terminal behavior sits consistently with idempotentHint=true (no state change on repeat). Auth/permission requirements and the response shape are still unspecified.

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 with no filler; the action and scope come first, then prerequisites, then side effects and error semantics. Every clause carries decision-relevant 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-param mutation with no output schema, it covers prerequisites, side effects, and failure semantics adequately. It omits permission/precondition requirements and confirms only implicitly that no data is destroyed.

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%, but the schema descriptions are near-empty ('projectId (path).'), so the description carries real weight by naming both required params and telling the agent that composeJobId originates from the compose tool. It adds no format or validity detail beyond that.

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

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

Starts with a specific verb+resource ('Cancel an in-flight compose job') and immediately disambiguates it from the cluster of cancel_* siblings with the parenthetical use case 'stop a runaway/mis-priced ensemble'. An agent can distinguish it from cancel_job, cancel_render and cancel_export 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?

States the trigger context ('runaway/mis-priced ensemble') and where the required ids come from ('from compose'), which is real routing guidance. It stops short of explicitly naming the alternative cancel tools for other job types, so an agent must infer that renders/exports go elsewhere.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description earns credit for adding the 422 no-op-reject on terminal exports and the source of the exportId. It could say more about what happens to partial output artifacts or whether the cancel is reversible, but the error semantics are a genuine addition.

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, front-loaded with the action and scope, followed by required inputs and then the failure mode. No filler, 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 2-param mutation with no output schema but full annotations, the description covers scope, prerequisites, and the terminal-state error. Minor gaps remain around post-cancel state or partial-artifact cleanup, but 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 description coverage is 100% and both parameters are documented as path params, so the baseline is 3. The description adds only the provenance hint ('from the export enqueue'); no format or validation detail beyond the schema.

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

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

States a specific verb (cancel) plus a precisely bounded resource: an in-flight NLE export limited to fcpxml/premiere. The parenthetical scoping distinguishes it from the cluster of nearby cancel_* siblings (cancel_compose, cancel_render, cancel_job) well enough for an agent to pick correctly.

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 prerequisites (projectId + exportId, with exportId sourced 'from the export enqueue') and a state condition ('in-flight', 422 if already terminal), which tells the agent when the call is valid. It stops short of explicitly contrasting itself with cancel_render/cancel_compose/cancel_job, so the alternative-selection guidance is inferential 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?

Adds meaningful behavior beyond annotations: the 422 no-op-reject on already-terminal jobs, best-effort box reaping, and 'cancel never meters' (no billing impact). This is rich context that isn't derivable from the annotations. Annotations already cover idempotency and non-destructiveness.

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 dense sentences, front-loaded with the core action and scope. The parenthetical job-type list and the TTL/metering details are useful, though the sentence is somewhat packed. 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 single-param mutation tool with no output schema, the description covers the why, the scope, the billing behavior, and the terminal-state edge case. It omits auth/permission requirements and the response shape, but is largely complete.

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

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

Schema coverage is 100% (jobId is documented). The description adds that the jobId is the one 'returned by an enqueue call', giving provenance, but no format details. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb+resource ('Cancel a running async job') and enumerates the job types it applies to (verify / preview / brand-kit-extract). It distinguishes itself from siblings like cancel_compose/cancel_render/cancel_export by targeting the generic async job returned from an enqueue call, and from wait_job.

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 motivating scenario ('abort a mis-priced job instead of waiting out its TTL'), which implicitly contrasts with wait_job. However it doesn't explicitly name wait_job as the alternative or state when not to cancel (e.g., terminal jobs), leaving some 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 destructiveHint=false and idempotentHint=true; the description reinforces this by stating it is a no-op on terminal renders, which is meaningful behavioral context beyond the annotation. It doesn't state permission or auth requirements, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the action and scope, then prerequisites, then the no-op caveat. No wasted words.

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

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

No output schema exists, but for a simple 2-param cancellation the description covers the action, inputs, and terminal-state behavior, and annotations carry the safety profile. Only auth/permission context is missing.

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

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

Schema description coverage is 100% and both parameters are documented in-schema, so the baseline is 3. The description adds only the provenance note that renderId comes from create_render, with no format or path syntax detail beyond the schema.

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

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

Specific verb 'Cancel' on a specific resource 'in-flight render', with a parenthetical that scopes what counts (runaway/queued job). The name 'cancel_render' is clearly distinguished from siblings like cancel_compose, cancel_export, and cancel_job by resource.

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

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

'Needs projectId + renderId (from create_render)' tells the agent the prerequisite producer of the identifiers, and 'No-op if already terminal' tells it when the call is pointless. It does not explicitly contrast with cancel_job or retry_render, but the resource-specific naming makes the routing clear.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds meaningful behavior beyond that — async job semantics, loud refusal when a Brief field cannot be honored, graphics carried verbatim rather than re-authored, and clientNonce-driven dedup. The one gap is that 'saves the winner to the project' doesn't state what happens to any existing composition, which matters for a non-readonly mutation 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 with the operation and outcome, then the source-selection rule, then the return and the follow-up call — a sensible information order. It is long and dense, and some of the briefId parenthetical restates the schema description, but almost every clause carries a decision an agent must make.

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

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

For an async, nested-body, multi-path tool this covers the source selection, the prerequisites for each path, the refusal behavior, and the required follow-up job-wait — everything an agent needs to call it correctly. The output-shape sentence is redundant given the output schema exists, but it is not a 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?

Schema coverage is 100%, but the description adds a constraint the schema does not encode at all: the source fields are a mutually exclusive choice where EXACTLY ONE must be set. It also labels each path's intent (PLANNED/GENERAL/CLIPPING), which is semantic value beyond the raw 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?

States a specific verb+resource (start an async Director compose job) and immediately scopes what the job does: author candidates, verify each, save the winner. It also distinguishes the three source paths by name (briefId / fromComposition / suggestionId) so an agent can tell this apart from create_brief, suggest_briefs, apply_composition and create_render without opening other 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 prerequisites per path — 'create_brief first' for the PLANNED path, 'seed it with apply_composition first' for the GENERAL path — and names the pairing tool for the CLIPPING path (suggest_briefs). It also names the immediate follow-up call, wait_job(kind="compose", id=composeJobId, projectId=...), which is exactly the routing 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?

Discloses async job behavior (returns consultJobId, poll via wait_job), mode-dependent latency (~30s-2min vs minutes), that amend yields an adoptable candidateIndex while advise yields only guidance, and the ifMatch/409 binding rule. This is well beyond the annotations, which only flag non-read-only/non-idempotent. Minor gap: no explicit statement of whether the consult job itself mutates server state, which matters given readOnlyHint=false.

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

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

Front-loaded with the core constraint, and every clause carries actionable information about modes, polling, and adoption. It is dense and long, with some redundancy against the schema's own mode description, and the 'explore' handling slightly duplicates the schema entry, but it stays on-task.

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 async tool with nested body, enums, and an output schema present, the description covers the full lifecycle an agent needs: invoke, poll with the right job kind, and consume/adopt the result. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real operational meaning: amend is the default, what each mode returns and how to consume it, and that ifMatch binds proposals and must be applied before other edits or a 409 results. The focus/intent semantics largely mirror the schema, keeping it short of 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+resource+scope ('Ask the Director for editing advice on the project's CURRENT composition') and immediately bounds it ('it NEVER writes your composition'), which separates it cleanly from write siblings like apply_composition and select_candidate. An agent can tell what this does without opening the schema.

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

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

Gives explicit mode selection rules ('Use advise for a fast directional nudge, amend for a grounded, adoptable fix') and even handles a not-yet-shipped mode ('explore is coming soon → use amend'). It further routes the downstream step to wait_job and select_candidate, so the when/when-not is fully specified.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=false), and the description adds real context beyond them: upsert-in-place semantics, tenant scoping with no project arg, and the downstream binding consequence. The only friction is that 're-POSTing the same kitId updates it in place' reads as idempotent behavior while idempotentHint=false suggests repeated calls may have side effects; it is a mild tension rather than a hard contradiction, and no permission/auth requirements are stated.

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+resource and the upsert/update duality, then the workflow and binding path, so the important routing info comes first. It is dense with parentheticals and REST asides, but nearly every clause carries actionable meaning.

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

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

An output schema exists so return values need not be explained, and the description supplies the workflow, upsert behavior, and tenant scoping needed to select and call the tool correctly. The remaining gap is partial-update semantics (replace vs merge on re-POST) and auth expectations, which are left unstated for a large mutation.

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% on a single deeply nested body object, so the schema already carries the field semantics and the baseline is 3. The description only adds a high-level 'fonts/colors/logo' summary, and notably omits whether a re-POST replaces or merges the rest of the kit, which matters for an upsert.

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

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

Starts with a specific verb+resource ('Create or UPSERT a brand kit') and immediately defines its scope ('Sets fonts/colors/logo', 'Tenant-scoped'). The parenthetical that re-POSTing the same kitId is 'also the brand-kit UPDATE path' tells an agent this single tool owns both create and update, distinguishing it from any assumed sibling updater.

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

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

Gives an explicit workflow position ('brand step 0'), the exact downstream alternatives for binding ('pass its kitId as brandKitId to create_project, or attach it to an existing project via update_project'), and the consequence of skipping that step ('create_render produces UNBRANDED output'). This is genuine when-and-how guidance rather than restated purpose.

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

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

Annotations only say it is a non-idempotent, non-destructive write. The description adds substantial context beyond that: honor-or-refuse semantics for moment pinning and duration, seededGraphics carried verbatim as locked clips, exclusions as hard negatives, and the default gate behavior with the 60min checkpoint timeout. It omits some details (e.g. auth/permissions) but is well above the annotation baseline.

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 compose follow-up, which is good. But the field enumeration is a dense run-on list packed into three sentences across two paragraphs, forcing the reader to parse a long comma-separated inventory. It is informative but not cleanly structured.

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

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

Given the complexity of the brief (nested beats, graphics, seededGraphics, gates) and that an output schema exists (so return value detail is not needed), the description covers the essential semantics: the compose step, the quote-relay requirement, verbatim lock behavior, and gate defaults. It is largely complete, though it could spell out when to prefer update_brief over create_brief.

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

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

Although the schema itself carries very rich inline descriptions (coverage reads 0% only because top-level nesting is a single 'body'), the prose adds high-level meaning by enumerating the brief fields (goal, audience, beats[], captions, motionStyle, seededGraphics, exclusions, gates) and clarifying contested semantics like durationSec honor-or-refuse, locale meaning 'ALL on-screen copy + captions', and emphasisPhrases applied to captions. This meaningfully aids an agent above what the raw schema communicates at a glance.

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 (Persist) and resource (a Brief) and immediately distinguishes it from siblings by naming it the Director's input contract whose spec is the storyboard skill's output. The follow-up ('Then compose it: compose with {briefId}') situates it precisely in the flow versus update_brief, get_brief, 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?

It explains the post-write step (compose with {briefId}) and that the response quote must be relayed before composing, which implies when to call. But it never explicitly says when to use create_brief versus update_brief on an existing brief, nor prerequisites (project existence). Implied usage only.

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: the return shape (a hosted Stripe URL), the guarantee that a saved card is never silently charged, that the human confirms on Stripe, that the org comes from the key and not the body, and the required billing:write scope. The non-destructive/one-off nature aligns with destructiveHint=false and is reinforced rather than merely repeated.

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 return value, then constraints, then when-to-use. Dense and mostly waste-free, though the multiple mid-sentence clauses and emphatic caps make it slightly heavier 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?

With an output schema present the description needn't detail returns, yet it summarizes { url } anyway plus auth scope, org resolution and eligibility criteria. Complete enough that an agent can select and invoke it correctly on the first try; the only loose end is the unmentioned `interval` field, which is a schema inconsistency more than a description omission.

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

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

Schema description coverage is 0%, so the description must compensate: it enumerates the three plan values and explains that the org is never passed in the body. However it is silent on the schema's `interval` field, which it arguably contradicts by declaring 'no subscription tiers' — a real gap in parameter coverage.

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 up front: 'Top up the CURRENT org's credit wallet.' An agent can tell this apart from billing siblings like list_plans (discovery) and get_account (balance check) without opening any schema.

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

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

Explicit when-to-use ('Only send a user here when get_account shows the relevant balance at or near zero') and explicit routing to the discovery alternative ('Discover the packs with list_plans'). The when-not condition is inferable from that same sentence.

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

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

Annotations only say it is a non-idempotent, non-destructive write. The description goes well beyond that: the source is admitted before storage via template lint, determinism checks (no timers, Date, network, CSS animation) and declaration validation, refusals name the offending rule, a version-3 source is refused as component_source_retired, and the return is the ComponentResponse (id + metadata).

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

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

Front-loaded with the purpose before the contract detail, and the SOURCE CONTRACT sentence is a useful signpost. It is dense and reads as a wall of clauses rather than discrete steps, but nearly every sentence carries contract information an agent would otherwise have to guess.

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 deeply nested write tool with an output schema, the description covers the essentials: input shape, validation/refusal behavior, versioning rules, and downstream placement. Return values needn't be spelled out given the output schema. Minor gaps remain around the non-source body fields, but nothing critical 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?

Overall schema coverage is high, so the baseline is 3, but the description earns extra by explaining the source object shape ({version:4, componentId, template, manifest, definition}), what the template sub-composition must contain, that manifest slots are image or video, and that data-composition-variables is the definition's projection. It stops short of covering the other optional body fields (origin, tokens, examples, propSchema, ejectedFrom).

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 and store a custom component) and immediately narrows it to what the artifact is: a tenant-scoped native scene that tiles declared images/videos in 3D space. This is distinguishable at a glance from siblings like update_component, get_component_source and preview_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?

Gives real usage context: components are tenant-scoped (no project arg), the result is referenced from a composition, and placement later goes through execution/placement objects with slots kept out of params. However, it never states when to prefer create_component over update_component or how it relates to resolve_builtin_component / repin_component, so routing between siblings is left to inference.

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

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

Beyond the annotations (non-destructive, non-idempotent create), the description discloses meaningful behavior: brandKitId binds a kit that themes every render, omitting it yields unbranded output, and the tool returns the ProjectResponse. It doesn't state that repeated calls create duplicate projects (the idempotentHint=false implication), but the added brand semantics and return shape are real disclosure.

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

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

Front-loaded with the purpose, then why it's needed, then parameters, then the brand binding, then the return shape. Dense but each sentence carries information; only mildly long.

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 and annotations covering safety, the description supplies the missing context an agent needs (purpose, callers, brand binding, return). The only gap is that width, height, and description params are not mentioned, though the schema documents them.

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 semantic value: brandKitId's effect (colors/fonts/motion across renders, sourced from create_brand_kit) and the format sub-fields (aspectRatio/fps/resolution). It omits width/height/description, which the schema covers, so it modestly exceeds baseline.

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

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

States a specific verb and resource (create a project) and defines what a project is ('the unit you compose and render into'), then names the consuming siblings (compose, apply_composition, create_render, preview family) that require a projectId. An agent can distinguish this from create_brand_kit, create_render, or list_projects 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?

Explains why/when to call it (any tool needing a projectId requires one to be minted first) and points to update_project for rebinding or changing the brand kit later. There is no explicit 'when not to use' or preconditions, but the motivating context is clear.

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, idempotent=false, destructive=false. The description adds genuine context beyond that: renders are queued asynchronously, output themes from the project's brand kit, and without a bound kit the output is unbranded. It doesn't state whether duplicate submits are deduplicated (relevant given idempotentHint=false), so it falls short of a 5.

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

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

Front-loads the core action, then returns shape, then brand-kit dependency, then next steps — a sensible order. It is somewhat dense, packing REST PATCH and webhook-payload asides that are useful but tangential, keeping it just short of optimal tightness.

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

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

For a high-complexity async tool with a nested body and an output schema, the description covers the full lifecycle: submission, return shape/warnings, brand-kit dependency, and how to retrieve the finished file. Nothing an agent needs to call it correctly is missing, and return details are already carried by the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining that brandKitId is a project-level binding and can alternatively be set via REST PATCH /projects/:id. It also implies the compositionId default ('the project's active composition'), which the schema already documents, so the net gain is modest.

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 ('Queue') and resource ('an MP4 render of a project's composition'), making the async render action unambiguous and distinguishable from sibling preview_* and compose tools. An agent can identify exactly what this produces without opening the schema.

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

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

Clearly routes the agent to the follow-up path: wait_job(kind='render', ...) for blocking or create_webhook on render.completed for push. It also explains brandKitId binding via create_project/update_project. However, it never contrasts this tool against sibling alternatives like preview_clip or apply_template, leaving the choice of render-vs-preview implied.

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

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

Annotations mark this as a non-readonly, non-idempotent, non-destructive, closed-world mutation, and the description substantially enriches that: it discloses the two-step reserve-then-PUT protocol, the short-lived uploadUrl with expiresAt, the ~5 GB per-PUT cap, the HTTPS PUT requirement, and the async follow-on via list_media polling or create_webhook. This is exactly the extra behavioral context annotations alone cannot carry.

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

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

The routing decision and the two-step protocol are front-loaded, and each sentence does work (purpose, steps, async follow-on). It is dense and slightly long, but there is no filler or redundancy.

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

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

Despite an output schema existing, the description helpfully narrates the return shape ({ id, uploadUrl, expiresAt }) and the required follow-up call, and it fully covers the async processing path for a fairly complex multi-step mutation. 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 100% (baseline 3), but the description adds genuine value beyond it: it enumerates the body fields (filename, contentType allowed enum, size in bytes) and clarifies the ~5 GB per-PUT transfer limit that differs from the schema's 10 GiB total-size maximum. It stops short of documenting the optional projectId, so not a full 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+resource (ingest a LOCAL file / create upload) and immediately distinguishes itself from the sibling import_media by the condition that selects each. An agent can tell this apart from import_media, prepare_media, and finalize_upload 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 states when to use this tool ('no public URL to hand import_media') and when not ('prefer import_media whenever the bytes already sit at an https URL'). It also names the mandatory follow-up (finalize_upload) and downstream consumers, leaving nothing to inference.

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

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

Annotations only cover safety hints (not read-only, open-world, non-idempotent). The description goes far beyond: the secret is returned ONCE, activation is synchronous via a signed challenge that must be echoed, failure yields status:'pending' with no events, and the exact POST payload/headers/verification flow are 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?

Dense and front-loaded: the core routing decision comes first, then delivery, activation, and recovery in order. It is long, but nearly every sentence encodes a distinct operational fact, with only minor compression possible.

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 async tool with a nested schema and an output schema, the description covers the full lifecycle: registration, delivery contract, secret handling, synchronous activation, failure state, and recovery, plus a pointer to the resource/endpoint for the full event contract.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: events are a single terminal event per job kind with status in the payload, and checkpoint.ready means a held compose paused for review. It does not explain settleMs or several enum values, keeping it at 4.

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

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

States a specific verb and resource ('Register a webhook') and immediately positions it against a named sibling ('instead of blocking on wait_job'). An agent can distinguish it from wait_job, verify_webhook, and delete_webhook without opening any schema.

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

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

Explicitly says when to use it ('the right pattern for fan-out/async agents', long-running jobs) and when not to (blocking on wait_job). It also names the recovery alternative for a failed activation ('recover with verify_webhook, no delete/recreate'), removing the most likely mistake.

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 genuinely new context beyond those flags: that compose jobs already run are unaffected because they snapshot. That is exactly the downstream-impact information an agent needs before deleting.

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, the destructive action front-loaded and the caveat immediately after. Nothing 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?

For a single-parameter destructive delete with no output schema, the annotations plus the snapshot caveat cover what an agent needs to call it safely. It could say more about irreversibility or permission requirements, but the essential information 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 description coverage is 100% for the single briefId parameter, so the schema documents it fully. The description adds no additional meaning about the parameter, making the baseline of 3 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?

It states a specific verb and resource ('Delete a brief') clearly enough that an agent distinguishes it from get_brief, update_brief, or delete_composition. It does not explicitly differentiate itself from the other delete_* siblings, but the resource noun carries the meaning.

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 describes side effects, not usage. There is no statement of when to delete vs. update or archive a brief, and no prerequisites or warnings about irreversibility.

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 beyond them by disclosing the cascade (version history is destroyed), the specific refusal behavior with status code 409, and the required precondition. That is high-value behavioral context the annotations cannot convey.

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

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

Three tight sentences: the action with its destruction scope is front-loaded, the failure mode follows, and the remedy/discovery tool closes it. No filler, and the constraint is placed where an agent will read it before calling.

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

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

For a destructive two-param delete with full annotation coverage and no output schema, nothing essential is missing: what is deleted, what else is destroyed, the blocking condition, its status code, and how to resolve it are all stated.

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 both parameters (projectId, compositionId) are documented in the schema. The description hints at project scoping but adds no syntax, format, or ID-source detail beyond the schema. Baseline 3 applies.

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

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

Specific verb (Delete) + resource (composition) + scope ('and its version history') plus a project-level scoping phrase. It distinguishes itself from the many sibling deletes (delete_project, delete_brief, delete_media) and the composition-family tools by naming the exact object and the cascade.

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

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

Explicitly states the blocking condition (REFUSES the ACTIVE composition, 409) and gives two remedies ('make another one active first, or delete the project'), plus a pointer to list_compositions to discover which is active. This is exactly the when/when-not/alternative structure.

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 genuine domain context beyond that: the critic stops running in Director gates and score_composition immediately, which tells the agent the blast radius of the deletion.

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-loading the verb+resource+key before the consequence. Nothing is wasted and 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?

For a single-parameter destructive delete whose annotations already cover safety, the description supplies the impact context (Director gates, score_composition), which is the main thing an agent needs. Missing only recovery/permission notes.

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 criticId. The description only restates that the critic is identified by criticId and adds no format or syntax detail beyond the schema.

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

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

States a specific verb (Delete) and resource (registered critic) plus the identifying key (criticId). It is clearly distinguishable from siblings like register_critic and list_critics 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?

Usage is implied by the deletion effect, and there is no direct alternative sibling for removing a critic, but the description never states prerequisites, when-not to use it, or how to recover from an accidental delete. Adequate but with clear gaps.

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 adds value beyond them by disclosing the concrete consequence: compositions referencing the item will fail to render, plus explicit irreversibility. It does not mention auth/permission requirements or behavior on repeated deletion, which keeps it from a 5.

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

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

Three short sentences, no filler, with the destructive nature stated first and the risk condition second. 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?

For a one-parameter destructive tool with no output schema and full annotation coverage, the description supplies the two things an agent most needs: irreversibility and downstream render impact. It omits how to obtain or verify a mediaItemId and behavior on re-deletion of an already-deleted 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% for the single mediaItemId parameter, so the schema carries the burden. The description adds no meaning (no format, source, or retrieval hint for the ID), 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?

The description states a specific verb and resource ('Permanently delete a media item from your library') with the scope modifier 'permanently' front-loaded. It is trivially distinguishable from the other delete_* siblings (delete_brief, delete_composition, delete_project, delete_webhook) because the resource 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?

It gives a clear usage condition ('only delete media no composition still needs') and implies the cleanup context, which tells the agent when this is appropriate. It does not name an explicit alternative (e.g., a detach/replace tool) or a precondition check step, so it stops short of full when/when-not/alternatives 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 destructiveHint=true and readOnlyHint=false, so the bar is lower, but the description still adds real value beyond them: it discloses the cascade ('Removes its composition and render history') and the ownership prerequisite. The one gap is that 'irreversible' largely restates destructiveHint, and idempotentHint is not explicitly acknowledged.

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, front-loaded with the action and followed by the two facts that matter most (cascade scope, ownership/irreversibility). No filler; 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?

For a single-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies everything needed: the target, the side effects, and the precondition. Nothing an agent must know before calling is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents projectId fully and the baseline is 3. The description adds only the implicit constraint that the project must be one the caller created, with no format or identifier details 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 project') plus scope ('cleanup', ownership). It is trivially distinguishable from the other delete_* siblings because the resource (project) is explicit, so an agent can route without opening any schema.

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

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

Gives a clear precondition for use ('only call on a project you own and no longer need'), which functions as a when-to-use constraint. It stops short of naming an explicit alternative or exclusion (e.g., detach vs. delete), so it is strong context rather than full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered; the description adds real value by naming the concrete side effect — the signing secret is invalidated and the action is irreversible. It stops short of stating what happens to in-flight/queued deliveries or auth requirements, but that is a minor gap given the annotation 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 short clauses with the irreversible consequence front-loaded immediately after the action. Zero filler and nothing to trim.

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

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

For a single-parameter destructive tool with no output schema, the description supplies the action, the effect, and the irreversibility warning — enough to call it safely. Only marginal items (behavior on an already-deleted webhook, permission requirements) are absent.

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?

One required parameter with 100% schema description coverage, so the schema already carries the parameter burden. The description adds no format, sourcing, or lookup guidance for webhookId, 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?

Specific verb+resource ('delete a webhook subscription') with a clarifying parenthetical that states the observable effect ('stop receiving its deliveries'). That effect wording makes it easy to tell apart from update_webhook and verify_webhook without opening either schema.

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

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

The stated effect implies when the tool is appropriate, but there is no explicit when-to-use, no prerequisite (e.g., confirming the webhook exists), and no routing to alternatives such as update_webhook for partial disablement. Usage must be inferred.

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 state it is not read-only, not idempotent, not destructive. The description goes well beyond that: it explains the reframing behavior (point/face/active-speaker focus), that the source's authored intent is copied, that a NEW INDEPENDENT composition is saved in the same project (source untouched), and what is returned. It also routes the agent onward to create_render or apply_composition.

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 payload before the supporting detail, and the trailing parenthetical carries genuinely useful disambiguation rather than filler. It is dense and slightly long, but each clause (behavior, return value, follow-up tools, exclusion) 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?

For a nested-body mutation tool, the description covers invocation shape, side effects on the source, reframing behavior, and the return value, and an output schema exists for the return contract. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value by spelling out the body shape (fromCompositionId + targetFormat with aspectRatio/fps/resolution) and by clarifying the semantic distinction between targetFormat here and create_render.format, which the schema alone does not convey.

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 a precise resource ('a reframed SIBLING composition for a different aspect ratio'), and explicitly names the feature (Auto-Reframe / Magic-Resize). It clearly differentiates itself from create_render and apply_composition, both of which appear 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?

Gives an explicit positive use case ('make 9:16 + 1:1 + 4:5 cuts from one 16:9 edit') and an explicit exclusion with the correct alternative ('to only change resolution within the SAME aspect, pass create_render.format instead'). When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds genuinely new behavioral context: the two response modes triggered by presence/absence of the type argument, plus an emphatic 'exact' vocabulary hint that matters when authoring calls.

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, no filler. The purpose is front-loaded, the branch behavior follows, and the 'read before authoring' call to action closes it. Every sentence carries information an agent acts on.

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

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

No output schema exists, but the description compensates by describing the return shape in both modes (name/description list vs. JSON Schema for one op). For a single-optional-parameter read tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further by explaining what happens in each branch (omit -> compact list of names and descriptions; pass type -> only that operation's JSON Schema) and by echoing a concrete example value (captions.fromComposition). That is meaningful semantics beyond the schema text.

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

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

States a specific verb and resource: 'Discover the exact CompositionOp vocabulary accepted by apply_composition.' Crucially, it names the sibling that consumes this vocabulary (apply_composition), so an agent can immediately distinguish this introspection tool from the mutation tools around 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?

Gives clear context ('Read this before authoring edits or captions') and the routing rule to apply_composition. It does not state any when-not condition or exclusion, but for an introspection helper with a single obvious consumer, the guidance is effectively complete.

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

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

Annotations cover only the safety/idempotency profile, and the description adds substantial behavior the annotations cannot express: async jobId handoff, the 20s timeout, SSRF/private-URL blocking, non-2xx and non-HTML handling, and the critical non-obvious trait that failures degrade to EMPTY token arrays as a succeeded job rather than erroring. This is exactly the kind of disclosure that prevents an agent from misreading an empty result as a bug.

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 ASYNC contract, and essentially every clause carries operational information (jobId, wait_job kind, degradation behavior, fallback). It is dense with nested parentheticals and em-dashes in a single paragraph, which slightly impairs scanability, but there is no filler to cut.

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?

Complete for an async, single-parameter, output-schema-backed tool: the description supplies the job lifecycle, the wait_job continuation, the persistence gap and its remedy, plus failure semantics that the output schema alone would not disambiguate. Nothing an agent needs to call or correctly interpret this tool is missing.

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

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

Schema coverage is 100% for the single url parameter, so the baseline is 3, but the description adds real semantic constraints beyond 'format: uri': the URL must serve server-rendered HTML/CSS, and JS-rendered SPAs will typically yield empty output. That materially changes how an agent should pick and interpret the value.

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

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

States a precise verb+resource ('queue brand-token extraction from a website URL') and immediately scopes what is produced (colors/fonts/title/description) and how (HTML/CSS regex parse, not vision). It also names the two sibling touchpoints, wait_job and create_brand_kit, so an agent can route without opening either schema.

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

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

Gives explicit sequencing ('returns a jobId immediately; then wait_job(kind="brand_kit_extract", id=jobId)'), an explicit exclusion ('NOT a screenshot/vision pass'), a persistence boundary ('does NOT persist — review the tokens, then call create_brand_kit'), and a fallback path for JS-rendered SPAs. When-to-use, when-not-to-use, and the alternative are all covered.

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

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

Annotations declare only the generic safety profile (not read-only, not destructive, not idempotent); the description adds behavior they don't capture — state transitions (image/asset -> 'complete' immediately, audio/video -> 'processing'), the exact 400 failure modes (no bytes PUT, item not owned), and the returned shape. This is meaningful disclosure beyond the structured fields.

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

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

Front-loads the action and its precondition, then the behavioral outcome, then the error cases, then the next step. Every sentence carries distinct operational information; 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 pipeline-mutating tool with rich annotations and an output schema, the description covers everything an agent needs: prerequisite, state effects, failure conditions, and the correct follow-up call. It even restates the return shape, which already exists as an output schema.

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

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

Schema description coverage is 100% and the schema already documents both mediaItemId and the optional audioRole enum with rich semantic detail. The description adds no parameter-level meaning of its own, so the baseline of 3 for a fully-covered schema 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 ('Finalize a direct upload') and pins its place in the pipeline relative to create_upload. It also names its difference from sibling flows (asset/image vs. audio/video handling), so an agent can distinguish it without opening a schema.

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

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

Gives the explicit precondition ('once you have PUT the bytes to the uploadUrl from create_upload') and names the follow-up alternatives ('call wait_job(kind="media", id=mediaItemId), or use a media.completed webhook'). It also names when it fails, so the agent knows what NOT to do out of order.

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 the async lifecycle, the exact success payload ({ id, status:"generating", estimateUsd? }), the 402 cost-ceiling failure mode, and the webhook event name. Annotations (readOnly=false, idempotent=false, destructive=false, openWorld=false) are consistent with, and supplemented by, this operational detail.

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

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

Front-loads purpose, then generator list, parameter placement, return/error contract, and async handling in that order. Dense but every clause carries information; the generator enumeration is slightly list-heavy but justified by the enum's importance.

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

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

For an async, nested-body, cost-sensitive generation tool, the description covers input shape, success and failure returns, completion paths, and downstream usage of the id. Nothing needed to invoke or follow up on the call is missing.

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

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

Schema description coverage is 100% and the style sub-schema already documents aspect/durationSec/voice/speed/stability, so the description largely reinforces rather than adds. It does however clarify field placement (presentation controls in body.style, frame/image references in body.refs) and enumerates the generator values, which is useful orientation at the top level.

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 enumerates the generator modes, which cleanly separates it from sibling tools like import_media, prepare_media, and extract_media. An agent can tell what this produces and how it differs from adjacent media tools.

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

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

Gives clear routing guidance for the generator choice and, importantly, two completion paths (wait_job(kind="media", id=mediaItemId) or the media.completed webhook). It does not explicitly contrast when to use this versus import_media or prepare_media, so it stops short of full when/when-not coverage.

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 only readOnlyHint/openWorldHint available, the description carries the full behavioral burden and does so richly: it explains the shared-wallet funding model, that balance values are alternative restatements of one pool rather than separate budgets, that null/0 listUsdPerUnit mean distinct things, and the free_generation_cap failure mode. This is well beyond what annotations provide.

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

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

The opening 'ORIENT FIRST' cue is well front-loaded, but the bulk is a dense, jargon-heavy single paragraph mixing billing, entitlement and error semantics. Much of the field-by-field billing lecture could be trimmed or deferred to the output schema, so it is over-sized for a no-arg read.

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 supplies the interpretation key (balance vs included, fundedBy, creditCost, costCeilings) an agent needs to act on the response. Nothing required to call or make sense of this tool is missing.

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

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

Zero parameters gives a baseline of 4, and the description adds a useful note — 'No args — identity is resolved from your key (never echoed from input)' — clarifying that the key is the implicit input. No further parameter detail is possible, so this is the ceiling of useful value.

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

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

The description states a specific verb and resource up front — 'show THIS key's account' — and enumerates exactly what it returns (org binding, plan, entitlements map, per-call cost ceilings). It is clearly distinguishable from siblings like get_usage or list_plans.

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?

'ORIENT FIRST — show THIS key's account before you spend a metered call' gives explicit when-to-use guidance framed by a cost constraint. It goes further by telling the agent what to inspect (balance, generationLimit, listUsdPerUnit) and how to react to a billing_required error.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description does not contradict it. The description adds that a brief carries a 'current quote (compose + estimated render)', which is mild extra insight into returned content. It does not, however, disclose staleness, freshness, or error behavior for a missing id, so it remains a moderate contribution.

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 tight sentence with the operation front-loaded and no wasted words. It is efficient, though the parenthetical gloss is a small extra that could be trimmed.

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

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

For a simple read-by-id tool with an output schema and annotations covering safety, the description supplies enough to call it correctly. It notes the primary content (intent + quote) without needing to restate return values the output schema already defines.

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% for the single parameter, so the schema already documents briefId. The phrase 'by id' merely reinforces the schema without adding format, sourcing, or validity details. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

Specific verb (Read) plus resource (brief) with a scoping qualifier ('by id'), which naturally distinguishes it from list_briefs and the create/update/delete_brief siblings. It also adds a useful gloss on what a brief contains (persisted intent + current quote). Siblings beyond the by-id/list distinction are not named explicitly, so it stays just 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?

The description is purely descriptive and gives no when-to-use condition, prerequisites, or alternatives. It never tells the agent when to reach for this over list_briefs or get_composition, or when the embedded quote is what's actually needed. Consistent with the calibration where a lack of when-to-use language earns a 2.

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 readOnlyHint=true and openWorldHint=false, and the description adds substantial context beyond that: the contents of the packet (stage artifact, presigned stills, critic verdicts, money triple, reviewUrl) and the instruction to relay evidence rather than raw JSON. It stops short of describing pagination, expiry, or error behavior for an unresolvable checkpointId.

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 definition and organised around what the packet contains and how to act on it. It is dense but a single long paragraph; the trailing webhook/wait_job clause restates how the decision is learned and could be trimmed.

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

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

An output schema exists so return values need not be explained, yet the description's account of packet contents is what drives the agent's downstream behaviour (relaying the money triple and reviewUrl). Combined with the resume hand-off, the definition is complete enough to invoke and act on correctly.

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

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

Schema coverage is 100% and there is only one parameter whose schema description ('checkpointId (path).') is thin. The description compensates by explaining where checkpointId originates — the wait_job awaiting_input payload — which is meaning the schema itself 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?

States a specific verb+resource ('Read a checkpoint packet') and defines what a checkpoint is — 'the durable approval unit a held compose pauses at' — which separates it cleanly from list_checkpoints and wait_job in the sibling set.

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 trigger condition ('when wait_job reports awaiting_input with {checkpointId, stage, version}') and the follow-up action ('Answer an awaiting packet with resume(checkpointId, ...)'). It also distinguishes hosted vs non-hosted review flows, leaving no ambiguity about when to call this versus its alternatives.

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 readOnlyHint/openWorldHint annotations: unavailable exact pins are refused, retrying a head or another scope is forbidden, builtins always require exact collection plus pin, ID-only builtin reads are refused, and slots are bound per placement in execution.assets rather than caller params. These are precisely the failure and scoping behaviors an agent needs and none of them are derivable from the structured fields.

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

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

The core action and pin requirement are front-loaded, but the middle sentence is an overstuffed clause stack ('retaining sourceSnapshot with its complete versioned definition, manifest and template beside its exact pin and schema metadata') that largely restates return-value content the output schema already covers. The fork procedure is useful, but the same content could be stated in considerably fewer words.

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

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

For a three-parameter read tool with an output schema and no nested objects, the definition covers everything an agent needs: when the pin is required, how builtins differ, what refusal means, what the snapshot contains, and how to reuse it for a fork. Nothing material is missing.

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

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

Schema description coverage is only 33% (componentId is described as '(path)', sourceVersionId and builtinCollection are undocumented), so the description must compensate and largely does: it explains what sourceVersionId pins, what the builtinCollection enum values select, and the org-scoping that applies when builtinCollection is omitted. The componentId parameter itself still has no added meaning beyond the schema.

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

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

States a specific verb and resource: 'Read an exact component source as complete JSON' pinned to an immutable revision via sourceVersionId. It implicitly distinguishes itself from preview_component and resolve_builtin_component by requiring an exact pin and refusing ID-only builtin reads, but it never names those siblings directly, so the differentiation is inferential rather than explicit.

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 selection conditions: supply sourceVersionId from the selected catalog card, and for an explicitly selected builtin also supply builtinCollection. It also states the negative case (without builtinCollection resolution is org-scoped) and redirects forking work to create_component, but it does not compare this tool against resolve_builtin_component or preview_component as alternatives.

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 and openWorldHint, yet the description adds real context: 'free', the oversize-degradation behavior to a STRUCTURAL SUMMARY with a header, the REST fallback, and the dependency/brand-identity tokens returned on guarded endpoints. Minor redundancy ('Read-only') with readOnlyHint, but the degradation contract and token guidance are genuine behavioral disclosure.

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

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

The core purpose is front-loaded in the first clause, and most sentences carry distinct, actionable information. The token-preservation advisory ('never refresh the basis to hide a conflict') is useful but skews toward authoring guidance on a read tool, and the paragraph is dense enough that a reader must parse heavily."

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

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

No output schema exists, so the description rightly carries the return-value burden: it enumerates the composition's contents and describes the degraded summary shape and its header. Given four parameters and the cross-tool identity mapping, an agent has enough to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by tying compositionId to the same identity used as composition_id on apply and compositionId on preview_frame/create_render, and by explaining the v1 guarded-endpoint semantics of includeDependencies and the expectedBrandIdentity returned with componentExecutionVersions. That is meaningful incremental semantics, though partly duplicative of the already-decent schema 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 ('READ BACK a composition as JSON') and enumerates exactly what that object contains (tracks, clips, card HTML, reframe segments, captions, markers, format). It explicitly positions itself against siblings — the object create_render encodes, the body validate_composition needs, and the thing that is NOT the op-based write path (apply_composition). An agent can distinguish it from list_compositions, apply_composition, and validate_composition 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?

States concrete use cases (feed validate_composition, diff after an edit, archive/share for re-render) and an explicit exclusion — 'Authoring stays op-based (apply_composition) — do not round-trip this object back as a write.' It also names the alternative reader path (REST) for oversized reads. When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful context beyond that: the response is 'bounded,' the full transcript body is 'deliberately elided,' and this is to prevent MCP overflow. That explains why the read is scoped as it is, which the annotations alone do not convey. It omits return format/pagination details, but those are covered by the output schema.

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

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

Two sentences, front-loaded with the verb and resource, then the enumeration of returned facets. The list is somewhat long but each item earns its place by clarifying the bounded scope. No filler.

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

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

With an output schema present, the description need not detail return values, yet it still summarizes them to aid selection, and it names the follow-up tool for full transaction access. For a single-param read tool, an agent has everything needed to call it correctly.

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

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

There is a single required mediaItemId parameter with 100% schema description coverage, so the schema already carries parameter meaning and the description adds nothing param-specific. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (bounded authoring context for a media item), then enumerates the returned facets (dimensions/thumbnail, face roster, transcript counts/sample, temporal grids, fact readiness). This lets an agent distinguish it from siblings like get_media_facts and get_transcript without opening any schema.

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

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

Explicitly routes the agent to the alternative: 'follow with get_transcript for exact paginated word timings,' giving the condition that selects the sibling. It lacks an explicit when-not-to-use statement, but the sequencing guidance is clear and actionable.

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 readOnly, idempotent, and closed-world, so safety is handled. The description extends this with the readiness lifecycle (pending | ready | failed | available | unavailable) and the requirement to wait before downstream calls, which is genuine behavioral context beyond the structured fields.

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

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

Front-loaded with the purpose, then the exact-check recipe, then the fallback, then the sequencing caveat. Every sentence carries procedural information, though the jargon density (SOURCE window, prepared without intent) slows comprehension slightly.

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

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

An output schema exists so return values need not be explained, and the description still surfaces the exact.state enum, which helps interpret results. Combined with the annotation coverage, an agent has enough to call and use the tool correctly, with only the exact response shape left to the output schema.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds coupling semantics the schema does not: the three filters must be sent together and anchored to the same SOURCE window as prepare_media, and the paired-omission case is a valid whole-source query rather than an error.

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: reading prepared subject tracks and behind-subject mattes for one media item. It is clearly distinguishable from read siblings like get_media_context and get_composition, though it never names an alternative tool 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?

Gives explicit conditions: pass kind + startSec + endSec together for an exact readiness check using the same SOURCE window sent to prepare_media, or omit all three filters for a whole-source check when subjectTrack was prepared without intent. It also adds a sequencing rule (wait for the fact to be ready before preview_frame / score_composition).

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?

readOnlyHint=true already covers the safety profile, so the description earns credit for added context: it discloses the bundled payload (brand kits, critics, presigned thumbnails, decision log) and that the critics are a machine-checkable standard enforced by Director gates and score_composition. 'Presigned thumbnails' usefully signals links may be ephemeral, though no auth or rate-limit detail is given.

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 returned contents and closing with the usage trigger. The 'legible taste' / 'house style' metaphors add flavor without much payload, keeping it just short of maximally efficient.

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

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

An output schema exists, so return values need not be re-explained, and a zero-param read tool requires little more. The description covers purpose, payload, and the pre-compose usage condition adequately; only minor behavioral detail (auth, link lifetime) is absent.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to add here. It correctly describes an implicit org scope with no parameter-level gaps.

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 resource (the org's profile) and enumerates exactly what comes back: brand kits, critics, reference media, and a checkpoint-decision log. It is distinguishable from neighbors like get_account or get_brief, though the 'legible taste in ONE read' framing is flowery and only clarified by the enumeration that follows.

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

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

Gives an explicit when-to-use trigger: 'Read this BEFORE composing for an org you haven't worked with.' It does not name an alternative tool or when NOT to use it, but the precondition is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: word start/end are seconds from source media start, and the formatter omits the unbounded fullText duplicate. These are non-obvious behavioral details not derivable from annotations or schema.

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

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

Two tight sentences, with the core read semantics front-loaded ahead of the time-unit note and pagination mechanics. Every clause carries information; there is no filler or repetition 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?

An output schema exists, so return-value explanation is unnecessary. Given a read-only, 4-param, output-schema-backed tool, the description covers time semantics, paging flow, and formatter behavior adequately; only cross-tool routing is absent.

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 all four parameters are already documented in the schema, establishing a baseline of 3. The description reinforces the limit/after paging flow and recommends limit=20, but adds no syntax or constraint detail beyond what the schema carries.

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

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

The description names a specific verb and resource ('Read exact source-time transcript words') and scopes it to 'bounded utterance pages.' That is clear enough for an agent to identify the tool, though there is no sibling transcript tool to differentiate against, so no contrastive routing is offered.

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 operational usage (pass limit at 20, then pagination.nextCursor as after), which is genuinely helpful for driving the tool, but never states when this tool is appropriate versus alternatives (e.g., get_media_context or get_media_facts for transcript-adjacent data). Usage is implied rather than framed.

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

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

Annotations only declare readOnlyHint and openWorldHint=false, so this description earns credit for adding real context: newest-first ordering, that the amount is the event's LIST price which a plan allowance may zero on the invoice, and the billing:read scope requirement. It does not discuss paging behavior beyond the cursor schema.

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

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

Three sentences, front-loaded with the ledger definition, then the usage motivation, then the filter and scope facts. Dense but each clause carries information; the parentheticals are load-bearing 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?

With an output schema present, return values need no explanation, and the description covers ordering, attribution fields, price interpretation, filtering, auth, and pagination entry point. What remains unstated (paging loop behavior, empty-result semantics) is minor for a read-only list tool.

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

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

Schema coverage is 100% (baseline 3), and the description adds meaning on top: it frames projectId/jobId/[from,to) as the filter set and motivates jobId with the "did my failed render post a charge?" use case. It restates rather than extends the from/to inclusivity semantics already documented.

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 resource (the A2 usage ledger of metered billing events) with a clear scope (newest-first, attributed) and enumerates the fields returned. No sibling tool covers billing/usage, and the description makes the ledger's identity unmistakable without opening the schema.

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

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

Gives a concrete usage scenario ("what did project X cost this period?") and the intended method — query rather than summing quotes — plus the billing:read scope prerequisite and the filter axes. It stops short of naming when NOT to use it or a sibling alternative, but there is no competing billing tool to route against.

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

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

Annotations declare a non-idempotent, non-destructive, open-world write; the description adds substantial context beyond them — the return shape {id, status:"importing"}, that processing is async, the exact polling/webhook completion path, and the webhook payload semantics (status: complete|failed). This is exactly the behavioral detail a mutating async tool 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?

Front-loaded with purpose, then parameters, then return/async follow-ups; every clause carries signal (return shape, async path, webhook). Slightly dense with parenthetical em-dashes, but no filler sentences.

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

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

Given an output schema exists, return values need not be explained, yet the description still helpfully states {id, status:"importing"}. With async behavior, follow-up calls, and webhook semantics all covered, an agent has everything needed to invoke and chain this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description correctly notes url must be https and identifies the key fields, but it labels contentType as 'optional' while the schema marks it required (required: ["url","filename","contentType"]) — a material inconsistency that could lead an agent to omit a required field. It also omits the size/audioRole fields, which the schema itself documents.

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 ('Import a media item into your library') and immediately scopes it against the sibling upload path ('single call, no upload protocol'), distinguishing it from create_upload/finalize_upload/prepare_media. An agent can select it without opening the schema.

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

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

Explicitly frames itself as the 'agent-friendly ingest path' vs. the upload protocol alternative, and names concrete follow-ups: wait_job(kind="media", id=...), create_webhook on media.completed, and downstream consumers (get_media_context, suggest_briefs, composition source). When-to-use and next-step routing are both covered.

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

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

Goes well beyond the annotations: discloses async processing with the { id, status:"importing"|"ready" } shape, plan gating (402 billing_required), zero credit cost with the entitlements path, storage-gauge effect, provenance preservation, cross-org byte dedup, and the 422 candidate_mismatch failure mode. This is exactly the behavioral context annotations like readOnly/destructive cannot carry.

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

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

Front-loads the core action and result before layering on async, gating, cost, and error detail, so each clause carries operational information. It is dense and long, but no sentence is pure filler; slightly tighter grouping of the error/cost notes would help.

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 write tool with an output schema, it still supplies everything an agent needs to call it correctly: inputs, async follow-up via wait_job, downstream usage as a composition source, entitlement gating, cost, and recovery on failure. Nothing material is missing.

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

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

Schema coverage is 100%, so the structured fields already document the body, giving a baseline of 3. The description still adds meaning by identifying candidateId's source (search_resources), the projectId pairing, and the dedup/provenance semantics of the import; it only omits the curated pack lane that the schema body description mentions.

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 (import) and resource (a stock candidate keyed by candidateId from search_resources) and the exact resulting object (an ORG-OWNED media item in a project). This clearly separates it from siblings like import_media, select_candidate, and search_resources 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 concrete workflow context: pull candidateId from search_resources, pass projectId + candidateId, then poll wait_job(kind="media"), and re-run search_resources on 422 candidate_mismatch. It does not explicitly state when to prefer import_media or select_candidate instead, so it is strong but not a full when/when-not 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only the default-filtering behavior and 'each carries its quote', but the filtering rule is already spelled out in the kind parameter's schema description, so little new behavioral context is added.

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 packed sentences with the default behavior front-loaded and the mode variants enumerated compactly. Nothing is wasted, though the quoted enum values make it slightly dense to parse.

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, 100% schema coverage, and safety annotations, the description only needs to orient the agent, and it does so adequately by explaining the default-vs-variant list behavior. No critical aspect of calling this read-only list tool is left unstated.

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

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

Schema description coverage is 100%, so kind, after, limit, and projectId are all fully documented in the schema, including default and clamping behavior. The description restates only the kind semantics and says nothing about pagination or projectId scoping, so it adds no meaning beyond the schema.

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

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

States a specific verb+resource ('List briefs') and immediately clarifies what subset of briefs is returned and the three modes available. It does not explicitly contrast with get_brief or suggest_briefs, but the kind semantics make the scope unambiguous.

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?

Tells the agent what the default returns and when to reach for kind:"clip" vs kind:"all", which is genuine selection guidance among modes. It stops short of stating when to prefer a sibling like get_brief for a single record.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description adds substantial context beyond that: 'no source bodies or legacy thumbnail substitution,' the draft-status disclaimer about visual review/licensing, default page size of 20 with forward-only cursor pagination, and recommended-tier-first ordering. This is far richer than the safety-only annotation profile.

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 bloated, cramming two protocols, identity-pinning rules, package-handling, scene-shot exclusions, and tool routing into one dense block. The core purpose appears mid-way rather than up front, and the caps-lock 'DISCOVER WHAT TO BUILD WITH' framing is gimmicky. It is not appropriately sized or front-loaded for a list tool.

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

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

With no output schema, the description carries the burden of explaining returns, and it does describe card shape (identity.scope/revision, preset/recipe identities) and pagination via nextCursor. For a 12-parameter, zero-required tool with two modes, the coverage is broad and mostly sufficient, though the two divergent protocols make it hard to tell which fields apply when.

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 83%, so the schema already documents nearly every parameter and the baseline is 3. The description mostly enumerates filter params (category, kind, tier, useCase, mood, q, intent) that the schema already covers, and it references sourceVersionId and builtinCollection, which do not appear in the input schema at all. It adds little parameter meaning beyond the structured data.

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 clear verb+resource and scope: 'DISCOVER WHAT TO BUILD WITH — list the component catalog: the built-in primitive catalog plus your org-installed components.' It also distinguishes itself from siblings by explicitly saying not to pass package ids to clip.add, get_component_source, or cueframe://component resources. The primary statement of purpose is buried mid-description behind two projection-mode sentences, which weakens the front-loaded clarity.

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

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

It gives explicit when-to-use routing: origin:'builtin' vs origin:'library', when to call resolve_builtin_component then apply_template, and when to use get_component_source to fork a primitive. It also names an exclusion — scene shots are not listed here and should be authored with scene.add instead. Alternatives and conditions are spelled out, not implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: results are newest-first, the version stack with per-version status and decisions constitutes the retained review history, and nothing is deleted.

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 packed sentences with the primary action and ordering front-loaded, and parenthetical scoping kept brief. The em-dash aside on review history is dense but earns its place by clarifying retention.

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, full schema coverage, and annotations carrying the safety profile, the description supplies the remaining essentials: ordering, scoping intent, and retention behavior. Nothing an agent needs to call this correctly is missing.

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

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 after, limit, projectId, and composeJobId including cursor semantics and clamping. The description slightly enriches composeJobId/projectId intent but adds no syntax or format detail beyond the schema — 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 ('List checkpoint packets') plus a result ordering ('newest-first'), and the scoping parameters make clear this is a collection query rather than a single fetch. An agent can distinguish it from the sibling get_checkpoint without opening either schema.

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

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

It explains the two meaningful use contexts: composeJobId for a single run's v1→vN gate history, projectId for everything reviewable in a project. It never explicitly contrasts with get_checkpoint or states when listing is unnecessary, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further by disclosing the workflow role (supplying compositionIds for create_render/apply_composition) and what data distinguishes entries (format, active flag). It does not cover pagination or auth, but the added chaining context is meaningful given the annotation 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 tight sentences with the core purpose front-loaded and the chaining guidance second; no filler, no redundant restatement of the title.

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

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

For a read-only list tool with an output schema defining return shape and full annotation coverage, the description supplies everything needed to call it correctly and route its output. Nothing an agent requires is missing.

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

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

Schema description coverage is 100% and there is a single required projectId, so the schema already carries parameter meaning. The description adds nothing about the parameter's format or source, matching the baseline of 3 when the schema does the heavy lifting.

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

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

States a specific verb (list) and resource (compositions/videos), scopes it to a project, and clarifies terminology via '(video)'. It contrasts naturally with the singular get_composition sibling by specifying 'every composition in a project' plus format and active status.

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

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

Names concrete alternatives for downstream steps: use the returned compositionId with create_render for rendering or apply_composition for editing. This gives clear chaining context, though it never states when this tool should be avoided in favor of get_composition or other lookups.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: rubric text, rules, and evaluator URLs are write-only and never echoed in output, which prevents the agent from expecting those fields.

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

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

Three compact clauses, front-loaded with the list verb and field set, followed by the write-only caveat and the management routing. Every clause carries information; 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?

An output schema exists, so return-value explanation is not strictly required, yet the description still summarizes key fields and the crucial write-only caveat. Combined with the sibling routing, an agent has everything needed to call and interpret this tool.

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

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

There are zero input parameters, so the baseline is 4. The description instead documents output fields (tier enum, phase, floor, referenceMediaIds), which is useful though technically beyond input semantics.

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

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

States a specific verb and resource ("List registered critics") and enumerates the returned fields (criticId, label, tier, phase, floor, referenceMediaIds). It is clearly distinguishable from the sibling management tools register_critic and delete_critic, which are named 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 routes write operations to register_critic (upsert) and delete_critic, giving the agent clear context for the read/write split. It does not state an explicit when-to-use trigger for listing itself, but for a zero-arg list tool the implied usage 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it declares the return shape (IDs + metadata) and the concrete downstream tools that consume an ID. Pagination behavior is left to 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?

Two sentences, front-loaded with the action and resource, then filters, then return/downstream payoff. Nothing redundant and 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?

An output schema exists, so the description isn't obligated to explain returns, yet it still names the ID/metadata payload and its consumers. Combined with full schema coverage and clear annotations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all five params (kind, source, tag, after, limit) are already documented, including the exact-tag semantics and cursor clamps. The description only restates kind/source/tag without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb (List) and resource (media in your CueFrame library), with scope made concrete via the 'YOUR footage, not e2e debris' framing. It doesn't name the nearby listing/search siblings (list_catalog, search_resources) it could be confused with, so it stops short of full sibling differentiation.

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

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

Clear context for use: filter by kind/source/tag to find your own footage, and the returned ID feeds get_media_context, suggest_briefs, or composition sources. Downstream routing is well covered, but no explicit statement of when to prefer this over list_catalog/search_resources.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and reach profile is covered. The description adds 'No args — reads the platform catalog,' but that is largely a restatement of the empty schema and the readOnly hint, and it says nothing about catalog stability or size. Adequate but not additive.

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

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

A single sentence with zero waste: the verb and payload come first, then the usage trigger and its rationale. Nothing is repeated or 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?

With an output schema present, return values need no explanation, and the annotations cover the safety profile; the description supplies the pre-checkout context that is the only real complexity here. It is nearly complete, with the only omission being any disambiguation from the sibling list_catalog.

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

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

The tool takes zero parameters, so there are no parameter semantics to document and the baseline is 4. The description's 'No args' note correctly reinforces the 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?

States a clear verb (List) and resource (the plan catalog), and enumerates the payload contents (tiers, intervals, product ids, prices), so an agent knows exactly what comes back. It does not differentiate itself from the similarly named sibling list_catalog, which is the one gap keeping this from a 5.

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

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

Explicitly states when to call it ('BEFORE a checkout') and wires that to the concrete downstream consumer, create_checkout, explaining the consequence: requesting a real {plan, interval} instead of guessing an id. That is a named trigger plus a named alternative-to-avoid, exactly what this dimension asks for.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one behavioral hint — 'Each row carries the id every other tool needs' — but says nothing about ordering, pagination behavior, or result volume beyond what the schema and output schema already provide.

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

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

Two sentences and front-loaded, which is good, but the parenthetical '(steady-state entry, A9)' is internal shorthand that spends tokens without informing an agent. Roughly half the text 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 a full input schema, a declared output schema, and annotations covering the safety profile, the description only needed to orient the agent — which it does by positioning the call as the steady-state entry point and noting the id payload. Nothing essential is missing, though naming the read-only, non-mutating nature explicitly would have rounded it out.

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 'after' (opaque forward-only cursor) and 'limit' (1..100, default 20, clamping) are already fully documented in the schema. The description contributes nothing parameter-specific, 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?

The opener 'List your projects' is a clear verb+resource, and 're-orient in an existing workspace instead of minting duplicates' implicitly distinguishes it from create_project. The internal jargon '(steady-state entry, A9)' adds no meaning for an agent and slightly muddies an otherwise clean statement.

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 gestures at when to reach for this tool ('re-orient in an existing workspace instead of minting duplicates'), which is useful context, but it never names an alternative sibling (create_project, list_briefs, list_compositions) or states an explicit when-not condition. Usage remains inferable rather than spelled out.

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

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

Annotations cover read-only/open-world status, but the description adds real substance beyond them: results pass validation by construction (same table the font gate refuses by), every family's styles is ['normal'] because no bundled italic files ship, out-of-range weights are refused rather than synthesised, and the bundled-only scope excludes brand-kit faces. These are non-obvious behavioral facts 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?

Purpose and the search_fonts contrast are front-loaded, and the setup guidance precedes the field explanations. It is dense and largely earns its length, though the prose is heavier than strictly necessary for a no-arg list tool.

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

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

An output schema exists, yet the description still frames what the result means operationally (validation-by-construction, manifestVersion as a provenance record, brand-kit exclusion). Combined with the usage routing, an agent has everything needed to call it correctly.

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

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

There are zero parameters, so the baseline is 4. The description instead describes the returned fields (family name, weight ranges with static min===max semantics, caption defaults, bundled vs aliased bytes), which is useful but belongs to output rather than parameter semantics.

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

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

States a specific verb and resource ('the fonts the RENDERER can actually draw') and immediately contrasts it with the sibling search_fonts, which returns Google-catalog families the renderer cannot draw. An agent can distinguish the two without opening either schema.

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

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

Explicitly says to read it 'BEFORE authoring type, not after a refusal', and names the alternative (search_fonts) plus the condition that separates them. When-to-use and when-not-to-use are both stated.

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