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

With no annotations provided, the description carries the full burden. It discloses asynchronous behavior (immediate jobId), the polling endpoint, and a concurrency restriction. It does not mention side effects like artifact creation, but the output schema partially covers expected results.

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

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

Two short sentences, front-loaded with the core action and result, followed by the most important behavioral caveats. Every word 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?

Covers what the tool does, the asynchronous lifecycle, and a critical failure condition. Parameter docs, output schema, and sibling job_status fill the remaining gaps. It could be more explicit about what 'captions' output looks like or what 'another job' refers to, but it is not incomplete enough to confuse an agent.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds minimal parameter-level meaning beyond noting the fixed input file name 'narration.mp3', which is a small contextual bonus.

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 ('Transcribe'), a specific source resource ('narration.mp3'), and the produced result ('captions with word timing'). This clearly distinguishes it from sibling tools like render, voice, or compose.

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?

Tells the agent the expected follow-up action ('poll job_status') and a key constraint ('Rejects if another job is running'). It does not explicitly contrast with alternatives, but the sibling set is broad and the core workflow is clear enough.

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 it does disclose important behavior: the call returns immediately with a jobId, the agent must poll job_status, and concurrent jobs are rejected. This goes beyond the schema and gives the agent accurate expectations, though it does not mention overwrite behavior or cleanup.

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 with no wasted words: the first states the intended operation and target, the second gives essential async and concurrency guidance. The structure is front-loaded and easy 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?

The description captures the core behavior (async job, single-flight, output file) and the schema covers parameters along with an output schema for return values. However, given the large sibling toolset representing a pipeline, it does not explain where compose fits in the workflow or when it should be called relative to render, captions, or gif, leaving room for agent uncertainty.

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 schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds no extra parameter-level meaning; it only mentions the output path, which is not tied to any specific parameter beyond the dir context.

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

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

The description clearly identifies the operation ('Trim, sync, mux and caption') and a concrete deliverable ('output/final-demo.mp4'), so an agent can tell what compose accomplishes. However, it does not explicitly distinguish it from sibling tools like render, captions, or gif, which could also be involved in producing media outputs.

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

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

The description implies asynchronous usage ('Returns a jobId immediately — poll job_status') and a concurrency restriction ('Rejects if another job is running'), which helps an agent decide how to invoke it. It does not state when to choose compose over alternatives nor mention any prerequisites such as finished renders or recordings, leaving usage guidance mostly implicit.

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

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

The readOnlyHint annotation already establishes that this tool has no side effects, lowering the bar for behavioral disclosure. The description adds some useful behavior by noting that it 'flags LLM-only servers like Ollama,' but does not explain what happens if prerequisites are missing or how results are surfaced.

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

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

The description is a single compact sentence that front-loads the purpose ('Check prereqs') and then efficiently lists the relevant items. No unnecessary words or repetition are present.

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

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

Given the low complexity of the tool, a single optional parameter, and the presence of an output schema, the description is largely complete. It could mention what the tool returns or warns about, but the output schema likely covers that, so 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?

The schema already provides full coverage for the single 'dir' parameter with description 'repo to check for an installed skill.' The tool description adds no further meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function as checking environment prerequisites and enumerates specific items like node, ffmpeg, Chrome, TTS/STT endpoint, API key, playwright, and installed skill. This distinguishes it from sibling tools by focusing on environment readiness rather than rendering, recording, or other operations.

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 does not explicitly say when to use this tool versus alternatives, nor does it mention the tool should be run before rendering or similar workflows. It only lists what is checked, leaving the decision of when to invoke it 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?

The description adds meaningful behavioral detail beyond the readOnlyHint annotation by stating 'pure string generation — no network, no render' and explaining exactly where data comes from (origin remote, directory basename). This gives the agent a precise mental model of side-effect-free behavior and data provenance.

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 three sentences with no filler: it front-loads the primary output and key constraints, includes the data-source explanation, and points to docs for further detail. 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?

Given the output schema is present (so return values are documented), the description covers behavior, data sources, and the related CI workflow. Nothing critical is missing for an agent to select and invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics by clarifying how parameters are used: owner/repo are derived from the repo's origin remote and the demo name from the directory basename. This connects the dir and repo parameters to their actual role in generating the snippets.

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 output ('ready-to-paste embed snippets') with concrete formats (markdown GIF, markdown still, HTML video) and explicitly clarifies it is pure string generation, not rendering. This clearly distinguishes it from sibling media-generation tools like render, gif, and stills.

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 provides clear context: use it to produce embed snippets with stable raw.githubusercontent URLs, and pair it with the demo-publish workflow. It does not explicitly list when-not-to-use alternatives, but the emphasis on 'no network, no render' helps an agent infer that media generation tools are the alternative.

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 thoroughly. It discloses auto-attached environment/log context, conditional use of `gh issue create`, the fallback to a local markdown file plus prefilled New Issue URL, the guarantee of no other network call, and the dry-run preview behavior. This is exceptional behavioral disclosure.

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

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

The description is dense but every sentence earns its place: purpose, equivalent, auto-attach behavior, fallback path, network guarantee, usage trigger, skip condition, and dry-run mention. It is front-loaded with the core purpose and structured so an agent can quickly parse the decision-relevant facts.

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 an output schema exists, return-value documentation is already handled. The description covers when to use, what it does, how it behaves under failure/missing tooling, what gets auto-attached, and what the parameters mean in practice. Nothing an agent needs to correctly invoke it is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by clarifying that environment/log context is appended automatically and should not be duplicated in `body`, and by explaining that `dryRun` previews without filing. The `dir` parameter is also marked as recommended. This lifts it above baseline.

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

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

The description states a specific verb ('File') and a clear resource (a GitHub issue on the aidemo engine repo), and even positions it as the in-band equivalent of `aidemo feedback`. It is immediately distinguishable from all sibling tools, none of which involve filing feedback.

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

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

Explicitly states when to call ('whenever something felt broken, surprised, or needed a workaround') and when to skip ('if the session was clean'). It also contrasts with the CLI equivalent and explains the fallback behavior when `gh` is unavailable, giving an agent clear decision criteria.

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 provided, the description carries the full burden of behavioral disclosure. It discloses the async job behavior, the rejection when another job is running, and the lack of authentication requirement. It does not mention potential overwriting of existing frames or error conditions, but the key behaviors are 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?

The description is two sentences, front-loaded with the purpose and followed by usage notes. It is efficient and includes no fluff, making it highly concise.

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 that the tool has an output schema (so return values are defined) and the description covers the core behavior, async pattern, concurrency limitation, and the alternative usage, it is fairly complete. It could mention error handling or file naming, but those are not critical for an agent to call the tool correctly. The description is adequate for 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 description coverage is 100%, so each parameter is documented in the schema. The description adds a little context by mentioning 'final video (or the raw take)' which relates to the 'source' parameter, and 'output/frames/' which relates to the default 'out' directory. However, it does not add substantial meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool dumps evenly spaced PNG frames from a video into a directory for review, with specific verbs and resources. It does not explicitly differentiate from the sibling tool 'stills', which could serve a similar purpose, so it is clear but not fully distinguishing.

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 explicitly tells when to use it: instead of hand-running `ffmpeg -ss`. It also notes it needs only the video (no key) and describes the async behavior (returns jobId, poll job_status) and the concurrency restriction (rejects if another job is running). This provides clear usage context and 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=true, so the description needn't repeat safety. It adds behavioral context beyond that: the guide is ~1000 lines, supports partial retrieval via a topic slice, and allows H2 heading prefixes. This helps the agent anticipate response size and fetch strategy. No contradiction.

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 well-structured sentences. The purpose and usage are front-loaded, and the parameter explanation is compact but complete. No wasted words; 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 simple read-only guide tool with one optional parameter and an output schema, the description fully covers what an agent needs: what it returns, how to invoke it, and when to use it. 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% (topic is fully described in the schema). The description adds value by recommending which slices to start with and noting that any H2 prefix works, enriching the schema's enumeration. This goes beyond the baseline, so a 4 is warranted.

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

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

The description clearly states the tool's purpose: 'The canonical guide to authoring demos' and enumerates its contents (storyboard schema, action vocabulary, etc.). It differentiates from siblings by positioning itself as the first call before authoring, and its specificity ('canonical', 'FIRST') leaves no ambiguity about what it does.

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 instructs when to use: 'Call this FIRST before authoring or editing a storyboard.' It also provides a recommended sequence ('start with core, then fetch attention/polish/chatgpt-apps as needed') and explains the slicing behavior. This gives clear, actionable guidance for an agent.

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

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

The readOnlyHint annotation already signals that this is a safe read operation. The description adds meaningful behavioral context beyond that: the schema is generated from the engine's own zod schema and represents the exact validation contract, making its authority and reliability clear without needing to repeat 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?

The description is a single, focused sentence that front-loads the core subject (JSON Schema for storyboard.json) and then adds the key context about provenance and validation authority. No filler or redundant restatement of the title.

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

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

For a zero-parameter, read-only schema retrieval tool with an output schema available, the description is complete. It tells the agent exactly what this returns, why it is authoritative, and how it relates to the engine's validation process.

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 has zero parameters, so the description has no parameter semantics to explain. Baseline 4 is appropriate because there is nothing missing and the empty input schema is fully consistent with the tool's purpose.

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

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

The description identifies a specific resource (storyboard.json schema) and states its provenance and function: it is the exact JSON Schema the engine validates against. This clearly distinguishes it from sibling tools like validate_storyboard or get_authoring_guide, which serve different purposes.

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

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

The description implies strong usage context: because this is the exact contract used for validation, agents should consult it when they need authoritative schema rules. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for a simple retrieval 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?

With no annotations, the description carries the transparency burden. It discloses async behavior and concurrency rejection, but omits side effects such as file creation/overwrite and error behavior beyond the rejection.

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, two sentences, and contains only essential information with no fluff or repetition.

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

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

The description gives the overall async workflow and a concurrency constraint, but it does not cover parameter meaning, defaults, output details, or failure modes, so the agent may struggle 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?

Only one of four parameters has a schema description, and the tool description does not explain fps, out, or width. The role of dir may be inferred from 'output/final-demo.mp4', but most parameters remain ambiguous.

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 action: converting output/final-demo.mp4 to a README-ready GIF. It also clarifies the asynchronous return and concurrency restriction, making the tool's purpose unmistakable.

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 provides procedural guidance (returns jobId, poll job_status, rejects if another job is running), but does not explicitly say when to choose this tool over sibling rendering/recording tools or when not to use 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?

With no annotations, the description carries the full burden. It discloses key behaviors: operates without an LLM or browser, leaves narration as placeholders, notes approximations, and creates demos/<name>/. This is valuable context that goes beyond the schema.

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

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

The description is a single dense sentence that front-loads the purpose and then details output, behavior, and next steps. It is efficient and each clause contributes meaning, though it could be slightly clearer with structured breaks.

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 description covers input, output location, process behavior (no LLM/browser, placeholders, approximations), and even hints at next steps ('Then write the narration and probe.'). An output schema exists to explain return values. It lacks explicit error conditions and force/dir handling, but these are minor given 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 75% (high), so the baseline is 3. The description reinforces file types and name purpose, but these are already in the schema (file: 'absolute path to trace.zip or the test file'; name: 'creates demos/<name>/'). It adds little beyond what the schema already documents.

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

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

The description clearly states the tool imports a Playwright trace or test file into a storyboard draft, specifying the output location and content. It distinguishes from siblings by its input type (existing trace/test) but doesn't explicitly name alternatives, so it misses the 5 for sibling differentiation.

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

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

It provides clear context for when to use: when you have an existing Playwright trace or test to convert into a storyboard. It doesn't explicitly exclude other scenarios or name alternatives, but the context is unambiguous and the description implies the tool is for existing artifacts.

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 provided, the description must carry the full burden of behavioral disclosure. It does describe the creation of demos/<name>/ and the fromUrl inspection process, including the follow-up step of writing narration and turning candidates into clicks. However, it omits behaviors like the force parameter, error handling for existing directories, or side effects on the filesystem, leaving some gaps in transparency.

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

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

The description is a single, compact sentence that front-loads the primary action and then explains optional behavior. It is efficient and avoids fluff, though the structure is somewhat run-on and could be split for clarity. It still earns a 4 for being informative without unnecessary length.

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

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

For a tool with 7 parameters, a nested viewport object, and an output schema, the description covers the main scaffolding flow and the fromUrl mode adequately. However, it does not mention the force parameter, behavior on existing directories, or error conditions, which are relevant for an init tool. The output schema handles return values, but these operational gaps prevent a higher score.

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 schema has 71% parameter description coverage, so the baseline is 3. The description adds meaningful context for dir (absolute path recommended, default server cwd) and for fromUrl (explaining how headings become scenes and selectors become beats). These enrich the schema and clarify key parameters, though it does not add details for force or profile beyond the schema.

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

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

The description clearly states the tool creates demos/<name>/ with a starter brief and storyboard, which is a specific verb-resource action. It also explains the fromUrl variant that inspects a live page, distinguishing it from sibling tools like record or render. The title reinforces the purpose, leaving no ambiguity about what the tool does.

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

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

The description implies usage for scaffolding a new demo and explains the fromUrl flow, but it does not explicitly state when to use this tool versus alternatives or when not to use it. There is no mention of exclusions or preferred scenarios compared to siblings like record or compose, so the guidance is implicit rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It states side effects ('Writes logs/inspect-<n>.json and a screenshot'), async behavior ('Returns a jobId immediately — poll job_status'), concurrency restrictions ('Rejects if another job is running'), and environmental context ('logged-in state included'). This fully informs the agent of the tool's operational traits beyond what a schema alone would convey.

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

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

The description is three sentences, each earning its place: the first defines the core function, the second gives usage guidance, and the third lists side effects and constraints. It is front-loaded with the primary purpose and contains zero filler. This is an exemplar of concise, well-structured tool documentation.

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 of this complexity (7 parameters, nested objects, output schema, async behavior), the description is remarkably complete. It covers purpose, usage timing, side effects, concurrency, and the selector ranking strategy. Since an output schema exists, the description need not enumerate return values. Nothing an agent needs to correctly invoke and interpret the tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides; it only indirectly references the 'dir' parameter when mentioning the demo directory for outputs. No new meaning is introduced for any of the 7 parameters, so the score remains at the baseline.

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

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

The description clearly states the tool's function: 'Open a URL in the recording profile... and list every visible interactive element with UNIQUE selectors ranked...' It is specific about the verb (open, list) and resource (URL, interactive elements). However, it does not explicitly name an alternative sibling tool (e.g., 'probe') to distinguish itself, so it falls short of the 5-point bar which requires explicit sibling differentiation.

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

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

The description gives a clear usage context: 'Use it BEFORE writing targets — no selector guessing, no wasted probe.' This tells the agent when to employ the tool (before authoring targets) and implies it should be used instead of guesswork. It does not explicitly state when NOT to use it or name a specific alternative, but the guidance is actionable and sufficient for most cases.

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 provided, the description carries the full behavioral burden and does so well: it discloses best-effort semantics, mid-record salvage behavior, and asynchronous settlement. Telling the agent to poll job_status for the final state is exactly the kind of non-obvious behavioral guidance needed.

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, each carrying distinct value: cancel semantics, mid-record behavior, and async resolution with a pointer to job_status. It is front-loaded with the core purpose and has 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?

The description covers the important behavioral context for a simple one-parameter cancel tool: best-effort, timing, salvage behavior, and how to observe final state. The only notable omission is guidance on where jobId comes from, but the output schema exists and the parameter set is minimal.

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 for the parameter, but it never mentions jobId or how to obtain it. The single parameter's name is self-explanatory, but no additional meaning is added beyond the schema's 'jobId: string'.

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

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

The description opens with 'Best-effort cancel' – a specific verb and resource – and adds concrete behavioral detail about when cancellation is checked. It clearly differentiates from siblings by positioning job_cancel as the stopping operation and explicitly pointing to job_status for final state.

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

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

The description gives clear usage context: cancellation is best-effort, checked between actions/scenes/stages, and the job settles asynchronously, so the agent should poll job_status afterward. It doesn't explicitly state when not to use it or compare with alternatives beyond job_status, but the intended workflow 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?

The readOnlyHint annotation already covers safety, and the description adds behavior beyond that by scoping results to 'this server session' and specifying 'newest last' ordering. It does not discuss empty-session behavior, but the output schema covers return structure.

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

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

The description is a single seven-word sentence that front-loads the complete meaning with no filler. It is as concise as possible for a no-argument list tool.

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

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

For a zero-parameter, read-only tool with an output schema, the description covers the core calling semantics: what is listed and in what order. It is slightly incomplete by not referencing job_status for single-job detail, but this is a minor omission.

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

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

With zero parameters, the input schema is empty and the description needs to add no parameter meaning. The baseline of 4 applies because there are no parameter semantics to clarify.

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

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

The description identifies the tool's output as every job in the current server session, with an explicit sort order (newest last). This clearly separates it from sibling tools such as job_status (single-job status) and job_cancel (cancellation).

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

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

The description implies the tool is for session-wide job enumeration but gives no explicit when-to-use guidance or contrasts with job_status/job_cancel. An agent must infer the intended use case from the tool name and sibling list.

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

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

Annotations only provide readOnlyHint=true, and the description adds meaningful behavior: progress fields are populated only for certain stages, and it returns log tail, failure-artifact paths, and a feedbackHint on genuine failure. No contradiction with annotations.

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

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

The description is a single dense sentence that front-loads the core fields and packs in useful specifics like the stages for which progress is populated and failure artifact details. It is somewhat heavy due to parentheticals, but every element 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?

Given that an output schema exists, the description sufficiently covers what is returned, including status, stage, progress, log tail, result/error, failure artifacts, and feedbackHint. It omits explicit lifecycle or polling guidance, such as when a job is considered complete, but this is not a critical 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?

The schema documents tailLines with a default, while jobId has no description, but 'of a pipeline job' implies its role as the job identifier. The description clarifies return contents rather than parameter-specific semantics, only partially compensating for the 50% schema coverage.

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

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

The description clearly states that the tool returns status, stage, per-scene progress, log tail, and final result/error for a pipeline job. This is specific enough to distinguish it from siblings like job_list and job_cancel.

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 title 'Poll a job' implies its intended use for checking job progression, but there is no explicit when-to-use or when-not-to-use guidance against alternatives such as job_list or job_cancel. Usage context is mostly inferred rather than stated.

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

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

With readOnlyHint=true already covering safety, the description adds meaningful behavior: it is browser-free, it produces a per-scene pacing forecast, and it checks specific pitfalls. It also discloses that 'lang' lints a narrations[lang] translation at that language's speaking rate, which goes beyond 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?

The description is two dense, information-rich sentences with no filler. It front-loads the core purpose ('Browser-free preflight over a storyboard') before enumerating checks and usage rules, and every clause contributes 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?

Given the tool has an output schema, a read-only annotation, and a 5-parameter schema with 80% coverage, the description supplies the remaining context: when to run it, how inputs are mutually exclusive, what kinds of issues it detects, and what lang does. Nothing essential is missing for an agent to select and 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 coverage is 80%, so the baseline is 3, but the description adds crucial parameter behavior: 'Pass exactly one of dir / path / json' and the meaning of lang. This compensates for the schema's otherwise sparse lang field and clarifies mutual exclusivity.

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: a 'browser-free preflight over a storyboard', and lists concrete lint categories (pacing forecast, selector/wait pitfalls, no-op keys). It also signals how this differs from render/probe by saying it runs 'before probe/render', which helps an agent distinguish it from siblings.

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

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

The description gives clear usage context: 'Run it after every storyboard edit, before probe/render' and 'Pass exactly one of dir / path / json'. It lacks explicit when-not-to-use guidance or named alternatives, so it stops short of a 5.

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

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

With no annotations, the description carries the burden and does well: discloses record-only nature, optional narration, golden file writes, immediate jobId with polling, and job rejection. Missing details like error handling or output format but output schema exists.

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

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

Three sentences, no waste, purpose front-loaded. Each sentence adds essential behavioral or workflow context.

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 12 params with strong schema coverage and an output schema, the description covers the core flow (jobId, polling, golden mechanics, rejection). It doesn't describe all parameters but the schema does; it's complete for the main workflow.

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 92%, so the schema already documents parameters. The description adds value by explaining the role of updateGolden and golden ('with updateGolden writes...', 'with golden deep-compares...') and the 'narration optional' nuance, enriching beyond schema.

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

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

States a specific verb+resource ('Record-only dry run to verify selectors/timing') and distinguishes from siblings like 'record' by explicitly being a dry run. The golden comparison behavior adds further specificity.

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?

Implies usage for verification and CI via golden comparison, and notes rejection when another job is running. Doesn't explicitly name alternatives or when-not-to-use, but the 'dry run' framing clearly separates it from 'record'.

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 provided, the description carries the behavioral disclosure burden. It reveals the async nature (jobId + polling) and a concurrency restriction (rejects if another job is running), which are valuable. However, it does not mention file side-effects beyond 'record raw video + timeline.json' or any profile-wiping behavior, though the parameter descriptions cover the 'fresh' option.

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 sentences with zero redundancy. The primary purpose is front-loaded, followed by the critical async and concurrency behaviors. Every word 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?

Given the 10-parameter schema with detailed descriptions and an output schema, the tool description covers the essential operational facts (what it produces, how to track it, concurrency limit). It omits explicit alternatives, but the schema and output schema fill most contextual gaps, making it adequate for an agent to call 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 90%, so the schema already documents most parameters (e.g., 'fresh' explains when to use a wiped profile). The tool description adds no additional parameter meaning beyond what the schema provides, meeting the baseline for high coverage.

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 action ('Drive the storyboard in Chrome and record raw video + timeline.json') and clarifies the async workflow ('Returns a jobId immediately — poll job_status'). This clearly distinguishes it from siblings like render, frames, or gif, which produce different outputs.

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 explains the tool's purpose but does not explicitly mention when to choose it over alternatives. It does note a constraint ('Rejects if another job is running'), but lacks explicit 'use this when...' or 'not for...' guidance, leaving the agent to infer from the name and output type.

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 burden of behavioral disclosure. It reveals that the tool returns a jobId immediately and requires polling job_status, and that it rejects if another job is running. This covers async behavior and concurrency. It does not mention file outputs or long-running nature, but it addresses the most critical operational behaviors.

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 sentences with zero filler. It front-loads the core purpose (the pipeline) and immediately follows with the key behavioral traits (async jobId and concurrency rejection). Every word 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?

Given the complexity (13 parameters, nested objects, and an output schema), the description covers the essential workflow and constraints. It does not repeat schema parameter details, and the output schema handles return values. It lacks explicit prerequisites like a valid storyboard, but for a tool this size, the description is adequately 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?

The schema description coverage is 85%, so the schema already documents the parameters thoroughly. The description text does not add parameter-specific meaning beyond the schema—it only provides the pipeline overview and two behavioral notes. Since the schema handles the heavy lifting, the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs a full pipeline (voice → record → captions → compose) and identifies it as the CLI `render`. It distinguishes this from the individual step tools (voice, record, captions, compose) by explicitly naming the pipeline, giving the agent a precise idea of what this tool does and what it is not.

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

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

The description implies this is for complete renders (the full pipeline) but does not explicitly state when to use this versus the individual step tools. It mentions a concurrency constraint (rejects if another job is running) but lacks a clear 'use this when X, use individual tools when Y' statement, leaving the decision partially 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?

Without annotations, the description carries the full burden and it does well: it discloses async job behavior, polling requirement, rejection when another job is running, and that stills come from the CLEAN take with no captions/zoom. It could also mention file-writing effects or cancellation behavior, but the core operational traits are clear.

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

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

The description is compact and front-loaded with the primary action. Every sentence adds necessary information: output format, source take, prerequisites, async response, and rejection behavior. No redundant 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?

For an async extraction tool, the description captures the full lifecycle: what it produces, where, from which source, under what prerequisites, and how to track completion. The output schema covers the jobId return, so the description does not need to restate return values. It is complete enough in context.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds contextual meaning around the recorded timeline and output/stills directory, but it does not substantially enhance the semantics of dir or out 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 ('Extract'), a concrete resource ('recorded take'), a destination ('output/stills/'), and a precise output format ('one PNG per still marker'). It clearly differentiates from sibling tools like render and gif by specifying screenshot mode and the CLEAN take source.

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

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

The description gives clear prerequisites ('Needs only a recorded timeline (no key)'), async behavior ('Returns a jobId immediately — poll job_status'), and a rejection condition ('Rejects if another job is running'). It does not explicitly name alternative tools or when to use them instead, but the conditions are strong enough to guide an agent.

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

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

Annotations already declare readOnlyHint=true, and the description adds the non-execution behavior ('without running anything') and the relaxed-mode semantics ('makes narration optional (probe semantics)'). It does not describe return values, but the output schema exists to cover that, and there is no contradiction with annotations.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, and the parameter guidance is compact and immediately actionable.

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 validation tool with an output schema, the description covers the essential input-mode selection and the only ambiguous flag. The term 'probe semantics' is somewhat jargon-heavy and could be clearer about the relationship to the sibling probe tool, but overall an agent has enough information to call the tool correctly.

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

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

Although schema description coverage is 80%, the description adds crucial information absent from the schema: the mutual-exclusion rule ('exactly one of: dir, path, json') and the meaning of relaxed ('narration optional / probe semantics'), which the schema leaves undescribed. This goes well beyond the baseline and materially helps an agent invoke the tool correctly.

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 action ('Validate a storyboard') against a specific resource ('the engine schema') and adds the key qualifier 'without running anything', which distinguishes it from execution-oriented tools like render or probe. It clearly differentiates from sibling tools like lint_storyboard by focusing on schema validation rather than style/lint checking.

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

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

The description gives explicit selection guidance for input modes: 'Pass exactly one of: dir, path, or json', which is critical for correct invocation. It provides clear context for when to use the tool (validation without execution) but does not explicitly name alternatives like lint_storyboard or state when relaxed mode should be chosen over strict mode.

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 covers the most important traits: async job creation, the required polling pattern, incremental skip behavior, and a concurrency rejection guard. It does not elaborate on file mutations or edge cases, but the disclosed contract is enough for safe usage.

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, each carrying a distinct fact: what it generates, how to get the result, and when it will refuse. No filler or redundancy, and the main action 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?

Given that an output schema exists and the schema documents four of five parameters, the description covers the missing operational contract: immediate jobId, polling via job_status, and the single-running-job limit. The main gap is absence of sibling comparison, but for a job-launching tool this is sufficient for an agent to invoke and monitor it.

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

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

Schema coverage is 80%, so most parameters are already documented and the description does not need to repeat them. It adds some relevance to the incremental behavior, hinting at what force might override, but force's exact semantics remain implicit. Thus it meets the baseline while adding only modest parameter-level 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?

The description names a specific action and resource: generating per-scene TTS narration at scene granularity. 'Per-scene TTS' clearly separates it from sibling tools like record, captions, render, and compose, even though no sibling name is used. The parenthetical 'skips unchanged scenes' adds distinctive scope.

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

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

The description implies proper use: generate TTS narration, poll job_status, and avoid launching while another job is running because it rejects. However, it does not explicitly say when to prefer this tool over alternatives such as record or render. This is adequate contextual guidance, but not strong 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?

With no annotations provided, the description carries the full burden. It discloses that it returns a jobId immediately (async), requires polling job_status, and rejects if another job is running. It also notes 'no key, no browser' for auth/environment. This covers key behavioral aspects, though it does not mention whether it overwrites existing files or if it is read-only, but the context suggests a non-destructive export.

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

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

The description is concise, with three sentences that front-load the primary output and then cover inputs and behavior. It is well-structured and avoids redundancy, though it could be slightly more organized with explicit headings or bullet points for readability.

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

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

The tool has 4 parameters, an output schema, and no annotations. The description explains the purpose, inputs, outputs, async nature, and concurrency constraint. It does not detail the JSON manifest structure, but that is covered by the output schema. It also mentions polling job_status, which is a sibling, and gives enough context for an agent 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 four parameters with descriptions. The tool description adds minimal parameter-specific detail beyond what the schema provides—it references the output directory default and the language variant, but these are already in the schema. Per the baseline for high coverage, a 3 is appropriate.

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

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

The description clearly states the tool exports a walkthrough package from the final video, listing specific output artifacts (index.html, guide.md, PNGs, SRT/VTT, JSON manifest) and the inputs (rendered video + report.json). This is a specific verb+resource with no ambiguity, and it distinguishes itself from sibling tools by focusing on the final export step.

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

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

The description gives clear usage context: it requires only the rendered video and report.json, and explicitly states it does not need a key or browser. It also mentions the async behavior and rejection condition. However, it does not explicitly contrast with alternatives like frames, stills, or gif, so the 'when to use' is implied but not exhaustive.

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