pitchboom

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

Adds substantial context beyond annotations: it costs no credits but counts toward a daily URL-analysis quota, it creates/mutates a draft project (consistent with readOnlyHint=false), and it is asynchronous, requiring polling. The quota and async-polling disclosures are exactly the kind of behavior an agent cannot infer from the annotation block.

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 cost/quota note, then the action, then the required follow-up, then the alternative. 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?

The async workflow is covered, but with no output schema the description never says what analyze_url returns (job id, project id, or status) or how to identify which project to poll. For an async mutation tool that is a meaningful gap in an otherwise strong definition.

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

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

Schema coverage is only 33% — project_id is described in the schema, while url (required) and language have no descriptions at all. The description clarifies that project_id defaults to a new draft project, but never mentions the language parameter or its effect, leaving one of three parameters completely opaque to the caller.

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 (starts reading a website) and resource, and enumerates exactly what gets extracted (screenshots, colors, fonts, logo, copy). It distinguishes itself from siblings by naming get_project (polling) and create_project (which already does this with a 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?

Explicitly routes the agent: it says to poll get_project until analysis_status is ready, and that create_project with a url already performs this analysis, implying this tool is for the standalone/into-existing-project path. Both the follow-up tool and the overlapping alternative are named.

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

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

Annotations already establish that this is a non-readonly, destructive, idempotent operation. Beyond that, the description discloses the concrete side effects (voice-over, music, render), that credits are held at confirm, and crucially what happens if the price has increased: nothing runs and the new total is returned for the user.

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

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

Two concise sentences, front-loaded with purpose and immediately followed by the critical max_total constraint and failure behavior. Every sentence carries operational value.

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

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

For a destructive mutation with no output schema, the description covers the important behavioral details: side effects, credit gating, and the failure return path. It could be stronger by clarifying the job_id/video_id selection or success response, but the core invocation guidance is complete.

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

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

Schema description coverage is 67%, and max_total is already documented in the schema. The description adds useful failure behavior for max_total, but does not explain the job_id-video_id choice beyond what the schema partially provides.

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

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

States a specific action and resource: resuming a video that is waiting for storyboard approval, including the downstream voice-over, music and render work. It is clear enough to distinguish from get_storyboard/update_storyboard, though it does not explicitly name or contrast with confirm_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?

The condition for use is clear: the video must be waiting for storyboard approval, and max_total must match the total the user accepted. It does not explicitly state when not to use it or name sibling alternatives, but the triggering context is well specified.

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 covered. The description adds genuinely new context beyond the annotations: partial billing ('pay only for steps already finished') and credit-hold release, which materially affects an agent's decision to cancel. It doesn't say whether in-flight steps are terminated or whether cancellation is irreversible, keeping it below a 5.

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

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

Two tight sentences with zero filler, and the operation scope is front-loaded ahead of the billing consequence. 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?

Annotations cover the safety/idempotency profile and the description adds the billing consequence, so the agent has what it needs for a one-parameter mutation. Without an output schema, some return-value or terminal-state behavior (e.g., canceling an already-finished job) is unstated, but this is a minor gap.

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

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

Schema description coverage is 0%, but the single parameter is job_id with an explicit uuid format and pattern, making it largely self-explanatory from the schema itself. The description adds nothing about the identifier, which is acceptable here but leaves no margin above baseline.

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

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

Specific verb ('Stops') plus resource ('job') and explicit state scope ('queued, running or approval-waiting'). An agent can immediately distinguish this from siblings like get_job_status or edit_video.

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

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

The description constrains usage by naming the three job states eligible for cancellation, which tells the agent when this applies. It does not explicitly name an alternative (e.g., get_job_status to verify state first) or state what happens on an already-completed job, 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?

Adds substantial context beyond the annotations: credits are held up front, billing is consumption-based, unused credits return automatically, and platform-side failures are refunded. The idempotency note overlaps idempotentHint=true but is framed usefully as 'confirming the same quote twice starts nothing new', clarifying the practical consequence rather than restating the flag.

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, none wasted, front-loaded with the step position and the action before the approval gate and billing details. Dense but readable.

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 commit tool with rich annotations and no output schema, everything an agent needs is present: gating condition, cost behavior, refund semantics, and duplicate-confirm behavior.

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

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

Schema coverage is 100% and the quote_id description already names the four producing tools, so the schema carries the parameter burden. The description only adds the notion of 'this exact quote and amount' and reuse of the same quote twice; 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?

States a specific action chain – holds the quoted credits and starts the work – plus the 'Step 2 of 2' framing that separates it from the estimate/quote sibling. An agent can tell this is the commit step, not a read or a quote request, 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?

Gives a clear hard precondition: call only after the user explicitly approved this exact quote and amount. It does not name the companion tools (get_estimate, create_project) or say what to do instead when approval hasn't happened (e.g., cancel_job, get_estimate), so routing is strong but not fully enumerated.

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

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

Adds substantial behavior beyond the annotations: nothing is charged, the site analysis is free, the call returns a quote rather than a job, quotes expire after 30 minutes, and the tool is non-destructive and gated on user approval. Language resolution precedence (explicit > site > brief > en) is spelled out with the timing caveat ('at the latest at confirm_operation').

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

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

Front-loads the two most decision-relevant facts ('Step 1 of 2: nothing is charged') before any detail. The single dense paragraph is efficient, though the trailing language-precedence sentence is long and largely duplicates the schema's language description.

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

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

For a 19-parameter, non-idempotent, open-world tool with no output schema, the description still names the return payload (quote_id, credits per video and total, balance after) and the confirmation/expiry contract. Nothing critical to calling it correctly is missing.

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

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

Schema coverage is 74%, so the baseline is 3. The description enumerates parameter names (platform, aspect, duration, tier, resolution, voice, music, quantity, Brand Kit) but mostly without adding meaning beyond the schema, and it restates the goal/custom/goal_description rules already documented in the schema.

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

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

States a specific verb and resource ('Creates a draft project') and pins its place in the pipeline ('Step 1 of 2'), which is exactly what separates it from confirm_operation and get_estimate. An agent can pick it correctly without opening the schema.

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

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

Explicit sequencing guidance: 'Show the quote to the user; only after they approve that exact amount, call confirm_operation(quote_id)' — a clear when-to-use and when-not-to-proceed rule. The sibling get_estimate, which also produces cost estimates, is never mentioned, so one alternative remains ambiguous.

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

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

Goes well beyond the annotations: free instant spec-version bump, a re-render quote priced on edited length, and a hard stop requiring confirm_operation for voice-over edits. The versioning model implied by base_spec_version is gestured at ('a new spec version') but not fully explained, and nothing is said about what a stale base_spec_version does or why idempotentHint=false matters.

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 sibling anchor, then the three behavioral branches. Dense but nearly every clause carries information; the parenthetical field lists and stacked exceptions make it read as a wall of text rather than scannable statements.

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 describes what comes back (a new spec version plus a re-render quote, or a quote_id). For a mutation tool with three required params at 0% schema coverage, the main remaining hole is base_spec_version semantics and the failure mode for a stale version.

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

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

Schema description coverage is 0%, so the description must compensate. It helps greatly on 'ops' by pointing to update_storyboard's op vocabulary, and it implies video_id must refer to a previously rendered video. But base_spec_version — a required integer with a min of 1 and the key to optimistic concurrency — is never explained, leaving one of three parameters semantically opaque.

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 ('Edits a rendered video') and immediately anchors it to the sibling it mirrors ('the same ops as update_storyboard'), so an agent can tell edit_video apart from update_storyboard without opening either schema. The closing precondition ('Only for a video that was rendered at least once') further narrows the target resource.

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

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

Explicitly partitions when edits apply immediately (text, order, timing, CTA, captions) versus when they are not applied and instead yield a quote_id to feed confirm_operation (voice-over changes). It also states an exclusion ('New generated images aren't available: media must come from the project') and names the downstream tool for the deferred 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description only needs to add value. It does so by specifying the breadth of the payload (billing state, plan, policy, key scope), though it says nothing about freshness/caching or rate limits.

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

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

A single front-loaded sentence packs the return contents plus the call-first heuristic with zero filler. Every clause adds information an agent would 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?

With no output schema, the description carries return-value disclosure and does it well by listing the payload categories. It doesn't describe the shape or units of the returned data, a minor residual gap for a zero-argument read tool.

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

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

The tool takes zero parameters, so the baseline is 4 by rule. The description correctly implies a fixed, argument-free snapshot of account state.

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

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

Names a specific resource (credit balance) and enumerates exactly what it returns: available/on-hold credits, recent usage, plan, monthly grant, 4K policy, and API-key permissions. No sibling tool covers this resource, so an agent can distinguish it immediately.

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?

"Call it first when unsure whether something is affordable" gives a clear triggering condition. It stops short of naming the nearest alternative (get_estimate) or stating an explicit when-not, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's key contribution is the reassurance 'Nothing is charged', which resolves the real risk of a quote/refresh call. It also implies why idempotentHint=false: a refresh produces a new quote. It does not explain rate limits or whether old quotes are invalidated.

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 with the most important fact ('Nothing is charged') front-loaded, then each mode stated once. Every sentence carries information; nothing is repeated from 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 3-optional-parameter tool with no output schema, it covers both modes, the cost question, and the expiry scenario. It does not describe the shape of the quote returned for the project_id branch (fields, expiry window), a small remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the default behavior for quantity ('the project's') and the expiry rationale for project_id, which is meaning beyond the schema text. All three parameters are covered, with only the uuid format left 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?

The description names a specific verb+resource and splits the tool's two modes cleanly: read an existing quote by quote_id, or mint a fresh quote for a draft project by project_id. An agent can predict both outcomes without opening the schema. It stops short of naming a sibling, but no sibling tool overlaps enough to require 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 states the selection rule between the two modes explicitly ('With quote_id: ... With project_id: ...') and gives a concrete triggering scenario ('after the previous one expired'), plus the option to change quantity. It does not say when to prefer this over get_project or get_options, 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine behavior beyond them: the response enumerates credits lifecycle and pending-approval state, and wait_seconds turns this into a bounded long-poll (≤ 50). It does not say what happens when no job exists or whether the wait can time out, which keeps it below a 5.

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

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

Two sentences, both dense and front-loaded — the payload list first, the blocking-behavior caveat second. No filler, and the parenthetical lookup alternative is placed right where the reader needs 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 carries the return-value burden and does so by naming the fields returned. It is slightly incomplete on edge cases — what is returned when neither id is supplied (zero required params) and what happens if no job exists — but for a read-only status tool this is close to sufficient.

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

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

Schema coverage is 67% and the description compensates: it explains the video_id alternative ('the video's latest job') and the wait_seconds long-poll semantics plus the ≤ 50 ceiling, matching the schema's maximum. job_id itself is left to the schema, which is acceptable given the UUID format and pattern are documented there.

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 ('Status of a job') and immediately scopes the two lookup modes (job_id or the video's latest job). The enumerated payload — steps, progress, credits held/used/released, storyboard-approval wait, errors — makes it unmistakable versus siblings like cancel_job, approve_storyboard, or get_video.

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

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

Usage is implied rather than stated: the 'wait for storyboard approval' mention hints at the approve_storyboard relationship and the wait_seconds sentence implies polling, but there is no explicit 'use this when…' or 'do not use this to cancel/approve' guidance. An agent can infer the context but must do the 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered; the description adds genuine context beyond that — values are plan-dependent ("durations up to your plan's maximum"), pricing is returned (credits per second, including screen-adjusted rates), and resolution follows a "4K policy". It omits that voice listing is paginated and filterable via the language param, which the schema covers instead.

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

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

One dense sentence plus a short directive, front-loaded with the scope (accepted values for two named tools) before the enumeration. The parentheticals ("the seven presets", "per second with your code's screens") carry real information rather than filler, though the run-on construction is slightly hard to scan.

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

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

There is no output schema, so the description carries the burden of describing the response — and it does so by naming each returned category and its key modifiers (custom goals, plan-limited durations, Studio/Standard credits, 4K policy). 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% and the parameters are all voice_* filters with detailed 'With language: …' descriptions already in the schema. The description adds nothing about the parameters themselves; it instead documents the returned categories. Baseline 3 is appropriate where 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 precisely what the tool returns — the full set of accepted values for create_project and request_variant — and enumerates the categories (goals, platforms, aspect ratios, durations, qualities, resolutions, languages, voices, music moods). An agent can immediately distinguish it from siblings like get_estimate or get_credit_balance.

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

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

"Use it instead of guessing ids" is an explicit call-to-action and rule-out of the failure mode it prevents, plus it names the two downstream tools it serves. It lacks an explicit 'do not use for X' exclusion, but the intended usage context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value by disclosing the payload shape — that the response aggregates settings, site-analysis status, a video sub-list with job state, and any open quote — which tells the agent this is a heavy composite fetch, not a thin record read. It is silent on missing-project behavior, but that is a minor gap given the annotation coverage.

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

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

A single sentence with zero filler, and the returned-content list is front-loaded. It is telegraphic (no verb), which costs some readability but not economy.

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 well by enumerating the returned fields and their nesting concept (videos each with status and latest job). The main omissions are error behavior for a nonexistent or unauthorized project, which an agent doing a direct id lookup would benefit from.

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 exists and the schema already supplies type, uuid format, and a strict pattern, so parameter meaning is largely carried by structured data despite 0% description coverage. The description never mentions project_id or the uuid requirement, adding nothing 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?

The description names a single resource (one project) and enumerates exactly what comes back: settings, site-analysis status, videos with status and latest job, open quote. That is specific enough to separate it from list_projects and get_video, though it is written as a noun fragment rather than an explicit verb+resource statement.

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 list_projects (to discover an id) or get_video (for a single video). The phrase 'One project' weakly implies singular lookup, but there are no conditions, prerequisites, or named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered by structured data. The description adds two things annotations cannot: that spec_version is required downstream to edit, and a prompt-injection warning that the text originates from an analysed website and must be treated as data — a meaningful behavioral disclosure for an agent consuming untrusted content.

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

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

A single dense sentence plus a short safety clause — front-loaded with the resource, then the edit-workflow hint, then the security warning. The parenthetical field list is heavy but earns its place because there is no output schema to carry that 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 takes on the burden of describing return values and does so by enumerating scenes, CTA, voice, music and spec_version. Combined with the injection warning and the edit prerequisite, an agent has enough to call it and handle the result; only behavior on a missing/invalid video_id is unaddressed.

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

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

There is one required parameter, video_id, with 0% schema description coverage, and the description never mentions it or explains where to obtain it. The uuid format makes its meaning largely self-evident, so this is not a severe gap, but the description adds no semantic value over the schema for the sole input.

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

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

The description names the exact resource (a video's storyboard) and enumerates its contents — scenes in order, CTA, voice, music, spec_version — so the agent knows precisely what comes back and can distinguish it from get_video or update_storyboard. It loses a point only because it is phrased as a noun phrase rather than an explicit verb ("retrieve the storyboard for a video").

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

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

Usage is only implied: the parenthetical "spec_version (needed to edit)" signals a read-then-edit workflow with update_storyboard, which is a genuinely useful hint. But there is no explicit statement of when to call this versus get_video or approve_storyboard, and no prerequisites or error conditions are given.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description earns credit for what it adds: download URLs are signed, expire in one hour, are returned only for rendered versions, and must not be stored or shared. That is real operational context beyond the structured hints.

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

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

A single dense sentence that front-loads the returned fields and ends on the actionable warnings. The nested 'and, for rendered versions, ...' clause is slightly tangled but no words are wasted.

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

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

For a two-parameter read tool with full annotation coverage and no output schema, the description covers the returned payload, the conditional nature of download URLs, and the expiry/security constraint. Nothing essential for a correct 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 0%, so the description must carry the parameters. video_id is self-evident from context, and the render-conditional mention of download URLs hints at include_download_urls, but it never names the flag or explains that it defaults to true and can suppress URLs.

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

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

States the resource precisely ('One video') and enumerates exactly what comes back: status, settings, visibility, public page, versions, and download URLs. That clearly separates it from list_videos and the project/storyboard siblings, though no sibling is named explicitly.

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

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

Usage is only implied: the note about one-hour signed URLs and 'download right away' signals the download use case, but the description never says when to choose this over list_videos or how it relates to edit_video/get_project. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the returned field set and the default-kit fallback semantics, which the annotations cannot express.

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

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

Two sentences, front-loaded with what the tool returns and followed by the action it enables. The parenthetical field list is the most compact way to convey the return shape, 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?

With no parameters and no output schema, the description carries the burden of describing the response, and the field enumeration plus default-flag mention does that adequately. Minor omissions such as ordering or whether kits can be absent entirely are not material for a simple zero-arg list.

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

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

This tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The only identifier mentioned, brand_kit_id, belongs to create_project rather than this schema, but it is clearly framed as such and does not mislead.

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 ('Your Brand Kits') and enumerates exactly what each entry contains (id, name, colors, fonts, tone, tagline, website, default flag), so an agent knows this is a read of brand kit records. The verb is implied by the tool name rather than stated, and no sibling is explicitly contrasted, which keeps it just short of a 5.

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

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

It states the downstream use clearly: take a brand_kit_id from this list and pass it to create_project, and if you have none the default kit applies. That is actionable context linking this tool to a named sibling, though it doesn't state exclusions or when listing is unnecessary.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful behavioral detail beyond that: results are newest-first, include specific fields, and are paginated via cursor returned as next_cursor.

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 two compact clauses, front-loads what the tool returns, and uses the remaining sentence for the essential pagination behavior. There is no wasted text.

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

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

With no output schema, the description usefully enumerates returned fields and explains the pagination loop via next_cursor. It omits detail about how limit affects results, but for a simple read-only list tool it is otherwise complete enough to invoke correctly.

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

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

Schema coverage is 50%. The cursor parameter's schema already says 'next_cursor of the previous page,' and the description reinforces the pagination contract and names the next_cursor return field. The limit parameter is not explained in the description, though its bounds and default are in the schema.

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

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

The description clearly identifies a collection-listing operation for projects and names the returned fields plus ordering. It distinguishes itself from get_project by implying a list of multiple projects, though it does not explicitly name sibling alternatives.

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 'Your projects' and the pagination instruction, but there is no explicit guidance on when to use this versus get_project or list_videos. It tells how to paginate once selected but not when to select it.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description adds real behavior beyond them: results are sorted newest first, filters are combinable but singular ('one project or status'), and pagination is cursor-based.

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

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

A single sentence with zero waste; ordering and scope are front-loaded before the pagination note. Every clause adds 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?

Given zero required params, a flat schema and no output schema, the description covers filters, ordering and pagination well enough to call the tool correctly. The only missing piece is the page-size control (`limit`), which the description leaves entirely to the schema.

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

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

Schema coverage is only 25% (only `cursor` is documented), so the description must compensate. It covers `project_id` and `status` (repeating the enum) and the cursor pagination model, but never mentions `limit`, its default of 20, or its max of 50 – a meaningful gap for a paginated list.

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

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

Specific verb+resource ('Your videos') plus ordering ('newest first') and filter scope (project or status). An agent can immediately distinguish it from get_video (single video) and list_projects 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?

Usage is implied by 'optionally for one project or status' – it tells the agent the filters exist but not when to prefer this over get_video for a specific ID, nor any prerequisite for pagination. Adequate for a self-evident list tool, but no explicit when/when-not 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?

The description adds meaningful behavior beyond the annotations: quote-only with no charge, returns a quote_id for confirmation, and explains that reformat is recomposed rather than cropped. It does not mention quote expiry or that repeated calls may create separate quotes, which would have made it fully transparent given idempotentHint=false.

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-loads the most important fact: this is a non-charging quote step. The remaining sentences earn their place by explaining variant kinds and the next step.

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, schema-rich tool with no output schema, the description covers purpose, pricing semantics, the quote_id return, and the confirm_operation handoff. Remaining gaps around idempotency and quote lifetime are minor but real.

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

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

Schema description coverage is 71%, so the schema already documents several parameters well. The description still adds useful semantic mapping between kind values and parameters, such as translate using languages and reformat using aspect ratios, though it does not cover count, visibility, or voice_id 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?

The description states a specific verb and resource: it prices a variant of a ready video and returns a quote_id. It distinguishes the four variant kinds and explicitly frames the tool as step 1 of 2, making it easy to separate from confirm_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?

It gives clear usage context by saying this is step 1 of 2, nothing is charged, and the returned quote_id feeds confirm_operation. It does not explicitly compare against alternatives such as get_estimate or state when not to use this tool, so it stops short of full when/when-not guidance.

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

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely new behavior: the call is free, edits are gated on base_spec_version (optimistic concurrency), length growth raises the pending-approval price, and the response carries the new version plus undo_ops. It doesn't spell out what happens on a version mismatch, which keeps it below 5.

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

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

The lead ('Free.' + purpose + version source) is well front-loaded, but the op catalogue is one semicolon-chained run-on with no line breaks or grouping, which makes it slow to scan for a single op. Every clause carries information, so it is dense rather than padded, but the structure costs 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 correctly closes the loop by naming the return values (new version, undo_ops). Constraints on voices, media, and length/pricing are all present; only failure-mode behavior for a stale base_spec_version 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 0% and the ops item schema is only {op: string} with additionalProperties, so the description is the sole source of op semantics — and it delivers, mapping payload keys for vo.set, text.set, scene.insert, scene.timing, cta.set, music.set and pace.set. base_spec_version's provenance is also explained; only video_id is left implicit.

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 ('Applies edit ops to a storyboard') plus a crucial state qualifier ('that waits for approval'), which separates it from approve_storyboard and get_storyboard without opening a schema. The enumerated op vocabulary makes the scope concrete.

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

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

Explicitly tells the agent to source base_spec_version from get_storyboard and voices from get_options, and restricts media to the project — real usage prerequisites. It stops short of naming when to prefer edit_video or approve_storyboard instead, so no exclusions are stated.

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