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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the useful side-effect clarification 'without generating media' and the scoping word 'owned,' but says nothing about error behavior when no cache exists or whether the inspection is expensive. Some added value, but not rich.

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

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

A single front-loaded sentence with no filler; the scope qualifier and the non-media constraint are packed in efficiently and 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 return-value burden and does name what is reported (entry identities, logical and physical sizes). This is nearly complete for a read-only inspector; only the absence of any error/empty-cache behavior keeps it from a 5.

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

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

Schema description coverage is 100% and the single optional cache_root param is documented as 'Local cache directory used by cache.run.' The description adds no syntax, default, or override semantics beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (inspect) and resource (owned local cache), plus the concrete attributes surfaced: entry identities and logical/physical sizes. The phrase 'without generating media' distinguishes it from the media-oriented siblings (cutbolt_media_inspect), though it never names the sibling explicitly.

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

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

Usage is only implied: 'inspect' versus the sibling cutbolt_cache_prune suggests read-vs-delete, and 'without generating media' hints at a safe, non-mutating inspection. There is no explicit when-to-use statement, no mention of when to prefer cutbolt_cache_prune, and no prerequisites (e.g., whether a populated cache is required).

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

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

Annotations declare idempotentHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds genuinely useful destruction scope: it states which entries are removed and, importantly, which artifacts are preserved. It does not cover auth requirements or what a prune reports back, so it falls short of a 5.

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

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

One sentence, front-loaded with the action and budget constraint, closing with the non-destructive scope guarantee. No filler and no 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?

With only two parameters, full schema coverage, and no output schema, the description supplies what an agent needs to invoke it safely: what it evicts and what it leaves alone. Minor gaps remain around whether results over budget are still produced and what the call returns, though the schema hints at the former.

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

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

Schema description coverage is 100% and the Policy object already documents max_bytes, max_entries, their ranges, and the LRU eviction rule. The description's 'explicit byte/count budgets' merely restates that, adding no format or default detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb (evict/prune) and resource (least-recently-used derived cache entries) bounded by explicit byte/count budgets. The clause 'source media and exported files are not removed' sharply delineates scope, distinguishing it from cache_inspect and from any media/file tool in the sibling list.

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

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

Usage is implied by 'evict ... to explicit byte/count budgets' – an agent can infer this is for reclaiming cache space – but there is no explicit when-to-use, no prerequisite, and no named alternative such as cutbolt_cache_inspect for checking usage first.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description still adds real behavioral context beyond them: results are sorted, include sizes and root-relative paths, and engine state folders are silently skipped — the last being a non-obvious filtering behavior an agent should know about.

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

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

A single dense sentence, front-loaded with the verb and scope and then layering optional behaviors. Every clause carries information, though the semicolon-chained phrasing is slightly crammed and the trailing 'Read-only' is redundant with the annotations.

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

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

With no output schema, the description compensates by naming what is returned (paths, sizes, sort order) and the default root. Combined with full schema coverage and safety annotations, an agent has enough to call it correctly; only pagination/truncation behavior for the limit parameter is left unstated.

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

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

Schema coverage is 100% with good per-parameter descriptions and an extension example, so the baseline is 3. The description adds meaning the schema lacks, notably that input_root defaults to the workspace, which is not stated anywhere in the schema, plus confirmation of the recursive and extension-filter semantics.

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

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

The description gives a specific verb and resource ('List files and folders'), names the scope ('under input_root (the workspace by default)'), and characterizes the output ('sorted, with sizes and paths relative to it'). No sibling tool covers file listing, so there is no ambiguity to resolve, and the agent can tell exactly what this returns.

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: it is clear this is the tool for enumerating workspace contents, and the recursive/extension options signal typical inspection scenarios. There is no explicit when-to-use statement or routing to an alternative, and none of the siblings overlap, so no exclusion is strictly needed.

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 openWorldHint=false and idempotentHint=true, but the description goes further: cancellation is a soft request that publication can race and win, it does not delete final output, and it is safe to repeat. These are genuinely additive behavioral facts an agent needs to interpret the result correctly.

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

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

Three tight sentences, front-loaded with the core action and scope, then the polling/race semantics. Nothing is redundant and each sentence carries a distinct fact.

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

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

With no output schema and only minimal annotations, the description carries the burden and does so well: it covers scope, async behavior, race conditions, and repeat safety. It omits any mention of required permissions or what a successful cancellation response contains, 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 job_id and job_root are already documented, and the description adds no extra parameter-level meaning. Baseline 3 applies when the schema does all the parameter 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?

States a specific verb (cancel) and resource (job) and narrows scope to 'queued/running' jobs, which cleanly separates it from siblings like cutbolt_job_status, cutbolt_job_wait, and cutbolt_job_resume. It does not name a sibling explicitly, but the 'without deleting final output' clause disambiguates it from any delete/prune operation.

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?

'Poll until cancelled or completed' gives clear operational context for how to use the tool after calling it, and the race note tells the agent the outcome is not guaranteed. It stops short of saying when to prefer this over cutbolt_job_status or cutbolt_job_resume, so no explicit exclusion guidance is 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 already cover idempotency and non-destructiveness, and the description adds real policy detail on top: only opted-in interrupted jobs within attempt limit are retried, and terminal jobs are excluded. It does not say whether reconciliation mutates the saved publication or how the drain is scheduled, so it stops short of full transparency.

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 that front-load the primary action followed by the retry scope and the exclusions. No filler, though the compressed domain vocabulary makes some clauses need a second read.

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

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

For a zero-required-parameter control tool with no output schema, the description covers effect, retry scope, and exclusions, which is most of what an agent needs. It omits what the call returns or whether draining is blocking/asynchronous, a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100% and the single parameter 'job_root' is documented there as the queue directory tied to render.start. The description never mentions it, so it adds no parameter meaning beyond what the schema already provides; baseline 3 applies.

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

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

States specific verbs and effects: reconcile saved publication, wake the queue worker, drain queued jobs, retry opted-in interrupted jobs. This distinguishes it from cutbolt_job_start (launch new work) and cutbolt_job_wait (observe), though the domain phrase 'saved publication' is opaque without broader context.

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 defines which jobs are eligible ('explicitly opted-in interrupted retries within their saved attempt limit') and which are not ('Completed, cancelled and exhausted jobs are not rerun'), which implies usage. However there is no explicit guidance on when to prefer resume over cutbolt_job_start, job_wait, or job_status, or any prerequisite/precondition for calling it.

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

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

Annotations already declare idempotentHint and destructiveHint=false, and the description goes further by disclosing that arguments are validated synchronously, that the ticket is durable, and that independent jobs run concurrently. It does not, however, explain failure/retry behavior or what a rejected command does to the queue.

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

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

Front-loaded with purpose and workflow, no wasted framing. The long command enumeration partially duplicates the schema's run description, which is mildly redundant, but it remains readable and earns most of 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 queue/bootstrap tool with no output schema and a nested arguments object, it covers the full lifecycle: validation timing, durability of the ticket, concurrency, and the follow-up/cancel siblings. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so request_id, run, arguments and job_root are all documented in the schema itself. The description adds little parameter-level meaning beyond noting arguments are prepared/validated now, so the 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 ('Queue a long-running command in the background') plus the return artifact ('durable ticket'), and enumerates the exact command set. It clearly distinguishes itself from the read/wait siblings (job.status, job.wait) that consume its output.

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

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

Explicitly routes the agent downstream: 'Follow with job.wait or job.status', and prescribes the batching pattern 'queue several, then wait for them all with one job.wait job_ids; job.cancel stops one.' It names the alternatives and the conditions that select them.

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 real behavior beyond the annotations (idempotent, non-destructive): it discloses that an exited worker can trigger checked publication reconciliation or an opted-in retry, and that internal metadata may be updated while no worker is started. This is valuable side-effect context, though permission or rate-limit behavior is not covered.

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

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

Three dense sentences with no filler; return contents are front-loaded and the side-effect caveat follows logically. Slightly telegraphic phrasing costs it nothing major, but it's not maximally polished.

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-status tool with full schema coverage and annotations covering safety, the description supplies the key caveat an agent needs (side-effect reconciliation/retry without starting a worker). No output schema exists, but the receipt components are listed, so little is missing.

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

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

Schema description coverage is 100%, so the schema already documents job_id, job_root, and the detail enum. The description adds no additional parameter semantics; baseline 3 is appropriate 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?

States a specific verb ('Read') and enumerates the resources returned (saved state, frame progress, attempt history, completion/error receipt), which is clearly a status read. It doesn't explicitly contrast with siblings like cutbolt_job_wait or cutbolt_session_receipt, so it falls short of 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?

Implied usage context (checking job state after a render.start ticket), and it mentions an alternate path (worker-exit triggers reconciliation or retry), but it never says when an agent should call this versus cutbolt_job_wait or cutbolt_session_receipt.

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

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

Annotations only cover safety/idempotency, so the description usefully adds the blocking-wait semantics, the timeout default (30) and ceiling (120) that the schema omits, and that a timeout yields finished=false. It stops short of stating timeout/failure edge cases beyond that, but the added behavioral context is real.

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

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

Three tight sentences, front-loaded with the primary single-job behavior before branching into the multi-job case. 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?

With no output schema, the description carries the return-value burden and does so — it describes the per-job receipt, error or progress and status counts. save_as and job_root are left entirely to the schema, a minor gap for an otherwise dense definition.

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

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

Schema coverage is 100% (baseline 3), and the description goes beyond it: it supplies the timeout default of 30, explains the multi-job until=all/any switch, and clarifies that receipts are summaries unless detail=full — detail the truncated schema text does not complete.

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

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

The description names a specific verb and resource — wait for a queued/running job to finish — and spells out what comes back (status, progress, result, finished flag). It contrasts behaviorally with a snapshot tool like cutbolt_job_status by describing the blocking wait, but never names a sibling explicitly.

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

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

It clearly explains the two usage modes (single job_id vs job_ids with until=all/any), which is solid implied guidance. However, it never says when to prefer this over cutbolt_job_status or when not to block, so selection between siblings is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavior beyond that: it returns reasons rather than a truncated recipe when a source exceeds media.conform's 45000-output-frame cap, and it specifies that video-only conform recipes are produced, plus the requirement that the path live inside input_root.

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 scoping constraint are front-loaded, and the dense second sentence packs return values, downstream references, and the frame-cap exception without filler. It is slightly run-on, packing several distinct output facets into a single sentence, 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 must carry the return contract, and it does: content identity, stream metadata, timeline readiness with frame rate/frames/rational duration, or failure reasons plus a conform recipe. It is complete for the happy and non-conformable paths, though it says nothing about error behavior for missing or out-of-root paths.

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 already documented in the schema. The description echoes the input_root containment constraint ('inside an explicit input_root') but adds no format, syntax, or edge-case meaning beyond what the schema states; baseline 3 applies when the schema carries the load.

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

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

Names a specific verb (probe) and resource (a local source file inside input_root) and enumerates exactly what it returns: content identity (relative path, SHA-256, bytes), stream metadata, and a timeline verdict. However, it never explicitly distinguishes itself from siblings like cutbolt_timeline_check or cutbolt_cache_inspect, leaving the boundary to be inferred from the return shape.

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 makes the trigger clear: use it to learn a file's identity and whether it is timeline-ready, and it points to the natural downstream steps (media.add for ready assets, job.start with a media.conform recipe for those that are not). It does not name alternatives or state explicit when-not-to-use conditions, so it stops just short of full routing guidance.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, and the description adds useful routing behavior: routed commands never delete files or cancel jobs, long-running work uses job.start, and cutbolt_schema supplies complete arguments. It does not describe per-command side effects or return behavior, but it meaningfully extends the safety and routing context 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?

The key routing and safety guidance is front-loaded before the category list. The domain categories are somewhat lengthy but earn their place by helping the agent navigate a very large command enum.

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

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

For a complex router with a large enum and no output schema, the description is largely complete: it covers usage routing, safety exclusions, long-running jobs, and argument lookup via cutbolt_schema. It does not attempt to describe return values or per-command behavior, but those are impractical here and the routing context is strong.

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 that arguments are the command's usual arguments and directs the agent to cutbolt_schema for complete arguments. This gives useful semantic guidance beyond the schema's bare 'Command to run' and 'arguments' descriptions.

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

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

The description states a clear verb and resource: run a command from the enum with its usual arguments. It also distinguishes itself from direct siblings by saying 'Prefer direct tools when listed,' though the large enum means individual command purposes are not mapped beyond category hints.

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 explicitly tells when to use this tool versus alternatives: prefer direct tools when listed, use direct job.cancel/cache.prune for deletion or cancellation, use job.start for long-running work, and use cutbolt_schema to get complete arguments. These are concrete routing rules with 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 read-only/idempotent/non-destructive, so the trailing 'Read-only.' adds little. The real value is behavioral detail the annotations don't cover: large schemas degrade to an outline of variants and definitions, and `select` returns one part plus its references. No return-format guarantees beyond that, but it goes past the structured hints.

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

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

Three sentences, front-loaded with the purpose and followed by the narrowing behavior and the select syntax. Dense and mostly waste-free, though the enumeration of shared types is somewhat list-heavy.

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

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

There is no output schema, so the description carries the burden of explaining the return value and does so: outlines of variants and definitions by default, full schema on request, targeted fragment via select. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds concrete format examples the schema does not: 'operation + clip.append, or scene + Layer' clarifies how select composes with name. The `full` parameter is not otherwise illuminated, keeping this from a 5.

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

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

States a specific verb and resource ('Return the JSON Schema for one command's arguments') and enumerates both the command form and the shared-type abbreviations it accepts. An agent can tell immediately this is the schema-introspection tool, distinct from the session/job/cache 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?

Explains the practical workflow: large schemas return as an outline, and 'pass select ... for one part with everything it references' tells the agent how to drill down. It does not name an alternative sibling, but none of the siblings offer the same capability, so the omission is minor.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds important behavioral context beyond those: atomicity of the batch, the exact condition for safely reusing request_id, and the required response to REVISION_CONFLICT. It does not clarify how the 'receipt with semantic changes' behaves or warn about potentially destructive operations present in the schema, which keeps it from a 5.

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

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

Three tightly written sentences with the core purpose front-loaded, followed by retry guidance, conflict handling, and return note. Every sentence earns its place and avoids 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?

For a complex atomic batch tool with revision control and many possible operations, the description covers atomicity, idempotent retry, conflict behavior, and the return type. It omits details about the receipt contents and does not point to cutbolt_session_receipt for inspecting results, but the essential operational guidance is present.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description reinforces expected_revision and request_id semantics but does not add new syntax, format, or constraint details beyond what the schema provides. 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 ('Commit') and resource ('atomic editing batch') with the key concurrency precondition ('against expected_revision'). This clearly differentiates it from siblings like cutbolt_session_get, cutbolt_session_undo, and cutbolt_session_receipt.

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

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

Provides explicit retry guidance ('Reuse request_id only with identical arguments after a lost response') and conflict handling ('On REVISION_CONFLICT read and reconsider'). It does not name alternatives such as cutbolt_timeline_check or cutbolt_run, but the operational context for when and how to use this tool 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 idempotentHint/destructiveHint/openWorldHint, so the burden is lower, yet the description adds real value: it explains that re-sending identical arguments returns the original receipt (idempotency mechanics) and forces an existing store_root. It doesn't describe failure modes or what revision/project the call returns.

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, purpose front-loaded, followed by the hard prerequisite and the retry rule. Every sentence carries distinct information and nothing is wasted.

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

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

For a 7-parameter creation tool with no output schema, the description covers the creation modes, the store_root prerequisite, and idempotent retry behavior. It hints at a 'receipt' return value but doesn't state what the call yields, leaving a small 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 schema already documents every parameter including request_id's uniqueness and retry semantics. The description's mention of id/width/height/frame_rate and the snapshot merely recaps the schema's two-mode structure without adding syntax or format detail, so it stays at the baseline.

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

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

States a specific verb and resource ('Start a saved project at revision 0') and enumerates the two creation modes (id/width/height/frame_rate vs. full snapshot), which clearly sets it apart from session_get/apply/undo. It stops short of explicitly naming siblings, but the purpose 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?

Provides a concrete prerequisite ('store_root must be an existing local directory') and a retry pattern ('Retry with the same request_id and arguments'), giving clear operational context. It does not state when to prefer the snapshot mode over the id/dimensions mode or list exclusions, so it lands just below the top.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: that the head is a moving target while revisions are immutable, and that the call returns the entire project rather than a summary. It stays silent on the save_as side effect and on result size, which keeps it out of 5 territory.

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

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

Three short sentences, zero filler, with the primary capability front-loaded and the operational advice trailing. Every sentence carries information the structured fields do not.

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 tool with full annotation coverage and no output schema, the description supplies what an agent needs: it says the result is the full project. It omits how large that result may be and does not mention that save_as redirects output to a file, which is a minor completeness 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 the schema already documents project_id, revision, store_root and save_as. The description reinforces the head/immutable-revision distinction for the revision parameter but adds no syntax, defaults, or interaction rules (e.g. what happens when revision is null).

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

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

States a specific verb (read) and resource (the saved head or a chosen immutable revision) and adds the return scope ("Returns the full project"). It distinguishes head-vs-revision reads from the write-oriented siblings, though it never names an alternative tool like cutbolt_session_history or cutbolt_session_receipt.

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 conditions: read the head before editing, and use a receipt revision for rendering. That is usable routing guidance without naming the sibling tools explicitly, 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral content: the newest-first ordering and the exact pagination contract where a null cursor terminates iteration. It omits whether results are capped or how many entries exist in total, but the added value is above baseline.

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

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

Three short sentences, ordered purpose-first, then limits, then pagination; nothing is padded. The 'limit defaults to 50 (1-200)' clause largely restates schema data, keeping it just below a 5.

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

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

The tool has no output schema, yet the description instructs the agent to feed back a field named next_before_revision that is documented nowhere. For a paginated listing tool, the return shape (cursor, item summaries) should be described, so the definition is adequate but leaves a real gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining the cursor relationship between the output field next_before_revision and the before_revision input, which the schema only describes tersely as 'Return entries older than this revision'. It does repeat the limit default/range already 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?

States a specific verb and resource ('Read ... revision summaries') plus ordering ('newest-first'), so the agent knows exactly what it retrieves. It does not differentiate itself from the closely-named siblings cutbolt_session_get or cutbolt_session_apply, so it falls short of a 5.

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

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

The description gives a genuine usage rule for pagination ('Pass next_before_revision as before_revision for the next page; null means finished'), which tells the agent how to iterate. However, it never says when to prefer this over cutbolt_session_get or why you'd list history at all, so usage is only partially guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the REQUEST_NOT_FOUND outcome when a request never took effect, which is a non-obvious result that changes retry behavior. It doesn't disclose output shape, but that's minor for a lookup.

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, perfectly front-loaded: purpose, return/error semantics, then usage trigger. 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?

Near-complete for a read-only lookup with rich annotations, a fully described schema, and no output schema. The only gap is not describing the shape of the returned 'receipt', though that's acknowledged as optional when output schema is absent.

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

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

Schema coverage is 100% (all three parameters have descriptions), so the baseline is 3. The description clarifies that request_id refers to a committed change and implies project_id scope, but adds no syntax or format details beyond the schema.

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

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

States a specific verb (look up) and resource (request ID commit status), and explicitly distinguishes scope: 'without resending its arguments'. This clearly differentiates it from cutbolt_session_get (fetch state), cutbolt_session_apply (make a change), and cutbolt_job_status (a different lookup domain).

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 prescribes when to use it: 'after a lost response or restart before deciding to retry.' This is the exact condition that selects this tool over blindly retrying via cutbolt_session_apply, and the exclusions are 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds substance beyond that: history is preserved by writing a new revision, repeated calls step further back, and retries require identical request_id/expected_revision. It omits what failure looks like when there is no state left to undo.

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

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

Three short sentences, front-loaded with the action and mechanism, then the repeat semantics, then retry. Nothing is padded or restated.

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 stateful undo with idempotency annotations and fully documented parameters (including the REVISION_CONFLICT condition on expected_revision), the description covers what the agent needs to call it correctly. Edge cases such as undo at revision 0 or behavior with a stale store_root are left 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 the baseline is 3, and the description earns slightly more by pairing request_id with expected_revision as the retry tuple — a cross-parameter relationship neither field documents on its own. It adds no format or range detail beyond that.

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

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

The description gives a specific verb (undo) and resource (the latest applied state) and clarifies the mechanism: it writes a new revision rather than deleting history, which sets it apart from a plain rollback and from cutbolt_session_apply. It never names a sibling tool outright, so an agent must infer the boundary with apply/history on its own.

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

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

It states the repeat-to-walk-backward pattern and the retry condition, which is real operational guidance an agent would not otherwise have. It stops short of naming when not to use it (e.g. nothing to undo) or pointing to an alternative tool, so it is context-rich but not fully specifying.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered; the description reinforces this with 'Read-only.' It adds value beyond the annotations by disclosing the response contract ('Returns a text summary and findings; ok means no warnings or errors'), which annotations cannot express. It does not, however, describe performance cost on large timelines or how findings are ordered/limited.

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 well front-loaded: the core action leads, the check list follows, and the return contract closes. It is a single long sentence with no wasted filler, though the enumeration makes it dense enough to skim poorly.

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 diagnostic with no output schema, the description covers purpose, activated checks, optional-input conditions, and the shape of the return value. An agent has enough to call it correctly; only the absence of guidance on alternatives and result volume keeps it short of a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only marginal param meaning beyond the schema, mainly linking input_root to missing/changed media checks and transcripts to cut-word detection, which the schema descriptions already imply.

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

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

Opens with a specific verb+resource and scope ('Find likely mistakes without rendering') and then enumerates the exact classes of problems detected (flash frames, drift, jump cuts, black/silent stretches, disabled-track clips, unused assets, missing media, cut words). This is clearly a static validation tool, distinguishable from sibling tools like cutbolt_media_inspect or cutbolt_run.

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 parentheticals '(with input_root)' and '(with transcripts)' tell the agent which checks activate when optional inputs are supplied, which is useful conditional context. However, it never says when to prefer this tool over cutbolt_media_inspect, cutbolt_run, or a session-based check, nor any prerequisites beyond the required project snapshot.

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