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: accepted formats and size/duration limits, duplicate semantics ('the same file twice returns the existing item'), and the returned object shape { id, name, kind, durationSec, duplicate, restored }. It also scopes setDefault to new projects. This is unusually rich behavioral disclosure for a mutation 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?

Three tight sentences with no filler, front-loaded with the core action and its constraints before the routing note about set_project_bumpers. Every clause carries information.

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

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

No output schema exists, so the description's inline return shape is a genuine asset, and with no annotations it adequately covers limits, idempotency, and defaults. It stops short of stating permission/auth requirements or what happens if both url and uploadId are omitted (all 5 params are optional).

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the url-vs-uploadId mutual alternative and the new-projects-only scope of setDefault. It does not explain imageSeconds, which is left entirely to 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 concrete verb (add) plus the resource (video/image bumper) and the two accepted input sources (public url or uploadId). An agent can distinguish this from rename_bumper, list_bumpers, or set_project_bumpers 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 explicitly routes the 'make this the default' case: setDefault affects NEW projects only, and existing ones require set_project_bumpers. That names an alternative and the condition selecting it. It does not, however, spell out when to use add_bumper versus list_bumpers/restore_bumper, though those are largely self-evident from the name.

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

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

Annotations already declare readOnlyHint=true, lowering the burden, and the description goes further by describing the exact return shape (nested projects/clips with slots and via) and explaining what 'via' means. That is real added context beyond the annotations, though it says nothing about permissions or result 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?

Front-loads the purpose, then the return shape, then the actionable cue. Mostly tight, though the inline JSON-ish return shape and the 'via saying whether through the project or the clip's own choice' clause are a little dense.

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

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

With no output schema, the description compensates by spelling out the return structure and the meaning of 'via', and it covers the sole parameter and usage context. It is complete enough to invoke correctly, with only minor gaps around result scale.

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 is documented there (asset id, from list_bumpers), so the schema carries the burden. The description adds no parameter-level detail, making the baseline 3 appropriate.

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

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

States a specific purpose: it returns 'the projects and clips that use a library item,' which is a clear verb+resource and distinctive from siblings like list_bumpers or remove_bumper. It does not explicitly name a sibling to contrast with, but the impact-analysis intent is unambiguous.

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

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

The closing phrase 'Check before removing one' gives a concrete when-to-use tied to the removal workflow (remove_bumper). It conveys the context clearly but does not name the alternative tool or state exclusions explicitly.

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 behavioral burden and does so: it discloses the transcript prerequisite, the async lifecycle (returns status "preparing", renders in background ~1 minute), the required polling via get_clip, and the distinct duration constraints per mode (3 s–10 min for exact, ≥8 s for ai). This is context an agent cannot get from the schema alone.

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 tight sentences, each earning its place, with the core purpose front-loaded and the routing advice, lifecycle, and constraints following in priority order. No filler or restatement of the tool name.

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

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

No output schema exists, and the description compensates by describing the return shape and the polling flow. Slight gaps remain around failure modes (e.g. missing transcript, out-of-range bounds) and permissions, but for a 4-param create tool it is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: numeric bounds for mode=exact (3 s–10 min) and mode=ai (≥8 s) are not present in the schema's enum description. It adds constraints, though it doesn't restate projectId/startSec/endSec semantics.

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

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

States a specific verb+resource ("Add a clip from a time range of the source") and immediately names the sibling it is not (update_clip for existing clips). An agent can distinguish it from update_clip/rerender_clip without opening any schema.

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

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

Explicitly routes to the alternative: "To change an existing clip use update_clip instead," and states the prerequisite (needs a transcript) plus the follow-up flow (poll get_clip until done). When-to-use and when-not-to-use are both covered.

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

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

No annotations are provided, so the description carries the full burden, and it delivers the key behavioral trait: the call is asynchronous, returns immediately with status 'queued', and the download/transcribe/pick/render pipeline runs for minutes. It also documents the return shape and the intro/outro defaulting behavior. It omits permission/auth requirements and rate limits, so not 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 dense sentences, front-loaded with the purpose, then the return value, then the async lifecycle and the next-tool handoff, then defaults. No filler; every clause carries actionable 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 and no annotations, the description compensates well: it explains the immediate return object, the background pipeline duration, and the follow-up call. Combined with a 100%-covered input schema, an agent has everything needed to invoke 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 description coverage is 100%, so the schema already documents all 7 parameters in detail, establishing a baseline of 3. The description adds only the intro/outro defaulting rule, which the schema's own parameter descriptions largely already state ('omitted = your default intro'), so the marginal value is small.

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

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

States a specific verb and resource ('Start clipping a video from a URL') with the accepted source kinds enumerated (YouTube, Vimeo, direct link, anything yt-dlp fetches). This clearly distinguishes it from create_clip, which operates on already-analyzed clips.

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

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

Explicitly routes the agent to the follow-up tool: 'the pipeline runs in the background for minutes, so follow with wait_for_project(id).' That is a clear when-to-use-next instruction. It does not state when NOT to use it (e.g. re-analyzing an existing project via reanalyze_project), so it falls short of a 5.

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

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

Goes well beyond destructiveHint/idempotentHint: it discloses the side effect ('a render in progress stops'), that the deletion is soft and restorable for DELETED_RETENTION_DAYS (7 by default), and the exact return shape { changed, restorable } despite there being no output schema. That is the full behavioral picture for a destructive mutation.

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

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

Two dense sentences, front-loaded with the action and its immediate side effect, then the undo contract and return value. No filler; every clause carries information.

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

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

For a single-parameter destructive tool with no output schema, the description supplies reversibility, retention duration, in-flight render behavior, and return fields. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100% and the single `id` parameter is already documented in-schema as coming 'from get_project or search_clips'. The description adds no format or provenance detail beyond that, 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 ('Delete one clip of your project'), with the scope ('one clip') making it clearly distinct from delete_project and restore_clip in the sibling list. An agent can pick it out 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 the concrete alternative in 'Reversible: restore_clip brings it back' plus the retention window, which tells an agent both the undo path and its deadline. It doesn't spell out when to prefer update_clip or rerender_clip over deletion, so it stops short of full when/when-not coverage.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing the cascade to clips, that in-progress work stops, the 7-day retention window before permanent file removal, and the exact return shape. This is the kind of consequence detail an agent needs before calling a destructive tool.

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

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

Three compact sentences: effect first, reversibility second, return contract last. No filler and the destructive consequence 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?

Covers the cascade, the undo window, and the return payload even though no output schema exists, so 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?

Schema coverage is 100% and the single 'id' parameter is already documented with its source tools, so the description adds nothing parameter-specific. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb and resource ('Delete one of your projects and all its clips') plus the cascading scope. An agent can distinguish it from delete_clip and restore_project 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?

Names the recovery path explicitly ('restore_project brings it back for DELETED_RETENTION_DAYS'), which tells the agent the alternative and the time window for undo. It doesn't spell out when this is preferable to other cleanup calls, but the context is clear.

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

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

Annotations only cover readOnlyHint=true, so the description carries most of the behavioral burden. It discloses an important non-obvious trait: the returned URL requires the same Authorization header as the server, plus the return shape ({ url, clips, notRendered }) in the absence of an output schema. It still omits whether the export is synchronous or how rendering gaps should be handled.

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

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

Two tight sentences with zero filler: the first gives the payload and its contents, the second gives the return shape and the auth caveat. Information is front-loaded and every clause earns its place.

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

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

For a two-parameter read with no output schema, the description covers what the download contains, the response fields, and the auth requirement for the link. Minor gaps remain around failure/partial-render behavior, but nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so both id and clipIds are already fully documented (including the max 200 and 'must be rendered clips' constraints). The description adds no parameter-level meaning beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific resource and output: a zip download link of the project's rendered clips bundled with YouTube/TikTok metadata. No sibling tool does export/download, so an agent can distinguish it immediately from create_project, rerender_clips, 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?

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., clips must be rendered first), and no mention of what happens when nothing is rendered. Usage is only weakly implied by the noun phrase 'rendered clips'.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real behavioral value by disclosing that render status transitions to 'done' and that render diagnostics are part of the response, implying eventual-consistency/polling semantics. It stops short of stating polling cadence, rate limits, or freshness guarantees.

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

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

Front-loads the scope in one sentence, then the return behavior, then the sibling/polling guidance. The long field enumeration is dense but earns its place since there is no output schema; only minor trimming is possible.

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

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

With no output schema, the description compensates by listing the returned contents and confirming 'Returns the clip object', and it covers the read-only nature via annotations plus the render-polling lifecycle. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single 'id' param is already documented in the schema (from get_project or search_clips). The description adds no syntax, format, or edge-case detail 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?

States a specific verb and resource ('Everything about one clip') and then enumerates the concrete payload (text, bounds, scores, framing, style, intro/outro, render diagnostics, links), so the agent knows exactly what comes back. It also explicitly distinguishes itself from the sibling 'get_project', which returns clips only in brief.

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

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

Names the alternative (get_project for a brief list of all clips) and the condition that selects it, plus a concrete follow-up workflow: 'poll this after an edit to see the render finish (status done)'. The agent can route between list-view and single-clip-view without guessing.

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?

Annotations already declare readOnlyHint=true, and the description adds real value beyond that: it discloses the ordering (newest first), the return shape ({ at, type, ...details }), and the kinds of diagnostic content (failures with reasons). It does not mention pagination behavior for the limit cutoff, but is otherwise well-disclosed for a read-only 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 dense sentences, front-loaded with the resource and ordering, followed by the return shape and a routing hint. Every clause carries information; no filler.

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

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

For a read-only, two-parameter tool with no output schema, the description supplies the return shape, ordering, event taxonomy, and sibling routing. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so id and limit are already fully documented, giving a baseline of 3. The description adds only marginal meaning beyond the schema by implying chronological ordering; it does not elaborate on the limit's effect on older events.

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 project's pipeline history') and enumerates the exact event types returned (stage starts/completions, clip renders, retries, failures with reasons). It explicitly distinguishes itself from get_project, so an agent can separate the history tool from the current-state 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?

Gives a concrete use case ('find out why something failed or is slow') and names the alternative (get_project shows current state). This is a clear when-to-use plus alternative, though it never states when NOT to reach for this tool or any 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?

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 already declare readOnlyHint=true, so safety is covered; the description adds genuine value beyond that by disclosing the return shape and the behavioral detail that removed items remain restorable for 30 days. This is more than restating the 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?

Front-loaded purpose, then return shape, then actionable usage note; no filler sentences. The embedded return-shape listing is dense but justified since there is no output schema 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?

With no output schema, the description usefully enumerates the returned asset fields and the removal/restore window, which an agent needs to act on the result. It is nearly complete; only the sibling-alternative routing is absent.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description appropriately spends instead on return-value structure rather than fabricating parameter detail.

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?

Name, title, and the opening phrase 'Your intro/outro library' make clear this lists the bumper (intro/outro) assets. The resource is specific and it is distinguishable from sibling setters, though the listing verb itself is only implied rather than stated outright.

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

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

It tells the agent what the returned ids feed into: set_project_bumpers, set_clip_bumpers, or set_default_bumper, which contextualizes when to call it. It does not name a competing tool (e.g. bumper_usage) or state exclusions, so it falls short of the explicit alternative routing seen in the top-tier example.

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 already covers the safety profile, so the description's added value is the sort order, the inline return shape (including the derived 'clips: n/m rendered' field), and the pagination contract. It does not mention rate limits or auth, but for a read-only list tool the disclosed behavior is substantive.

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

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

Three tight clauses: identity/ordering, return shape + pagination, then sibling routing. Front-loaded and every sentence carries information an agent needs; nothing is padding.

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

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

No output schema exists, but the description documents the return payload and cursor field anyway, and it covers ordering and next-page mechanics. Combined with a fully described parameter schema, an agent has everything needed to call and page through 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 description coverage is 100%, so limit, cursor, and deleted are already fully documented, including the restore_project link for deleted. The description only restates the cursor handoff, adding no meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Your projects'), plus the ordering ('most recently updated first'), which immediately separates it from the mutating project siblings. It also names the two relevant alternatives (get_project, search_clips), so an agent can route without opening a schema.

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

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

Explicitly names alternatives with the condition that selects them: get_project for a single project's clips, search_clips for finding by words. Pagination guidance ('pass nextCursor as cursor for the next page') tells the agent exactly how to continue a multi-page call.

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 behavioral burden and does it well: it discloses that edited clips are preserved, that untouched AI picks are replaced but restorable via restore_clip 'for a while', the immediate return shape { kept, replaced }, and that picking is asynchronous. The only shortfall is that 'for a while' is vague about the actual restore window and no permission/lock requirements are noted.

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, zero padding, front-loaded with the action and the prerequisite, then preservation semantics, then return/async behavior, then sibling routing. Every sentence earns its place.

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

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

For a tool with no output schema and no annotations, the description covers the prerequisite, destructive/restorative side effects, the return contract, and the async follow-up. An agent has everything needed to call it correctly and chain the next step.

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 nested settings object is thoroughly self-documented, so the baseline is 3. The description adds only 'optionally with new settings' and does not clarify any non-obvious behavior (e.g. whether partial settings merge with existing values) beyond the schema.

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

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

Specific verb ('pick clips again') plus resource ('existing transcript'), with the prerequisite stated inline ('needs one'). It explicitly separates itself from update_project and retry_project, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives the when (re-pick from an existing transcript, optionally with new settings), the alternatives and their conditions ('To only save settings use update_project; to resume a failure use retry_project'), and the required follow-up ('follow with wait_for_project'). Nothing is left to inference.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing the blast radius ('Projects and clips already using it keep rendering with it'), the 30-day undo window, and the return shape { ok }. These are the non-obvious behaviors an agent needs before performing an irreversible-feeling delete.

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 short sentences, front-loaded with the action and its scope, then recovery, then prerequisite, then return value. Every sentence carries distinct information with no repetition of the title or schema.

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

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

For a one-parameter destructive tool with no output schema, the description covers effect scope, reversibility window, prerequisite check, and response shape. An agent has everything needed to call it safely and to recover from a mistake.

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

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

There is a single required parameter with 100% schema description coverage ('Library asset id (from list_bumpers)'), so the schema already carries the meaning and the description adds nothing further about it. 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 an item from your library and from your defaults') and immediately scopes what it does not touch. It names the sibling tools that matter (restore_bumper, bumper_usage), so an agent can place it against add_bumper/set_default_bumper 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 a concrete prerequisite ('check bumper_usage first') and the recovery path ('Undo with restore_bumper within 30 days'), which is real when-to-use guidance. It stops short of stating when not to use it (e.g., preferring set_default_bumper to merely swap a default), so it 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 only declare idempotentHint=true, so the description adds real value: 'Only the label changes; nothing re-renders' sets expectations about side effects, and the return shape is disclosed. It still omits permission/auth requirements and what happens if the asset doesn't exist.

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

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

Three short sentences, front-loaded with the action and scope, with the side-effect caveat and return shape following. Every sentence earns its place.

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

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

For a simple two-parameter mutation with an idempotency annotation, the description covers purpose, side effects, and return shape. Output schema is absent but the return fields are given inline, leaving little of consequence missing.

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

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

Schema description coverage is 100%, with both assetId and name documented including length bounds. The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (rename) and resource (library item / bumper), and the title clarifies 'bumper' means intro/outro. It does not explicitly distinguish itself from siblings like add_bumper or remove_bumper, but the operation is unambiguous.

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

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

The parenthetical '(removed ones too)' implies you may rename a removed item without restoring it first, which is a useful usage hint. However, there is no explicit when-to-use guidance and no named alternative (e.g., restore_bumper) is referenced.

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 carry idempotentHint, so the description adds substantial behavior: it is async, the new video replaces the old on completion (usually under a minute), the agent should poll get_clip, and the return shape { step: render | prepare } with the meaning of 'prepare'. This is rich context beyond the structured fields.

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

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

Dense but front-loaded: the action, the trigger conditions, the async semantics, and the sibling alternative all land within a few sentences with no wasted 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, so the description carries the return value and its variant ('prepare' vs 'render'), the async/polling model, and the replacement behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema itself documents the id parameter in detail ('Clip id, not a project id (from get_project or search_clips)'). The description adds no further param syntax or format, 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 ('Queue one clip for rendering again') and explicitly scopes it to a single clip, naming the plural sibling rerender_clips for multi-clip use. An agent can distinguish it from rerender_clips without opening either schema.

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

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

Gives concrete triggering conditions (rerender: false edits, a failure, or an intro/outro change) and names the alternative 'For several clips of a project use rerender_clips'. When-to-use and the sibling routing are both explicit.

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

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

Goes well beyond the lone idempotentHint annotation: it states which clips are queued versus skipped (finished/failed queued, still-rendering skipped), that each new video replaces the old on completion, and names the return payload. This is exactly the behavioral context an agent needs for a mutation-queue 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?

Four tight sentences: purpose, queue/skip semantics, return shape plus polling hint, and the sibling redirect, in that order. No filler and nothing redundant with the schema.

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

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

For a two-param batch mutation with no output schema, the description covers the trigger, the skip/replace semantics, the exact return shape, and the follow-up polling tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, with clipIds documenting the 1-200 bound and projectId its source, so the schema already carries the parameter semantics. The description adds no syntax or format detail beyond referring to 'several clips of one project', 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 ('Queue several clips of one project for rendering again') with scope ('in one step') and contrasts it against the single-clip sibling rerender_clip. An agent can distinguish it from rerender_clip and retry_project without opening any schema.

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

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

Gives the trigger conditions ('after edits or failures') and explicitly names the alternative for a narrower use case ('For a single clip rerender_clip is enough'). When-to-use and when-to-use-something-else are both present.

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

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

Annotations only declare idempotentHint=true; the description adds two real behavioral facts beyond that — the no-op outcome for non-removed items and that default status is not restored. It also discloses the return shape { ok }. It does not say what happens with an unknown or invalid assetId, which limits it to a 4.

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

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

Three short clauses: the action, the no-op caveat, the non-default caveat, plus the return shape. The core action is front-loaded and every sentence carries information an agent could act on.

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

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

For a single-parameter, idempotent restore with no output schema, the description covers what the tool does, the state precondition, side effects, and the response shape, so an agent can call it confidently. The only omission is failure behavior for an invalid or already-deleted assetId.

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 assetId property description already says "Library asset id (from list_bumpers → removed)". The description paraphrases the same sourcing hint without adding format, validation, or error semantics, so the baseline 3 applies.

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

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

"Bring one of your removed library items back" states a specific verb and resource, and naming list_bumpers anchors it to the bumper library rather than projects or clips. It never uses the word "bumper" explicitly, so the tie to the title (intro/outro) relies on the sibling reference.

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 tells the agent the precondition (item must be in the removed state, discoverable via list_bumpers) and what happens outside it ("restoring an item that is not removed changes nothing"). "It does not become a default again" implicitly routes the agent to set_default_bumper for that goal, but the alternative is never named outright.

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 idempotentHint=true, so the description carries most of the load and does it well: it discloses the positional side effect (the clip goes to the end of the project's clips) and the return shape { changed, status, needsRerender } with the meaning of needsRerender. It does not discuss permissions or whether restoring a replaced clip affects the replacing clip, leaving a small gap.

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

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

Two dense sentences with no filler: the capability and the affected set come first, then the return-value semantics and the required follow-up call. 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?

With no output schema, the description compensates by naming the returned fields and interpreting needsRerender, and it explains the placement side effect. For a one-parameter restore tool with only an idempotency annotation, nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% for the single id parameter, so the schema already documents the type and its provenance. The description repeats the same hint ('from get_project → replacedClips') without adding format or syntax detail, so this is the baseline 3 rather than added value.

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

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

States a specific verb (bring back) and resource (a deleted clip or one a re-analyze replaced), and names the exact source of such clips (get_project lists them as replacedClips). This is clearly distinguishable from siblings like delete_clip, rerender_clip, and get_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 clear trigger (restore a deleted or re-analyze-replaced clip) and explicitly routes the follow-up case: 'needsRerender means it never finished, so call rerender_clip.' No explicit when-not-to-use or alternative such as delete_clip is named, so it stops short of full routing guidance.

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

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

Annotations only declare idempotentHint, so the description carries most of the burden and delivers: the no-op case for non-deleted projects, the state transition where a processing project returns as failed, and the return shape { changed, status } despite no output schema. It does not mention permission/auth requirements, which is the only real gap.

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

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

One dense but well-ordered sentence: core purpose first, then discovery, then the no-op caveat, then the processing 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?

For a one-parameter mutation with an idempotency annotation and no output schema, the description supplies exactly what is missing: precondition, no-op behavior, state edge case, and the return shape. Nothing needed 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?

Single parameter with 100% schema description coverage, and the schema already says the id comes from 'list_projects with deleted: true' — the description repeats that same hint rather than adding new meaning. Baseline 3 applies when the schema does the work.

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

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

States a specific verb (restore) and resource (deleted project), and explicitly scopes what is recovered: 'with its clips and files'. It also names sibling tools (list_projects for discovery, retry_project for the processing case), so an agent can distinguish it from delete_project/restore_clip 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?

Explicitly states how to find the target ('find it with list_projects deleted: true'), what happens when the precondition fails ('restoring a project that is not deleted changes nothing'), and which alternative to use for the processing case ('retry_project resumes it'). Both the when and the when-not are covered.

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

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

With no annotations, the description carries the full burden and does well: it discloses what is preserved (finished clips, transcript, source), what gets redone (re-render unfinished clips, else pick/refine/transcribe), and the return shape { queue }. It does not mention permissions, cost, or idempotency of repeated retries, which keeps it short of a 5.

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

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

Front-loaded with the action and scope, then behavior, return value, and alternative. Dense but nearly every clause carries information; the branch enumeration ('re-render unfinished clips ... else pick clips, refine or transcribe again') is slightly heavy for a one-line description.

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

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

There is no output schema, so the description supplies the return value itself ({ queue }, the restarted stage) plus the follow-up tool. Combined with the stated preservation semantics, an agent has everything needed to call and chain this 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?

Only one parameter (id) and schema coverage is 100%, so the schema already documents its origin. The description adds no param-level detail, but with a single fully described parameter the baseline is 4.

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

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

States a specific verb (resume/retry) and resource (a failed or stuck project), and pins the starting point precisely ('from its furthest completed stage'). It also names the sibling it is not (reanalyze_project), so an agent can distinguish it without opening a schema.

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

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

Gives an explicit trigger condition ('failed or stuck project'), an explicit alternative with its condition ('To pick different clips use reanalyze_project instead'), and a follow-up step ('then wait_for_project'). Nothing about routing is left to inference.

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

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

Annotations only declare readOnlyHint=true, so the description carries matching and ranking behavior: every word must match, case-insensitive, typo-tolerant, best-first ordering. It also discloses the return envelope (projects max 8, clips max limit, ids/bounds/links, truncated flag) despite no output schema. It stops short of error or rate-limit behavior, keeping it out of top marks.

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

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

Three tight sentences with no filler: what it searches, what it returns, and the alternative tool, in that priority order. Every clause earns its place and the core 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?

No output schema exists, and the description compensates by outlining the result shape including the truncation flag and per-entity caps. Combined with full schema coverage on both parameters and the explicit sibling alternative, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics for q: implicit AND across every word, case-insensitive, typo-tolerant matching, and it clarifies that limit caps only the clips portion of the result. That is meaning beyond the schema's terse 'Words to find' example.

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 (Find) applied to specific resources (clips and projects) and names the searched fields (title, hook, caption). An agent can immediately distinguish search_clips from list_projects, the browsing sibling, 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?

Provides a concrete routing rule — 'Use list_projects to browse instead' — which contrasts searching by keyword versus browsing. It is clear context with an explicit alternative, though it doesn't cover edge cases like empty results or when to prefer get_clip over search for a known id.

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 partial-update semantics (omitted slots untouched), the meaning of each value mode, the rerender side effect ('re-renders only these clips'), and the return shape ({ updated, rerendered }) despite having no output schema. It omits permission requirements and what happens to clips that keep an inherited bumper.

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, front-loaded sentences with no filler: value modes and scope come first, then the rerender caveat, then the return shape. 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?

For a 7-parameter mutation with no annotations and no output schema, the description covers the critical gaps: operation scope, partial-update behavior, side effects, and the return shape. It stops short of stating prerequisites (e.g. that clipIds must belong to projectId, or permission needs).

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds value beyond it with the 200-clip cap, the slot-omission rule, and the scoping of 'rerender: true' to only the affected clips. The enum value semantics largely duplicate the schema's own parameter descriptions.

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

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

The description gives a specific verb (override) and resource (intro/outro of clips) plus a hard scope bound ('up to 200 clips of one project'), which implicitly separates it from the project-level sibling set_project_bumpers. An agent can tell what this tool mutates and on which entities 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?

Usage is implied by the clip-level scope and the partial-update note ('a slot left out is untouched'), but no sibling is ever named and there is no explicit 'use set_project_bumpers instead when...' routing. The agent must infer the clip-vs-project split from the description alone.

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

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

Annotations only provide idempotentHint; the description adds valuable scope behavior (future-only effect) and the null-clears semantic. It also mentions the return shape, though it doesn't note auth requirements or what happens to already-defaulted rows.

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

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

Three short clauses, front-loaded with the main action, then the scope caveat, then the return shape — zero waste.

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

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

For a 2-param idempotent setter with no output schema, the description covers scope, clear semantics, alternative tool, and return value. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds the 'assetId null clears it' semantic that clarifies the anyOf-null branch beyond the schema's terse 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?

States a specific verb (make default) and resource (intro/outro bumper), and clearly scopes it to future projects versus existing ones, distinguishing it from set_project_bumpers.

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 it affects projects created from now on, tells the agent existing projects are unchanged, and names the alternative (set_project_bumpers) for that case.

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 well: it discloses override precedence (clip-level choices survive), timing semantics ('Applies on each clip's next render'), the effect of rerender:true (re-renders finished clips now), that a slot left out is untouched, and the return shape ({ rerendered }).

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

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

Dense and front-loaded: the core action and value semantics come first, then precedence, then effect timing and the sibling routing. The colon/semicolon chain makes it slightly run-on, but every clause carries information.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description covers what is mutated, what is left alone, when changes take effect, override precedence, the return value, and the alternative tools. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema by explaining that omitted slots are untouched and that introSec/outroSec are persisted with the project while clip-level choices override them. The enum-value meanings largely duplicate the schema text.

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

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

Opens with a specific verb and resource scope ('Set one project's intro and/or outro'), immediately distinguishing project-level bumper config from the clip-level and default-level siblings. An agent can tell this apart from set_clip_bumpers and set_default_bumper 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 both adjacent tools and their scopes: clip-specific choices win ('Clips with their own choice (set_clip_bumpers) keep it') and set_default_bumper 'changes future projects instead'. It gives clear context for selection, though it never states an explicit 'use this when' rule or exclusion beyond the scope contrast.

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 behavioral burden and does so well: it discloses partial-update semantics, that style/layoutSections REPLACE the whole value (with null reverting to project defaults), the split between instant text edits and background-burned edits, the ~1 min async re-render, the rerender:false escape hatch, and that the response is the clip summary with a new status.

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 most consequential fact (only passed fields change) before the render/timing details and the follow-up call. No filler; every clause conveys a distinct behavioral fact.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description covers update semantics, async rendering, return shape and the polling loop. It omits error/conflict handling and any permission requirements, which are the remaining gaps for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond it by grouping parameters into instant text fields (title, caption, hashtags) versus burned-in fields (bounds, hook, framing, style, emphasis) and by clarifying the replace-vs-merge contract per group.

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 ('Edit one clip') and immediately scopes it with the merge semantics ('only the fields you pass change'), which distinguishes it from update_project, set_clip_bumpers and rerender_clip. An agent knows this is the partial-metadata-and-render edit path without opening any schema.

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

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

It routes the agent to companion tools: poll get_clip until the re-render finishes, and it implies rerender_clip is the alternative when rerender is false. It doesn't state an explicit 'use this when X, use Y instead' exclusion, but the context for each edit class 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 carry only idempotentHint, so the description does most of the work: it discloses partial-update semantics, the absence of reanalysis/rendering side effects, the follow-up tools needed to realise those effects, and the shape of the return object. It stops short of stating permission requirements, reversibility, or that a returned needsReanalyze flag implies a follow-up call is mandatory, so it is strong but not exhaustive.

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, zero filler: capability and field list first, patch semantics and the not-does boundary second, sibling routing and return shape last. Each sentence carries distinct 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?

For a mutation tool with a 26-key nested settings object and no output schema, the description supplies the patch contract, the non-effects, the routing to reanalyze_project/rerender_clips, and the four return keys. Nothing required 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 description coverage is 100% and every parameter (including the nested settings keys, the clear enum and the deprecated captionPosition) is documented inline. The description's parenthetical field list only re-summarises a subset of what the schema already states, so it adds no meaning beyond it; 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 (rename/change saved settings) and resource (project), then enumerates the affected settings groups (focus, instructions, clip length, maxClips, caption style, framing, pauses). It explicitly separates itself from reanalyze_project and rerender_clips, so an agent can route correctly without opening any schema.

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

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

States the patch condition ('only the fields you pass change'), what this tool does NOT do ('Does not re-pick clips or re-render'), and which sibling to use for each of those cases with the trigger condition. Both alternatives are named explicitly.

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 rest: it discloses that the call blocks, the timeout behavior, and the retry-on-timeout pattern. It adds the concrete return shape (status, stage, stageProgress, error, clips) without an output schema. Minor gap: no mention of auth or rate considerations, but the behavioral core is well covered.

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

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

Front-loads the blocking behavior and termination conditions, then the return shape and alternative. Dense but every clause earns its place; the inline return object is compact rather than bloated.

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 return structure and the timeout/retry hint, and it covers the blocking semantics and alternative tool. An agent has everything needed to invoke 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 description coverage is 100%, so both id and timeoutSeconds are already documented in the schema. The description only alludes to timeoutSeconds in passing and adds no syntax or semantics beyond the structured field, 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?

States a specific verb (block/wait) and resource (project), and gives the exact termination conditions: done, failed, or timeoutSeconds elapsed. It also names the sibling it is not (get_project) for non-blocking reads, 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: use get_project instead for a non-blocking look, and call this again if the timeout hint 'Still running' is returned. Both the when and the alternative are stated directly.

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