Cardboard AI

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that by enumerating what the response contains (plan, remaining exports, usage, credits, renewal timing) and positioning it as a pre-flight check. It doesn't say what happens when no subscription or credits are exhausted.

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, front-loaded clauses: first what the tool returns, then when to reach for it. Slightly awkward grammar ("before work their subscription may not cover") costs a little, but nothing is 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 no output schema, the description must communicate the return shape, and it does list the key data points. For a simple read-only, zero-param lookup this is nearly sufficient; only failure/lapsed-subscription behavior is unaddressed.

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 the baseline is 4. The description correctly implies a no-argument call by framing it around "the person's" account rather than any input.

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

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

States a specific resource and scope: the person's Cardboard subscription plus remaining exports, usage, generative credits, and renewal date. No sibling in the list surfaces account/subscription data, and the description makes that distinct role obvious.

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 triggering questions ("what plan am I on?", "how many exports do I have left?", upgrade intent) plus a proactive condition — call before work the subscription may not cover. It doesn't name an alternative or exclusion, but no sibling overlaps this domain.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent operation, so the description does not need to restate safety. It adds useful behavior: Cardboard copies each file into the project and prepares it like an upload from upload_media's card, and the result reports each file's media id or why it was not added. It does not mention limits such as the 10-file maximum, but the core behavior is well 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?

The description is front-loaded and mostly efficient: it starts with the action and resource, then adds the upload_media comparison, result behavior, and document exclusion. It is somewhat dense in a single paragraph, but every sentence contributes useful information.

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

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

There is no output schema, and the description compensates by explaining that the result names each file's media id or why it was not added. It also covers the key behavioral context: copying into the project, accepted media types, photo handling, and the document exclusion. For this tool's complexity, the definition is complete enough for correct invocation.

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

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

Schema coverage is 100%, so parameter documentation is already strong. The description adds meaning beyond the schema by listing accepted media formats, clarifying that files must be attached to the chat, and noting that a photo joins as an image. It does not explain file_id or download_url semantics, but those are covered by the schema.

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

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

The description states a specific verb and resource: adding video, audio, and photo files attached to the current chat into a project. It also distinguishes this from upload_media by explaining that the files are already in the chat and do not need to be picked again.

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

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

The description gives clear usage context: this is for media already attached to the chat, and it names upload_media as the related alternative. It also gives an explicit exclusion for documents such as briefs, scripts, and shot lists, which should remain in the chat. It does not explicitly cover the case of files not already in the chat, but the intended 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 only say destructiveHint=true; the description adds what an agent actually needs: edits are applied as one batch, text outside the replacements is preserved, non-unique/no matches cause no change at all, edits saved since `rev` merge item by item, and `prefer` decides conflict winners. That is substantial behavioral disclosure beyond the annotations.

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

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

Three dense sentences with the primary mode first and the fallback mode last; nearly every clause carries semantics. Some phrasing is compressed to the point of ambiguity, e.g. 'An edit that does not match exactly once changes nothing,' which reads awkwardly.

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

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

For a destructive mutation with no output schema, the description covers atomicity, failure behavior, merge semantics and the alternate full-file mode. It does not say what the call returns on success or point at undo_timeline as recovery, which would matter for an agent doing risky edits.

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 tying `edits` to text copied from print_timeline, tying `rev` to the printed header, and framing `source` as the bulk-rewrite escape hatch. Insertion-via-anchor lives in the schema rather than the description.

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 and immediately distinguishes its two input modes: `edits` for exact replacements vs `source` for rewriting most of the timeline. It also implicitly separates itself from print_timeline (the read side) by naming it as the source of the text. A sharper contrast with undo_timeline/check_timeline would push this higher.

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 workflow guidance: read with print_timeline, copy exact text, pass its `rev`, and use `source` only 'to rewrite most of the timeline.' The condition selecting each mode is explicit. No exclusion against undo_timeline or timeline_history as recovery routes.

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 destructiveHint=true annotation by disclosing concrete consequences: an export leaves no file, cancellable and non-cancellable work are distinguished, and generations always run to completion. That last detail alone prevents an agent from wrongly assuming it can stop a generation.

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 action and consequence in a single compact sentence pair, with zero filler. The middle clause about work that 'says so and ends on its own' is slightly oblique in phrasing but still earns its place as a caveat.

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

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

For a one-parameter destructive tool with no output schema, it covers what is destroyed and the cases where cancellation silently fails. It leaves unstated what the tool returns on success versus refusal, which an agent would want given the absence of 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?

Only one parameter with 100% schema coverage, so the schema already explains job_id as the id returned by a Cardboard tool. The description adds no further meaning, which is the expected baseline for a fully documented single param.

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 'stop' plus resource 'a running job' with a concrete example ('an export stops and leaves no file'). It does not name a sibling (e.g. job_status or generation_status) to contrast against, so differentiation is implicit rather than stated.

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

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

The description implies the condition for use (a job is running and you want it stopped) and warns that some work cannot be stopped, but never points to job_status or generation_status for checking state first, nor states what to do if cancellation isn't possible.

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

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

Beyond the annotations (which only say non-readonly, non-destructive), it discloses that uncached media will be transcribed as a side effect, that the timeline is mutated only when apply is set, and what the response looks like in each case. The ordering caveat about later tracks drawing under footage is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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

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

The purpose is front-loaded and every sentence carries real information (caching, return types, ordering). It is tightly packed and somewhat run-on; the final clause about drawing order requires re-reading, but nothing is padding.

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

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

With no output schema, the description does the necessary work of explaining both possible return values (summary vs JSX) and the timeline side effect. Gaps remain around preset ids and the three undocumented parameters, but the complex parts of the tool are covered.

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

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

Schema coverage is 50%: apply, preset, and project are documented in the schema, while language, trackName, and wordsPerCaption are undocumented in both places. The description clarifies apply's dual semantics and hints at preset's role (restyle), but adds nothing for language or wordsPerCaption.

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 names a specific artifact ('a <track kind="caption"> for the current timeline') built from a specific source (media transcripts), and it distinguishes the two execution modes. An agent can tell this apart from transcribe_media and apply_timeline 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 clearly states the apply/no-apply choice and what each returns, and warns that the returned JSX is meant for apply_timeline and that track ordering determines visibility. It stops short of an explicit 'use X instead when...' against siblings like transcribe_media, but the conditions for each mode are 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 already declare openWorldHint=true, destructiveHint=false and readOnlyHint=false, so the bar is lower; the description still adds real context — headless Chrome execution, the import-vs-return side effect depending on `project`, and that reduced motion is requested by default so stills don't catch transitions. It does not cover timing, failure behavior on unreachable pages, or rate limits, which keeps it off a 5.

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

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

Three sentences, front-loaded with the core action and modes, then output routing, then the scroll alternative. Every clause carries information (scope, side effect, or constraint) with no filler or restatement of the tool name.

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

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

With 13 parameters, no output schema, and an open-world fetch, the description does the important work: it discloses where the artifact ends up (project import vs returned result), which is the only return-value information an agent gets. It leaves out what the returned image payload looks like and what happens on capture failure, a modest but real 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%, so the baseline is 3; the description earns above that by documenting cross-parameter relationships the schema states only in isolated property descriptions — scroll produces a project import, conflicts with fullPage/selector, and overrides the view to 1440x810 unless width/height say otherwise. It does not restate defaults like scale=2 or theme semantics, which the schema already handles.

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

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

The opening sentence names a specific verb and resource (screenshot a web page in headless Chrome) and immediately enumerates the three capture modes: first screen, full page, one element. The follow-up sentences add the routing outcome (into a project vs returned in the result) and the scroll/video variant, so an agent can distinguish all modes 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?

Explicit conditions and exclusions are given: scroll 'Needs project; not with fullPage or selector', and without a project the image 'comes back in the result'. It even explains the choice between scroll and full page (sticky headers stay in view vs one tall still the edit has to pan over), which is exactly the kind of decision guidance that selects a mode.

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

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

Annotations already declare the tool read-only, idempotent, non-destructive, and closed-world, so safety is covered. The description adds a vague promise of a 'fresh session' plus latest preview and export, but doesn't say whether fetching state has side effects (e.g., starting a session) or when 'fresh' is recomputed. A 3 reflects modest added context against strong annotations.

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

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

It is a single short sentence with no padding, but it is not front-loaded with a clear action and the phrase 'For Cardboard's card' is opaque. Brevity is achieved partly by omitting essential context.

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 should clarify what 'session', 'preview', and 'export' contain and whether the operation is expensive or has side effects. It leaves the agent guessing about the return structure and the meaning of 'fresh session'.

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

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

Schema description coverage is 100%, and the schema already explains both 'project' and 'render'. The description adds no parameter meaning beyond the structured fields, so the baseline of 3 applies.

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

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

The description names a resource ('Cardboard's card') and lists returned components (session, preview, export), but never states a verb and gives no indication of what 'Cardboard' or 'card' means. An agent cannot distinguish this from show_preview or project_status from the text alone.

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

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

There is no when-to-use guidance, no mention of alternatives like show_preview or project_status, and no prerequisites. The only hint of context is the schema note about cards that play rendered files, which does not come from the description itself.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; 'without writing' largely restates this. It does confirm the dry-run semantics against a mutating sibling, which adds modest value, but it doesn't explain what the report contains or how conflicts in `prefer` are surfaced.

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

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

A single sentence with the key distinction (report vs. apply, no writes) front-loaded. Nothing 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 dry-run/validation tool with no output schema, the agent gets no sense of what the report looks like (diff format, conflict warnings, error reporting). Adequate for a safe read, but thin for a preview tool whose whole value is its output.

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 parameters (including rev, prefer, edits, source) are already documented in the schema. The description only echoes 'edits or source' and adds no format or conflict-resolution detail beyond the structured fields.

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 (report) and a precise relationship: it reports what apply_timeline would change for the same edits or source. This distinguishes it cleanly from apply_timeline without needing 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?

The phrase 'without writing' implies the preview-before-apply use case, and naming apply_timeline points at the alternative. But it never explicitly says when to call this versus applying directly, nor does it mention any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that the project is created empty, but says nothing about duplicate-name behavior, permissions/auth needs, or what identifies the new project afterward.

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

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

One short, front-loaded sentence with no wasted words, but this is under-specification rather than effective conciseness. The brevity leaves obvious questions unanswered.

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 should explain what a caller gets back (e.g., a project id) and how to proceed after creation. It provides none of that, and with a mutation tool plus an undocumented parameter this leaves real gaps for an agent.

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% and the single parameter `name` is documented only as a bare string type. The description does not explain what the name is used for, whether it must be unique, or any format constraints, so it fails to compensate for the coverage gap.

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

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

"Create an empty project" gives a verb and resource, but it is essentially a restatement of the tool name/title. The only added information is the word "empty", which hints that no media or timeline is pre-populated, but the scope of "project" is never defined.

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

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

There is no guidance on when to use this versus the many sibling tools (list_projects, show_projects, project_status, start_recipe). An agent must infer that this is the entry point for creating a new project container rather than opening an existing one.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description contributes only two cryptic hints: results are expressed in "source seconds" (timeline vs source timebase) and the operation is "offline" — presumably asynchronous or job-based, but this is never stated, nor is cost, speed, or whether it requires prior transcription/probing.

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 a single short fragment with no wasted clauses, so it is not bloated. But the terseness is under-specification rather than conciseness: it is not even a complete sentence, and the most useful information (units, offline behavior) is buried in a parenthetical.

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

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

For a 3-parameter analysis tool with no output schema, the description should say what is returned (a list of cut timestamps?) and clarify the "source vs timeline" timebase and the meaning of "offline". None of this is present, so an agent must guess at both invocation details and the shape of the result.

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

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

Schema coverage is 67%: media and project are documented, but threshold (a 0–1 float) has no description anywhere. The description says nothing about any parameter and in particular fails to explain what threshold controls (detection sensitivity) or what the default behavior is when it is omitted.

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 fragment "Shot changes in a video" identifies the resource (scene cuts) and implies the detect action, and it is distinguishable from the sibling detect_silence by subject matter. However, it is a noun phrase with no explicit verb, and it largely restates the title "Find scene cuts" rather than stating what the tool does. "As source seconds (offline)" adds return-content info but not a clearer purpose.

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

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

There is no guidance on when to use this instead of alternatives, no mention of prerequisites (does the media need to be uploaded/probed first?), and no reference to related tools such as detect_silence or measure_loudness. The parenthetical "(offline)" is unexplained and does not tell the agent under what conditions to call the tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely new facts: the analysis is offline and returned positions are in source-time seconds (a meaningful distinction in a timeline editor where timeline vs source time can differ). It says nothing about return shape or cost of analysis.

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 telegraphic fragments with zero filler, so nothing is wasted, but the lack of a verb makes it read like a search-index snippet rather than an instruction. The '(offline)' aside and 'Source seconds' floating fragment are under-structured for the value they carry.

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, closed-world tool with four well-documented parameters, the basics are covered. However, there is no output schema and the description never states what is returned (start/end pairs? per-track results?), leaving the agent to infer the response shape from the phrase 'Source seconds'.

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 minDuration (default 0.5s) and thresholdDb (default -30dB) are already fully documented in the schema. The description contributes only the 'Source seconds' unit note, which is marginal beyond what the schema provides; baseline 3 applies.

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

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

The description names a specific resource and scope: silent stretches within a media file's audio, with the parenthetical '(offline)' indicating the analysis is local rather than cloud-based. It is understandable apart from the name, though it never contrasts itself with adjacent tools like detect_scenes, measure_loudness or waveform_levels.

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

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

There is no guidance on when to reach for this tool versus siblings such as measure_loudness (level analysis) or detect_scenes (visual analysis), nor any prerequisites or exclusions. 'Offline' is the only hint about context, and it is unexplained.

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

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

Annotations already declare this as a safe, read-only, non-open-world tool, so the description does not need to restate safety. It adds content coverage about what the topics contain, but it does not describe the return format, behavior for unknown topics, or default behavior when no topic is supplied.

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

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

The purpose is front-loaded in the first sentence, and the topic list is relevant. However, the second sentence is a long run-on with internal references like `cb` and an extensive embedded list, making it denser and less scannable than ideal.

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

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

For a one-parameter, read-only documentation tool this is mostly adequate, but with no output schema the description should more explicitly state that it returns documentation text. It also leaves unclear what happens if `topic` is omitted or unknown.

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

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

With 0% schema description coverage, the description substantially compensates by explaining that `cardboard` is the editor agent's editing guide and that other topics cover commands or techniques, with many examples. It does not fully enumerate valid topic strings or clarify the optional/default behavior, but it gives the agent meaningful guidance for the sole parameter.

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

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

The description clearly states that this tool retrieves Cardboard documentation by topic, and it characterizes the `cardboard` topic versus other command/technique topics. It is distinguishable from the operational sibling tools, though it does not use an explicit verb like 'retrieve' or 'read'.

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 'documentation by topic' and the listed topic categories, but there is no explicit instruction such as 'use this when you need documentation' or 'do not use this to perform edits.' The agent must infer when this tool is preferable to the many sibling action tools.

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

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

Annotations already declare the write/open-world/non-destructive profile, so the description only needs to add outcome detail. It does: an image becomes a photo, and imported media gets the same thumbnails, waveform and proxy processing as native media. It omits whether the fetch is synchronous or long-running (relevant given sibling job_status/cancel_job).

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 front-loaded sentences cover capability and outcome with little waste. The 'joins the project' clause appears twice, which is minor redundancy rather than bloat.

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 four-parameter mutation with no output schema, the description covers what gets imported and how it is processed, but says nothing about return value (e.g. a media id or job handle) or failure/timeout behavior when a third-party site is unreachable.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds nothing parameter-specific — audioOnly and maxHeight are never mentioned — though the site list and image-as-photo note loosely clarify what url can accept.

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 (download a link's target into a project) and enumerates the source kinds: posts on YouTube, X, Instagram, TikTok, or a direct video/audio/image file. This implicitly separates it from upload_media (local files) and search_footage, but no sibling is named explicitly.

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

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

'Download what a link points at' implies the trigger condition — you have a URL rather than a file — but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as upload_media or search_footage.

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-destructive, non-read-only, closed-world call. The description adds real behavioral context: the render is async ('hands back a job at once'), takes minutes for long edits, is cancellable via cancel_job, and its result is retrievable through job_status with an id and download link.

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 action and the async behavior, and the parenthetical about export duration earns its place. The sentence about Cardboard's card playing the newest preview/export is slightly tangential but still aids discovery.

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 usefully explains what job_status returns (export id and file link). It covers lifecycle well, but for a 5-parameter export tool it leaves the output-quality parameters completely unexplained.

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 20% (just 'project'), yet the description says nothing about format, quality, frameRate, or resolution — no defaults, no note about what happens when they're omitted. The enums are self-describing but the agent gets no guidance on choosing values.

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

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

States a specific verb and resource ('Render the project in Cardboard's export pool') plus the source of truth ('from the originals in Cardboard's storage'), which separates it from AI-generation siblings like generate_video. It also explicitly names what it is not (look, verify_timeline for checking an edit).

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

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

Explicit selection guidance: 'For when the user wants the file; check an edit with look and verify_timeline instead.' It names the alternative tools and the condition that routes to them, plus points to job_status for following the render.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the output layout semantics (left-to-right, then down, with source times), but says nothing about defaults, whether the image is returned or written to disk/URL, or cost for large videos — notable gaps given there is no 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?

A single dense sentence with zero filler, and the most distinguishing information (output shape) is front-loaded. It is a noun phrase rather than a verb-led statement, but 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 media-processing tool with 6 parameters, no output schema, and 50% schema coverage, the description omits how sampling is controlled (count vs every), what the defaults are, and how the resulting image is delivered. An agent could not confidently call this correctly from the description alone.

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

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

Schema coverage is only 50%: 'count', 'columns', 'tileWidth' and 'project' are undocumented, and the description supplies no meaning for them — it never mentions tile count, per-tile interval, column count, or tile size. Only the tiling order ('left to right then down') loosely hints at 'columns', which is insufficient to compensate for the coverage gap.

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

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

The description states the concrete artifact produced — evenly spaced video frames tiled into a single image with per-tile source times — which is far more specific than the bare name 'filmstrip'. It lacks an explicit verb and never distinguishes itself from the nearby sibling grab_frame (single frame), so an agent must infer the difference.

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

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

There is no guidance on when to use this versus alternatives such as grab_frame, show_preview, or detect_scenes, and no stated prerequisites (e.g. whether the media must be in the current timeline project). The agent must infer the use case entirely from the output shape.

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

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

Annotations already mark this as a non-read-only, non-destructive write; the description adds real context beyond them: the placeholder appears on the timeline immediately and is filled when the run ends, credits are consumed, capacity differs by quality (6 vs 4 inputs), and best-quality edits cost more. It stops short of describing failure handling or what remains if a run fails.

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

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

Front-loaded with the core action and side effect, then cost/quality guidance, then parameter notes. The sentences are long and carry several clauses each, but every clause adds information rather than padding.

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

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

For an 11-parameter mutation with no output schema, the description covers the essential unknowns: what gets created on the timeline, what is returned immediately (generation id), and how to block for the result. Failure semantics and credit quantity are left vague, but enough is present to call the tool correctly.

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

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

Schema coverage is 91%, so the baseline is 3, but the description still adds meaning: `quality` tradeoffs (lettering/signage reliability), per-quality limits on `image`, and the default of 5 for `durationSeconds`. It leaves `model`, `aspect`, and `track` to the schema, which already documents them.

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

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

The first sentence gives a specific verb and resource ('Generate a still image from a prompt') plus the concrete side effect ('put it on the timeline as an image item'). This clearly separates it from siblings like generate_video and apply_timeline.

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

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

It states when to pick `standard` vs `best`, when to pass `image` (redraw or source from an existing shot), and how to get a synchronous result via generation_status with `wait: true`. It never says when not to use it, e.g. explicitly deferring video needs to generate_video, but the routing context is otherwise 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?

Adds substantial context beyond the annotations: consumes credits, dryRun is free and sends nothing, the output lands in a pending item that gets filled, and `auto` relies on cached transcripts and title accents. It also discloses the section-timing constraints (first at 0, ≥5 s apart, last ≥5 s before the end) that govern valid input — none of which the annotations convey.

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

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

Front-loads the core action and effect, then handles sections, auto, dryRun, and cost in short ordered sentences. It is dense with backticked parameter names and constraint clauses, but essentially nothing is padding; a slightly lighter touch on the constraint list would be the only 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 9-parameter, credit-consuming generation tool with no output schema, the description covers cost, mode exclusivity, section constraints, defaults, and what dryRun returns. What's missing is what happens after generation (async job? must poll generation_status/job_status?) and failure behavior, which an agent would need to complete the workflow.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by clarifying that `sections` start times are measured in seconds into the generated track rather than timeline time — a genuinely confusing distinction the schema alone leaves ambiguous — and by spelling out spacing rules the schema doesn't encode.

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 ("Compose instrumental music with Sonilo") plus the concrete effect: a pending audio item is filled with the finished track on a "Music" track. That separates it cleanly from siblings like generate_sfx, generate_voice, and search_music, which an agent can rule out 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 frames the two operating modes and their exclusivity ("auto builds them from the timeline instead" vs `sections`), and explains when to use dryRun (free preview, no generation) versus the paid real call. It doesn't name a sibling alternative for the same job, but the mode-selection guidance 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 state this is a non-readOnly, non-destructive, closed-world tool, and the description adds useful behavior beyond that: it creates a pending audio item filled with MP3 on an SFX track and costs credits. It does not explain async status checking or what happens if the SFX track is missing, but the added cost and placement details are valuable.

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 core action and followed by the practical placement rule and cost note. Every sentence earns its place with no wasted text.

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 full schema and annotations, the description covers the essential behavior: generation, MP3 fill, SFX track placement, start timing, and credit cost. It could be stronger by naming search_sfx as the alternative for pre-existing effects or by pointing to generation_status/job_status for completion, but it is largely complete for invocation.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including defaults and constraints. The description reinforces `start` as the timeline second for the effect and mentions the default SFX track, but does not add meaning beyond the schema for the other parameters.

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 (generate a sound effect) and adds placement behavior (on an SFX track, filling a pending audio item with MP3). It does not explicitly distinguish itself from siblings like search_sfx or generate_music, but the action is clear enough without opening the schema.

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

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

It gives clear usage context: place one per moment, set `start` to the timeline second it belongs to, and note that it costs credits. It does not mention when to prefer search_sfx for existing effects or when not to generate, so it lacks explicit alternatives or exclusions.

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

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

Goes well past the annotations: it discloses credit cost, ~12 minute wait for a 30 s take, that it returns at once with a generation id, that a pending clip is placed on the timeline immediately, that character reference sheets persist in the project and are hidden from media listings, and that errors explain what to fix. The annotations only supply the generic non-read-only, non-destructive 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 purpose is front-loaded in the first sentence, but the body is a dense ~400-word block with no lists or headings despite covering a dozen distinct routing rules, making it hard to scan. Most sentences do carry information, though a few pack several independent rules into one run-on clause.

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 18-parameter generation tool with no output schema, the description covers the essentials: what is created, where it lands, what comes back (generation id), how to wait for completion, cost, and per-model constraints. An agent could call this correctly without further documentation.

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

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

Schema coverage is 83%, so the schema already carries much of the load, yet the description adds real meaning for `model`, `quality`, `image`, `ref`, `character`, `motion`, `resolution`, and `durationSeconds` (per-model length limits, ref naming syntax like `@Image1`, `clip.mp4#2-8` ranges, cast description format). It is silent on `seed` and `negativePrompt`, and only lightly touches `start`/`track` defaults that the schema already covers.

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 concrete verb and resource ('Generate a video clip from a prompt') and immediately names the side effect ('put it on the timeline'), which separates it from generate_image, generate_music, and the search/read siblings. The model routing detail further pins down what this tool uniquely does.

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

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

Explicitly routes between alternatives: standard vs best tiers, when a multi-scene story is one Wan 3.0 run rather than a clip per scene, when `image` (first-frame) applies versus `ref` (reference material), and which models reject cast refs. It also names the follow-up tool ('generation_status with `wait: true`') and gives a composition rule for cast shots.

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 it is a non-read-only, non-destructive, non-open-world operation; the description adds real substance by disclosing the side effects — a pending audio item is filled with the MP3 and word timings are persisted as a transcript, and that it requires an ElevenLabs account voice. It stops short of mentioning generation latency, job/polling behavior, or failure modes when a voice name doesn't resolve.

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 core action and its effect, with parameter notes trailing. The `docs` topic reference earns its place as a routing hint, but the backticked voice-parameter restatement duplicates the schema 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?

With no output schema, the description usefully explains what the call produces (a filled pending audio item plus a stored transcript), and the 11 parameters are fully covered by the schema. Behaviour around the hosted provider — latency, quota, or whether the item appears immediately — is the only notable gap for a mutation tool of this complexity.

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 every one of the 11 parameters is already documented, including the voice id/name default and text audio tags. The description largely restates the `voice` parameter and only adds the pointer to the `docs` `voice` topic, so baseline 3 is appropriate.

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

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

States a concrete verb and outcome: narrate text with a hosted ElevenLabs v3 voice and place the resulting audio on the timeline, including that word timings become the media transcript. This clearly separates it from siblings like generate_music, generate_sfx, and generate_image, though those alternatives are never 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?

Usage is only implied — an agent infers it should call this when it needs spoken narration of a provided text. There is no guidance on when not to use it (e.g. versus uploading existing audio, or search_voices before choosing a voice), aside from a pointer to the `docs` topic `voice` for voice-selection 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?

Goes well beyond the annotations by disclosing a concrete timing bound (~30 seconds), the side effect that it fills the pending clip the run was placed for, and the progress-reporting fallback. This also explains why readOnlyHint is false for what looks like a read operation.

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

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

Two sentences, front-loaded with the purpose before the wait mechanics, with no filler. The wait explanation packs several behaviors into one clause, which is dense but earns its space.

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 and no annotations covering behavior, the description supplies the timing, the side effect, and the progress-reporting behavior an agent needs. It stops short of describing the actual shape of the returned status, which would help since there is no 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 0%, so the description carries the full burden. It explains `wait` well (accepts a boolean, blocks ~30s), but `id` is only implied by context and never stated as the generation identifier, leaving half the parameters undocumented.

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

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

Names the resource precisely ('the state of a generation') and anchors it to the producing tools generate_video and generate_image, so an agent knows exactly what it is querying. It does not distinguish itself from the other status-ish siblings (job_status, card_state, project_status), which keeps it 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?

Implies the workflow clearly: call this after generate_video/generate_image, and call it again later because 'a later call waits again'. There is no explicit when-not-to-use or guidance on choosing between this and job_status, so no exclusion guidance is offered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description usefully adds that the output is an image (not a URL or metadata), but says nothing about image format, sizing behavior, or what happens if the time exceeds the media duration.

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

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

A single front-loaded sentence with no filler. It is efficient, though the brevity comes at the cost of the missing usage and parameter detail noted elsewhere.

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 does note the return type (an image), which is the key missing piece. However, two of four parameters lack documentation and there is no guidance on alternatives, so it is adequate rather than complete for a tool with four inputs.

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

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

Schema coverage is 50%: project and media are documented in the schema, but 'at' and 'width' are not. The phrase 'source time' gives a small hint that 'at' refers to media time rather than timeline time, but 'width' is entirely unexplained and the description adds little else over 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 resource (one frame of a video or image) and the result (returned as an image), so the agent knows exactly what it produces. It does not differentiate from near-neighbors like filmstrip, show_preview, or look, which all return visual output.

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

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

There is no guidance on when to use this versus filmstrip, show_preview, or look, all of which can surface imagery. The phrase 'at a source time' hints at a use case but no explicit when/when-not is given.

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 substantive behavior beyond the read-only annotations: the roughly 40-second wait threshold, the fact that still-running jobs return partial progress such as "Rendering 40%", and that a later call waits again. These details materially help an agent understand blocking and partial-result semantics.

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

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

The description is front-loaded and appropriately sized, with the wait behavior and timeout details stated directly. The repeated phrase about 40 seconds is slightly redundant, but it does not obscure the key information.

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

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

Covers the essential call behavior, timeout, partial progress, and resumption for a tool with no output schema. It is nearly complete, though it leaves the relationship with similarly named sibling status tools implicit.

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

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

Schema coverage is 100%, and the schema already documents both job_id and wait. The description reinforces that job_id comes from a Cardboard tool, but it does not add syntax or behavior for the wait parameter beyond what the schema provides.

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 action and resource: waiting on a Cardboard job and retrieving its result. It explains the trigger condition (a tool returned a job instead of a result) and gives export_video as a concrete example. It does not explicitly distinguish itself from sibling tools like generation_status or project_status, so sibling differentiation is only partial.

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 for when to call it: after a Cardboard tool hands back a job in place of its result, and again later if the job is still running. It does not name when not to use it or explicitly compare with cancel_job or generation_status, but the usage condition 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 readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description still earns credit by disclosing filtering behavior an agent could not predict: results are tagged present/missing, and cast reference-sheet stills are silently omitted unless `all` is set — a real default that affects result interpretation.

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, no filler. The default-filter caveat is front-loaded in the second sentence where it matters most.

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

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

For a two-parameter read-only listing tool with no output schema, the description covers what the list represents (project media with presence status) and the one non-obvious default. Return shape beyond the present/missing marker is left implicit, which keeps it short of a 5.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by stating the default state of `all` (stills are left out unless set), which the schema's 'Include cast reference-sheet stills' does not make explicit.

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 the resource (media in a project) and adds a distinguishing detail — each entry is marked present or missing — which separates it from write-side siblings like add_media or probe_media. It's phrased as a noun fragment rather than an explicit verb, and no sibling is named, so it stops short of a 5.

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

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

Usage is implied by the description rather than stated: it clarifies that cast reference-sheet stills are excluded by default and that `all` opts them back in. There is no explicit when-to-use-this-vs-another-tool guidance against the many search_*/probe_media siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value on top: result ordering (most recently edited first), the default page size of 10, and the notable visibility trait that the output reaches only the agent and not the user. It does not cover pagination or error behavior, keeping it below a 5.

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

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

Two compact sentences that lead with what is returned and immediately follow with the sibling contrast and the paging rule. Slightly dense phrasing ('as text that reaches only you: the person sees none of it'), but every clause carries information.

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

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

With no output schema, the description does the work of explaining the return: projects with ids, newest-first ordering, default 10 results, and a total matching count. Combined with annotations covering the safety profile, an agent has what it needs, though pagination beyond the default is unaddressed.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, and the description's statements about limit and search largely restate them. It does add that total counts every match, which frames how the params relate to the returned count, but the parameter meaning itself is not extended much beyond the schema 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 (lists) and resource (the account's Cardboard projects), plus the ordering and the exact fields returned (ids). It explicitly contrasts with the sibling show_projects, so 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?

Names the alternative show_projects and the condition that selects it (output for the person in a chat card vs. text that only the agent sees). That is a clear routing rule, though there is no explicit statement of when-not to call this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value by disclosing what the result set contains (favourites, recent voices, clones) and that it is account-scoped. It says nothing about ordering, pagination, or whether voices include metadata needed for generate_voice.

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

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

One short sentence, front-loaded with the key scoping fact (the account's own voices) and followed by the enumeration of categories. No wasted words. The sentence fragment style omits an explicit verb but costs nothing in comprehension.

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, annotation-covered, zero-required-param read tool with no output schema, the description does enough: it fixes scope and points at the consumer tool. The main residual gap is whether returned entries include voice IDs usable directly in generate_voice, which the agent must assume.

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 single parameter ownedOnly is documented in the schema as "Only the account's clones", so the schema carries the burden. The description's mention of "its clones" loosely aligns with that flag but adds no syntax or default behavior. 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 resource scope: the account's own voices (favourites, recent, clones) intended for generate_voice. An agent immediately knows this is a personal voice listing, not a catalog search. It stops short of naming the closest sibling, search_voices, so the boundary is implicit 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?

The phrase "for generate_voice" implies the downstream purpose (pick a voice ID to synthesize), which is useful usage context. However, there is no explicit when-to-use vs. when-not, and with search_voices in the sibling set the agent must infer that this one is personal-only and that one is broader. 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?

Annotations already declare this as a safe, read-only, non-destructive operation, so the bar for behavioral disclosure is lower. The description adds that frames are composited 'as the player shows them' and returned as images, but it does not explain output limits, image handling, or how multiple frames are returned.

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

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

The description is a single tightly worded sentence with no wasted language. It front-loads the core output concept and stays appropriately brief.

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

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

The tool has 10 parameters and no output schema, so the description should carry some burden in explaining what comes back. It says images are returned, but it does not clarify multi-frame behavior, contact sheets, or inline versus referenced image output, leaving some contextual gaps.

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 80%, so most parameters are already documented in the schema. The description adds no parameter-specific meaning beyond the schema, which is acceptable given the high coverage but not a value-add.

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

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

The description clearly states the resource and output: composited timeline frames as seen by the player, returned as images. It is specific enough to understand what the tool produces, but it does not explicitly differentiate itself from siblings such as grab_frame, filmstrip, or show_preview.

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

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

There is no guidance on when to use this tool versus alternatives like grab_frame, filmstrip, or show_preview. The intended usage is only implied by the tool name and description.

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

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

Well beyond the annotations: it discloses that processing runs on a hosted GPU, consumes credits, is cached per media/stretch/mode, and returns a specific artifact (grayscale MP4 or PNG with white = subject). Annotations only say readOnly=false, destructive=false, so this context is genuinely additive. The notable gap is execution model — nothing says whether the call blocks or enqueues a job (relevant given cancel_job/job_status siblings), and the 5-minute cap lives only in the schema.

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

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

Three tight clauses with zero filler: purpose, cost/model, output format and color semantics are all front-loaded. Every sentence fragment earns its place and the output contract lands before any optional detail.

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

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

With no output schema, the description does the needed work on return values (file type per input, grayscale encoding, white = subject). What's missing for a 6-parameter, credit-consuming, non-read-only tool is the async/blocking behavior and how the resulting matte is retrieved or reused.

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 all six parameters are documented, and the description adds only oblique meaning via 'cached per media, stretch and mode' — hinting that from/to and fast/occlusion affect caching without naming them. That is marginally useful but doesn't explain the soft-vs-hard-matte tradeoff beyond what the schema's own param descriptions say.

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

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

Precise verb+resource: separates subject from background, with the meaningful split between video mattes (people) and image mattes (main subject). It does not name or compare against any sibling, but no sibling in the list overlaps with matting, so an agent can still place it unambiguously.

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

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

Usage is implied rather than stated: 'video mattes find people, image mattes the main subject' tells the agent what each input type yields, and the credit-cost note hints at a tradeoff. There is no explicit when-to-use/when-not, and no pointer to alternatives such as grab_frame or filmstrip for cheaper previews.

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, non-destructive and closed-world, so the safety profile is covered elsewhere. The description contributes the "(offline)" signal, which usefully implies synchronous local analysis rather than a render/job pipeline. It says nothing about cost on long files, caching, or failure behavior for silent/corrupt media.

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 fragment with the measured quantities front-loaded and zero filler. It is terse to the point of being noun-phrase-only, but every token conveys information.

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

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

With no output schema, the description usefully doubles as a return-value summary by listing the four metrics produced. For a two-parameter read-only analysis tool with fully documented parameters, that covers what an agent needs to call and interpret it; the missing piece is disambiguation from neighboring audio-inspection tools.

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

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

Schema coverage is 100% — both `project` and `media` carry their own descriptions, including the helpful pointer to the timeline.tsx header for media identification. The description adds nothing beyond the schema, so the baseline of 3 applies rather than a penalty.

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 resource (a media file) and enumerates exactly which measurements are produced: integrated LUFS, loudness range, true peak, mean/max volume. That is far more informative than a restatement of the title. It stops short of distinguishing itself from adjacent analysis siblings such as probe_media, waveform_levels, or detect_silence.

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

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

There is no statement of when to reach for this tool versus probe_media or waveform_levels, which likely report overlapping audio characteristics. The only contextual hint is the parenthetical "(offline)", which suggests local computation rather than a queued job, but that is left for the agent to infer.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: truncated responses are returned in line-based parts and the caller must continue with `from`, plus the tie-in to apply_timeline. Missing only detail on part size limits or format caveats.

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 with no filler, and the identity of the returned resource is front-loaded. The header enumeration is slightly cluttered but functional.

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

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

With no output schema, the description carries the return-shape burden, and it does describe both the header fields and the tree plus the multi-part return behavior. Only the exact part-size boundary and any diagnostics semantics remain unstated.

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

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

Schema coverage is 100% and each parameter has its own description, so the baseline is 3. The description corroborates the pagination semantics of `from` ('reads on') but adds no format or constraint detail beyond what the schema already provides.

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 the resource precisely: the canonical timeline.tsx for a project, including header components (aspect, duration, media table, diagnostics, rev) and the tree. This distinguishes it from write-side siblings, though the reading verb is only implied by the tool name rather than stated outright.

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 the pagination workflow ('a timeline longer than one result comes back in parts by line, and `from` reads on') and clarifies the relationship to apply_timeline ('takes edits copied from this text'). It gives clear usage context but no explicit exclusions versus timeline_history or check_timeline.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's contribution is the enumeration of returned attributes, which is real added context given there is no output schema. It stops short of saying how audio-only or image files are handled, or what happens when the media id is not found.

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

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

One short sentence fragment with zero padding, and the key information (what you get back) comes first. The telegraphic 'What a media file is:' phrasing is slightly awkward and reads more like a heading than an instruction, but it wastes no space.

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

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

For a two-parameter read tool with full schema coverage and no output schema, the description does supply the return-field overview that would otherwise be missing. Still absent are any behavioral edge cases and any hint about the shape of the response (flat fields vs. nested metadata block), leaving it merely adequate.

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% — both 'media' and 'project' are documented in the schema with concrete identification hints. The description adds nothing about parameter formats or resolution order, so the baseline 3 applies; the schema carries the full burden here.

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

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

The description states the resource (a media file) and enumerates the attributes that characterize it (kind, duration, size, frame rate, codec, audio), which conveys roughly what the tool returns. However, it is a noun-phrase fragment with no verb, so the action (inspect/report metadata) is only inferable from the title. It also does no sibling differentiation — nothing distinguishes it from list_media, matte_media, or transcribe_media.

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

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

There is no guidance on when to call this tool versus alternatives such as list_media or check_timeline, and no preconditions (e.g., that the media must already be added to the project) are stated. The agent must infer usage entirely from the title and the field list.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met. The description adds genuinely useful context beyond that: the split between `now` and `events`, event ordering (oldest first, relative timing), that `cause` comes from a fixed list, that `error` is raw evidence, and 'Opens no card' — all of which shape how the agent interprets results.

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

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

The first sentence is strong and front-loaded, but the body becomes dense and partly restates itself ('Its fields are for working out a cause' after already enumerating the fields). The field-by-field enumeration is useful but verbose enough to slow an agent scanning for the core action.

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 does not need to explain return shapes, and it usefully supplements them with semantic notes (now vs events, fixed cause list, retryMayHelp meaning) plus human-facing output guidance. It is essentially complete for a single-parameter read tool.

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

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

There is a single parameter with 100% schema description coverage ('Project id or exact name'), so the schema already carries parameter meaning. The description adds nothing about the project argument, which is acceptable at this coverage level but leaves the baseline unimproved.

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

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

The opening sentence names a specific verb-and-resource combination (project status across uploads, edits, renders, playback, exports in the last 6 hours) and scopes it clearly. It distinguishes itself from generation/job-level status tools by being project-wide and time-bounded, though it never names the sibling it is not (job_status, generation_status, card_state).

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 implies usage through phrases like 'working out a cause' and tells the agent what the person actually wants ('a sentence or two on what they'll notice and what happens next'), which is presentation guidance rather than tool selection. There is no explicit when-to-use or when-to-prefer-alternatives statement versus siblings like job_status or card_state.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: pictures are returned as images and folders return a file listing, which tells the agent what shape of result to expect.

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

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

One front-loaded sentence beginning with the verb and resource, with no filler. It is somewhat dense and runs long due to the enumeration, but every clause carries information.

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

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

No output schema exists, so the description must signal return shapes, and it does (image for pictures, listing for folders, file contents otherwise). With only two fully-described parameters, this covers what an agent needs to call it correctly.

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

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's single example (recipe/RECIPE.md) by naming other valid paths and explaining that inputs.json's media field references the user's own uploaded files, which helps the agent construct paths.

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

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

States a specific verb (read) and resource (files of the recipe a project was started from), and enumerates the concrete contents (brief, structure.json, inputs.json, user-written files, pictures). It is clear what the tool does, though it never names siblings like show_recipes or start_recipe to sharpen the boundary.

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 enumeration of readable artifacts rather than stated: the reader infers 'call this to inspect recipe contents' and that a folder path yields a listing. There is no explicit when-not or pointer to show_recipes/start_recipe for the 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?

Beyond the annotations, the description discloses that YouTube results are plan-gated ('on plans with web footage'), that results are relevance-ranked by how well each clip shows the query, and what each result carries (length, license, download link usable by download_media). It does not contradict readOnlyHint=false or openWorldHint=true, and the open-world nature is consistent with querying external libraries.

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: what it returns first, sources second, result shape and scope last. No restatement of the title 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?

With no output schema, the description usefully sketches the result fields and the license/plan caveats. It stops short of covering empty results, the default/maximum result count, or pagination behavior, which an agent might need before calling.

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 80%, so the schema already carries the parameter documentation; the description only adds that ranking is by query relevance. The one undocumented parameter (orientation) is left unexplained in both schema and description.

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 ('Video footage for a shot') and names the concrete sources it searches (Pexels, Pixabay, Internet Archive, Wikimedia Commons, YouTube), plus the ranking basis. It also sharply distinguishes itself from photo-oriented siblings with 'Video only; it finds no photos.'

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 scope exclusion ('Video only; it finds no photos') is a genuine when-not signal, and the mention of download_media hints at the follow-up step. But there is no explicit routing against the obvious alternative (generate_video for generating rather than finding footage) or guidance about when stock vs. archive vs. web sources apply.

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

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

Beyond the read-only annotations, the description discloses important behavior: results are ranked by fit, unmatched filters are dropped rather than returning an error, and the response indicates this. It also describes returned musical attributes and the usable download link, adding valuable context without contradicting annotations.

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

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

The definition is compact and front-loads the core search and ranking behavior. The second sentence is dense with return-value detail, but the information is useful and no sentence is purely redundant.

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

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

With no output schema, the description does well by summarizing the returned metadata and the download link. It does not explain every optional-parameter interaction, but the schema covers requiredness, enums, and limit constraints sufficiently.

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

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

The description adds meaning beyond the schema by explaining that query, genre, and mood are ranking/filter inputs and that a filter with no matches is dropped. The limit parameter is adequately covered by the schema itself, so the remaining gap is minor.

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 (tracks from Cardboard's music library) and a ranking/search behavior based on query, genre, and mood. It clearly distinguishes itself from music generation tools by searching an existing library and from SFX/footage search by the music-specific 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?

The description implies when to use it (finding existing music tracks by vibe, genre, or mood) but does not explicitly say when not to use it or name alternatives such as generate_music, search_sfx, or search_footage. Usage is inferable but not guided.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: results are relevance-ranked, each result carries length, suitability, volume, and a download link, and the library is 'Free' — meaningful since there is no output schema. It stops short of saying result count or what happens on zero matches.

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 what is returned and how it is ranked. 'Free.' is a clipped fragment but carries genuine cost information; 'when it suits' is slightly vague phrasing.

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

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

With no output schema, the description compensates by enumerating the shape of each result (length, suitability, volume, download link), which is exactly what an agent needs to plan the downstream call. Only minor gaps remain: no result cap mentioned in prose (schema covers it) and no empty-result behavior.

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%, including a fully enumerated category with per-value meanings, so the schema does the heavy lifting. The description adds how `query` and `category` interact in ranking, but says nothing about `limit` beyond what the schema already declares.

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 (search) and resource (sound effects from Cardboard's library) and explains the ranking model — relevance to `query` constrained by `category`. That alone distinguishes it from generate_sfx and search_music by resource type, though the description never names those siblings explicitly.

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

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

Usage is only implied: the phrase about 'the link download_media takes to bring it into a project' sketches the search-then-download flow. There is no explicit when-to-use guidance versus generate_sfx or download_media, and no note on when to omit `query` or `category`.

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 that this is a read-only, non-destructive, closed-world operation. The description adds meaningful behavioral context by naming the transcribe_media dependency and describing returned source and timeline times, which is especially valuable because there is no 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?

The definition is a single compact statement with the core action front-loaded and no wasted wording. It efficiently packs the scope, prerequisite, and return behavior into one sentence.

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

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

The core invocation is clear and annotations cover the safety profile, but the lack of an output schema makes the return description somewhat loose. It also omits phrase matching behavior and any result limits or pagination details.

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

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

The schema documents the project parameter as an id or exact name, while the phrase parameter only has a minLength constraint and no description. The description reuses both names but does not explain phrase matching semantics, such as exact match, case sensitivity, or multiple occurrences, so it does little to compensate for the 50% schema description 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?

The description states a specific verb and resource: finding a phrase across media with transcripts in a project. It also clarifies the return scope with source times per media and timeline times through clips, which distinguishes it from sibling search tools.

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

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

It clearly implies the prerequisite that a transcript must exist from transcribe_media, providing useful context for when this tool applies. It does not explicitly compare against sibling alternatives such as search_footage or transcribe_media, 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 establish readOnlyHint=true and destructiveHint=false, so the description doesn't need to re-declare safety. It adds value beyond them by disclosing result ordering (most-used first), the at-least-one-input precondition, and the paging mechanism via cursor. It does not say anything about page size or what fields a voice record carries.

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 well-formed sentence with the resource, ordering, precondition and paging clause — no filler, and the key constraint sits in the middle rather than being buried. Nothing here is redundant with a title of the same name.

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

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

With no output schema, the description carries the burden of describing results, and it conveys ordering and paging well enough to call the tool correctly. Minor gaps remain: page size, whether filters combine with AND, and whether query matches names versus descriptions are left to the schema. Adequate but not exhaustive for a five-parameter search.

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 80%, so per-parameter meaning is mostly already documented. The description still contributes the cross-parameter constraint (query OR a filter must be supplied) that no individual schema field expresses, and confirms cursor semantics as 'next page of the same search'. The untyped/undescribed remainder is small.

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 ("Search the ElevenLabs voice library") plus the default ordering ("most-used voices first"), which tells an agent what kind of result set to expect. It does not name the obvious sibling list_voices, so the agent must infer that browsing without a query belongs there rather than here.

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 a query or a filter" is genuine usage guidance that resolves the schema's zero-required ambiguity — the agent knows it cannot call this with an empty object. "Page with `cursor`" gives the iteration procedure. What's missing is an explicit exclusion pointing to list_voices for unfiltered browsing.

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

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

Annotations already mark this as non-read-only, non-destructive, non-idempotent, and closed-world. The description adds meaningful context beyond those hints: reports are read by Cardboard staff along with the person's name and email, submission requires consent, and the result returns a reference.

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

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

The description is front-loaded with the action and purpose, then adds consent and return behavior. It is efficient overall, though the three kind categories repeat information already present in the enum schema.

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

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

For a three-parameter tool with full schema coverage and annotations, the description covers the essential behavior: what is sent, who reads it, the consent requirement, and that a reference is returned. No output schema exists, but the return value is summarized adequately.

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 three parameters are already documented, including the enum values for kind. The description restates the kind categories in prose but adds no syntax or format details beyond the schema, and it does not discuss the optional project parameter.

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

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

The description states a specific verb and resource: it sends a report to Cardboard's team. It clearly distinguishes the three report kinds (bug, request, feedback) and is unlike any sibling tool, which are mostly media/timeline operations.

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 clear categories for when to use the tool: something went wrong, a missing capability, or general feedback. It also states the consent prerequisite (only after the person says yes). It does not name alternatives or when not to use it, but no sibling alternative exists for this 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 already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds the real behavioral payload: a player appears in the chat, it targets the latest edit now and the export once that finishes, and the person saves the file via a Download button. It doesn't cover edge cases such as what is shown when a project has no edits yet, which keeps it off 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?

The core action is front-loaded in the first clause. The third sentence restates the same point ('this player is how the person sees what they changed') at some length, so it is efficient but not maximally tight.

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 reasonably explains what calling it produces: a player in the chat and a Download path for exports. A brief note on behavior when no edit or export exists is the only missing piece for a single-parameter 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 is a single parameter with 100% schema description coverage ('Project id or exact name'), so the schema already carries the semantics. The description adds no format, lookup, or error behavior beyond it, which is the baseline 3 case.

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

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

States a specific verb and resource: it opens Cardboard's player in the chat, on the project's latest edit or on its export once finished. It also implicitly differentiates itself from siblings by naming apply_timeline, undo_timeline and caption_from_transcript as tools that produce nothing visible without 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 an explicit when: one call once a reply's edits are done. And an explicit why-not-alternatives: apply_timeline, undo_timeline and caption_from_transcript show nothing in the chat by themselves. An agent knows exactly when to reach for this versus the mutation tools.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by describing the rendered card, the pick interaction, and how a pick surfaces differently in ChatGPT ('Let's work on …' prefill) versus Claude (player opens, project name arrives in the next message). What it omits is scale/limits (how many projects the card can hold, whether there is paging) — a moderate gap for a listing tool.

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

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

Purpose is front-loaded in the first clause and every sentence carries content the agent needs (ordering, card contents, result summary, pick side-effects). The final sentence is long and packs two client-specific behaviours together, which slightly hurts scanability.

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

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

With no output schema, the description correctly compensates by stating what the result contains (a count and the six newest projects with edit times) and what a pick produces. The main missing piece is the relationship to list_projects, which is essential context in a suite containing both.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter claims conflict with 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?

Uses a specific verb and resource ('Lists the person's Cardboard projects'), plus concrete scope: most-recently-edited first, with thumbnail, duration and last-edited time. An agent knows what it returns. However it never acknowledges the sibling list_projects, so the reader cannot tell why two listing tools exist.

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

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

Usage is only implied: the card lets the person 'search the list there and pick a project,' which suggests this is the interactive/presentational listing path, versus list_projects presumably being the programmatic one. There is no explicit when-to-use/when-not statement and no named alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description need not re-establish safety. It adds real context: the UI behavior (picks shown first, all other recipes still reachable a tap away), the presence of slugs in the result for start_recipe, and the credit-cost nuance for recipes marked `usesGeneration`. It does not describe failure modes or the exact result payload, 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?

It is front-loaded with the core purpose, then parameter guidance, which is the right order. However, the first two sentences are long and contain redundancy ('the answer when they ask what Cardboard can make or do' repeats the prior clause; the recipe explanation is convoluted), and the guidance on docs-vs-parameterless-call is slightly tangled. It is dense and mostly earns its space, but could be trimmed noticeably.

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 five-parameter read tool with no output schema, the description covers when to call, how to populate each parameter, the two-step flow with the `recipes` docs topic, and the display behavior of the card. It stops short of fully specifying the return payload beyond 'names the matching recipes with their slugs', which is the main remaining 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?

With 100% schema description coverage, the baseline is 3; the description earns above that by clarifying what qualifies for `picks` ('only the recipes that make that whole kind of video... an effect, a title or a caption style is not a whole video'), that `also` is for alternative-kind recipes suited to the same footage, and that `search` is semantic rather than keyword matching. It does not add much on `heading` beyond the schema example, but overall adds meaning.

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

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

The description states a specific verb and resource — it shows Cardboard's recipe library as a card in the chat — and explains what a recipe is (a team-made edit template applied to the person's footage). It also distinguishes itself from read_recipe and start_recipe by noting the result lists slugs 'for start_recipe' and by pointing to the docs topic `recipes` for the full list.

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

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

It gives explicit when-to-use rules: call it when the person asks what Cardboard can make, and when they have stated a goal, first read the docs topic `recipes` and then pass `picks`. It also gives a when-not rule for `search` ('for words the person asked to search for, not for finding what fits their idea') and a fallback ('call show_recipes without them first if you do not yet know the slugs').

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds real behavior beyond that: it creates a project, populates specific paths, and triggers a UI side effect (opening upload_media's card). It does not state that repeated calls create separate projects or what happens on an invalid recipe, which matters for a non-idempotent tool.

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

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

Front-loaded with the core action and outcome, then conditions, then parameter nuance. The single long compound sentence packs several ideas and takes effort to parse, but no sentence is filler.

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

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

No output schema exists, and the description partially compensates by saying the result names still-open questions and that the upload card opens. For a 5-parameter creation tool it leaves gaps on error behavior, project identity in the response, and re-invocation semantics, but the essential mental model is present.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema for `answers`: answers are supplied "by id, as far as they have given them" and the result names the questions still open, clarifying that a partial answer set is legitimate. The `upload` and `recipe` semantics are essentially restated from the schema.

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

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

Names a specific verb and resource ("Makes a new project from one of Cardboard's recipes") and enumerates exactly what is materialized: the recipe's brief, graphics and data in recipe/, its media, and answers in recipe/inputs.json. That detail separates it cleanly from siblings like create_project (blank project) and read_recipe (inspection only).

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 conditional guidance on the main branch point: when the recipe takes media, the upload card opens unless `upload` is false, and it explains how to obtain the recipe identifier ("slug from show_recipes"). It gives no explicit when-not or failure guidance (e.g. don't call on an unknown slug, don't call twice for the same project), so it stops short of full routing guidance.

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

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

Annotations already declare the operation as read-only, non-destructive, and closed-world, so the description is not required to cover safety. It adds useful ordering context ('newest first') but says nothing about pagination, revision depth, or what a revision record contains, which would matter for an agent consuming the result.

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

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

The description is a single short sentence, front-loaded and free of filler. Its brevity is appropriate, though it leaves important details unspecified.

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

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

For a one-parameter read-only list tool with no output schema, the description is minimally sufficient to know it returns saved revisions in reverse chronological order. However, given the many nearby timeline-related siblings, it should do more to clarify the operation and result scope (e.g., whether it lists revision identifiers or full snapshots).

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

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

With only one parameter and 100% schema description coverage, the schema fully documents that 'project' accepts a project id or exact name. The description adds no parameter-level information beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states the resource ('saved timeline revisions') and an ordering ('newest first'), which helps identify the data. However, it omits an explicit verb (list/retrieve) and does not distinguish this tool from ambiguous siblings such as check_timeline, print_timeline, or undo_timeline, leaving the exact operation (listing revision metadata vs. returning revision contents) unclear.

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

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

There is no indication of when to use this tool, no prerequisites, and no mention of alternatives like print_timeline or undo_timeline. The ordering note is the only usage hint, and it does not help an agent decide between sibling tools.

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

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

Annotations declare readOnlyHint=false, and the description explains why: transcription output is persisted with the project for later calls, with `force` overriding the cache. That is genuine behavioral context an agent could not read off the annotations. It omits latency/job behavior (siblings job_status and cancel_job exist) and failure modes, keeping it below a 5.

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

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

Three sentences, no filler, with the core output shape stated first and the conditional `timeline` behavior last. The opening phrase 'The transcript of a media file's audio' is noun-phrase framing rather than an action statement, a minor structural weakness.

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 8-parameter tool with no output schema, the description covers what is returned (word-level timings, seconds), persistence semantics, and the timeline-mapping option, while the schema handles format/language/range details. It leaves open whether the call is synchronous and how long transcription takes, which matters given the surrounding job_status/cancel_job tools.

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

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

Schema coverage is 88%, so the schema already documents from/to/force/media/format/language and the baseline 3 applies. The description contributes meaning only for the undocumented `timeline` flag (times mapped through clips rather than source seconds), which is valuable but narrow.

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 the concrete resource and result: the transcript of a media file's audio, with per-word timings in seconds, plus the engine used. It implies the transcribe action rather than stating a verb outright, and it never names the siblings it is distinct from (search_transcript, caption_from_transcript), so an agent must infer the boundary.

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

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

It gives an implicit usage signal by explaining caching ('the result is kept with the project for every later call') and the `timeline: true` variant, which tells the agent when the mapped-time mode applies. It never says when to prefer this over search_transcript or caption_from_transcript, nor what a first call costs, so usage is only implied.

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

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

Annotations already disclose destructiveHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds that the revision source is timeline_history, but does not say what happens to the current timeline state or whether the revert itself can be undone, leaving a gap for a destructive mutation.

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

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

A single front-loaded sentence with no padding. The default behavior ('previous revision') is stated before the explicit-rev variant, which is the right ordering for an agent.

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

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

For a two-parameter destructive mutation with no output schema, the definition covers the core behavior but omits what the caller loses (current edits) and any confirmation/precondition expectations. That is acceptable only because destructiveHint carries part of the burden.

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%: 'project' is documented in the schema, but 'rev' has no schema description at all. The description partially compensates by telling the agent where to obtain a valid rev ('from timeline_history'), but it says nothing about project identification or rev range/validity.

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 ('Restore') and resource ('previous timeline revision'), which clearly distinguishes an undo/revert operation from apply_timeline and check_timeline. It stops short of explicitly contrasting with siblings, but the revert semantics are 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?

The description implies the two usage modes (default previous revision, or a specific rev sourced from timeline_history), but it never says when *not* to use this tool or how it relates to apply_timeline. The pointer to timeline_history is useful but is about parameter sourcing rather than tool selection.

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

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

Beyond the annotations it discloses the interactive-card behavior, per-file upload status feedback, and that photos land in the project as images — real context an agent can't get from the schema. It is weaker on the destructiveHint=true dimension: it never spells out what gets destroyed or discarded, leaving the 'replace' semantics partially implicit.

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

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

The structure is front-loaded and information-dense: capability first, then exclusions with alternatives, then the phone/export edge case. It is a single dense paragraph with long clauses, slightly harder to scan than a bulleted breakdown, but no sentence is filler.

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

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

For a three-parameter interactive tool with no output schema, the description covers what happens, what the card reports, and the one non-obvious workflow (phone copies replaced before export). It does not say what the call returns or how it behaves if the person cancels the card, which is the remaining 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%, so the parameters are already documented; the description still adds value by framing `replace` as part of a gated workflow (ask the person first, then call once per clip) rather than a bare media id. `goal` is not discussed in the description, but the schema fully covers it.

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

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

The description states a specific verb and resource ('Opens Cardboard's upload card in the chat') and names the exact file kinds accepted, so an agent knows precisely what it does. It also distinguishes itself from the sibling add_media by scope ('video, audio and photos already attached to the chat go in with add_media instead').

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 (device-local footage/photos must reach Cardboard), explicit when-not-to-use (documents like briefs, scripts, shot lists; chat-attached media), and names the alternative tool for each exclusion. The phone-original workflow ties invocation to a precondition ('before export_video, ask whether to replace those clips').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value by naming the five specific classes of problems detected, which is behavioral detail the annotations cannot convey, though it says nothing about whether issues are returned as a report, warnings, or a pass/fail verdict.

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 colon-led sentence, front-loaded with the verb and resource, followed by a tight enumeration. No filler and nothing buried.

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

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

There is no output schema, and the description does not say what the agent receives back (list of issues with positions? a boolean? errors that block export?). For a validation tool, the shape of the result is the main thing an agent needs and it 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?

Only one parameter ('project') and schema description coverage is 100%, so the schema already explains it accepts an id or exact name. The description adds no further meaning about that parameter, which is acceptable at this coverage 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?

The verb 'lint' plus the resource 'timeline' is specific, and the enumerated checks (overlaps, gaps, off-screen text, clips past source, missing media) make the operation concrete. However, it does not distinguish itself from the sibling 'check_timeline', leaving the agent unsure which of the two near-identical validators to pick.

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

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

There is no statement of when to use this versus check_timeline, print_timeline, or project_status, and no prerequisites or timing guidance (e.g. before export). Usage must be inferred entirely from the name and the list of checks.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not say what the returned image is (format, dimensions, a URL vs inline data), whether width/height default, or how generation cost/latency behaves for a render-like operation.

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

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

It is certainly short and wastes no words, but it is a single fragment rather than a structured sentence with a verb, so the brevity comes at the cost of clarity rather than from discipline.

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

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

For a tool with four parameters (two undocumented), no output schema, and a very close sibling in waveform_levels, the description leaves the agent without return-value expectations, sizing behavior, or routing guidance. It is not adequate to invoke the tool confidently.

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

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

Schema description coverage is 50%: media and project are documented in the schema, but width and height have no descriptions anywhere. The description mentions 'media file' only and says nothing about sizing, defaults, or what project scoping means, so it fails to compensate for the coverage gap.

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

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

The phrase 'the audio of a media file drawn as an image' does convey the resource (an audio waveform, rendered as an image), so it is more than a pure restatement of 'Waveform image'. But it is a noun fragment with no verb and no explicit distinction from the sibling waveform_levels, which an agent could easily confuse it with.

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

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

There is no statement of when to call this versus waveform_levels, filmstrip, or grab_frame, nor any prerequisite or context (e.g., that a project/media must exist). The agent must infer usage entirely from the tool name and schema.

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 non-destructive, closed-world behavior. The description adds genuinely new context: return values are normalized 0-1 peak/RMS samples. It does not disclose sampling resolution, the points cap, or what happens when points is omitted.

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

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

A single sentence that front-loads the resource and return format before the use case. 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 read-only, no-output-schema tool the description does convey the shape of the return data, which is the key gap filler. However, the undocumented 'points' parameter and the lack of any mention of output structure or resolution leave real holes for an agent tuning sampling density.

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

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

Schema coverage is 67%; 'media' and 'project' are documented, but the integer 'points' parameter has no description in the schema and the description only hints at it via 'sampled.' The 1-2000 range and default behavior are left unexplained.

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

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

Names a specific resource (peak and RMS audio levels) plus the normalized range 0-1, so an agent knows exactly what comes back. It does not differentiate itself from siblings like measure_loudness, detect_silence, or waveform_image, which cover adjacent ground.

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 clause 'for finding silence, beats or the loudest moment' gives intended use cases, which is more than nothing. But it never says when to prefer this over detect_silence or measure_loudness, nor any exclusions or prerequisites.

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