Takes for Mac

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

Annotations establish the safety profile (readOnlyHint=false, destructiveHint=false, closed world), so the bar is lower. The description adds genuine behavioral value beyond that: the storage is an APFS clone with 'no extra disk space' and the clips become visible on the Assets tab, which is context the annotations do not convey.

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

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

Two tight sentences: the action and its destination are front-loaded, the APFS parenthetical earns its place by explaining the no-cost behavior, and the final sentence adds the prerequisite without padding.

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

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

For a two-param mutation tool with no output schema and annotations already covering safety, the description is nearly complete: it states the destination, the disk behavior, and the visible result. It omits edge cases such as what happens if a clip already exists, but this is a minor 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 description coverage is 100%, so both parameters (session, files) are already fully documented in the schema. The description's 'use the file from list_broll' merely echoes the schema's files hint and adds no new format or syntax detail, so baseline 3 applies.

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

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

Specific verb ('Put b-roll clips') plus resource and destination ('into a session's broll/ folder'), with the visible effect ('show on its Assets tab next to the takes'). It also names the sibling list_broll as the file source, so an agent can distinguish it without opening schemas.

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

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

Clear context and a prerequisite: files should come 'from list_broll', which implies the workflow order. It does not, however, address when to use this versus a similarly named sibling such as save_broll, leaving that distinction to inference.

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

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

Annotations mark it non-read-only but non-destructive and open-world; the description adds genuinely new behavioral facts by naming the concrete outputs (generated/<file>-<voice>-vN.wav plus an .mp4 when video is present), which reassures the agent that originals are not overwritten. It also implies the ElevenLabs account dependency. It does not say whether the render is synchronous or must be polled via run_job/get_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?

Front-loaded with the core action, then scope, then outputs — a sensible ordering. It is dense but every clause carries information; only the slightly colloquial 'Say a clip again' opening costs it a point.

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 mutation tool with no output schema, the description covers the operation, the duration cap, the voice source and the produced artifacts. The notable remaining gap is execution behavior — whether this returns immediately or produces a job that must be polled through the sibling run_job/get_job.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint absent from the schema: start/end selection is capped at 5 minutes. It also frames file vs session as alternative sources and clarifies that voice comes from the ElevenLabs account, adding meaning beyond the field blurbs.

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: re-perform a recorded clip in a different voice via the ElevenLabs voice changer, preserving words, timing and emotion. That is far more informative than the bare name and implicitly separates it from text-to-speech siblings like voiceover, though no sibling is named explicitly.

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

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

Usage is implied rather than stated: 'The user acts the line, a character voice comes out' tells the agent this operates on already-recorded audio, and 'whole file or start/end' hints at scope choices. There is no explicit when-not or pointer to an alternative tool (e.g. voiceover for synthesizing new speech), so the agent must infer the routing.

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

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

Annotations only state readOnlyHint=false, destructiveHint=false, openWorldHint=false, which leaves the tool's actual behavior largely undisclosed. The description does add useful result-state semantics (a pass returns null, a skip explains why, a failure should be surfaced to the user), which is genuine value beyond the annotations, but it omits permissions, cost and whether the check itself mutates anything.

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 short, but the telegraphic, ungrammatical phrasing ('A failure looks wrong: tell the user its say') makes several sentences hard to parse and the front-loaded intent competes with ambiguous fragments. Brevity here costs comprehension rather than adding it.

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 tool with full schema coverage and no output schema, the description covers the essentials: what it checks, the retry loop, and the pass/skip/fail result states. Missing are the concrete failure categories it can report and what the caller is expected to do with a skip, which keeps 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%, so file, source and session are already documented, including the note about old paths surviving renames. The description adds no parameter-level syntax or usage nuance, 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 verb 'check' and resource 'edit' are present, and the description clarifies it validates an edit against its source take on dimensions like sound, picture, sync and rules. However, the phrasing is garbled ('tell the user its say', 'rules with a check') and no sibling tool is named or contrasted, so the agent gets only a rough sense of 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?

It does give a trigger ('Check each new edit before you show it') and a follow-up loop ('Fix each failure in a new version and check that'), which is more than implied usage. But it names no alternative tools and gives no exclusion conditions, so the routing guidance is partial.

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

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

Goes well beyond the annotations (which only cover read/write/destructive/open-world flags) by disclosing asynchronous background execution, a runtime estimate (~15-60 s per minute of audio), the produced 'file' WAV artifact, and that on=false keeps cleaned files. This is exactly the behavioral context an agent needs for a long-running 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?

Front-loads the core purpose and then layers workflow and timing in short clauses with no filler. The parentheticals are dense but each earns its place; slightly heavy for a single paragraph but appropriately sized for a 7-param async tool.

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

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

With no output schema, the description compensates by explaining where the result appears ('voice' under the take, 'file' when done) and how to consume it in edits. Remaining gaps are error/failure handling and confirmation of idempotency, which are minor relative to what is 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 description coverage is 100%, so every parameter is already documented in the schema; the description adds workflow context (which call starts vs. updates) but no per-parameter syntax or format beyond what the schema provides. Baseline 3 applies when the schema carries the semantics.

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

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

States a specific verb-and-resource ('make a take's voice sound like a proper mic') and enumerates the processing chain (echo, noise, clipping, hum, EQ, compressor, loudness), so the operation is unambiguous. However, it never distinguishes itself from the many voice siblings (change_voice, design_voice, voices, voiceover), 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?

Gives clear operational context: the first call starts a background job, later calls just change settings, and get_session is the way to observe progress. It does not, though, state when to prefer this over the neighboring voice tools, so exclusions are absent.

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

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

Goes well beyond the annotations by disclosing merge semantics (tokens.json merges by token name), overwrite policy (existing files skipped, never overwritten), and the destructive effect of move=true trashing source files. This is exactly the behavioral detail an agent needs for a destructive 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?

Dense but front-loaded, with the copy-to-new-style workflow stated first and behavioral caveats (merge/skip/move) following. Every sentence carries information; 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 destructive, no-output-schema mutation tool, it covers the essentials: source/target forms, item scope, merge/overwrite behavior, and the move side effect. Return values and error handling are unstated, a minor gap given the annotations.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning on top: concrete example item paths and the semantic outcome of the items parameter (merge for tokens.json, skip for others, omit for everything).

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 (copy library files from one library to another) and enumerates the valid library forms. Clearly distinguishes itself from read-only siblings like get_library and save_to_library.

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

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

Gives a concrete use case ('copy to a new style:<Name> to start a new style from an old one') that tells the agent when this tool is the right choice. It lacks explicit when-not or named alternatives, but the context is clear.

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

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

Annotations cover the safety profile (non-read-only, non-destructive, non-open-world), and the description adds real behavioral context: variants surface as tabs the user compares/edits/comments on, and only the main post is scheduled. It does not state whether adding variants overwrites or merges with existing ones (relevant given delete_variants/promote_variant siblings), so it stops 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?

Four dense sentences, front-loaded with what the tool does, followed by sequencing, editing, and the sibling alternative. 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 3-parameter mutation tool with no output schema, the description covers purpose, ordering, UI behavior, and alternatives, which is nearly complete. It leaves the return/confirmation behavior and the merge-vs-replace semantics of existing variants unstated, a minor 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, but the description adds meaning beyond the schema: it introduces the variant slug identity used later with set_post variant=<slug>, and illustrates the 'name' field with real examples ('Story first', 'Shorter', 'Single tweet').

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 (add) and resource (other versions of the session's LinkedIn or X post) with concrete examples of variant types. It is clearly distinguishable from set_post (main post), set_post_hooks (different openings), and promote_variant/use_post_variant (selection).

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 sequencing is given ('Write the main post with set_post first'), along with how to edit later ('set_post variant=<slug>') and the disambiguating alternative for a different use case ('For different openings of the same post use set_post_hooks'). The agent knows when and when not to call this.

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, closed-world write, so the safety profile is covered. The description adds the useful semantics that the created object is a library folder, but says nothing about what happens on duplicate names, required permissions, or what is returned.

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

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

A single front-loaded sentence with no filler; the parenthetical clarification earns its place by defining an otherwise ambiguous domain term.

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 creation tool with no output schema, the description is minimally adequate but leaves the agent guessing about success behavior and what identifier comes back, which matters for chaining into create_session or save_to_library.

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, fully documented in the schema (100% coverage), and the description adds no format, length, or uniqueness constraints beyond it. Baseline 3 applies when the schema does all the work.

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

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

Specific verb + resource ("Create a project") plus a clarifying gloss that a project is "a folder in the Takes library," which disambiguates it from the many other create_* siblings. It stops short of naming how it differs from create_session or create_style, but the resource is unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no pointing at siblings such as list_projects or create_session. The agent must infer context entirely from the name.

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

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

Annotations declare this is a non-readOnly, non-destructive write, and the description adds behavior beyond that: the session is 'offered in the Takes app unless open=false', pointing at a side effect. It doesn't mention permissions, whether a session is created in an existing project, or what happens on duplicate titles, but for an annotated creation tool this adds useful side-effect context.

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 sentence, front-loaded with the core action, then the open=false caveat. Efficient and readable, though the parenthetical 'see open_in_app' points at another tool rather than resolving the behavior inline.

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 main creation flow, the required title, and the app-offering side effect. Without an output schema, it could say more about what is returned (a session id?) and how variants relate to the session, but for a 5-param tool with full schema coverage it is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents title, script, project (created if missing, default Inbox), variants shape, and open default. The description repeats 'title' and 'script' but adds little new parameter detail. Baseline 3 is appropriate when schema carries the parameter burden.

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

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

States a specific verb+resource ('Create a recording session') and enumerates the key inputs (title, teleprompter script, optional variants). Clear enough to distinguish from siblings like create_project or create_variants, which are named differently for different resources.

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 notes the 'open=false (see open_in_app)' branch, which hints at a usage condition for app offering. But it doesn't say when to use this versus create_project, update_session, or create_variants — usage is implied rather than stated.

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

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

Annotations cover the safety profile (not read-only, not destructive, closed-world), and the description adds genuinely new behavioral detail beyond them: it creates a folder with status 'new' and returns an ordered set of steps. The 'keeps or trashes it' framing usefully signals the result is provisional and discardable, though nothing is said about auth or rate limits.

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

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

The action and its inputs are front-loaded in the first clause, followed by creation outcome and the downstream user step. Three sentences with little waste, though the closing sentence about comparison on the Styles board is more narrative than operational.

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 summarizing the returned pipeline steps and the provisional 'new' status of the created style folder. Complete enough to call the tool correctly; only the relationship to set_style and variant tools remains 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 description coverage is 100%, so all four parameters are already documented, establishing the baseline of 3. The description enumerates accepted source kinds (link, video, image, words), which adds slight meaning over the schema's 'link, file path or words' but does not clarify name/template usage.

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

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

States a specific verb and resource ('Start a new style from an example'), plus the kinds of source material accepted, so an agent knows exactly what gets created. It does not explicitly contrast itself with the sibling set_style (which presumably applies an existing style), so it falls short of full sibling differentiation.

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

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

Usage is implied through the intended flow ('The user compares it with the other styles on the Styles board and keeps or trashes it'), which conveys the create-then-evaluate context. There is no explicit when-to-use/when-not-to-use statement and no alternative named relative to set_style or the variant 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, destructiveHint=false, openWorldHint=false, so safety profile is known. The description adds valuable behavioral context: variants appear as tabs, users can pick one as main, and the tool avoids overwriting the main script. It doesn't cover rate limits or permissions, but the core behavior is well explained.

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 concise sentences that front-load the core action and then provide the key usage guideline. No wasted words; every sentence adds value.

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 tool's simplicity (2 required params, no output schema, clear annotations), the description provides all necessary context: what it does, how variants behave, and when to use it versus overwriting. Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by giving examples of variant names ('Punchy hook', 'Story first') and explaining that each variant shows as a tab, which clarifies the purpose of the 'variants' array beyond the schema's structural definition. This extra context warrants a 4.

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

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

The description clearly states the action (add alternative versions) and resource (the script). It distinguishes itself from siblings like update_variant or promote_variant by explaining the creation of multiple variants as tabs, and explicitly says to use this instead of overwriting the main script.

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

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

Explicitly states when to use this tool: 'Use this instead of overwriting the main script when offering options.' It also contrasts with the implied alternative of overwriting, giving clear guidance on 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 sparse annotations, the description discloses critical behavior: it fixes the take's audio offset and frame rate, moves cut points inside words to the word's edge and lists them in 'moved', uses clean voice when clean_voice is done, writes specific output files, and returns either 'done' or a job depending on cut length. These are substantive operational details not captured by 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?

The description is front-loaded with the core purpose and then layers in behavior, limitations, alternatives, and outputs. It is dense but every major point serves the agent; it is longer than a minimal description, though appropriate for a complex tool with no output schema.

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

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

For a mutation tool with no output schema and only basic annotations, the description covers the important missing context: what it fixes, what it writes, length-dependent return behavior, edge-case handling, and alternatives when the tool cannot perform a requested edit.

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

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

Schema description coverage is 100%, so the schema already documents session and the nested segment fields. The description repeats the segment shape and adds only that rough_cut's cut has the same shape, which provides mild contextual help but does not add syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource: cutting takes into one clip with constant frame rate, synced voice, and word times. It explicitly distinguishes itself from set_best_cut by noting that set_best_cut only marks a range while cut_take makes the video.

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 identifies itself as the default for cutting a take and clearly lists when not to use it (J/L cut, speed change, cut inside a word, effect), directing the agent to use its own ffmpeg instead. It also names set_best_cut as a related alternative and explains the division of labor.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds meaningful context beyond them: this is a soft delete to Trash rather than a permanent purge, and the variant text remains retrievable via post history. That recoverability detail is exactly the kind of behavioral nuance the annotations cannot express.

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

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

A single front-loaded sentence with zero waste. The most important fact, that variants go to Trash rather than being destroyed, leads the statement.

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

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

For a 3-parameter mutation with no output schema, the description covers what happens to the affected data and that text survives in history. It omits any note on restoring trashed variants or partial-failure behavior, but the core action is adequately explained.

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 session, platform, and variants are all documented in the schema itself. The description adds nothing about parameter syntax, formats, or the enum values, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Move post variants to the macOS Trash'), so an agent knows exactly what is affected. It does not differentiate itself from the similarly-named sibling delete_variants, leaving the agent to infer the difference from parameter shapes.

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

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

There is no when-to-use, when-not-to-use, or alternative guidance. The agent cannot tell from the text when this is preferred over delete_variants or trash_sessions, so it must infer the routing.

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

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

Annotations already flag destructiveHint=true, but the description adds genuinely new behavioral context: deletion is a move to macOS Trash, and the underlying text persists in history. That tells the agent the effect is recoverable in principle, which the annotations alone do not convey.

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

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

One sentence, front-loaded with the action, with the parenthetical reserved for the one piece of non-obvious information. No filler or repetition of schema content.

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

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

For a two-parameter destructive tool with no output schema, the description covers the essential behavioral fact (soft delete, history retained). It is slightly thin on whether the operation is reversible via a restore path or what a caller should expect afterward, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, with both 'session' and 'variants' fully documented in the schema, so the description carries no additional parameter burden. It adds no format, id-provenance, or batch-size detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Move variants to the macOS Trash") and clarifies the operation is a soft delete rather than permanent removal. It does not distinguish itself from near-neighbours like delete_post_variants or trash_takes, so the agent must infer the target type from the name alone.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named. With siblings such as delete_post_variants, trash_takes, and trash_sessions in the toolset, an explicit statement of which variant scope this covers would have been valuable.

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 it is a non-read-only, open-world, non-destructive operation. The description adds real behavioral detail beyond that: it writes three mp3 files to specific paths (generated/voice-<name>-1..3.mp3 when session-scoped, otherwise _library/voices/) and surfaces them on the Assets tab. It stops short of saying whether re-running or saving overwrites anything.

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 purpose and stays within a few sentences, with every clause carrying information. The parenthetical file-path detail makes the middle slightly dense, but nothing is redundant.

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

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

For a 6-parameter, no-required-params tool with no output schema, the description covers the design/save lifecycle and where samples land. It does not clarify the default behavior when session is omitted beyond the library-path hint, a minor 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 adds value by explaining how save and name interact — save carries a sample's save id and name labels the kept voice — which is the trickiest part of the two-call flow, pushing it slightly above 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?

It states a specific verb and resource ('Design a new ElevenLabs voice') and gives a concrete example query ('warm German woman, 40s, calm, slow'). The word 'new' distinguishes it from sibling voice tools like change_voice, clean_voice, and voices, which act on existing voices.

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

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

The description lays out the two-phase workflow explicitly: call once to write three samples, then call again with save=<sample save id> plus name to keep one. That is clear context for correct invocation, though it states no when-not-to-use conditions and never names an alternative sibling.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) it discloses that files are written (generated/<file>-fix-vN.wav and an .mp4), that the source file is auto-transcribed when no <stem>.words.json exists, the 0.8-1.25x speed window needed to preserve timing, the dependency on an ElevenLabs account, and the lip-sync limitation. These are exactly the side effects and constraints that structured fields do not carry.

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

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

The purpose is front-loaded, but the body is a run-on packed with implementation detail (backend names, file naming conventions, speed math) that is hard to parse on first read. Some of it earns its place as behavioral disclosure, but the paragraph would benefit from being split into purpose, inputs, and outputs.

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 14-parameter write tool with no output schema, the description does the heavy lifting an agent needs: what gets produced, where it lands, and the on-camera lip-sync caveat. It is only missing explicit sibling routing and any permission/account prerequisites beyond the implicit ElevenLabs dependency.

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 3 is the baseline, but the description adds real meaning: how 'old' is resolved (words as said from the transcript, or start/end in seconds), how 'near' disambiguates repeated words, and what the default voice is. It stops short of explaining the stability/style/similarity defaults in any depth beyond what the schema already says.

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

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

The opening clause gives a concrete verb and resource: 'Correct what was said in a take or clip,' which is distinguishable from siblings like change_voice, voiceover, or clean_voice. However, the rest of the sentence buries the purpose under backend mechanics (ElevenLabs vs. Takes, word-edge splicing), making the core action slower to extract than it should be.

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 tool is for fixing already-recorded words in a take or clip, and the 'old' parameter discussion hints at the transcript/word-level workflow. There is no explicit when-to-use vs. when-not-to-use guidance and no routing to siblings such as voiceover or change_voice, which an agent would plausibly confuse this with.

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 genuinely useful behavioral context: what fields video vs image vs text comments carry (rect, frame, said, quote), and how to interpret them, which goes beyond annotations.

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

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

One very dense run-on sentence cramming comment-payload syntax into a tool description. Poorly front-loaded and hard to parse; the comment-content details would better belong in an output description.

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

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

Read-only, schema is fully described, but there is no output schema, so the description attempts to convey the return shape (frame, said, quote). It partially covers this but in a cramped way and omits pagination or 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%, so the schema already documents all four parameters. The description's mention of 'pass library, not session' adds a small routing nuance but mostly restates the file/status/enum semantics 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?

Dense description conveys that it retrieves review comments, but it's buried under extensive schema-like detail about comment payloads. It doesn't cleanly state verb+resource up front, and doesn't distinguish from the sibling reply_comment.

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 hints at usage ('pass library, not session', 'read it to see what the comment means', 'Default: open comments'), implying a retrieval context. But there is no explicit statement of when to use this versus alternatives, and no 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=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: that the response includes the exact commands used to build the edit and the versions preceding it, which tells the agent the payload is large and historical rather than a snapshot.

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 dense sentence plus one short pointer sentence, with the core purpose front-loaded before the parenthetical detail. The list of recipe components is compact, though the trailing 'the versions before it' phrasing is slightly loose.

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 by enumerating what the recipe contains and noting that prior versions come with it, and the sibling pointer disambiguates from get_session. It still leaves unstated things like response size or how versions are keyed, but nothing that would cause a mis-call.

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

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

Schema description coverage is 100% and both parameters are well documented in the schema (including the 'hook' / 'hook-v4' / path forms and the default newest behavior). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('The recipe of an edit') and then enumerates its actual contents (cut list, voice, layers, music, sfx, cover, checks, commands, prior versions). It also names the sibling get_session and clarifies that get_session is a 'short form of the newest one', so an agent can distinguish the two without opening a schema.

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

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

The comparison to get_session ('shows a short form of the newest one') implies when to reach for this tool: when the full recipe or historical versions are needed. It stops short of an explicit 'use X when..., use this when...' rule or any exclusion, so it is strong but not fully prescriptive.

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, non-destructive, non-open-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the annotations: the blocking-wait semantics of wait_s, the ability to re-call to continue waiting, and that the session-only form returns jobs ended in the last day. It does not cover error/timeout behavior of the wait, which is a minor gap.

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

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

Three tight sentences with the return profile front-loaded, followed by wait semantics and the session mode. There is little waste, though the parenthetical 'other takes tools wait too' is awkwardly phrased and slightly obscures meaning rather than earning 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?

For a read-only getter with no output schema, the description usefully enumerates the returned fields and covers both invocation modes, which is what an agent needs to call it correctly. The remaining gap is how waiting interacts with errors or timeouts, but overall it is complete for this tool's 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the operational meaning of wait_s (blocks until the job ends in this call; re-call to keep waiting) and the session-without-id listing behavior, neither of which the schema states. Only the id parameter gains little extra meaning beyond its schema 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 the resource (a job) and enumerates exactly what is returned: status states, progress, time left, log lines, exit code and files. It implicitly distinguishes itself from the write-side siblings run_job/stop_job, though it never names them. The verb is implied ('get') rather than stated, but the resource+return-profile is specific enough to identify the tool.

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

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

It explains two distinct calling modes — passing wait_s to block until completion (and calling again to keep waiting), and passing session without id to list recent jobs. That is real usage context. However it never names an alternative tool or a when-not condition (e.g., vs higgsfield_status, replicate_status, or stop_job), so the routing guidance is only implied.

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

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 goes well beyond them by itemizing the returned payload (style name and template, README.md style guide, tokens.json colours/type/spacing/radius, assets by group with every version, fonts, open comment counts, merged tokens). This substitutes for the absent output schema. It stops short of describing size, caching, or pagination behavior.

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

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

The instruction-bearing clause is front-loaded, which is good, but the middle is a single dense run-on stringing together several parenthetical enumerations of payload fields. Every element is informative, yet the absence of sentence breaks or grouping makes it harder to scan than it needs to be.

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

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

With no output schema, the description carries the full burden of describing return values and does so concretely, covering the style, both libraries, and the merged tokens. The session-vs-project parameter interplay is left to the schema text, which already covers it 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 both parameters are documented in the schema, which sets the baseline at 3. The description adds real semantic value on top by explaining that omitting 'project' switches the tool to returning the list of styles rather than a specific style's merge, which is behavior the schema text does not state.

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

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

The opening clause gives a specific verb and resource ('Read the style a video uses') and the description goes on to enumerate exactly what is returned, so it is clearly distinguishable from write-side siblings like set_style, create_style, and copy_library. The only weakness is that 'the style a video uses' versus the large library payload takes a full paragraph to disambiguate.

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 situational guidance ('Read it before you design anything: a thumbnail, captions, a motion graphic, a slide') and notes the no-project mode yields the list of styles. It does not name alternatives or state when not to use it, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing the return shape (next_gap, buffer semantics) and the empty-state behavior, which matters because there is no output schema. It stops short of pagination or error behavior, so a 4 rather than a 5.

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

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

Front-loaded with what the tool returns, then usage, then the fallback path — good ordering. The first sentence is a dense list that runs long, but every clause (next_gap, buffer, ready posts) carries distinct information rather than filler.

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

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

With zero parameters and no output schema, the description carries the full burden and meets it: it describes the returned fields, defines next_gap and buffer, and covers the no-plan empty state with the corrective next step. Nothing essential for calling it correctly is missing.

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

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

The tool takes no parameters, so there is nothing to document and the baseline is 4. The description does not need to add parameter meaning.

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

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

States a specific resource (the user's posting plan) and enumerates exactly what it contains: weekdays, slots in the next 14 days, next_gap, buffer, and ready posts with no time. This clearly separates it from set_plan (writes the plan) and get_post_queue (post statuses), so an agent can pick it without opening a schema.

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

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

Gives two concrete triggers: tying a new take or edit to a fillable slot, and suggesting a time when the user marks a post ready. It also handles the negative case explicitly — 'No plan yet: ask the user which days, then set_plan' — naming the sibling to call next.

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

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

Annotations already establish a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful context beyond them: the per-item 'action' field values (schedule, move, replace text, delete, nothing) and the timezone semantics (this_mac vs LinkedIn's scheduler zone). This is meaningful behavioral context, not restatement.

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 resource definition before the field enumeration, and there is no filler. The single long sentence dense with parentheticals is slightly heavy but every clause (fields, timezone, action) carries information that would otherwise be missing.

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 enumerating the returned fields (platform, session, title, text/tweets, media_path, status, at, action) and explaining timezone behavior. Combined with fully-covered params and safety annotations, an agent has what it needs; only pagination/ordering edge 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?

Schema coverage is 100%, so all three optional params are documented in the schema and the baseline is 3. The description reinforces the default filter ('marked ready or that is scheduled', LinkedIn/X only) but adds no syntax or edge-case detail beyond the schema's enum and defaults.

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 resource precisely ('the posting plan') and scopes it clearly: LinkedIn and X posts that are marked ready or scheduled, across all projects, sorted by time. This distinguishes the default output from drafts and posted items. It stops short of naming a sibling to route against, so 4 rather than 5.

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

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

Usage is implied through context ('The user sets the times with [schedule] on the post tab, or asks you to pick them'), which hints at when the queue is relevant. However, there is no explicit when-to-use statement or named alternative (e.g. post_history, get_plan), leaving selection to inference.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, but the description adds non-obvious behavior: rules are surfaced once per chat via get_session/next_path, once via a write tool, and the no-area response changes to counts with a 'full=true at 10' threshold. This is meaningful operational context beyond the annotations, though 'full=true at 10' is left cryptic.

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

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

Front-loaded with purpose, but the body is a single sprawling sentence packing the entire step taxonomy inline plus two more run-on sentences of behavioral rules. Every element is arguably useful, yet the structure makes it hard to scan and could be tightened without losing content.

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

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

For a read-only, single-optional-parameter tool with no output schema, the description covers purpose, usage timing, dedup semantics, and the no-argument default. Only the unclear 'full=true at 10' convention leaves a gap an agent might need to resolve.

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 'area' including the 'post'/'edit'/'all' shorthands. The description nevertheless adds the default behavior when area is omitted (step list with rule counts), which the schema does not state, giving extra value over the baseline 3.

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

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

The description states a specific resource ('the rules learned from the user's comments') and its organization ('one file per step'), enumerating the step taxonomy (plan, make, package, publish, engage). It is distinguishable from siblings like set_rule or check_edit, though the phrasing is dense and the 'read rules' framing only emerges in the second sentence.

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

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

Gives explicit timing ('Read and follow the steps you work on before you write, edit or design') and names alternative discovery paths ('get_session and next_path show new ones once per chat; a write tool shows unseen ones once'), which tells the agent how rule surfacing differs across sibling tools. No explicit when-not-to-use, but the context is clear.

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

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 contributes one useful behavioral fact beyond that: the tool returns the entire text rather than metadata. It says nothing about size limits, pagination, or error behavior for an unknown version id.

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 zero filler, and it leads with the verb and the payload ('full text'). It is efficient, though arguably too thin to be maximally useful.

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 only two parameters, full schema coverage, and read-only annotations, the definition is serviceable. But there is no output schema, and the description only vaguely gestures at the return value ('full text') without noting scope or failure modes, leaving a modest 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 description coverage is 100%, so both 'session' (with its rename-tolerant path note) and 'version' are fully documented in the schema. The description adds no format or provenance detail beyond the schema's own note that the id comes from the history list. Baseline 3 applies when the schema does the work.

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

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

The description gives a clear verb ('Get') and result ('the full text'), making the operation unambiguous. However, it says 'one saved version' without naming the script resource or distinguishing it from siblings like script_history (which enumerates versions) or restore_script_version (which mutates).

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 prerequisites, and no named alternative. At best the purpose implies you invoke it when you want to read a version's text, which is a tautology rather than 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful behavior beyond that: the chat-scoped 'rules' (only rules this chat has not seen) and the state flag edit_ready. It stops short of describing size limits, pagination, or cost of a large session payload.

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 clause, but the rest is one sprawling run-on sentence that blends return-value documentation, file-location lore, and workflow commands. It is dense rather than wasteful, yet it would be more usable broken into a 'returns' sentence and a 'what to do next' 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?

With no output schema, the description is the only source for the return shape, and it does a thorough job listing takes, assets, folders, warnings, checks, and rules. A few fields (checks/edit states, rules semantics) are alluded to rather than explained, leaving minor gaps for a tool that returns a large aggregate object.

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

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

The single parameter is fully documented in the schema (accepts 'Project/folder', absolute path, or id, and survives renames/moves), so the schema does the heavy lifting. The description adds nothing about the session argument, which is the correct baseline when schema coverage is 100%.

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

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

The description opens with a specific verb and resource ('Get a session') and then enumerates the exact payload: id, title, full script, takes with file path/duration/keeper/name/start time, asset files, folders, warnings, checks, and rules. This is far more than a restatement of the name and lets an agent distinguish it from siblings such as list_sessions or get_edit_recipe.

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 operational context: fix files flagged in 'warnings', cut takes with cut_take and rough_cut by default, and follow the 'rules' for the next step. It names sibling tools as the follow-on actions, but never states when to call get_session itself versus list_sessions or get_script_version, so selection guidance is implied rather than explicit.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds the behaviors that actually matter: it returns at once and the job runs in the background, output lands at <session>/generated/<name>-vN and surfaces in the Assets tab, each job costs the user's Higgsfield credits, and it must be one job per ask rather than a batch. It also discloses the storyboard 'Generating' state transition.

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

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

Front-loaded with purpose, scope, and return behavior before the workflow detail, and nearly every sentence carries operational content. It is still a dense multi-clause block with parenthetical model lists and inline JSON, which makes it heavier to parse than an ideal single-purpose description.

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

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

For a 13-parameter mutation tool with no output schema, the description covers the missing pieces: asynchronous return semantics, where the artifact lands, cost/credit implications, storyboard integration, and the three edit workflows. An agent has everything needed to invoke it correctly without guessing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantics beyond it: shot=<id> binds the clip to a storyboard shot and inherits aspect ratio and length, image='sketch' is a composition-only reference requiring params {mode: omni_reference}, video= plus {mode: video_edit} selects the edit path, and workflow=reframe pairs with aspect_ratio. Default model resolution is also explained.

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

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

Opens with a specific verb+resource ('Make or change a video with Higgsfield') and names the model family backing it (Seedance, Kling, Veo, 30+ more). It immediately differentiates from the nearest sibling: 'Video only: images go to make_image.' An agent can route between this and make_image without opening either schema.

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

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

Gives explicit when-to-use branches: generate vs. change (video=<session file> with mode video_edit), reframe via workflow=reframe, and storyboard use via shot=<id> including how to write the prompt from the shot's do/say. It also states the exclusion (images → make_image) and the fallback when the plugin is missing or unauthenticated.

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 the safe, read-only, open-world profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds useful context by enumerating the job states it reports (running, done, error) and revealing that it probes install/sign-in state. It does not cover failure modes or what happens when Higgsfield is not installed.

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 compact sentence with the primary question front-loaded and the optional session-scoped behavior trailing. Slight awkwardness in the 'with session, its Higgsfield jobs' clause, but 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?

With no output schema, the description carries the burden of indicating what comes back, and it does so at a reasonable level: install state, sign-in state, credit count, and per-job status buckets. Nothing critical is missing for a zero-required-param status probe.

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 `session` parameter's accepted forms ('Project/folder', absolute path, id, rename-tolerant) are fully documented in the schema. The description adds only the semantic that session narrows results to Higgsfield jobs, which is a marginal addition over 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?

The description names a specific verb+resource pair: checks whether Higgsfield is installed, signed in, and how many credits remain, plus per-session job states. This distinguishes it from the sibling `higgsfield` (presumably the generation tool) as a diagnostic/status companion. It stops short of explicitly contrasting with that sibling, so it falls one notch below a 5.

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

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

The phrase 'with session, its Higgsfield jobs' implies two modes of use — call bare for account status, pass `session` for job detail — but this is left to inference rather than stated as when-to-use guidance. No alternatives or prerequisites are named.

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

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

Adds substantial behavior beyond the annotations: the exact file naming scheme (take-NN-[name-]camera.<ext>), automatic take numbering, reading length, and in-place rename vs copy semantics. Annotations only cover the safe-write profile; the description discloses what actually happens to the caller's files, which is the key risk.

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 purpose, then the naming/behavior, then the two invocation modes, then file handling. Dense but every sentence carries information; the session.json warning is a useful guardrail rather than filler.

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

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

For a write tool with no output schema, it covers naming, numbering, list behavior, and copy/move semantics adequately. It is slightly light on failure modes (duplicate names, missing files) but 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 the schema already documents each field, setting a baseline of 3. The description goes further by clarifying the mutually exclusive one-take (path/screen_path) vs. multi-take (takes=[...]) calling conventions and the meaning of move, adding real value 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 verb and resource ('Add recordings that already exist ... to a session as takes') with concrete examples (QuickTime, phone, download). It clearly distinguishes itself from siblings like add_broll, save_broll, and rename_take by describing the import-and-name behavior.

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

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

Gives a clear condition for use ('recordings that already exist') and an explicit anti-pattern ('Never edit session.json by hand'), plus the copy-vs-move rule. It does not, however, name sibling alternatives such as add_broll or save_broll, so the routing guidance is implied rather than explicit.

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

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 context beyond that: the storage path structure, the full set of returned attributes, and the fact that the user sees the same clips in the app's B-roll tab. No pagination or ordering behavior is disclosed.

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

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

Roughly three tight sentences, front-loaded with what it lists, then the return fields, then usage. The trailing app-tab sentence is slightly peripheral but still helps the agent understand the user's mental model.

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

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

No output schema exists, but the description enumerates the returned fields (title, folder, filmed, orientation, duration, description, keywords, path), which compensates. For a read-only list tool with annotations carrying the safety profile, nothing critical is missing.

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

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

Schema coverage is 100%, so query/folder/orientation are already fully documented in the schema, including the enum values. The description reinforces the content of folders and the filmed YYYY-MM field but adds no new parameter syntax or semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the user's own b-roll') and pins the scope to _library/broll/<folder>/ with concrete examples of content. It distinguishes 'the user's own' clips from generic media, though it never names the sibling it is not (e.g. search_media, phone_videos).

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

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

Gives a clear when-to-use: 'Use it for B-ROLL shots in a storyboard or an edit before asking the user to film new b-roll.' This frames the decision point well, but offers no explicit when-not or named alternative for discovering non-owned media.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is low, and the description still adds real behavior: new downloads from the Epidemic Sound source folder are copied in first, and playback only ever plays the single file, never a song beside it. The ffmpeg mixing instruction is genuinely useful invocation context, though the phrasing around it is muddled.

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

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

Purpose and usage are front-loaded, but the body drifts into tangential material — the explanation of what SFX are (whoosh, pop, typing) and the ffmpeg mixing/voice-over passage read as production coaching rather than tool definition. Trimming those would sharpen an otherwise efficient opening.

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

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

There is no output schema, and the description compensates by enumerating the exact fields returned and the side effect of importing new downloads. Combined with the two optional filters, an agent has enough to call it and interpret results, though it never says whether an empty library or no-match query returns an empty list.

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

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

Schema description coverage is 100%, so the schema already documents both `group` (Music or SFX, omit for all) and `query` (words in the file name). The description adds the field list returned but no extra semantics for the parameters themselves, so the baseline 3 applies.

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

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

States a specific verb and resource (list the user's music and sound effects) and enumerates the returned fields (file, title, artist, genre, bpm, duration, path), which no sibling like list_broll or search_media claims. An agent can tell it apart from the other library/media tools without opening a schema.

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

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

"Use for picking a song or an SFX for an edit" plus "The app's Use button asks you for this" give clear triggering conditions. It stops short of naming alternatives (e.g. search_media for cross-library lookups, get_library for general assets), so there is no explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that each project is returned with a session count, which is useful, but says nothing about ordering, pagination, or whether empty projects appear.

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

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

Two short sentences, front-loaded with the resource and its payload, and the entry-point cue placed last where it is most useful. 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 zero-parameter, read-only listing tool whose annotations carry the safety profile, this is nearly complete. The only real omission is what an agent should do after listing projects, which is hinted at by "Start here" but not spelled out.

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

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

The tool takes zero parameters, so the schema leaves nothing to explain; per the rubric this earns the baseline 4. The description correctly implies no filtering input is needed.

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

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

States a specific verb (List) and resource (Takes projects) and adds what the result carries (session counts per project). It is distinguishable from list_sessions because the resource is projects, not sessions, though it never explicitly names that sibling to sharpen the contrast.

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

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

"Start here." implies this is the entry point of a discovery flow, which is mild usage guidance. There is no when-not condition and no explicit alternative named, so the routing guidance is only implied.

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

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

Annotations already establish readOnly/no-destructive, so the safety profile is covered. The description adds genuinely new behavioral detail beyond the annotations: the result ordering (newest first) and the fact that each session carries take and keeper counts, which matters because no output schema exists.

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

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

A single tight sentence with the resource and scope front-loaded and no redundant clauses. Every element (project scope, ordering, returned counts) earns its place.

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

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

For a simple one-parameter list tool with no output schema, the description covers scope, ordering, and payload contents adequately. It omits pagination/limit behavior and filtering options, which are minor gaps for this tool's 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?

With 100% schema description coverage on the single parameter (including the pointer to list_projects), the schema does the heavy lifting. The description adds no syntax or format detail for the project argument, so the baseline 3 applies.

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

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

States a specific verb and resource ("List sessions") plus scoping ("in a project"), ordering ("newest first"), and returned aggregates ("take and keeper counts"). This cleanly separates it from get_session (single) and list_projects (different resource), though it never explicitly names those siblings.

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

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

There is no statement of when to use this versus get_session or list_projects, and no prerequisites or exclusions. Usage is only inferable from the verb and the project-scoped 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing latency ('waits about 10-60 s'), the returned artifact path ('<session>/generated/<name>-vN.png') plus the model used, and fallback behavior ('When one model fails the next one draws'). This is exactly the extra context annotations cannot carry.

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

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

The opening sentence is front-loaded and useful, and most sentences carry workflow information that cannot be dropped. However, the prose is dense with nested parentheticals ('flare (GPT Image 2.5 Flare, the default for a new image)'), which hurts scannability and makes the reader reconstruct the flow.

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 mutation tool with no output schema, the description covers what is produced (file path, model, Assets tab), timing, fallback, and the full draft/final lifecycle. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented, but the description adds real workflow meaning: it explains that 'from' redraws a picked draft at 4K with the same prompt, that 'images' takes session files or 'sketch' with shot, and that prompt is optional with from. This is more than restating the schema.

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

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

States a specific verb and resource ('Make or change an image') and immediately scopes the source ('straight from Google or OpenAI'), then explicitly names the sibling it must not use ('never use higgsfield for images'). An agent can distinguish this from higgsfield without opening either schema.

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

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

Gives an explicit draft-then-final workflow, names the conditions that select each model ('flare... default for a new image', 'sunburst... default for a change'), and states exclusions ('Never make a final before the user picks', 'One image per ask'). Alternatives and when-not rules are both present.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds a genuinely useful behavioral note that the target project is auto-created when missing, which annotations do not convey. However it omits what happens to source folder references or whether moves are reversible.

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

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

A single tight sentence with the key side effect in parentheses. 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 two-param mutation tool with annotations and no output schema, the definition covers the essentials but lacks any note on source-state consequences or failure modes. Adequate but with visible 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 coverage is 100% so the schema already documents both parameters. The description adds no format or syntax detail beyond the schema's 'Sessions as Project/folder' note, so baseline 3 applies.

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

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

States a specific verb (move) and resource (sessions) plus target (another project). Distinguishes itself from siblings like trash_sessions, though it doesn't name an alternative explicitly.

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

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

No indication of when to use this versus create_session or trash_sessions, and no prerequisites. The parenthetical '(created if missing)' hints at a side effect but does not frame usage 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 declare readOnlyHint=false with destructiveHint=false, meaning calling this tool has some non-read side effect, yet the description never explains what state changes (presumably reserving/advancing a version). It does add useful behavioral context the schema lacks — that edit/thumbnail calls also return the user's rules 'once per chat,' implying per-session delivery semantics — but the source of the non-read-only flag remains undisclosed.

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 purpose, then compact per-kind pattern lines, then the call-before-write instruction. Information-dense with little waste, though the parenthetical asides ('plus an option word for several') are slightly compressed and require inference.

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

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

There is no output schema, so the description must convey returns — and it does by specifying the returned path shape plus the per-chat rules payload. Combined with the fully documented input schema, an agent has almost everything needed; only the non-read-only side effect is left unstated.

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

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

Schema description coverage is 100%, so the schema already documents kind, name, ext, group, library, and session. The description reinforces meaning by tying kind values to concrete output paths and by noting the -vN suffix is ignored and that library names can create new styles, but most of this duplicates schema text rather than extending 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 function — computing the target folder and next versioned filename for a new asset — and enumerates the exact path pattern for each of the three kinds (edit, thumbnail, library). An agent can immediately tell this is a path-allocation/query tool rather than a writer, though the naming of the tool itself carries less of the meaning than the format examples do.

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

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

It gives an explicit sequencing instruction: 'Call it before you write any of these,' which tells the agent exactly when this tool is required relative to render/write operations. It does not state when it should NOT be used or name an alternative, but the conditional format rules function as 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 only declare readOnlyHint=false / destructiveHint=false / openWorldHint=false, so the description's disclosure that it never steals focus, never plays anything, and merely marks a dot is meaningful added context. It stops short of explaining reversibility or what the user sees on click.

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 then the two qualifying constraints. The final fragment ('Once per finished result...') is terse but earns its place as a usage rule.

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

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

With one fully documented parameter, existing annotations, and no output schema, the description covers what an agent needs: what it does, how it behaves, and how often to call it. Minor gaps (no return/confirmation detail) are not required 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?

Schema coverage is already 100%, so the baseline is 3; the description adds that the single path may point at a project, session, or file (e.g. a new edit), which slightly broadens and disambiguates the schema's own examples.

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 (offer a project/session/file in the Takes app) on a specific resource, and the 'gets a dot and opens only on a click' clause makes the effect unambiguous. It is clearly distinguishable from list/get/create-style siblings because it is about surfacing an item in the app UI rather than manipulating data.

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

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

Explicitly states when to use it ('once per finished result') and when not to ('not for drafts or in-between steps'), which is real dispatch guidance. It does not name a sibling alternative, so it falls just short of a 5.

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

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

Annotations already declare it read-only and non-destructive, so the safety profile is covered. The description goes further by disclosing ordering (oldest first), the transcription cost/engine (~10 s per video, Whisper), and the fact that it also surfaces recent sessions for matching. It doesn't mention pagination or a cap on results, which is the only notable gap.

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

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

Two sentences, front-loaded with the core resource and scaffolded with the flag-driven variations. The second sentence is dense and crams session-matching plus import_take into one clause, 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?

With no output schema, the description carries the burden of describing returns, and it does: fields returned, ordering, and the paired session listing. It omits result-count limits and what the entry identifiers look like, which would have made matching/importing unambiguous.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the time cost and engine for listen=true and the downstream move=true behavior for import_take. That extra context about practical consequences of the flags edges it above 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?

The description identifies a specific resource — videos AirDropped from an iPhone sitting in ~/Downloads — and enumerates what comes back (length, recording time, transcribed opening words). It is clearly distinct from media-oriented siblings like list_broll or search_media. The verb is only implicit ('lists'), keeping it short of a clean 5.

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

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

It gives conditional guidance for the flags (all=true for everything, listen=true to transcribe, import_take with move=true to pull a take in), which is genuinely useful. However, it never states when to prefer this over list_broll, search_media, or next_path, and there is no explicit 'use this when' framing.

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 genuine domain context the annotations cannot: a card reserves that day's posting slot, a post with a time fills it, and the board expands to the card's week. It does not state reversibility or what happens to an existing card on the target day, so this is a modest add rather than rich disclosure.

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

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

Front-loaded with the core action and its three variants, and every later sentence carries domain meaning. Sentences about the thumbnail and user drag-reordering are the softest, but they justify the 'before' parameter and the card model, so waste is low.

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-param mutation tool with no output schema, the description closes the important loops: what a card means, how it interacts with scheduled posts, and what to read afterward ('Returns get_plan'). Only the fate of an already-placed card on the target day and permission expectations 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 description coverage is 100%, so the schema already documents day, before, and session in full (including the empty-day removal and the 12-week limit). The description only loosely reinforces these through its card-ordering narrative and adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource with all three modes spelled out: place a session's video card on a day, move it to another day, or clear the day. It points the agent at the read counterpart ('Returns get_plan') but never distinguishes itself from the sibling set_plan, so an agent comparing the two must still open the schemas.

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

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

'Use it when the user asks you to plan videos; one call per video' gives an explicit trigger and a batching rule. It also encodes the removal condition (day empty). There is no explicit when-not guidance relative to set_plan or set_post, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the ordering of results, the fields returned (version, draft, author, note, created, preview), and the lifecycle fact that a version is saved on every Claude change and while the user edits.

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 scope and ordering, then the field list, then the how-to for the optional parameter. Every clause carries information, with no filler or restated 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 appropriately documents the returned shape and ordering, and the parameters are fully covered by the schema. Minor gaps remain (pagination/limits, behavior when no versions exist), but nothing that would cause a misinvocation.

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 documented in the schema itself, setting the baseline at 3. The description's only added meaning for 'version' ('get its full text ... to compare with the current post') largely restates the schema text 'Optional: one version's full text.'

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

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

States a specific resource ('Every saved version of the post and its variants') and a concrete scope ('newest first'), then enumerates the returned fields. An agent can distinguish this history-listing tool from sibling mutators like restore_post_version or delete_post_variants without opening either schema.

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

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

Gives a clear context cue — 'Pass version to get its full text, e.g. to compare with the current post' — which tells the agent when the optional parameter matters. It stops short of naming alternatives (e.g. restore_post_version) or stating when not to use this tool, so it falls below the explicit when/when-not bar.

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

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

Annotations already declare this a non-read, non-destructive, closed-world write. The description usefully goes beyond them by disclosing the fate of the prior state: 'The old main stays in history,' which explains the mechanism behind destructiveHint=false and implies reversibility. It does not mention auth/permission requirements, keeping it short of a 5.

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

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

Two short sentences, zero waste, with the core action front-loaded and the consequential side effect stated immediately after. Appropriately sized for the operation.

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

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

For a simple two-parameter mutation with no output schema, the description covers what happens to both the promoted variant and the displaced main, which is the key contextual fact. It stops short of noting any side effects on dependent posts/scripts, which would round it out.

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

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

Schema description coverage is 100%, so both parameters ('session' with its id/path/rename handling, and 'variant') are fully documented in the schema. The description adds no parameter meaning beyond that, making 3 the correct 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?

The description states a specific verb ('Make... the main script') and resource ('a variant'), so the operation is unambiguous. However, it does not differentiate itself from related siblings such as update_variant or restore_script_version, which an agent might plausibly confuse with promoting a variant.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named despite close siblings (update_variant, restore_script_version, use_post_variant). The agent must infer the routing from the tool name alone.

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

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

Goes well beyond the annotations (which only declare non-read-only, non-destructive, closed-world) by disclosing refusal conditions ('it refuses on a failed check'), the accept override, the post-side effect ('puts the version on the posts that follow this edit; a version the user picked stays'), the comment-side effect (fixed_in/resolve auto-set), and concurrency handling ('go_back' for a newer saved version). This is exactly the mutation context the annotations cannot carry.

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

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

Front-loaded with the core action, and every clause adds distinct information (refusal, accept, post placement, comment replies, note, once-per-version, set_post fallback). It is a dense run-on paragraph rather than a scannable list, which costs a point, but there is little waste.

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 six-parameter mutation tool with no output schema, the description covers refusal, side effects, sequencing, and the follow-up call. It omits only minor detail such as error surface or what the saved version returns, which is a small residual 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 already 100%, so baseline is 3, but the description adds relational meaning: accept is '[{rule, why}] for a fail you meant', replies behave 'like reply_comment' with fixed_in/resolve set for you, and note becomes the changelog line. These tie parameters to workflow behavior rather than restating field docs.

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 ('Save a checked render as the next version, edits/<name>-vN.mp4, with its recipe') and names the exact artifact produced. It is clearly distinguishable from siblings like render_edit (which produces the render) and set_post (which shows a different file on a post).

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

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

Gives explicit lifecycle guidance ('Call it once per version') and routing to alternatives ('To show another file on a post, call set_post media=... after'), plus the escape hatch for intentionally failed checks via accept. An agent knows when to use this versus its neighbors without inference.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false; the description goes further by disclosing the concrete side effect — renaming the take's files to a specific pattern — and the reset semantics of an empty name. It stops short of covering collision handling, error cases, or whether the take must be in a particular state, 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 short fragments, front-loaded with the core action and then the consequential file-naming effect and reset behavior. Every clause carries information; 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?

For a 3-parameter, no-output-schema tool with full schema coverage and annotations, the description covers purpose, the main side effect, and the reset case. Remaining gaps (name collisions, required take state, or error behavior in a pipeline-oriented toolset) are minor but real.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds meaning the schema does not: what the name parameter actually produces in filenames (take-NN-<name>-camera.mov / -screen.mov) and the NN numbering convention. 'Empty name resets' repeats the schema, so the added value is the rename pattern rather than a full parameter walkthrough.

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 ('Name a take') and immediately names the observable effect on the take's files (take-NN-<name>-camera.mov / -screen.mov), so the agent knows exactly what this tool changes. No sibling in the list (import_take, cut_take, trash_takes, move_sessions) overlaps this rename/name operation, and the file-pattern detail makes the scope unambiguous.

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

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

The description implies the tool's role (naming/renaming a take) and notes that an empty name resets, but it never states when to use this versus adjacent take tools or what preconditions must hold. Usage is inferable rather than explicit, which is the definition of a 3.

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 non-readonly/non-destructive/non-openworld, so the description carries real burden and delivers: it is asynchronous ("as a job"), constrained ("One render of a name runs at a time"), consumes the clean voice once, and forbids using a finished edit as input. It does not explain what rendering destroys or overwrites or what the job result contains, but the added behavioral context is substantive.

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

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

Front-loaded with the core action, but the body is a run-on of parenthetical fragments and embedded field lists that are hard to parse on first read. Much of it earns its place given the complexity, yet it could be tightened and ordered more clearly.

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 6-param tool with nested objects and no output schema, the description covers the recipe/changes distinction, the concurrency constraint, and the handoff to publish_edit, and hints at the async return ("a job"). It leaves open what the job result looks like and how to retrieve it, but the workflow is essentially complete.

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

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

Schema coverage is already 100%, so baseline would be 3, but the description adds meaning beyond the schema: it enumerates recipe fields (name, cut, frame shapes, over, music, sfx, steps, cover), ties cut to rough_cut, and explains merge-patch semantics including list replacement and null removal. These are genuine additions rather than repeats.

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 ("Build an edit from a recipe") and frames the operation as producing a job, which distinguishes it from sibling publish_edit and check_edit. The additions "as a job, and check it" and the field-level recipe walkthrough make intent clear, though the sentence is dense enough that the core action is slightly buried.

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

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

Clearly routes the agent: recipe for a first version, base+changes for a next version, and names the follow-up step ("Returns a job; then publish_edit"). It even gives an operational rule for comparison ("to compare two options, give the second a new name"). It stops short of explicit when-not-to-use or a contrast against get_edit_recipe/check_edit.

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 (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing that the call returns at once while the job runs in the background, exactly where the artifact lands (<session>/generated/<name>-vN.mp4) and how it is surfaced, that each job costs the user money, and the auth prerequisite. Cost and async behavior are the traits an agent most needs and they are spelled out.

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, price model, and the key async/return behavior, so the most important facts come first. The body is dense and sentence-heavy with nested parentheses, but given 13 parameters, nested params, and monetary/async side effects, almost 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?

There is no output schema, yet the description covers the return semantics (returns immediately; file path and Assets visibility), the cost implication, the auth path, and the shot-integration side effect. For a high-complexity open-world generation tool this is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine routing guidance: the named fields map to the model's own input names, and everything else must go into params under the model's names. It also clarifies that image is the FIRST FRAME and sketches must not be used there. It stops short of per-parameter formats (it defers those to replicate_model).

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 ('Make or change a video on Replicate') and immediately distinguishes itself from the sibling higgsfield by naming the same model family and the pricing difference. An agent can tell which video-generation tool to pick 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?

Explicit routing rules: leave model out for the user's default, consult replicate_status for defaults, call replicate_model first to see inputs/defaults/allowed values, use shot=<id> for storyboard integration, and never use the sketch as the first frame for a shot. It also states the hard constraints (one job per ask, no batches, no token → open Plugins › Replicate).

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=true, so the safety profile is covered without description help. The description adds little behavioral context beyond the default-value hint and the shape of the returned input list; it says nothing about auth requirements, rate limits, or failure modes for an open-world call.

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

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

It is short, but it is two loosely joined fragments that are not front-loaded with a clear action. The parenthetical list and the trailing clause mix return-value description with invocation advice, so brevity does not translate into clarity.

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

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

For a single-parameter, read-only lookup with no output schema, the description conveys roughly what comes back and the default behavior. However, it omits any routing guidance among the several Replicate-related siblings and never states the action plainly, leaving a small 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% and the schema already documents the 'model' parameter format ('owner/name, e.g. bytedance/seedance-2.5'). The description adds meaning beyond the schema by explaining that omitting model yields the default, which clarifies the optionality semantically rather than just syntactically.

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 is a sentence fragment that describes what the tool returns (a model's inputs: type, default, allowed values) rather than starting with a clear verb+resource. An agent can infer this is a lookup that returns a model's input schema, but the phrasing 'so a job can set what the user asks for' is confusing boilerplate. It makes no attempt to distinguish itself from close siblings like replicate and replicate_status.

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

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

The only guidance offered is 'Leave model out for the default,' which addresses one parameter case rather than when to call this tool. There is no indication of when to prefer replicate_model over replicate, replicate_status, or run_job, leaving the agent to guess in a crowded Replicate-related sibling set.

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

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

Annotations already declare it read-only, non-destructive, and open-world, so the safety profile is covered. The description usefully adds what the response contains (token-set state, account, default models, job statuses), but says nothing about auth requirements, rate limits, or freshness of the status data.

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 dense sentence with no padding, and the unconditional outputs are front-loaded before the session-conditional clause. However, the semicolon splices two unrelated ideas and the opening 'Is a ...' wording is grammatically broken, hurting scannability.

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

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

With no output schema, the description does the work of enumerating the returned categories (token set, account, default models, per-session job states), which is the essential information for a status tool. The absence of any clarification on how to interpret error-state jobs or stale tokens is a minor 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% and there is a single optional parameter, so the baseline is 3. The description adds a small amount of meaning by clarifying that the session parameter changes the response to that session's job list, but the accepted id/path/rename semantics live entirely in 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?

It names the resource (Replicate token/account/default video models) and the conditional scope (a session's Replicate jobs across running/done/error states), so an agent can tell it apart from `replicate` and `replicate_model`. The phrasing is a fragmentary 'Is a ...' construction, but the enumerated outputs make the purpose concrete.

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

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

The description implies usage via 'with session, its Replicate jobs', telling the agent that omitting session yields account-level status while supplying it scopes to that session. It never states when to prefer this over `get_job`, `replicate`, or `replicate_model`, and gives no explicit exclusions.

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

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

With annotations only declaring readOnly=false/destructive=false, the description carries real behavioral weight: it discloses that resolve=true closes a comment, that a resolved comment in a session requires a lesson, that lesson='new' creates a rule persisting "to the next videos too," and that clicked replies jump to fixed_at. That is substantial state-change disclosure beyond the annotations. It omits permissions, partial-failure behavior, and what a bad lesson/rule id does.

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

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

Purpose is front-loaded and almost every clause carries payload, but the body is a single run-on paragraph that crams batch syntax, field semantics, and a lesson decision tree together without line breaks or lists. Dense enough to be hard to parse even though little is redundant.

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

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

For an 11-parameter, nested, batch-style mutation with no output schema, the description covers the workflow, the batch payload shape, the jump target semantics, and the full lesson/rule taxonomy including merge behavior. An agent has enough to construct a correct call without opening anything else.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds meaning the schema does not: text is "one line ('Caption 20% smaller')", fixed_in is "the new version's file", fixed_at is "the second in it where the fix shows", and it spells out the lesson/missed/'new'/'one-off' decision tree. It also steers toward replies=[...] over the single-id path.

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

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

The opening sentence gives a specific verb and resource ("Reply to review comments and resolve them"), so the agent immediately knows this is the write-side counterpart to get_comments. It is not tautological and is clearly operational. It never names the read sibling (get_comments) explicitly, so it stops short of full sibling differentiation.

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

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

Gives concrete when-to-use guidance: "After a round of fixes, send ONE call with replies=[...] for every comment" buckets replies instead of firing one call per comment, and "Unclear comment: ask a question, resolve omitted" covers the edge case. It does not name an alternative tool for reading comments or for re-replying, so alternatives are implied rather than stated.

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

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

Annotations mark this as a non-read-only write but not destructive, and the description explains why: 'The current text is saved to history first.' That safety mechanism and the conditional target (variant vs main post) are real behavioral context beyond the structured fields, though it omits any permission or error behavior.

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

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

Two tight sentences with the primary action front-loaded and the two important conditions (target location, history backup) packed into parentheticals. No wasted words, though it could be marginally tighter.

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

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

For a mutation tool with full annotation coverage, complete schema descriptions, and no output schema, the description covers the essential outcomes: where the restored text lands and what happens to the current text. The main gap is disambiguation from restore_script_version.

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

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

Schema description coverage is 100%, so the schema already documents session, version, and platform thoroughly. The description adds no parameter syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb ('Put an old version back') and resource (post version), and clarifies the destination logic (variant if it exists, else the main post). It is clear on its own, but it does not distinguish itself from the sibling restore_script_version, which is the natural confusion point.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g., version must come from post_history), and no mention of the sibling restore_script_version to disambiguate. Usage is only implied by the tool name and the 'version id from the history list' schema note.

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

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

Annotations declare a non-destructive write (readOnlyHint=false, destructiveHint=false), and the description adds a genuinely useful behavioral fact beyond them: the current text is snapshotted to history first, so the action is reversible. It does not cover failure modes (invalid/deleted version id) or permission requirements.

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

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

A single sentence with zero waste, and the core action is front-loaded ahead of the parenthetical side-effect note. Nothing to trim or reorder.

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 mutation with a fully documented schema, no output schema, and annotations covering the safety profile, the description supplies the missing piece (the auto-snapshot behavior). Only the prerequisite of sourcing the version id from script_history is left 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 description coverage is 100%, so both 'session' (path/id plus rename tolerance) and 'version' (history id) are already fully documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the heavy lifting.

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

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

States a concrete verb ('put back') and resource ('an old version'), making the revert operation unambiguous. It does not explicitly name the sibling it differs from (e.g. restore_post_version or get_script_version), so it relies on the tool name for disambiguation.

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

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

There is no explicit when-to-use guidance, no prerequisite (e.g. obtain the version id via script_history), and no routing to or away from siblings like get_script_version or restore_post_version. Usage is only implied by the verb.

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 it is non-destructive and non-read-only, so safety is covered. The description adds real behavioral context beyond that: exactly what is returned (clip plus dropped-with-reasons and missing script lines) and an explicit instruction to surface dropped/missing results to the user. It still doesn't say whether the cut is persisted or how it interacts with the edit recipe.

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 is dense but purposeful; the return-shape and workflow notes each carry information. There is mild redundancy between 'like cut_take' and 'see cut_take for your own ffmpeg', keeping it from a 5.

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

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

With no output schema, the description correctly describes the return payload (clip, dropped with why, missing) and the intended follow-up workflow. It is complete enough to invoke and act on, though persistence/error behavior is not addressed for this multi-param mutating tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including defaults. The description reinforces the gap semantics ('pauses longer than gap') and the takes ordering ('each script line once'), but adds little beyond structured data. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Make a first cut of the takes against script.md', with concrete scope (each script line once, last full try, no false starts/stutters/ums). It also distinguishes itself from the sibling cut_take ('like cut_take', 'see cut_take'), so an agent can route correctly without opening either schema.

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

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

Gives clear situational context: it is 'only a first draft' and should be improved freely by editing the cut and calling cut_take, which effectively names the follow-up alternative. It lacks explicit 'when not to use' guidance or prerequisites, so it stops short of a 5.

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

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

Beyond the readOnly/destructive annotations, it discloses async behavior (returns a job id at once), that the job outlives the chat and Takes, that progress surfaces in the session's Jobs row, and the shell/cwd the command runs in. This is rich lifecycle context the annotations cannot convey.

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

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

Dense and front-loaded: the primary action and its threshold lead, followed by lifecycle and execution details. Every sentence carries information with no filler.

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

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

With no output schema, the description still covers the return value (job id), the job lifecycle, and how to await completion. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning for 'cmd' by stating it runs in zsh inside the session folder. It adds little for label/outputs/session beyond what the schema already documents.

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

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

States a precise verb+resource ('Run slow work') and enumerates concrete cases (render, Demucs, Whisper, matting, commands over ~30s), distinguishing it from get_job/stop_job and from ordinary Bash execution. An agent immediately knows this is the async long-work launcher.

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 threshold ('over about 30 s') and a hard exclusion ('never as a background Bash job or with sleep'), which is exactly the when/when-not guidance an agent needs. It also points to the wait mechanism via the result note.

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 say readOnlyHint=false but destructiveHint=false, and the description adds meaningful side-effect context: it creates an APFS clone, and Gemini describes the clip in the background and injects description/keywords. However it doesn't describe what happens to the source or how the async Gemini process resolves.

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?

Single dense sentence front-loads the action and destination, with parenthetical clarifications kept short. It is information-dense but not wasteful.

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

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

For a mutation tool with no output schema, the description covers destination, naming, side effect (Gemini description), and the permission gate. It omits error behavior or what happens if the folder is new in more detail, but is largely complete.

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

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

Schema description coverage is 100%, so the schema already explains each of the 4 parameters in detail. The description adds the destination convention and that the clip gets auto-described, but no additional semantics beyond 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?

Clearly states a specific verb and resource: 'Save a video of a session into the user's b-roll library.' It even names the destination path pattern and distinguishes itself from add_broll/list_broll by being the save-to-library operation. The sibling relationship with save_to_library (a similarly named sibling) is not addressed, leaving some ambiguity vs that tool.

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

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

Explicitly gates invocation with 'Only on the user's ask,' which is a clear when-to-use rule, and names the sibling tools list_broll and add_broll to indicate a related workflow. It doesn't however state when NOT to use it vs save_to_library or add_broll, which are the closest alternatives in the sibling 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 readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the write-and-safe profile is covered. The description adds genuinely non-structured context: the artifact becomes the next version at assets/<group>/<name>, appears on the Styles board where the user comments, and requires a playable preview. It stops short of stating overwrite/reversibility or error behavior.

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

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

Three sentences, all load-bearing, with the core action and its destination front-loaded. The cadence sentence is slightly wordy but still earns its place as the usage trigger.

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 carries the burden and does so: it covers creation semantics, versioning, destination path, downstream visibility, and required file format. With all 7 parameters documented in the schema, an agent has everything needed to invoke this correctly.

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

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

With 100% schema description coverage the baseline is 3, but the description adds real constraints beyond the schema: the file must be a playable preview (.mp4 or .png), source_dir preserves the HyperFrames composition, and the note travels with the saved asset. This meaningfully enriches how file and source_dir should be supplied.

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 (keep/save) and resource (reusable part of an edit) in the style library, and enumerates concrete artifact types (title card, lower third, caption look, transition, cover layout, sound). An agent can distinguish this from snapshot-style siblings like get_library, create_style, and save_broll without opening a schema.

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

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

"Do it after each edit for every part a later video could use again" gives a clear trigger and cadence for using the tool. It does not, however, name when not to use it or point at an alternative sibling for related operations such as retrieving library contents.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing sort order ('newest first') and the returned content ('author, note and a preview'), which matters since no output schema exists.

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 sentence, front-loaded with the verb and resource, then ordering and returned fields. No filler; every clause earns its place.

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

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

For a read-only single-parameter tool, the description covers scope, ordering, and return fields, and annotations cover safety. It doesn't mention pagination or result limits, which is the only notable gap for a history listing.

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 single session parameter is fully documented in the schema itself (formats, id, rename tolerance). The description adds nothing about the parameter, so the baseline 3 is correct.

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

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

States a specific verb (List) and resource (saved versions of the script and variants), plus ordering and returned fields. It reads clearly as a history/listing operation distinct from get_script_version (single) and restore_script_version (mutation), though it never names those siblings explicitly.

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

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

The 'newest first' ordering implies the typical use case (scoping recent versions, likely before a restore), but there is no explicit when-to-use, when-not, or mention of the sibling alternatives get_script_version/restore_script_version.

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 read-only, non-destructive, non-open-world operation, lowering the bar. The description still adds substantial value by disclosing matching semantics ('by meaning'), result ordering ('Best hit first'), and the exact return fields (path, kind, at, about) in the absence of an output schema. It stops short of covering edge cases like empty 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?

Front-loads the core purpose in the opening clause, then adds result-shape and usage detail. It is information-dense and each sentence earns its place, though the long parenthetical example lists make it slightly heavier than strictly needed.

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 semantic search tool with no output schema, the description fully covers what is searched, what each result contains (including the meaning of 'at' and 'about'), ordering, and typical use cases. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that 'query' is matched by meaning with concrete examples and maps the 'kinds' enum to observable media types. This clarifies intent beyond the terse schema text 'What to find, in plain words'.

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: 'Find footage by meaning across the whole library' and enumerates exactly what is searched (clips by scene, stills/thumbnails, and spoken/scripted words). It cleanly distinguishes itself from sibling listers like list_broll, list_music, and get_library by being a semantic search rather than an enumeration.

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 when-to-use scenarios: 'find b-roll for a storyboard shot or an edit before asking the user to film it' and 'find an old take or clip the user describes', plus the 'Same search as ⌘K' anchor. It does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare a non-destructive write (readOnlyHint=false, destructiveHint=false), and the description usefully adds that this 'only marks a range' rather than creating media, that the result is user-visible in the Storyboard tab, and how the range is attributed relative to Gemini's. It does not cover permissions or whether a prior agent range is overwritten, so it stops 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?

Four compact sentences, with the core action and the Gemini caveat front-loaded before the restatement and the cut_take handoff. Every sentence carries information, though the visibility note and the 'only marks a range' reminder could be merged without loss.

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 7-parameter mutation tool with no output schema, the description supplies the missing behavioral context: what it changes, who sees it, how it relates to Gemini's suggestion, and the next tool to call. An agent has everything needed to call it correctly and to know what it does not do.

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

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

Schema description coverage is 100%, so the schema already documents end, why, said, clean, start, session and take; baseline 3 applies. The description adds only indirect meaning (the transcript/frames framing maps loosely to said and clean) and introduces a 'by=agent' attribution that has no corresponding schema field, which mildly muddies rather than clarifies 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?

States a specific verb (Set) plus resource (best cut of a storyboard take) with an explicit precondition (after you checked it). It cleanly separates this from the sibling cut_take by noting it 'only marks a range', 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 source (Gemini's best_cut stays under 'gemini'; this writes by=agent), explains the verification step (compare with transcript and frames), and routes the follow-up action explicitly: 'To make the clip, call cut_take with that range.' This is when-to-use plus what-to-do-next with no inference required.

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

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

Annotations declare readOnlyHint=false / destructiveHint=false, so the write-but-safe profile is already covered. The description adds the non-obvious behavior that omitting the optional parameter clears the favorite rather than leaving it untouched, and that the result surfaces as a star on the script's tab — context 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?

Two short sentences, front-loaded with the action and its visible effect, followed by the clearing rule. No filler, no restatement of the tool name.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the description covers the action, the target, and the clearing behavior. It could be slightly stronger by noting whether the favorite is per-session or per-project, but nothing essential to a correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the consequence of omitting draft ('to clear it'), which the schema's draft description ('main' or a variant id.) never states, and by pairing that with the optional/required distinction.

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

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

Specific verb+resource: 'Mark one script as the favorite (star on its tab)', which is unambiguous and describes the visible effect. It does not, however, distinguish itself from similar-sounding siblings such as set_keeper, set_best_cut, or promote_variant, so the agent has no explicit routing cue.

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 an operational rule ('Omit draft to clear it'), which is genuine usage guidance for the clearing case. But it offers no when-to-use/when-not guidance relative to siblings like set_keeper or promote_variant, and no statement of prerequisites (e.g., must the session already have a script).

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

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

Goes well beyond the annotations (which only flag destructiveHint=true) by describing exactly what is replaced and the downstream consequences: hooks appear above the teleprompter, selecting one moves it into the script's first paragraph/hook slot, and each take records its opening hook in the 'hook' field. This gives an agent real behavioral context for a destructive setter.

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

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

Three sentences, front-loaded with purpose and the destructive side effect before elaboration. It is dense but each clause (replacement behavior, teleprompter display, hook slot, take recording, sibling routing) carries distinct information rather than repetition.

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 sufficiently explains what the tool does and its downstream effects, and annotations already cover the safety profile. Nothing critical is missing for correct invocation, though it does not state permission/collaboration requirements for editing an active session's hooks.

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

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

Schema description coverage is 100% and both parameters are fully documented there, so the schema does the heavy lifting. The description adds the notion that hooks are 'opening lines' for a session and implies ordering ('best first' is in the schema), but contributes little parameter meaning beyond what is already structured. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Offer several hooks (opening lines) for a session') and immediately names its key side effect ('Replaces earlier hook options'). It also distinguishes itself from the variant tools ('Use this for hook options; use variants for different whole scripts'), letting an agent separate it from siblings like set_post_hooks or create_variants.

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 this tool and 'variants' by scope ('hook options' vs 'different whole scripts'), giving clear when-to-use guidance. The alternative reference is a bit loose since the sibling list contains create_variants/update_variant rather than a bare 'variants' tool, so the routing is slightly ambiguous but still actionable.

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

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

Annotations already declare this is a non-destructive write operation (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds that both starring and unstarring are possible, but it omits the effect of omitting the optional keeper parameter and whether setting a new keeper affects any existing keeper.

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 front-loaded sentence with no filler. Every word contributes to stating the operation.

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

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

For a low-complexity tool with full schema description coverage and useful annotations, the description covers the core action. However, it leaves a practical gap around the optional keeper parameter: it does not clarify behavior when keeper is omitted, and it does not mention whether a session can have only one keeper.

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 fully documented in the schema itself. The description adds no parameter-level detail beyond what the schema already provides, which is the expected baseline when coverage is this high.

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 pair ('Star or unstar') and resource ('a take as the keeper'), making the action clear. However, it does not explicitly distinguish this tool from nearby siblings like set_best_cut or rename_take, so an agent must infer the difference from the keeper concept.

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 says what the tool does but gives no guidance on when to use it versus alternatives, nor any prerequisites or exclusions. An agent receives no help deciding between set_keeper, set_best_cut, or other take-modifying 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 it is a non-read-only, non-open-world, non-destructive mutation. The description adds two pieces of behavior the annotations do not: that the plan is fully replaced ("Overwrites the plan") and that the call returns the get_plan result. That overwrite semantics is exactly the kind of side effect an agent needs before calling. It could still say more about what happens to unspecified fields or default persistence.

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 terse sentences with zero filler, and the core action is front-loaded ahead of the overwrite caveat and the return-value note. Nothing redundant.

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

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

For a 4-parameter mutation with no output schema, the description covers the action, the overwrite side effect, and the returned payload (get_plan), which is enough for correct invocation. It stops short of describing default behavior for omitted parameters, which is left to the schema.

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

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

Schema description coverage is 100%, with each of days, time, weeks and platforms documented inline including defaults and ranges, so the schema carries the load. The description adds only the loose phrase "posting days the user picked," which does not clarify parameter syntax beyond the schema. Baseline 3 is appropriate.

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