reelsaw

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

With no annotations, the description carries the full burden and does most of it: idempotency ('the same file twice returns the existing item'), checksum verification and license recording for provider hits, the fact that provider materializations are not listed in your library, and the forward-only effect of setDefault. It omits permission/auth requirements and any rate-limit or cost context for provider materialization.

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 constraint that matters most (exactly one source) and ending with the caveat about setDefault. The dense parentheticals are efficient rather than redundant, though the packed first sentence takes effort to parse.

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

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

Nine parameters with 100% schema coverage and no output schema, and the description still specifies the return shape ({ id, name, kind, mime, durationSec, duplicate, restored, owner }) plus the meaning of the duplicate/restored flags via the idempotency note. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema cannot express: that url, uploadId, and provider+externalId are mutually exclusive source selectors, and that setDefault applies only to future projects. That is genuine value beyond the field-level 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?

The opening sentence gives a specific verb (add) and enumerates the three mutually exclusive source modes that produce distinct outcomes: an upload in your library, or an instance-shared copy materialized from a search_assets hit. It names the sibling tools (search_assets, update_asset) that bracket this operation, so an agent can place it without opening any schema.

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

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

'Add from exactly one source' states the mutual-exclusion rule and then maps each available input (public url, uploadId, provider+externalId) to its use case, which is real routing guidance. It also scopes setDefault to NEW projects only. It stops short of saying when not to use this tool (e.g. restore_asset for previously deleted items), so it is not fully exhaustive.

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

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

With no annotations, the description carries full weight and does well: it discloses the return shape { ok, flagId, rerendered, hint }, which implies a review flag is created, and explains how to reverse the change. Missing are permission requirements, whether the source transcript or existing renders are otherwise altered, and what `hint` means.

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

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

Three compact clauses: the effect first, the constraint second, the return and undo last. Nothing is padded and the most important information is front-loaded.

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 annotations and no output schema, the description supplies both the response fields and the reversal path, which is exactly the gap structured data leaves. It could go one step further on permission or review-workflow impact, but an agent can call it correctly.

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

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

Schema coverage is 100%, so the baseline is high; the description still adds meaning by tying startSec/endSec to "the words spoken" and clarifying that text is what the captions should read, reinforcing the whole-word constraint. No redundant restatement.

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

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

Names the concrete effect (captions show "text" instead of the spoken words) plus the exact span parameters, so it is unmistakable what resource is mutated. The contrast with review_transcript_flags (undo path) and add_transcript_cut clarifies its niche.

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 motivating case ("a misheard name, say"), a hard precondition ("the span must cover whole words"), and an explicit undo route via review_transcript_flags with status rejected. It stops short of saying when to prefer add_transcript_cut or list/flags-review workflows instead.

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 no annotations, the description carries the full burden and does well: it discloses that the operation mutates the transcript, affects captions and rendered video, requires whole-word spans, returns specific fields, and can be reverted via review_transcript_flags. It omits failure behavior if the span does not cover whole words and any permission/auth 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?

Three compact sentences, front-loaded with the action and effect, followed by return shape and undo guidance. Every sentence adds useful information with no 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 mutation tool with no annotations and no output schema, the description is largely complete: it explains the effect, return fields, and reversal path. The main gap is what happens when the span fails the whole-word requirement and whether there are other prerequisites.

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 a meaningful constraint beyond the schema by stating that startSec and endSec must cover whole words, which affects how the agent should choose those values.

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

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

States a specific verb and resource: 'Remove the words spoken between startSec and endSec from the transcript', and immediately explains the downstream effect on captions and rendered video. It also distinguishes its undo path from review_transcript_flags, making the operation identifiable against transcript-related siblings.

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

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

Gives an explicit reversal route: 'Undo it by passing the flagId to review_transcript_flags with status rejected.' It also states the constraint that the span must cover whole words. It does not, however, compare itself to add_transcript_correction or say when to cut versus correct.

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 destructiveHint=true, it discloses exactly what gets destroyed: every clip's own sections are cleared unless keepOverrides, and finished clips are re-rendered. It also notes forward behavior ("New clips get it too") and the response shape, which annotations alone would never 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 front-loaded sentence that leads with the action and the applicability constraint, followed by the return shape. It is dense with parentheticals and nested clauses, but no sentence is filler.

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

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

For a destructive mutation with no output schema, it covers the source of truth, the clear/keep behavior, the re-render default, the effect on future clips, and the returned fields. An agent has everything needed to call it correctly and know the consequences.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the semantics of `at` (the clip's section at that point, else its first framed section) and how keepOverrides interacts with the project framing (other clips' sections "still win"). It adds meaning rather than restating field descriptions.

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

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

States a specific verb and resource: copy one clip's framing (mode, nudge, subject, crop) and make it the project's reframe/reframeAdjust. It also scopes the operation to recordings with a fixed layout, which separates it from per-clip tools like rerender_clip or update_clip.

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

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

Gives a concrete when-to-use condition ("a recording whose layout never changes (a slide deck with a webcam tile, a fixed camera)"), which implicitly excludes variable-layout projects. It does not name an alternative tool for the case where layouts vary, so the routing is clear but not exhaustive.

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

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

Annotations supply only destructiveHint=true; the description earns credit by disclosing that replace swaps (destroys) existing clip layers, that templates are not linked afterwards, that rerender controls whether finished clips update now or later, and what the response contains including skipped clipIds with reasons. It does not mention permission requirements or whether the call is synchronous/queued, which for a destructive batch mutation would be useful.

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 scope, then parameters, then return shape — a sensible order with no filler sentences. The prose is over-compressed in places ("the intro / outro it sets as each clip's own", "bumpers: slots set"), which costs a little readability but not much length.

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

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

With no output schema, the description usefully summarizes the return payload (updated, rerendered, skipped with reasons, layersSkipped, bumpers), and it covers every parameter's behavioral consequence plus the non-linkage semantics. Remaining gaps are peripheral: sync vs async execution, partial-failure semantics beyond the skipped list, and permission prerequisites for a destructive batch write.

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 mode, clipIds, rerender, projectId and templateId are already fully documented in the schema, and the description largely restates them. The only genuinely additive semantics is the caveat about layerTemplateId on update_project affecting only later-created clips. Baseline 3 applies 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?

"Write a template onto clips of one project" names a specific verb (write/apply) and resource (layer template → clips), and adds scope (up to 200 clipIds, or all). "Not linked afterwards" separates it from the template-management siblings (save_layer_template, update_layer_template) that would otherwise look similar. An agent can distinguish this from every sibling 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?

It gives the operative decision rules: mode replace vs add, rerender true/false, and clipIds omitted = every clip. The note that "update_project settings.layerTemplateId only affects clips created later" implicitly tells the agent this is the tool for retroactive application, which is a strong when-to-use signal. It stops short of explicitly naming an alternative tool for the settings-only path.

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 readOnlyHint=true by disclosing non-obvious semantics: replaced clips are excluded, and a deleted asset's layer is skipped when a template is applied. These behavioral details materially affect how an agent interprets results before a destructive action.

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, followed by the return shape and then the actionable caveat. The inline return-shape block is dense but justified since no output schema exists; 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?

With no output schema, the description supplies the full response shape (projects with nested clips/slots/via/overlays/music, and templates with layers) and the caveats that affect interpretation. An agent has everything needed to call it and read the result correctly.

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

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

There is a single parameter, and the schema already documents it fully (id from search_assets), so baseline applies. The description adds no syntax, format, or sourcing guidance beyond what the schema states.

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 (a library item) and precisely what is reported: its use as intro, outro, overlay or music on projects and clips, plus layer templates. This is clearly distinguishable from siblings like get_clip or search_assets, which retrieve content rather than reverse-lookup usage.

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 closing instruction 'Check before deleting one' gives an explicit trigger for calling this tool, implicitly routing agents here before delete_asset/purge_asset. It does not explicitly name those siblings or state when-not to use it, so it stops short of a full routing rule.

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 no annotations, the description carries the full burden and does well: it discloses the return shape and the two possible `kind` outcomes, and warns that payment requires a human in a browser. It never says whether calling it creates a Stripe session as a side effect or is idempotent, which matters for a tool that provisions checkout state.

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 clauses with no filler, front-loaded with the 'Hosted instances' scope qualifier. The nested parenthetical and 'Returns { url, kind: ... }' shorthand make it slightly harder to parse than it needs to be, 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?

No output schema exists, and the description compensates by naming the returned fields and the `kind` discriminator. Parameters, hosting scope, human-in-the-loop requirement, and the alternate return path are all covered, so an agent knows what it will get and what to do with it.

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

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

Schema coverage is 100% and the schema already documents both `plan` (from get_billing) and `interval` (month/year with default), so the description repeats rather than extends that. It adds nothing about format constraints, casing, or invalid-plan behavior 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 exactly what is returned: a Stripe Checkout URL for a plan, or the Billing Portal page when the account already pays. It explicitly distinguishes itself from get_billing, which supplies the plan/interval values rather than the URL.

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: 'Plans and intervals come from get_billing' routes the agent to the sibling that supplies inputs, and 'a person must open it in a browser, an agent cannot pay' sets a hard usage constraint. The 'Hosted instances' prefix implies self-hosted installs are unsupported, but that exclusion is left implicit.

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 no annotations, the description carries the full burden and does well: it discloses that the call is non-mutating (returns a URL rather than acting), that a human must open it in a browser, and that self-hosted deployments get a 'billing not enabled' outcome instead of a URL. It omits whether the URL is user-scoped, expiring, or requires admin auth, which leaves some behavioral gaps.

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

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

Three tight clauses: what it returns and what it is for, the human-in-the-loop requirement, and the self-hosted fallback. Nothing is wasted and the primary purpose is front-loaded.

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 tool with no output schema, the description explains the return payload ({ url }) and the human browser step, plus the self-hosted degenerate case. Lifetime/expiry of the URL and any auth prerequisites are the only notable omissions.

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

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

The tool takes zero parameters, so per the baseline this scores 4. The description adds no parameter information but none 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?

The description states a specific artifact (a Stripe Billing Portal URL) and its concrete uses (see invoices, change card, cancel at period end), which clearly separates it from a checkout URL or a billing status read. It does not name the nearest siblings (billing_checkout_url, get_billing) explicitly, so the differentiation is inferred rather than stated.

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

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

It gives a clear usage condition split by deployment: on hosted instances it is the way to manage billing, while on a self-hosted Reelsaw it simply reports that billing is not enabled. There is no explicit routing to alternatives, but the hosted/self-hosted framing supplies usable context for when the tool applies.

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=true, and the description adds substantial behavior: the full return shape, the fact that available is null for non-release/source builds, the cached polling cadence, and what refresh does. There is no contradiction with the read-only annotation.

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

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

Two dense sentences with no wasted framing. The admin restriction is front-loaded, and the return shape is stated compactly because no output schema exists to carry 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 one-parameter, read-only diagnostic tool with no output schema, the description covers audience, return values, the key edge case, caching behavior, and refresh semantics. Nothing important for correct invocation appears to be 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% and already documents refresh, default false, and the once-per-minute limit. The description adds useful context by explaining why refresh exists: the server otherwise returns the last cached check from its every-few-hours polling.

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: checking whether a newer Reelsaw release is published. It also names the admin-only audience and distinguishes this operational/update check from the many project, clip, and bumper tools 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?

It clearly says this is for admins and explains that the server normally checks every few hours, while refresh: true forces an immediate GitHub check. It does not name alternatives or explicit when-not-to-use conditions, but the intended context is clear.

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

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

With no annotations, the description carries the whole burden and does so well: it discloses that the call is asynchronous, that preparation is queued, that rendering follows automatically and takes about a minute, and that the caller must poll get_clip. It does not cover failure modes or what happens if the range exceeds the stated 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?

Every sentence earns its place and the core purpose comes first, but the single dense paragraph with stacked parentheticals ("(title, hook, scores)", "(about a minute)") makes it heavier to parse than necessary. No wasted claims, just tight packing.

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 giving the exact return shape { id, status, queued, hint } plus the follow-up workflow via get_clip. Combined with the mode limits and the transcript prerequisite, an agent has everything needed to call this correctly on the first try.

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 constraints the schema lacks: a 3 s–10 min bound in exact mode and a ≥8 s minimum in ai mode. It does not add anything for projectId, startSec, or endSec beyond what the schema already states.

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 and resource ("Add a clip from a time range of the source") and immediately adds the prerequisite that the source needs a transcript. It distinguishes itself from update_clip and get_clip by name within the same paragraph.

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?

Spells out the two operating modes with their selection criteria (exact keeps your bounds, ai lets the model pick the best moment) and names the alternative for mutation ("To change an existing clip use update_clip instead"). The transcript prerequisite further tells the agent when this call will not work.

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?

No annotations exist, so the description carries the burden and does well: it discloses the asynchronous pipeline (download, transcribe, pick, render) running for minutes, the immediate return shape with status 'queued', and the required follow-up call. It could be stronger by mentioning error conditions or whether creation consumes quota, but the core behavioral profile is clearly disclosed.

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

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

The opening action and source options are front-loaded, and the sentence is dense with useful detail. However, it is a single long run-on sentence that could be split for easier scanning.

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

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

For a 9-parameter, nested, no-output-schema tool, the description provides the crucial return shape and async follow-up guidance, which compensates for the missing output schema. It does not cover error behavior or quota implications, but 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 description coverage is 100%, so the baseline is 3. The description reiterates the uploadId flow and intro/outro default semantics, but those are already documented in the schema; it adds little parameter-level meaning beyond what the schema provides.

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

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

States a specific verb (start clipping) and resource (project), plus the two source modes it accepts. It also names the follow-up sibling wait_for_project, so an agent can distinguish it from read/update siblings without opening schemas.

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

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

Explicitly says how to start (URL or uploaded file via POST /api/upload with uploadId) and what to do after (follow with wait_for_project(id)). It also states the intro/outro default behavior versus supplying introAssetId/outroAssetId, so the invocation path is fully prescribed.

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 no annotations, the description carries the full burden and does it well: it discloses the return shape { endpoint, secret }, the one-time-only nature of the whsec_ secret (an irreversible behavior), how to verify deliveries, and the public-https / private-network constraint. These are exactly the facts an agent needs before firing a mutation it cannot 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?

Four dense sentences with zero filler, front-loaded with the verb and the event list, then the return contract, then the URL constraint. The event enumeration is long but is load-bearing information, not padding.

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

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

No output schema exists, yet the description documents the response object and the secret's one-time visibility, covers the https requirement, and names the verification path. Nothing essential for a correct first call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond the enum names by explaining what each event actually delivers ('project.done (with every clip, share links and the zip)', 'clip.done (also re-renders)'). It does not add anything for the optional 'description' label, but the schema already covers that adequately.

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 ('Subscribe a URL to events') and enumerates the exact event types it accepts. It also names the sibling it is not ('delete_webhook unsubscribes'), so an agent can place it in the webhook lifecycle without opening another 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?

'This is how a Zapier or Make app subscribes' plus the parenthetical pointing at delete_webhook as the inverse gives clear context and one named alternative. It does not explicitly contrast with update_webhook or rotate_webhook_secret, which are the closest ambiguous siblings for an agent that already has a webhook registered.

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

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

With only destructiveHint=true available, the description carries the burden well: it discloses soft-delete semantics (moves to Deleted), the retention window is discoverable via list_deleted, the key non-obvious side effect that existing projects/clips keep rendering with the asset, and the return shape { ok }.

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

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

Three tight clauses, each earning its place: what it does, what survives, how to undo/verify, and what comes back. The behavioral constraint is front-loaded ahead of the recovery advice.

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 mutation with no output schema, the description covers effect, reversibility, retention, downstream render impact, and the return value. Nothing an agent needs in order to call this safely 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?

A single required parameter with 100% schema description coverage (including its provenance, 'from search_assets'), so the schema already does the work. The description adds only an indirect hint that the asset must be one of the caller's own uploads, not syntax or sourcing detail beyond the schema.

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

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

States a specific verb+resource ('Delete one of your uploads') and immediately clarifies the scope: it leaves the library and defaults but goes to 'Deleted' rather than being destroyed. This implicitly separates it from purge_asset while explicitly naming restore_asset and asset_usage, so an agent can place it among the delete/purge siblings.

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

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

Gives real procedural guidance: 'check asset_usage first' establishes a precondition, and 'Undo with restore_asset (list_deleted says how long it is kept)' points to the recovery path. What's missing is an explicit exclusion — it never says to use purge_asset when permanent removal is intended.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial behavior the annotations do not: a render in progress stops, the item becomes visible in Deleted, deletion is reversible for DELETED_RETENTION_DAYS (7 days default), and storage still counts until purge_clip. It also describes the return payload fields, which is especially valuable 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?

The description is dense and front-loaded: purpose first, then lifecycle consequences, then the bulk alternative, then return fields. Every sentence carries operational information and there is no filler.

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

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

For a destructive single-item delete with no output schema, the description covers the full operational picture: what happens to an in-flight render, where the item goes, how long it is restorable, when storage is actually freed, the relevant sibling tools, and the return object fields. Nothing essential is missing.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema ('Clip id (from get_project or search_clips)'). The description does not add any further meaning about the id parameter, so the baseline of 3 for full schema coverage 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?

The description opens with a specific verb and resource ('Delete one clip of a live project') and immediately distinguishes scope from the bulk sibling ('For several clips of one project use delete_clips'). An agent can tell exactly what this tool does and how it differs from delete_clips, purge_clip, and restore_clip.

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 names the alternative for bulk deletion ('use delete_clips') and explains the lifecycle context: the clip appears in list_deleted, is restorable via restore_clip for the retention period, and only stops counting toward storage after purge_clip. That gives clear when-to-use and when-to-use-something-else 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?

Goes well past destructiveHint/idempotentHint: in-progress renders are stopped, deletions land on Deleted and are restorable for DELETED_RETENTION_DAYS, skipped ids are ignored (explaining the idempotency claim), and storage continues to be billed until purge_clip. It also documents the response payload, which no output schema provides.

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

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

Front-loaded with the action and scope, then lifecycle, then return shape; no filler sentences. The trailing return-field enumeration is dense but pays for itself since there is 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?

Covers action, side effects, recovery window, purge relationship, retry semantics and the full return object, compensating for the absent output schema. Nothing needed to invoke or interpret the call 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, but the description adds real semantics: all clipIds must belong to a single live project, and ids already in the deleted state are silently skipped rather than erroring — behavior an agent needs to interpret results.

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 with scope: 'Delete several clips of one live project in one step', and disambiguates from the singular sibling by calling out the batch/selection-bar semantics. An agent can distinguish it from delete_clip, delete_project and delete_asset without opening any schema.

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

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

Names the recovery path (list_deleted, restore_clip, DELETED_RETENTION_DAYS) and the true-removal alternative (purge_clip), and notes that already-deleted ids are skipped so retries are safe. It does not explicitly say 'use delete_clip for a single clip', so one routing decision is left implicit.

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?

Although annotations already declare destructiveHint=true and idempotentHint=true, the description adds substantial behavioral context: deletion is soft (goes to Deleted), it clears the template from project defaults, existing clips retain their layers, and the return value includes whether a default was cleared. It also names the restore path and the retention reference.

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

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

The description is compact and front-loaded: the delete behavior, default-clearing effect, existing-clip behavior, undo path, retention reference, and return shape all appear in a few tight clauses with no filler.

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

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

For a single-parameter destructive tool with no output schema, the description covers the important effects: what happens to the template, project defaults, existing clips, how to undo, where retention is documented, and what the return value contains. Nothing essential is missing.

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

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

Schema description coverage is 100% and the only parameter's schema already explains that it is a layer template id available via list_layer_templates. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Delete a template') and immediately distinguishes this soft delete from permanent removal by saying it goes to Deleted and can be undone. An agent can tell this apart from purge_layer_template without inspecting either schema.

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

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

The description gives clear recovery guidance ('Undo with restore_layer_template') and points to list_deleted for retention duration. It does not explicitly compare against purge_layer_template, but the soft-delete semantics strongly imply when this tool is appropriate rather than permanent purge.

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 and idempotentHint, but the description goes well beyond them: it discloses the soft-delete/retention model, that storage keeps counting until purge, that used minutes are not refunded, and the exact return payload. Nothing an agent needs to predict the consequences is missing.

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, front-loaded with the destructive effect and scope, then reversibility window, then the residual-cost caveat, then the return shape. Every clause carries information an agent would otherwise have to guess.

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

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

There is no output schema, and the description compensates by naming the returned fields ({ changed, restorable, storedBytes, forgetDecisions, message }). Combined with the retention and billing caveats, this is complete for a two-parameter destructive mutation.

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

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

Schema coverage is 100% and both parameters (id, forgetDecisions) are documented there, so the schema does the heavy lifting. The description mentions forbidDecisions only as a return field and adds no syntax or constraint detail about either input parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete one of your projects and all its clips") and immediately scopes the effect: work in progress stops and clips go with the project. It is clearly distinguishable from the sibling purge_project, which the description names as the permanent-removal path.

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: restore_project is the undo path within DELETED_RETENTION_DAYS (7 days default), and purge_project (or the retention sweep) is what actually frees the data. It also warns that minutes already used stay counted, which is decision-relevant before calling.

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 the description goes beyond that by disclosing exactly what is destroyed: future deliveries stop and the delivery log is removed with it. It also names the return shape { ok, message }. It stops short of saying whether the deletion is reversible or what permission is required.

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

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

Two compact clauses: the action with its consequence front-loaded, then the return contract. No filler and nothing repeated from the structured fields.

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

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

For a one-parameter destructive tool with annotations and full schema coverage, this is nearly complete: mutation effect, collateral data loss, and return value are all covered. The remaining gap is whether the operation is permanent or has any restore path.

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

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

Only one parameter, and the schema already documents it at 100% coverage ("Webhook id (from list_webhooks)"). The description adds nothing about the id's format or sourcing, 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 ("Remove a webhook") and immediately qualifies scope with "(unsubscribe)." It is unmistakably distinct from create_webhook, update_webhook, and list_webhooks, though it never names a sibling to route the agent.

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 guidance and no alternative named (e.g., update_webhook to disable delivery without deleting). The word "unsubscribe" only implies the use case rather than stating conditions or prerequisites.

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

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

The description adds substantial behavioral detail beyond the readOnlyHint annotation: it describes the return shape, the oldest-first ordering, eval-case grouping, and cursor-based pagination. It does not mention auth or rate-limit behavior, but those are less critical for a read-only export.

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 efficiently covers return shape and pagination in a few dense but purposeful sentences. Every sentence contributes useful information.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so by specifying items, cases, and nextCursor. It also covers ordering and pagination, making the definition complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaningful semantics by explaining that the returned nextCursor is fed back into the cursor parameter until null, which clarifies the pagination contract beyond the schema field 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 clearly identifies the resource and output mode: a paginated export of the decision log, ordered oldest first, intended for evals. It does not explicitly distinguish itself from the sibling list_decisions tool, so it is clear but misses 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?

It gives clear usage context by saying the export is 'for evals' and explains the pagination loop ('Pass nextCursor back until it is null'). It does not state when not to use this tool or explicitly point to list_decisions for ordinary browsing.

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

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

Goes well beyond readOnlyHint: discloses that the returned link requires the same Authorization header as this server, that unrendered clips are silently excluded (notRendered), and what the error responses mean. That is exactly the kind of non-obvious auth/partial-result behavior an agent cannot infer from annotations.

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

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

Front-loaded with the outcome (a zip download link), then preconditions, then return shape. Dense but every clause carries information; only the nested parentheticals slightly slow parsing.

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 supplies the exact return shape ({ url, clips, notRendered }) and the mechanism for consuming the link (Authorization header). Combined with precondition and error behavior, an agent has everything needed to call and use this correctly.

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

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

Schema coverage is 100% and both parameters (id, clipIds with max 200 and rendered-only constraint) are already documented in the schema. The description mentions rendered vs picked clips but adds no syntax or format detail for the parameters themselves, so baseline 3 applies.

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

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

States a specific verb and resource ('a download link for a zip of the project's rendered clips with YouTube/TikTok metadata'), which no sibling tool duplicates — delete_project, get_project, rerender_clips all do different things. An agent can immediately tell this is the export/download 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?

Gives concrete preconditions ('the project must be live and at least one picked clip rendered') and explains failure outcomes. It does not name an alternative sibling for the case where nothing is rendered (e.g. rerender_clips), so it stops just short of explicit alternative routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds important context: deletions cannot be undone, affect learning behavior, and return { forgotten, message }.

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 short and front-loads the destructive operation and its learning consequence. The parenthetical phrase 'projectId, live or already deleted forever' is slightly awkward but overall the sentence is efficient.

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

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

For a one-parameter destructive tool with no output schema, it covers the essential scope, irreversibility, learning effect, and return shape. It could be more complete by relating explicitly to set_learning or non-destructive decision-log tools.

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

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

Schema description coverage is 100%, and the one optional projectId is already documented. The description reinforces that omitting projectId deletes everything, but adds little syntax or format detail beyond the schema.

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

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

States a specific verb and resource: delete entries from the decision log, with the consequence that Reelsaw stops learning from them. This clearly distinguishes it from sibling read/export tools like list_decisions and export_decisions.

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 project scoping well: projectId limits deletion to one project, omission deletes all. However, it gives no explicit guidance on when to use this versus related tools such as set_learning, list_decisions, or export_decisions.

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

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

The readOnlyHint=true annotation covers the safety profile, and the description adds real context beyond it: what the response contains, that limits carry a source (instance, plan, admin override), and that self-hosted deployments return an explicit 'not enabled' answer rather than an error. It stops short of stating permission requirements or what canManage implies for the caller.

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 hosted-instance scope, which is good, but the first sentence's prose list and the second sentence's return-key list largely restate each other (plan, subscription, period, limits, limitSource, usage, watermark, plans appear twice). The self-hosted note is the one non-redundant sentence and should not be buried at the end.

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 return-value burden and does so by enumerating the response keys plus the top-level enabled/reason/canManage fields. With zero parameters and a read-only annotation, the remaining gaps (auth requirements, what canManage gates) are minor for a status-reading 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?

The tool takes no parameters, so there is nothing for the description to disambiguate beyond confirming it acts on the current instance without arguments. Baseline applies.

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

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

The description names the resource (billing/subscription for a hosted instance) and enumerates exactly what it reports: plan, billing period, effective limits with provenance, period usage, watermark status, and available plans. It also explicitly carves out the self-hosted case, so an agent can tell immediately whether this tool applies to the running instance.

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 context is implied by the hosting distinction ('Hosted instances…', 'On a self-hosted Reelsaw this answers that billing is not enabled'), which is genuinely useful for deciding whether it's worth calling. However, it never names the obvious alternative, billing_checkout_url, nor states the condition that selects one over the other (e.g., view status here, obtain a payment URL there).

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, so the safety profile is covered; the description adds genuine context beyond that by promising 'Returns the clip object' and explaining that the response includes both 'own' and 'effective' values with their source (clip|project|default). That inheritance behavior is the kind of thing an agent cannot infer from structured fields.

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

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

Purpose is front-loaded and the usage hint is short and actionable. The opening sentence is a long enumeration of return fields that borders on run-on, but each item tells the agent something exists in the response, so little of it 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?

There is no output schema, so the description's enumeration of returned fields and the own/effective/from resolution rules are essential and present. It also explains the render-status polling pattern. What is missing is minor (e.g., what happens with an invalid or stale id).

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 single parameter already carries a description ('Clip id (from get_project or search_clips)'). The description adds nothing about the id format, so the schema does the work and the baseline of 3 applies.

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

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

States a specific verb and resource ('Everything about one clip') and then enumerates exactly what that means (text, bounds, scores, emphasis, layers, render diagnostics, links). It explicitly distinguishes itself from get_project ('lists all clips in brief'), so an agent can choose between them 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 a concrete alternative (get_project for the brief list) and gives an explicit operational trigger: 'poll this after an edit to see the render finish (status done).' That is clear when-to-use guidance, though it does not cover when to prefer get_clip_captions or search_clips instead.

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 readOnlyHint=true, the description discloses that captions mirror the rendered video's lines and times including the intro, that they exist even when the style has captions off, that the return value is file text, and that a clip rendered before caption files returns a message pointing at rerender_clip. That stale-render behavior is exactly the kind of non-obvious trait the description must 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?

Three sentences, front-loaded with what the tool returns, then parameter nuance, then the failure case. Dense but every sentence earns its place; slight compression could improve readability.

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, but the description states the return value is file text and explains what that text contains. Combined with the stale-render case, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful plain-language semantics: words: true yields karaoke-style word timestamps and only applies to VTT. That clarifies the interaction between the two optional parameters beyond what the schema states.

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 (fetch the captions of a clip's last render) and pins down the exact artifact form (SRT or WebVTT file text). The phrase 'a clip's last render' distinguishes it from project-level transcript siblings such as get_transcript and get_project_transcript_file.

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

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

It clearly states the context in which this tool applies (captions of the last render, intro included, regardless of style settings) and routes the stale-render case explicitly to rerender_clip. It doesn't explicitly contrast with get_clip or get_transcript, but the trigger conditions 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?

readOnlyHint=true already tells the agent this is a safe read, and the parameterless schema confirms nothing is mutated. The description does add real behavioral value by naming the returned fields and explaining what `ready` means, but it stops short of saying whether preferences are per-instance or per-user, or what an empty result implies.

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 core answer front-loaded and the return shape immediately after. No filler, though the field walkthrough is slightly terse and could be grouped more cleanly.

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

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

With no output schema, the description carries the burden of explaining the return value and does so, covering both emailEnabled and the ready note. For a trivial parameterless read tool that is close to sufficient; only the relationship to the setter tool 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?

Zero parameters, so the baseline is 4. The description uses its space on output field semantics instead, which the schema cannot cover, so nothing is lost by the absence of parameter discussion.

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 the resource concretely: which optional emails the instance sends, broken down by topic, with the top-level return shape given. The verb is implied (a read/query) rather than stated outright, and the sibling set_email_preferences is never named, so the agent must infer the read-vs-write split itself.

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

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

There is no statement of when to call this versus set_email_preferences or get_instance_settings. The note that emailEnabled false means no mail is sent is interpretive context, not a usage condition, so an agent gets no 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=true, and the description adds substantial context beyond that: admin-only authorization, refusal behavior for hosted non-admins, a null return when the item is gone (retried or deleted), and the clip/project deduplication rule. These are exactly the behavioral traits an agent cannot infer from structured fields.

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

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

Three compact sentences, no filler. The admin restriction leads, the return payload and the clip-suppression rule follow, and the null case closes it out — front-loaded and dense with information.

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

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

No output schema exists, yet the description enumerates the returned fields, covers the null result, and documents the authorization boundary. For a two-parameter read tool, an agent has everything needed to call it and interpret the response.

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

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

Schema coverage is 100%, so both parameters are already documented, including the kind enum. The description still contributes meaning by tying kind to a behavioral consequence (clip suppression when its parent project failed), which the schema does not convey. Baseline 3 plus that added semantics merits 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?

Names a specific verb+resource (retrieve one failed project or clip) and immediately enumerates what comes back: title, owner email, stage, full recorded reason, and timestamp. That field list plus the admin restriction makes it unmistakable against siblings like list_failures or get_project.

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

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

Gives concrete routing advice: a clip whose project also failed is not returned, so retry the project instead. That is an explicit alternative path. It stops short of stating when to prefer this over list_failures for enumeration, which is the only real gap.

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, so the description isn't burdened with safety claims. It still adds real value by disclosing that secrets are masked and that provenance (env vs db) and ignored keys are part of the result — traits an agent needs to interpret the output 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?

Front-loaded with the purpose and audience, then the return shape. The long parenthetical setting list is dense but earns its place by telling the agent what is covered before it calls.

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 present, the description fully compensates by spelling out the return object's fields (values, env, override, source, ignored, groups, help, updatedAt/updatedBy). Nothing needed to call or interpret it is absent.

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

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

The tool takes zero parameters, so the baseline is 4 by rule. No parameter meaning is missing because there is nothing to document.

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

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

States a specific verb and resource ('the instance settings in force') and enumerates the domains covered (sign-up mode, quotas, retention, etc.) plus provenance. An agent can distinguish it from the mutation sibling set_instance_settings 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?

'Admins only' gives a clear access prerequisite, and the read-only framing implies inspection usage. But it never names set_instance_settings as the write alternative or says when to prefer this tool over sibling lookups like check_for_update or get_billing.

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 no annotations, the description carries the full burden and does so: it discloses the security-relevant trait that links bypass Authorization, the side effect that this GET-shaped tool mints/reuses links, the reuse rule ('the active link is reused unless label or ttlDays ask for a separate one'), and expiry/revocation semantics. It also explains what happens for unrendered clips ('say why'), which prevents blind retries.

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 key distinguishing fact (public, no-auth download links) followed by return shape and link-lifecycle rules. The first sentence is dense with consumer examples but each serves agent selection; nothing is padding, though the prose is tighter-packed than ideal.

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

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

No output schema exists, yet the description inlines the return structure ({ clips: [{ clipId, links: { clip, thumb, srt, vtt } }], export }) with per-link { linkId, url, expiresAt }. Combined with reuse/expiry/revocation rules and the unrendered-clip failure mode, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying label and ttlDays to link-identity behavior ('ask for a separate one') — that interaction is not expressed in the schema descriptions. It also frames the non-obvious default behavior (active link reuse) that the parameters override.

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 — returns share links that anyone can download without an Authorization header — plus the shape of the result. It is clearly distinguishable from the adjacent list_media_links and revoke_media_link tools, which it implicitly references via revoke semantics.

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 consumer scenarios (Buffer/Metricool schedulers, Instagram's video_url, Zapier/Make, or a person) that tell an agent when to reach for this tool. It stops short of explicitly contrasting with list_media_links (which presumably lists already-created links) or stating when not to use it, so it is clear context rather than 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 only declare readOnlyHint=true, so the description carries the burden of describing the return payload and does so richly, including the non-obvious replacedClips field and its link to restore_clip. It stops short of pagination, size limits, or error behavior, 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?

Front-loaded with what the tool returns, followed by one routing sentence. It is dense but each clause (clip fields, replacedClips, sibling routing) earns its place; only the 'Returns the project object' sentence is slightly redundant with the opening enumeration.

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

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

With no output schema, the description must convey the response shape, and it does so field-by-field, including the otherwise undiscoverable replacedClips semantics. Combined with the sibling routing, an agent has everything needed to call and interpret this tool.

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

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

There is a single parameter with 100% schema description coverage, and the schema already states the id and where to obtain it (list_projects, search_clips, create_project). The description adds nothing about the id beyond what the schema provides, 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 and resource and enumerates exactly what the project payload contains (status, settings, intro/outro, transcript summary, clips with their fields). It also names the sibling tools it is not (get_clip, get_transcript, get_project_events), 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?

Explicitly routes the agent to alternatives: get_clip for one clip's detail, get_transcript for words, get_project_events for pipeline history. It also states the purpose of replacedClips (restore_clip), giving a clear when-to-use signal for a downstream tool.

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

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

readOnlyHint is already declared by annotations, but the description adds real behavioral detail beyond that: the response shape '{ projectDefaults }' and the crucial semantics that unset keys are absent and fall back to built-in values. This is exactly the kind of return-value subtlety annotations cannot convey, though nothing is said about permissions or rate limits (low relevance for a read).

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

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

Two sentences, no padding: the identity/scope of the resource comes first, the return shape and absent-key semantics second, the handoff to set_project_defaults last. Every clause carries information an agent would otherwise have to guess.

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

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

For a zero-parameter read tool with no output schema, the description supplies what is missing from structured data: the returned key name, the absent-key fallback rule, and the companion mutation tool. Nothing an agent needs in order to call it correctly is absent.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly implies no inputs are needed and spends its words on the return payload instead.

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

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

States the specific resource ('the settings every new project starts with') and enumerates the fields it covers (language, vocabulary, instructions, focus, clip lengths, pauses, captions, refine steps). The closing sentence names its mutation counterpart set_project_defaults, so the agent can distinguish it from the rewrite tool without inspecting schemas.

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

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

Clearly frames the tool as the read side of project defaults and explicitly routes mutation to set_project_defaults. It does not state when-not conditions (e.g., when get_project would be preferred for a specific project's settings), but for a zero-argument getter the intended 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?

With readOnlyHint already declaring safety, the description adds genuinely new behavioral context: live progress ticks are not stored (so polling will not surface in-flight state), the order is newest-first, and the return shape is given. It stops short of saying what a truncated result looks like or how far back history goes.

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

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

Two dense sentences, front-loaded with what the tool is and immediately followed by the qualifier about unstored ticks and the return shape. Every clause carries information, though the parenthetical and clause list make it slightly harder to scan than a purely linear phrasing.

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

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

No output schema exists, but the description supplies the return shape and event taxonomy, which is the key missing piece. The only real gap is pagination/truncation semantics for limit, which matters for an agent that may need older events.

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

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

Schema coverage is 100%, so both id and limit are already fully documented in the schema, including the 1-200 range and default. The description adds only the ordering guarantee, not any meaning for the parameters themselves, 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 resource (the project's pipeline history) with a concrete scope and ordering (newest first), plus the exact event kinds returned. It explicitly contrasts with get_project's current-state view, so an agent can pick between them 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 an explicit use case ("find out why something failed or is slow") and names the alternative (get_project) with the condition that selects it. It does not address the other overlapping siblings such as get_failure or get_queue, which also surface failure details, so the routing is clear but not exhaustive.

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

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

readOnlyHint=true already covers the safety profile, and the description adds real value on top: returns file text (not a parsed structure), timing is in source-video seconds, and words:true only affects VTT word timestamps. It doesn't mention failure behavior when no transcript exists, which is the one behavioral gap for a retrieval 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?

Two sentences, front-loaded with the output format and segmentation, then the words/format behavior, then the sibling pointer. Nothing is redundant with the schema or 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 does the job of describing what comes back (file text, one cue per segment, source-video seconds). Complete for the happy path, though it never says what happens if the project has no transcript or is still processing, which matters in a pipeline with wait_for_project and reanalyze_project siblings.

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 semantics the schema lacks: that cue timing is expressed in source-video seconds, and that the words flag produces a per-word <timestamp> marker in the cue rather than a separate field. That clarifies intent beyond the enum/default documentation.

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

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

States a specific verb+resource (get the project transcript file) and pins the output form: SRT or WebVTT subtitle file, one cue per segment, in source-video seconds. It explicitly distinguishes itself from the closely named sibling get_transcript by contrasting file-based subtitles with plain timed lines.

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 get_transcript to read it as plain timed lines instead' names the alternative and the condition that selects it, so an agent can route between the two transcript tools without opening either schema. The subtitle-file vs timed-lines distinction is the exact decision an agent faces here.

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 readOnlyHint=true, it discloses authorization behavior (non-admins refused on hosted) and a truncation flag in the response, plus what error may appear. That is meaningful operational context an agent cannot infer from the annotations. It does not state rate limits or how partial results are ordered/filled when truncated, which keeps it off a 5.

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

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

Three sentences, with the admin gate and the metric list front-loaded before the return shape and the list_failures exclusion. Dense but essentially waste-free; the parenthetical field enumeration is the only slightly heavy part.

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 by naming the top-level shape { queues, active, truncated, error? } and the key fields (project title, attempt, started, lastError). Inner structure of queue entries and truncation behavior are only sketched, which is the remaining gap for a read-only summary 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly does not invent arguments and instead spends its words on scope and return shape.

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 (queue) and what it reports — waiting/running/retrying counts per pipeline stage plus in-flight jobs — in concrete terms. It explicitly distinguishes itself from the sibling list_failures ("Failed work is list_failures, not this"), so an agent can pick between them without opening schemas.

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

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

Gives a hard prerequisite ("Admins only", hosted non-admins are refused) and routes the failed-job case to list_failures. It stops short of naming other adjacent alternatives (e.g. list_workers, list_failures sibling set) or the situations that make this the right call vs. a project-status tool, but the usage 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, so safe read is covered. The description adds valuable behavior: the truncation policy ('output longer than maxChars is cut with a note saying which fromSec to continue from') and the return format, which goes beyond the annotation's safety hint.

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 focused sentences with no waste, front-loading the output format and then covering the truncation behavior and the recommended use case. Slightly dense but well-structured.

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

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

For a read-only transcript tool with no output schema, the description covers the return format, truncation behavior, and downstream use case. It is nearly complete, though it could mention whether the range is clamped to video length or how missing projects are handled.

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 fully documents all 4 parameters. The description mentions the time range and maxChars truncation, but adds no syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('transcript') and describes the exact output format ('[m:ss] text' timed lines). It also distinguishes it from siblings by naming create_clip as the downstream use case.

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

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

Explicitly tells the agent 'Use it to pick your own moments for create_clip', giving a clear use case. However, it doesn't state when NOT to use it or name an alternative for retrieving transcript text in a different way.

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 flag destructiveHint=true; the description supplies the actual consequence: the transcript is re-cleaned, clips are picked again, and 'accepted and rejected fixes, cuts and corrections on the old transcript are lost for good'. That is exactly the irreversibility context an agent needs before a destructive call. It stops short of noting auth requirements or size/rate constraints, so a 4 rather than 5.

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

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

Three sentences, front-loaded with the purpose, then the source constraint, then the return shape and next step — no filler. The first sentence is long with nested parentheticals, which slightly slows parsing but every clause carries distinct information.

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

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

For a 6-parameter destructive tool with no output schema, the description covers applicability states, the mutually exclusive source inputs, the destructive consequence, the return shape, and the required follow-up call. Nothing an agent needs to invoke it safely and 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 would be 3, but the description adds a constraint the schema does not encode: exactly one of text, uploadId or url must be supplied (the schema only requires id). That meaningfully reduces malformed calls beyond what the field descriptions convey.

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

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

States a specific verb and resource ('Use an SRT or WebVTT file as the project's transcript') and explicitly contrasts it with the default path ('instead of transcribing'), which distinguishes it from siblings like reanalyze_project or refine_project. An agent can identify the operation without opening the schema.

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

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

Names concrete lifecycle states where it applies ('right after create_project (only the video is fetched)' and 'on a done or failed project'), and prescribes the follow-up call ('follow with wait_for_project'). It also gives the mutual-exclusion rule ('Give exactly one of text, uploadId or url'), leaving nothing to inference.

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

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

Annotations only declare readOnlyHint=true, while the description adds meaningful behavior: decisions are returned newest first, are retained after project deletion so the system can learn from them, and include summary/item/pagination fields. It also explains the special meaning of clip.replaced and explicit=false. These details go well beyond the annotation, though permission or rate-limit behavior is not discussed.

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 moves efficiently into return shape and kind semantics. It is fairly dense but each part contributes useful information, with only mild run-on density in the first 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?

For a read-only list tool with no output schema, the description supplies the return structure, ordering, pagination field, retained-after-deletion behavior, and kind semantics. Combined with full schema coverage and readOnlyHint, it gives an agent enough context to call and interpret the tool correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds useful semantic grouping for kind values as fix.* transcript fixes versus clip.* decisions, and clarifies the meaning of clip.replaced with explicit=false. It also notes that projectId may refer to an already-deleted project, reinforcing the schema's wording.

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

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

The description clearly states a specific verb and resource: it lists the user's decision log, including accepted/rejected/cut/corrected/edited/deleted/restored decisions, newest first. It is specific enough to distinguish this from generic listing tools, though it does not explicitly name sibling tools such as export_decisions or forget_decisions.

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 as viewing the decision history, but the description gives no explicit when-to-use guidance and does not contrast this tool with nearby alternatives like export_decisions, forget_decisions, or set_learning. An agent can infer the purpose, but routing between decision-related siblings is left to the agent.

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

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

Annotations declare readOnlyHint=true and the description is fully consistent, adding behavior the annotation can't: max 200 items with a truncated flag, retention windows (keepDays/libraryDays/templateDays), and that purgeAt null means kept until deleted forever. This is exactly the extra context the annotation bar asks for.

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 scope and the newest-first ordering, then the return shape, then the sibling routing. Dense and nearly waste-free, though the item-shape enumeration and the four sibling name pairs make it a long single paragraph that could be split for scanability.

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

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

No output schema exists, so the description carries the full burden of describing the return value and does so precisely (items fields, total, truncated, max 200, retention fields, purgeAt semantics). An agent has everything needed to call it and interpret the result.

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

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

Zero parameters, so the baseline is 4; the description has no parameter semantics to add and none are needed. It redirects that space into return-shape detail instead.

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 ('one newest-first list of projects, clips of live projects, library items and templates'), plus the scope 'Restorable deletes (the Deleted page)'. That scope qualifier cleanly separates it from list_projects, search_clips and the restore_*/purge_* 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?

Explicitly routes the agent: restore_project/restore_clip/restore_asset/restore_layer_template bring items back, purge_* removes them permanently, implying this tool is the read-only discovery step before either. It doesn't state an explicit 'do not use for X' exclusion, which keeps it from a 5.

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

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

Goes well beyond the readOnlyHint annotation: it discloses the admin-only permission requirement, the hosted-tier refusal behavior, the aggregation semantics (child clips are collapsed into the parent project failure), and the truncation/nextCursor pagination behavior. These are exactly the traits an agent needs before calling.

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: access restriction first, then scope, then the clip-aggregation caveat, then return shape, then filters. Slightly crammed, but nearly every clause carries information an agent needs.

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

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

There is no output schema, yet the description names the return keys ({ items, nextCursor, total, limit, truncated }) and explains pagination via cursor. Combined with the auth and filtering notes, an agent has enough to call this correctly without inspecting anything further.

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 five parameters are already documented with examples and formats. The description only restates q, stage, and since at a high level and says nothing about limit or cursor, so it adds marginal value over the schema — baseline 3.

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

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

States a specific verb and resource ('failed projects and clips across the instance') plus the fields returned (owner email, stage, reason, when). It is clearly distinct from get_failure (single item) and retry_failures in intent, though it 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?

Explicitly scopes the audience ('Admins only', 'Hosted non-admins are refused') and gives a concrete routing rule: a failed project's clips are not listed separately, so retry the project instead. It also tells the agent which filters to apply (q, stage, since), though it doesn't contrast against get_failure or retry_failures by 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?

With readOnlyHint already declaring safety, the description adds substantial behavior: newest-first ordering, pagination via nextCursor, a deleted field meaning restorable items, and detailed semantics for layer timing modes. This goes well beyond what annotations provide and gives an agent operational context for interpreting results.

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

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

The description is front-loaded with the tool's purpose and has no filler, but it is a single dense run-on sentence with many nested clauses. The information density is justified because there is no output schema, though readability could be improved with structural separation.

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

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

There is no output schema, so the description must carry return-shape information, and it does: it names the item fields, explains nextCursor/total/deleted, and defines the timing object used by layers. For a read-only listing tool with only two simple parameters, this is complete enough for an agent to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that nextCursor goes into cursor when paging, which clarifies how the pagination parameter is meant to be used.

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 pair: it lists the caller's layer templates, defines them as reusable layers plus optional intro/outro, and states the default ordering (newest first). That clearly separates it from sibling mutation tools like save_layer_template, update_layer_template, apply_layer_template, and delete_layer_template.

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

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

Usage is implied by the verb 'Your layer templates' and by the pagination details, but there is no explicit when-to-use guidance, prerequisite note, or alternative mentioned. An agent can infer this is the listing/read tool, but the description does not route it against alternatives such as get_clip or apply_layer_template.

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, so safety is covered; the description adds genuinely non-obvious behavior by disclosing that URLs are masked, that items carry a state enum with active/expired/revoked values, and that pagination is cursor-based via nextCursor. Nothing here contradicts the read-only annotation.

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

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

Two sentences, zero filler, with scope and ordering front-loaded and the alternative routing in the second sentence. The return-shape enumeration is long but dense with useful field-level detail that no output schema provides.

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, describing the returned fields, the cursor, and the total is exactly the right compensation, and the masking caveat prevents misuse of the url field. The only gap is that the available filters are never surfaced in prose, though the schema covers them fully.

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 limit, active, clipId, cursor, and projectId are all documented in the schema. The description adds no parameter meaning beyond that — it never mentions the filtering options — so it sits at the baseline rather than exceeding 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 the resource ('Your share links') and the ordering ('newest first'), which pins down this as a personal-scope list operation distinct from get_media_links. It never uses an explicit list verb, but the name plus scope wording is unambiguous enough for an agent to select it.

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

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

It names a sibling alternative and the exact condition that selects it: 'Use get_media_links for a full URL.' It gives no guidance on when this tool should not be used (e.g., filtering for a specific project vs. browsing all), so it falls short of explicit when/when-not coverage.

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