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

Annotations already establish that this is a safe, read-only, non-destructive, closed-world operation. Beyond that, the description adds meaningful behavioral context: events are reported in source ms, typed text is omitted unless includeText is true, marker timing has specific pause/resume semantics, and audio valleys are derived only with a microphone.

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

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

The description is front-loaded with the core action and then enumerates event types in a single dense sentence. It is long and somewhat run-on, but nearly every clause contributes specific semantic information needed to understand the output.

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 complex event categories, lack of output schema, and poor schema descriptions, the description does substantial work by listing returned event types and timing semantics. It still omits projectPath meaning and exact output structure details, so it is strong but not fully 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 0%, so the description must compensate. It fully explains includeText by stating that typed text is omitted unless it is true, but it leaves projectPath unexplained beyond the schema's type and minimum length requirement.

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 and resource: reading what happens in the raw recording, with a detailed enumeration of event types it extracts. It is much clearer than the bare tool name screenstudio_analyze, but it does not explicitly distinguish itself from sibling tools such as screenstudio_transcript_read or screenstudio_plan_edit.

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 what the tool returns but says nothing about when to use it versus alternatives. It does not name sibling tools, prerequisites, or when-not-to-use conditions, leaving routing guidance to inference.

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

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

Annotations supply destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: it explains that apply is live and undoable, that save silently replaces existing brands, that delete is permanent even when a brand no longer reads, that caption contrast is validated against WCAG 4.5:1 with an automatic readable fallback box, that the cursor set is checked against the app, and that toPreset reports when the build cannot save presets. It also states what is mutated (settings in the open editor) and that it returns settings and reasons.

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 core purpose is front-loaded in the first sentence and the action list is set off cleanly. It is dense and long, but for a six-action tool with a large nested brand object, most sentences earn their place; the enumeration of brand fields is long but load-bearing since the schema lacks descriptions.

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 7 parameters, a nested brand object, no output schema, and annotations that only flag the safety profile, the description is largely complete — it covers each action's behavior, validation checks, limitations, and even return semantics ('returns the settings it changed and why'). The unexplained stepMs parameter and the action/parameter 'save' collision are the remaining gaps.

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?

Top-level schema description coverage is 0%, so the description carries the burden and does so well: it explains name, projectPath (which project apply/toPreset act on), show (suppress live preview unless false), and the entire nested brand object (colours, backdrop modes, captions, cursor, sound, radius, shadow, padding, voice, music). Two gaps remain — the stepMs parameter is never mentioned, and the boolean 'save' parameter is ambiguous against the action of the same name.

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

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

The opening sentence states a specific verb+resource and scope: 'Save a client's brand once and apply it to any project as one live, undoable config op.' It further distinguishes this tool from siblings like screenstudio_presets and screenstudio_editor_apply by enumerating its six actions (save/list/show/delete/apply/toPreset). An agent can identify what this tool owns 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?

Each action is described with its own trigger and behavior — save replaces a same-named brand, delete is permanent even for unreadable brands, toPreset asks the app to persist a Screen Studio preset. It notes the current limitation ('Image backdrops are not supported yet'). It does not explicitly name alternate sibling tools for overlapping work, so there is no hard when-not/alternative routing, but action-level guidance is strong.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the meaningful scope detail that the result is a static, closed set of shipped assets, but says nothing about return shape or size.

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 opens with the scope ("Everything Screen Studio ships") and then enumerates contents compactly. Every clause earns its place; there is no filler.

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

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

For a zero-parameter, read-only reference tool with no output schema, the description adequately conveys what the catalog contains. It could have gone slightly further on how results are keyed or grouped, but nothing needed to call it correctly is missing.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description's embedded config paths (e.g. cursor.set.id) explain what the enumerated items correspond to, adding useful context even though there is no input to document.

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

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

The description names a specific resource (a catalog of settings-addressable assets) and enumerates its contents with concrete config paths like styles.background.systemName and device.frameKey. It distinguishes itself from generic list tools, though it lacks an explicit verb and overlaps somewhat with siblings like screenstudio_music and screenstudio_voice_lines.

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

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

"Everything settings can point to" implies this is the lookup table for valid IDs before configuring settings, but no explicit when-to-use or when-not-to-use guidance is given, and it does not route the agent away from the music/voice siblings.

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 (readOnlyHint=true, destructiveHint=false) already establish this is a safe, non-destructive read, so the description only needs to add behavioral context. It contributes that the tool reads the open editor's live state and conditionally applies recipe/off-recipe rules, but says nothing about the response shape or the impact of the mode switch beyond that.

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 core purpose is front-loaded, which is good, but the first sentence is a single mega-clause stuffed with a long parenthetical checklist. Most items earn their place as scannable criteria, yet the structure is dense and could be broken up 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?

For a 6-parameter tool with nested objects, no output schema, and only 33% schema coverage, the description covers the function and the recipe interaction reasonably but never describes what a 'judgment' returns or how issues are surfaced. Annotations cover safety, but the output/result gap keeps this at minimum-viable.

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 low (33%), so the description must carry more weight. It clarifies the relationship among recipe, recipeOverrides, and brand (overrides 'merge into the recipe's'; brand is 'you planned with'), which is genuinely additive, but projectPath, sceneId, and style's behavior beyond the enum remain undocumented.

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 verb ('judge/check') and resource ('a timeline') are stated, and the description concretizes the scope with a specific list of pacing/look concerns (zooms, rates, choppy cuts, speed ramps, cropping, flicker). It reads as a distinct pacing-review tool, but it never names or contrasts with siblings like screenstudio_analyze, so the agent must infer the boundary.

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: 'With recipe (plus the recipeOverrides and brand you planned with)' hints at a precondition, and 'Uses the open editor's live state when available' gives context. There is no explicit when-to-use versus when-not, and no named alternative, so guidance is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the precondition that the editor window must be on screen, the 24-tile cap, and the tile label format. It stops short of describing the returned artifact itself.

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

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

Front-loaded with the core purpose and packed with useful specifics, with no filler sentences. It is dense and long-ish, but each clause (moments captured, tile format, jobIds mode, sibling routing, precondition) 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 six-parameter, zero-required, no-output-schema capture tool, the description covers the two modes and the precondition an agent must satisfy. The gap is the display/appearance parameters (style, width, columns) and projectPath, which an agent would have to guess at.

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 carry the parameter burden, and it only partly does: playbackMs (with its 24-item cap) and jobIds (expanding to one row per export at opening/midpoint/ending) are explained. style, width, columns and projectPath get no mention at all, leaving half the surface undocumented in both places.

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 — reviewing a whole edit as a labelled grid of the open editor's preview — and enumerates exactly which moments get captured. An agent can distinguish it from editor_frame 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?

It names the alternative explicitly ('Use it before editor_frame, which is for a close look at one moment') and gives the selection condition (broad review vs. single-moment close look). It also covers both operating modes: editor capture vs. the jobIds path for finished exports.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and the description adds substantial context beyond them: the human-pace pointer glide, the stop conditions (focus loss, occlusion, user mouse movement), the app allow-list restriction, and the hard exclusion of system shortcuts like command+space/tab/q. This is unusually rich behavioral disclosure for a mutating UI tool.

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

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

The core purpose is front-loaded in the first clause, and each sentence carries real information, but the whole definition is delivered as one very long run-on paragraph mixing action semantics, safety limits, and pointer physics, which makes it hard to scan. Structuring the action list, the pointer behavior, and the restrictions into distinct sentences or bullets would preserve the content while improving retrieval.

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, open-world UI automation tool with no output schema, the description covers safety, side effects, restrictions, and per-action semantics well. It stops short of saying how observationToken is obtained (presumably from screenstudio_desktop_inspect/screenshot) or what the call returns on success or on being interrupted, which would close the 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 description coverage is 0%, so the description has to carry the parameters, and it largely does: taps is explained as 'a burst of count taps every intervalMs at one point, for mash buttons,' hold as 'press for ms, then release,' key as taking modifiers with a layout caveat, and scroll as taking optional x/y with a described pointer fallback. The top-level pace and observationToken parameters are never explained, which is the only real gap.

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

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

The description states a specific resource and scope — 'One visible native step on an observed window' — and enumerates the exact step types (focus, move, click, doubleClick, drag, taps, hold, type, key, scroll), so an agent knows precisely what single unit of work this performs. It does not, however, distinguish itself from the sibling screenstudio_desktop_perform, which sounds like an overlapping performer, nor from desktop_inspect/screenshot.

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

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

Usage context is implied through runtime conditions rather than tool selection: it explains that input stops if focus is lost, a point is covered, or the person moves the mouse, and that terminals/password managers/System Settings are off limits unless SCREENSTUDIO_ALLOW_APPS names them. There is no statement of when to prefer this over desktop_perform or when to observe first with desktop_inspect/screenshot.

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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior — the token expires in 60 seconds and can only be used once — but says nothing about what the inspection actually yields or what happens with a stale/invalid windowId, which matters since there is no output 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?

A single front-loaded sentence with zero filler; the token constraint is stated in the same breath as the action rather than buried.

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, 0% parameter coverage, and a return value that is an implicit handoff token, the description should explain what consumes the token and how the 60-second window constrains the next call. That linkage is absent, leaving the agent unable to sequence 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 description coverage is 0% for the single required windowId, so the description must carry the meaning. 'Exact native window' hints that windowId must reference a live native window handle, but it gives no source for that id, no format beyond integer, and no failure behavior.

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 ('Inspect an exact native window') plus the distinctive artifact it produces (a 60-second, single-use observation token), which separates it from desktop_screenshot/desktop_action/desktop_perform in the sibling list. It does not explicitly name those siblings, so differentiation is inferable rather than stated.

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

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

There is no when-to-use guidance, no prerequisite for obtaining a windowId, and no statement of how this differs from or precedes desktop_action/desktop_perform. The only usage hint is the single-use token lifetime, which an agent must reverse-engineer into a workflow.

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=false, openWorldHint=true and destructiveHint=true, so the safety profile is covered; the description adds context they cannot, namely per-action hold defaults (click 1.2s, type 0.9s, key 1s, scroll 1.2s), that the whole run is one continuous take, how markers alter the recording, and how minDurationMs stretches the final hold. It does not warn that this drives the real cursor/desktop or mention auth/failure behavior, so not a 5.

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

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

Front-loaded with the core action, then layered with detail; there is little filler since nearly every clause carries a default, a threshold or an integration rule. It is somewhat dense and parenthetical-heavy, which slightly hurts scannability, but nothing is redundant.

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

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

For a 5-parameter, 0%-coverage, no-output-schema tool whose annotations already cover safety, this is adequate but not complete: the required observationToken's origin and lifetime are unexplained, most step action types and their parameters get no treatment, and nothing is said about what the call returns or how failures mid-take behave.

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 and largely does: pace, markers and minDurationMs all get concrete semantics and defaults beyond the raw schema, and steps gets a behavioral contract (max 12, hold after each). Gaps remain — observationToken (a required parameter) is never explained, and holdMs plus several action types (drag, taps, hold, focus, doubleClick, move) are undocumented.

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 — 'Perform a whole beat in one take while recording' — with concrete scope (up to 12 steps, each followed by a visible hold). An agent can tell this is the multi-step, recorded desktop-automation sibling, though it never explicitly names screenstudio_desktop_action as the single-step alternative, so the differentiation is implied rather than stated.

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

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

Gives real usage context: one continuous take yields natural pacing, pace 1.3 is calmer, markers:true is what pairs the beat with screenstudio_analyze and screenstudio_narrate (pinToMarkers), and minDurationMs is meant to be set from a narration line's durationMs plus ~400ms. There is no explicit 'do not use this when…' or a named alternative for single actions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about scaling behavior, but does not disclose return format (image bytes vs URL), latency, or failure modes for an invalid windowId, leaving behavioral gaps beyond the 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?

Two sentences, front-loaded with the core action, which is good. However, the second sentence is garbled/truncated ('so large windows stay readable and small.'), costing clarity for the space it consumes.

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 2-parameter capture tool with annotations covering safety and no output schema, the essential action and the width behavior are conveyed. But windowId sourcing, return type, and relationship to desktop_inspect/action siblings are unaddressed, leaving it only minimally 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 0%, so the description must carry parameter meaning. It partially compensates by explaining the width parameter (points-wide scaling, default 1280), but the required windowId is undocumented — an agent is not told how to obtain a valid window id.

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: 'Screenshot the target native window.' It is clear what the tool does, but it does not explicitly differentiate itself from desktop siblings like screenstudio_desktop_inspect or desktop_action, which may also return visual/window 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?

'before deciding where to act' implies a position in a capture-then-act workflow, giving implied usage context. However, it names no alternatives (e.g., inspect vs screenshot vs action) and states no explicit when-not condition, so selection guidance is only suggestive.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries the real burden and does so well: it covers ordered execution, animated vs instant application (show default), save-after-each-apply, checkpoint id, and the failure model (partial:true, failedAt, error, prior ops remain, no save, use restore with checkpointId). It does not contradict the annotations. What remains thin is the pacing/taste check return value and whether screenstudio_editor_view is needed to see the editor window.

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 wall of prose with one long sentence enumerating ops, another merging behavior and defaults, and a third covering checkpoint/failure semantics. It is front-loaded only in the first sentence; the middle is hard to parse as a list of supported operations, and the op vocabulary is buried inline. It crams schema-level detail (radius, bevel, chromaticAberration, edgeFalloff01) into the description where it duplicates 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?

Given the complexity (op union with 19 members, 10 top-level params, no output schema), the description covers the essential call contract: ordered ops, animated vs instant, save behavior, checkpoint/undo path, and the units convention. Missing are the shape of the return checkpoint value, what the pacing and taste check contains, and any mention of editor window state (screenstudio_editor_view) — the last is inferable but not stated.

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 only 20%, so the description should compensate, and it partially does: it names the ops, gives examples for config dotted paths, and clarifies unit conventions ('all times in source ms', 'target x/y 0-1', 'rects 0-1'). But with 10 parameters and many nested op schemas, top-level params like brand, style, sceneId, recipeOverrides, stepMs, save and show get almost no explanatory text beyond the schema defaults.

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 (Edit) and resource (the open project in the editor window), and the description is dense with the exact op vocabulary an agent needs to apply an edit batch. It is clearly distinguishable from siblings like screenstudio_editor_restore (undo) and screenstudio_editor_state (read).

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

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

Usage context is clear: 'Edit the open project live in the editor window' and the closing note about screenstudio_editor_restore with the checkpointId explicitly names the undo alternative. It does not, however, state when to use this tool versus screenstudio_editor_save, screenstudio_plan_edit, or screenstudio_check_pacing, which is a gap for a tool this heavy.

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, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds non-annotation context that matters: the 6-frame cap, the requirement that the editor window is on screen, and the fact that no export/file is produced. It does not say how frames are returned, but with no output schema that is a minor gap.

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

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

Two sentences, zero filler, with the action and purpose front-loaded and the precondition as a short trailing constraint. 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 read-only preview-capture tool with no output schema and two params, the description covers intent, limits, and the key environmental precondition. The remaining gap is the return shape (images inline vs paths), which the description leaves unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains playbackMs indirectly ('playback times (up to 6)') but gives no format or unit detail (the schema's ms unit is only inferable from the param name), and projectPath is not addressed at all. Partial compensation only.

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 ('Capture the editor's rendered preview at playback times') and adds the intent behind it (check framing, zoom targets, legibility). The phrase 'without exporting' distinguishes it from the sibling export_frame tool.

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 clear context for when to use it ('to check framing, zoom targets and legibility') and a hard prerequisite ('The editor window must be on screen'). It implies a route away from export_frame via 'without exporting', but never names the alternative tool explicitly, so it stops short of a 5.

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

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

Annotations already disclose readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that this manipulates the editor's own history (as opposed to project files), which is useful context, but says nothing about reversibility of redo, or how the 'steps' batching behaves.

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 tight sentence with no filler, and the core action is front-loaded. It is arguably too terse given the undocumented parameters, but it wastes nothing.

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-parameter mutation tool with 0% schema coverage and no output schema, the description should at least clarify projectPath and step semantics. As written it covers only the high-level action, leaving key invocation details to inference.

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% and the description mentions no parameters at all. The 'action' enum (undo/redo) is self-explanatory in the schema, but 'projectPath' and 'steps' (with its default of 1 and max of 200) are left entirely undocumented, so the description does not compensate for the coverage gap.

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 ('Step') and resource ('the editor's own undo/redo history'), reinforced by a concrete analogy ('like pressing Cmd+Z'). It's clear what the tool does, though it doesn't name the potentially confusable sibling screenstudio_editor_restore to differentiate itself.

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

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

The Cmd+Z analogy implies the general usage context, but there is no explicit when-to-use, when-not, or comparison against alternatives like screenstudio_editor_restore or screenstudio_editor_apply. An agent must infer when this is preferred over those.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds no further behavioral context — no ordering, scoping, or return shape — leaving it essentially a restatement of the name.

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

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

A single front-loaded sentence with zero waste. It is efficiently sized, though its brevity overlaps with under-specification rather than pure conciseness.

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

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

For a zero-parameter read tool with no output schema, the description is adequate to identify the tool but does not indicate what a returned entry looks like (project name, id, window). An agent can call it correctly, but the result shape must be discovered at runtime.

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 and there is nothing for the description to clarify. It correctly avoids inventing parameter semantics that do not exist.

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 (List) and resource (projects open in Screen Studio editor windows), which is clearly distinguishable from write-oriented siblings like screenstudio_editor_open, screenstudio_editor_apply, and screenstudio_editor_save. It does not explicitly name a sibling to differentiate against, so it falls short of a 5.

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

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

There is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as screenstudio_editor_state or screenstudio_editor_open. Usage is only weakly implied by the word 'list', so this is below the minimum-viable bar.

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=false, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description usefully adds that an already-open project is reused rather than re-opened and that the call returns a timeline; it says nothing about failure behavior for bad paths or focus-stealing side effects of opening a window.

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 front-loaded sentences with no filler; the core action and its reuse behavior come first. The closing sentence about the person watching edits is marginally decorative but conveys a real property of the 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 single-parameter tool with no output schema and annotations covering the mutation profile, this is roughly adequate. It still omits the shape of the returned timeline, path format expectations, and error behavior, which an agent would need for robust invocation.

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% and the description never mentions projectPath at all, so it does not compensate for the missing schema documentation. It doesn't state whether the path must be absolute, a project file, or relative to some root.

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: 'Open a project in a Screen Studio editor window,' which is distinct from siblings like editor_list, editor_state, and editor_apply. It doesn't explicitly name a sibling to contrast with, but the action itself is unambiguous.

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

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

The parenthetical '(or find it if already open)' implies idempotent reuse, which quietly tells the agent it needn't check open state first. However there is no explicit when-to-use vs alternatives guidance, e.g., relative to editor_list or editor_state.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, covering the safety profile, so the bar is lower. The description adds that this drives real-time human viewing, but omits whether playback blocks until completion, whether it requires an open editor, and how range bounds behave beyond defaults. readOnlyHint=false is consistent with playback altering editor state, so 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?

A single front-loaded sentence with the verb leading and no wasted words. It is appropriately sized, though the brevity comes at the cost of the missing detail noted elsewhere.

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 playback action with no output schema and 0% parameter documentation, the description is too thin. It does not explain blocking behavior, whether an editor must be open, or the range semantics an agent needs to call it correctly.

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

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

Schema description coverage is 0% for all three parameters, so the description must carry the burden. It only implies a range exists (mapping loosely to fromMs/toMs) and says nothing about units, format, defaults, or what projectPath identifies, leaving the parameters materially under-specified.

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 ('Play a range in the editor window'), and clarifies intent with 'so the person can watch it'. It does not explicitly distinguish itself from related siblings like screenstudio_editor_seek or screenstudio_editor_view, so it falls short of a 5.

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

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

There is no guidance on when to use this versus alternatives such as screenstudio_editor_seek, editor_view, or editor_frame. The phrase 'so the person can watch it' implies real-time playback but gives no conditions, prerequisites, or exclusions.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description is consistent, adding that current editor state is replaced by the saved checkpoint (an overwrite). It does not disclose permissions needed, whether the restore is reversible, or how the timeline differs from settings.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though slightly terse for a state-mutating operation.

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

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

For a one-parameter mutation with annotations covering the safety profile and no output schema, the description is adequate but omits where checkpointId comes from and what a restore affects. Enough to attempt a call, not enough to call confidently.

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 parameter meaning. It weakly signals that checkpointId refers to a checkpoint created by editor_apply, but never states the parameter name, its UUID format, or how to source a valid value; the schema supplies format/pattern but not provenance.

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 (put back/restore) and resource (editor timeline and settings) and ties the operation to 'an apply checkpoint', which links it to the sibling editor_apply. It distinguishes itself from generic editor siblings, though it does not explicitly contrast with editor_history or editor_open.

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

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

There is no guidance on when to restore versus using editor_apply, editor_history, or editor_open, nor any instruction on how to obtain a checkpointId. Usage is only implied by the phrase 'apply checkpoint'.

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 this is a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The Cmd+S analogy adds useful context that the operation persists in place, but nothing is said about what gets written, overwrite/versioning behavior, or failure modes.

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

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

A single front-loaded sentence with zero waste; the analogy is dense 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?

The tool is low-complexity (one param, no output schema) and annotations carry the safety profile, but the description leaves the central projectPath requirement and save semantics (in-place vs new file) unaddressed, so it is only minimally 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 0% and the description never mentions the required projectPath parameter. Worse, "the open project" implies the target is implicit, which sits awkwardly against a mandated projectPath argument the description leaves unexplained.

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 ("save") and resource ("the open project"), reinforced by the concrete Cmd+S analogy that tells an agent this persists editor state. It is clear against a sibling like editor_apply, though it never names that distinction 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?

No when-to-use guidance, no prerequisites, and no mention of the close sibling editor_apply (which likely applies edits rather than persisting them). The agent must infer the save-vs-apply boundary entirely.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, with no open world, so the safety profile is partly covered. But the description doesn't explain the effect of seeking (does it pause playback? require an open project?) or the interaction between the two optional time parameters. Little context beyond the 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?

One sentence, front-loaded and compact, but so terse that it omits important qualifiers. It is minimally acceptable in size but not richly structured.

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

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

For an editor mutation with no output schema and zero parameter documentation, the description is too thin. It omits prerequisites (open project), precedence of sourceMs vs playbackMs, and any effect on recording state, leaving gaps for an agent to call it correctly.

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

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

Schema description coverage is 0% for three parameters, so the description must compensate. It only vaguely mentions 'playback or source time' and does not clarify units (schema hints ms), precedence when both are supplied, or that projectPath is required.

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 ('move') and resource ('editor playhead') with the target ('playback or source time'). It clearly describes the action, though it doesn't distinguish itself from siblings like editor_frame or editor_play beyond the time axis.

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?

No guidance on when to use this versus alternatives such as screenstudio_editor_frame or screenstudio_editor_play. An agent is left to infer that seek sets the playhead without playing.

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 safe-read profile is covered. The description usefully conveys that this is *live* state and that includeConfig widens the payload, but it omits what happens when no editor is open and the trailing note about config ops is a routing hint rather than 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 core content is front-loaded in the first clause, and the includeConfig condition is stated before the exhaustive settings list. The parenthetical enumeration is dense but each item earns its place; only the trailing 'config op' sentence reads as slightly extraneous.

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 compensates by enumerating the returned data (timeline elements, playhead, undo state, style summary, settings). Safe-read annotations cover the mutation risk, so the main residual gap is the undocumented projectPath and the unstated editor-must-be-open precondition.

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 burden. includeConfig is well explained (it unlocks every project setting), but projectPath is never described at all, leaving roughly half of the two parameters undocumented. The long parenthetical enumerates returned fields rather than parameter semantics.

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

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

The description names a specific resource (the open editor's live timeline) and enumerates its concrete contents: slices, zooms, camera layouts, masks, playhead, undo state, and style summary. It is clearly a read-state tool, but it never explicitly distinguishes itself from nearby siblings like screenstudio_editor_view or screenstudio_editor_list.

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

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

The clause 'with includeConfig, every project setting' tells the agent when to enable that parameter, which is genuine conditional guidance. However, there is no explicit statement of when to call this tool versus editor_view/editor_list, nor any prerequisite that an editor must already be open; usage is only implied.

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 mark readOnlyHint=false and destructiveHint=false, and the description adds the key nuance that although it drives the interface state, it 'Changes nothing in the project'. That scoping detail meaningfully complements the annotations rather than repeating them.

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

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

A single dense sentence front-loads the core purpose and enumerates the operations, followed by a short scope clause. It is information-rich and mostly waste-free, though the enumeration makes it long.

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 8-parameter tool with 13% schema coverage and no output schema, the description covers the main capabilities but leaves gaps: how projectPath works, whether operations combine (e.g., select plus panel), and what 'close' does. Adequate but incomplete for the tool's 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 only 13%, so the description must carry the load. It maps panel options, timeline select categories and id-based selection, timelineMs units, sidebar/timeline toggles, and preview-only, which compensates reasonably. However it never mentions the 'close' parameter and does not clarify interactions between select, close, and panel.

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 ('Drive') and resource ('the editor interface') and enumerates the concrete operations: opening panels, selecting timeline items, setting the timeline span, toggling sidebar/timeline, and preview-only. The sibling set is not named explicitly, but 'Changes nothing in the project' implicitly separates it from mutating siblings like editor_apply.

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 lists what the tool can do but gives no guidance on when to prefer it over siblings such as editor_state, editor_open, editor_list, or editor_apply. No prerequisites or when-not-to-use conditions are stated, so an agent must infer the selection rationale.

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=false, destructiveHint=false and openWorldHint=false, so the mutation-but-safe profile is partly covered. The description usefully adds that the source project is preserved, which clarifies the scope of the side effect. It does not say what happens to partial output files or whether cancellation is reversible, so it adds context but not full behavioral detail.

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 that states the action and its key non-effect with zero waste.

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

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

For a simple one-parameter mutation, the description plus annotations cover the essentials (what it does, that it is non-destructive). However, it omits what happens to the job/output after cancellation and any prerequisite state, leaving some gaps for a state-changing operation.

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% for the single jobId parameter, so the description carries the burden; it implies a job identifier is required but adds no format, sourcing, or lookup detail beyond the schema's uuid type and pattern. Baseline 3 for a single-param tool where the schema already constrains the type.

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

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

States a specific verb (Cancel) and resource (export job), clearly distinguishing it from the sibling export_start/export_status/export_frame/export_variants tools. The qualifier 'known' hints that the job must already exist, but the description stops short of naming siblings 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?

There is no explicit when-to-use guidance, no statement of prerequisites (e.g. the job must be running), and no comparison to alternatives such as letting an export finish or re-running export_start. Usage is only loosely implied by 'known export job'.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without description help. The description adds one piece of behavioral context — the frame comes from a *completed* render — but says nothing about output format (image bytes, file path, or URL), whether the frame is persisted, or any failure mode when the export is not finished.

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?

It is short, but this is under-specification rather than conciseness: a single sentence fragment with no verb and no front-loaded statement of action. Nothing is padded, yet the brevity costs more than it saves for a tool whose behavior is not self-evident.

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 is the only place an agent could learn what a 'frame' return looks like, and it omits that entirely. For a read tool that presumably returns image data, the missing return-format information and the ambiguous meaning of jobId leave the definition inadequate despite the tool's low 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 0%, so the description must carry the load. 'playback milliseconds' usefully supplies the unit for timeMs, which the schema only types as a plain number with minimum 0, but jobId's meaning (export job vs project id) is left entirely to the parameter name and uuid pattern. Partial compensation for a two-parameter tool.

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 fragment 'A frame of the completed render at playback milliseconds' identifies the resource (a frame) and its scope (the completed render, not the editor preview), which implicitly separates it from siblings like screenstudio_editor_frame and screenstudio_source_frames. However, it is a verbless noun phrase that never says what the tool does (extract/return/fetch) or what it produces, leaving the purpose only inferable.

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

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

There is no when-to-use guidance, no prerequisites stated as instructions, and no mention of the obvious alternatives (screenstudio_editor_frame for editor previews, screenstudio_source_frames, screenstudio_contact_sheet). The only faint hint is 'completed render,' which implies a finished export job is required, but this is never stated as a usage condition.

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

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

Annotations only cover the safety profile (not read-only, not destructive, closed world). The description adds genuinely non-derivable behavior: async job semantics ('Returns a job; poll status'), the source live/disk field in results, the no-overwrite guarantee with the delivery_failed + renderedPath failure shape, and the meaning of keepRender. These are substantive operational details beyond the annotations.

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

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

Front-loaded with the core action, then the critical no-overwrite and polling facts. The height/aspect-ratio examples are somewhat verbose and partly restate the schema description, but every sentence carries usable information and nothing 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?

With no output schema, the description carries the return-value burden and does so well (job handle, poll status, source live/disk, delivery_failed + renderedPath). Missing pieces are minor: no mention of how long renders take or where output paths may be written.

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 only 14% across 7 parameters, so the description must compensate. It explains format (mp4/gif), height semantics (duplicating the schema's own height description), keepRender, and outputPath's no-overwrite consequence, but says nothing about fps or quality. Partial compensation for a sparse 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: render the editor's current view (including unsaved edits) to a local MP4 or GIF. The 'live editor vs saved project' framing distinguishes it from a plain project export, though no sibling (e.g. export_frame, export_variants) 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?

Implies usage ('including unsaved edits', 'without a save dialog') and says to poll status after starting a job, but never states when to prefer this over export_variants or export_frame, nor any exclusion conditions. Usage is implied rather than prescribed.

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

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

Annotations declare it is non-destructive and not open-world, but readOnlyHint=false is the only notable flag and the description adds useful return behavior: it yields the delivered file with encoded media properties once complete. It still omits what is returned while the job is pending, error/failure states, and whether polling is safe or rate-limited.

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

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

A single front-loaded sentence with no filler; the verb and resource lead, and the return behavior follows as a subordinate clause. Nothing is wasted.

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

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

For a polling tool with no output schema, the description should carry the return-value burden, and it only partially does (mentions the file and encoded properties). Pending, failed, and expired job outcomes, plus the relationship to export_start, are 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 0% and the description never mentions jobId. The schema does constrain it to a UUID format/pattern, so an agent can infer the type, but the description adds no semantics about where the jobId comes from or how it is obtained.

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

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

States a specific verb (Inspect) and resource (an export job), which cleanly separates it from export_start, export_cancel, export_frame, and export_variants. It does not explicitly name or contrast with any sibling, so it falls short of the top band.

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

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

There is no guidance on when to call this versus the other export tools, nor any note that it is meant to be polled after screenstudio_export_start. Usage is only implied by the word 'job'.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses a rich set of behaviors: rendering is serialized in Screen Studio, a progress notification fires per target, renders past renderTimeoutMs are cancelled, a second call for the same project/outputDir is refused while one runs, files never overwrite, and the editor state is left unchanged. It also details the mapping of aspect, padding, caption and zoom behavior per target.

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 core purpose is front-loaded well, but the body is one very long paragraph dense with nested parentheticals, which makes it hard to scan for a single parameter or behavior. Much of the content earns its place, but the structure fights comprehension rather than aiding it.

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

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

For a 10-parameter tool with nested objects, no output schema, and 30% schema coverage, the description is thorough: it covers inputs, per-target behavior, side effects, naming/outputs, timeout/concurrency limits, and even summarizes the return (files, warnings, notes). An agent has what it needs 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?

With only 30% schema coverage across 10 params, the description compensates well: it expands each target with its aspect/resolution/fps, explains baseName's naming pattern ('<baseName>-<target>.<ext>'), what kit adds by default (poster PNG, .srt/.vtt, chapters, manifest, contact sheet), the chapter ordering rules (first at 0:00, ≥10s apart), and how recipe overrides frame rate and resolution. Only recipeOverrides is left unexplained.

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

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

The description opens with a specific verb and resource: 'Render one edit for every place it goes, in one call,' and enumerates the exact seven targets with their resolutions and frame rates. An agent can tell this is the batch multi-variant exporter (versus the single-target screenstudio_export_start) 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 'one call' for 'every place it goes,' and it explains that recipe-supplied targets become the default. However, it never states when NOT to use it or names the alternative (e.g. export_start for a single target), and there is no explicit guidance on choosing between style/recipe combinations.

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 say readOnly=false/destructive=false; the description goes far beyond by disclosing that apply:true mutates live and is undoable-then-saved, that an existing blur mask grows to cover new findings, and that a highlight or disabled mask blocks a blur. It also details the return payload and the detection pipeline, none of which structured fields provide.

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

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

Purpose is front-loaded and almost every clause is functional, but the single dense paragraph and the rendering minutiae of the preview sheet (960px, red fills, yellow rings) push past what an agent needs to invoke the tool. Efficient overall, mildly bloated in places.

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 full burden and does: it enumerates the returned detections, masked preview, preview sheet, notes, and addMask ops, plus mutation side effects. Nothing needed to call or interpret the tool 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?

With 0% schema description coverage the description must carry the params, and it does: apply (live vs preview), ignore (drops expected kinds, enum explained semantically), everyMs/maxFrames (frame-grid behavior), extraTerms (plain words or /regex/flags, and that a term inside a longer secret widens the blur), and projectPath implicitly. It adds real meaning beyond the bare schema types.

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 ('Find private text in the footage... propose blur masks') and the scope is unmistakable. No sibling tool does sensitive-data detection, so the agent can route to it on name/description alone.

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?

Frames the use case ('before publishing') and distinguishes the preview mode from 'apply: true' (masks added live in the open editor), and names screenstudio_editor_apply as the consumer of its ops. It stops short of explicit when-not-to-use guidance, but the default-off vs apply-on split is a clear contextual cue.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds two genuinely useful traits on top: the connection is bound to 127.0.0.1 (no remote exposure) and a running app is never killed or restarted (idempotent, non-disruptive to existing sessions). It stops short of saying whether the call blocks until the app is ready or how it behaves if the app is not installed.

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, both earning their place: the first states what the tool does and its connection scope, the second states the non-destructive guarantee. Nothing is padded.

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 only needs to convey what happens when it is called, which it largely does (launches app, local automation binding, leaves running instances alone). Minor gaps remain around synchronous vs. async behavior and failure cases, but nothing an agent needs to avoid a wrong call.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to supply; the empty schema is self-explanatory. Baseline 4 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 states a specific verb (launch) and resource (Screen Studio) plus the operating mode (local automation connection bound to 127.0.0.1). That distinguishes it immediately from siblings like screenstudio_quit, screenstudio_status, and screenstudio_record_start without opening any schema.

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

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

Usage is only implied: the presence of a launch tool next to status/quit/record tools makes the 'start the app first' context inferable, and the note that a running app is never restarted hints at idempotent use. But there is no explicit statement of when to call this rather than attaching to an already-running instance, nor of prerequisites or ordering relative to other tools.

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 annotations: work happens on a COPY so the main edit stays intact (consistent with destructiveHint=false), sound is muted, the cursor returns to start and zooms end before the restart, and output is 1080p60 MP4 + silent WebM + GIF under maxGifBytes + poster. It also enumerates exactly what is returned, including the SSIM join-quality score and side-by-side end frames.

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 purpose is front-loaded and almost every clause conveys necessary behavior, so little is wasted. However, the body is a dense comma-chained mega-sentence that is harder to parse than it needs to be, costing readability for a complex 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 complex, 8-parameter tool with no output schema, the description covers the workflow, the destructive/non-destructive model, the plan vs apply modes, and the full return payload, so an agent can call it correctly. Residual gaps are the unexplained 'show' toggle and the path parameters' expectations.

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 0% schema description coverage the description must carry the load, and it does for most params: targetMs (4-15s), apply (plan vs apply), maxGifBytes (GIF size cap), baseName ('<name> Loop.screenstudio'), and formats (which files render). It leaves 'show', projectPath, and outputDir unexplained, which is a real but minor gap.

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 deliverable ('Make a seamless loop for a landing page hero or a README') and details exactly what it produces (MP4/WebM/GIF/poster plus a looped copy of the project). It is clearly separable from siblings like screenstudio_export_variants, which export rather than synthesize a seamless loop from a copy.

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 clear use context (landing page hero or README) and distinguishes the planning mode via 'apply:false only plans and shows the join from the raw recording.' It does not name an alternative tool or an explicit when-not-to-use, so it stops short of full routing guidance.

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

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

Annotations declare write/mutating (readOnlyHint=false) with destructiveHint=false, so the description is not the sole carrier of safety info. It adds genuine behavioral context: fade-in/out is applied, ducking is transcript-driven, and if narration exists the music is mixed under rather than replacing it. It stops short of stating whether an existing background track is overwritten or permissions 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 sentences, front-loaded with the core action. The narration parenthetical is slightly redundant but adds the mechanism insight needed to avoid misreading dedup behavior.

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?

Mutation tool with no output schema and full annotation coverage; the description supplies the behavioral mechanics (fading, transcript-driven ducking, mix-vs-replace). The main gap is absence of detail on the track identifier format and volume/duckTo semantics, which are the only parameters with defaults.

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% for 5 parameters, so the description must compensate. It explains duckUnderSpeech (dips while anyone speaks, sourced from the transcript) but leaves track, duckTo, volume, and projectPath entirely unexplained beyond their names and JSON type/defaults.

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 (lay a track under the edited video) and resource (Screen Studio's music library), plus fade behavior. No sibling tool in the list does music-bedding, and the description names the related narration music option to distinguish the mechanism.

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 the use case (backing music under an edited video) and notes the narration relationship, but gives no explicit when-to-use versus screenstudio_narrate's music option, no prerequisites, and no statement of when this tool is the wrong choice.

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: it discloses that line text leaves the Mac via an online Microsoft voice service (matching openWorldHint), that the app's own AI/recorded voiceover tracks are disabled, how mixing/music ducking and caption file outputs work, and what the return value reports (start/end, choices, warnings). It also defines the re-sync state-retention rules.

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

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

Front-loaded with the core purpose and organized into behavior, pinning, captions, return value, and re-sync. It is dense and long, with several multi-clause sentences, but virtually every clause carries decision-relevant information rather than padding.

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

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

For a 10-parameter mutation that performs network speech synthesis and retimes audio, the description covers side effects, privacy, dependencies on marker-producing tools, caption output modes, return contents, and re-sync semantics. With no output schema, it still explains what comes back.

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 high (80%), so baseline is 3, but the description adds semantics the schema omits — notably the sourceMs vs playbackMs distinction ('stays on its moment through later edits') and the pinToMarkers 300ms/marker-i rule including the skipped-marker edge case. It does not explain line limits or the nested text constraints, so not a full 5.

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

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

Opens with a specific verb+resource ('Voice over the video') and then distinguishes itself from siblings by noting Screen Studio's own AI and recorded voiceover tracks are disabled and that music laid by screenstudio_music stays under the voice. An agent can tell this apart from screenstudio_music and the voice/caption siblings without opening a schema.

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

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

Gives clear operational context: call again without lines after changing the cut to re-sync, re-sync keeps last voice/rate/music/volumes/captions unless overridden, and markers come from screenstudio_desktop_perform markers:true or screenstudio_record_control addMarker. It does not explicitly state when to prefer this over related narration siblings, so it stops short of full alternative routing.

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

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

Annotations only cover safety (readOnlyHint=true), and the description adds substantial behavior beyond that: precedence rules ('explicit arguments win over the recipe, and the notes say what replaced what'), protection guarantees ('Speech from the transcript is never cut or sped up'), recipe/brand layering rules, and a concrete statement of what is returned (ops, pacing check, scored beats, director's notes). Nothing here conflicts with readOnlyHint.

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?

Almost every clause maps to a parameter, so the length is largely earned, but it is delivered as one unbroken run-on paragraph with no bullets or grouping, making it hard to scan for a 20-parameter tool. Shorter lists of defaults and precedence rules would materially improve usability.

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

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

For a complex, low-schema-coverage tool with no output schema, the description covers the planning workflow, defaults, precedence between recipe/args/brand, and the return shape. A few parameters (maxZooms, applyStyleConfig) and the interaction between zoom='auto' and maxZooms remain uncovered.

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 20 parameters at only 30% schema description coverage, the description carries the burden and mostly succeeds: it defines look, style, recipe, markers, markerBeatsMs, targetMs, structure, keep/drop, speedUps, tightenPausesMs, removeFillers, brand and aspect with semantics and defaults. It leaves maxZooms, applyStyleConfig, projectPath and recipeOverrides (only schema-documented) unaddressed, so the coverage is strong but not complete.

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

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

Opens with a specific verb+resource ('Propose an edit from the footage') and immediately distinguishes itself from the write path by noting it returns ops for screenstudio_editor_apply. The sibling it feeds is named, so an agent knows this is the non-mutating planning step, not the apply 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?

Gives real usage context: 'talkingHead ... skipped when the recording has no camera', 'speedUps:false for narrated videos', 'tightenPausesMs (250-400 for talking videos)', and 'No recipe is applied unless named'. It references screenstudio_recipes and screenstudio_brand for follow-up, though it never states an explicit when-not or names a competing planning tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that (the tool returns ops rather than mutating). It adds substantial context beyond the annotations: edit points always land in a pause, are at least 5s apart, and the returned ops 'clear the layouts track first' in screenstudio_editor_apply — a downstream destructive effect worth knowing.

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

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

Purpose is front-loaded in the first clause and every sentence carries information — no filler. The middle section is a dense, jargon-heavy run-on ('the cutout camera is the default layout, on the side away from the clicks...') that takes effort to parse, which keeps it short of a 5.

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

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

With 21 parameters, no output schema and no parameter descriptions in most of the schema, the description covers the essentials an agent needs: what it returns ('ops for screenstudio_editor_apply, the stretches, a layout check and notes saying why') and how the two `from` modes differ. It leaves the behavioral effect of many tuning parameters unexplained, so it is not fully complete for a tool of this complexity.

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

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

Schema description coverage is only 19% across 21 parameters, so the description must compensate, and it does for the policy-critical ones: `side` ('away from the clicks'), `bookends` (full screen for opening line and sign-off), `splitScreen` (under long talk with nothing clicked), `zoom` (screen only while a zoom asks the viewer to read) and `minStretchMs` wiring. However, roughly half the parameters (markers, markerBeatsMs, maxZooms, targetMs, structure, removeFillers, tightenPausesMs, keep/drop) get no explanation at all.

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 — 'plans camera layouts from the speech, clicks and zooms' — and frames the tool as a 'camera director for talking-head recordings'. It is clearly distinguishable from siblings like screenstudio_plan_edit (which plans edits) and screenstudio_editor_apply (which consumes the returned ops).

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 explicit routing advice for the `from` parameter: 'from timeline (default) plans over the open editor's current cut; from plan plans over a fresh screenstudio_plan_edit plan, so pass the same recipe and plan options you applied it with'. It also names the downstream consumer (screenstudio_editor_apply) and a no-op case ('A recording with no camera gets no layouts'), but never states a when-not-to-use condition.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety baseline is covered. The description adds genuinely new behavioral context the annotations cannot: the interaction where an open editor retains stale settings and its next save writes them back over the preset, which warns against a specific destructive sequence.

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 two modes, then a compact caution sentence. Dense but every clause earns its place; no filler 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?

For a dual-mode tool with no output schema, the description covers both actions and the destructive apply workflow adequately. It could say more about what 'list' returns, but the safety-relevant behavior is well covered.

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% for three parameters, so the description must carry the burden. It conveys the mapping implicitly (apply a preset to a project file => presetPath + projectPath, list needs none), but never explains the parameters by name, their formats, or which apply to which action.

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 two specific verbs (list/apply) against a specific resource (the person's saved Screen Studio presets), and clarifies that apply uses 'the app's own preset apply' rather than the editor's settings path. Clear without opening the schema, though it does not name the nearby sibling screenstudio_editor_apply 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?

Gives a concrete when-to-use constraint: apply to a project that is NOT open in the editor, because an open editor will overwrite the preset on its next save. Strong contextual guidance, though no alternative tool is named for the editor-open case.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds real context beyond that by framing the operation as a copy that preserves the original. It still omits important behavior: what happens if destinationPath already exists, whether it overwrites or fails, and whether the whole bundle (media included) is copied.

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 well-formed sentence with the action and its purpose front-loaded and zero filler. Nothing needs to be trimmed and nothing is buried.

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 two required params, no output schema, and a low-complexity operation, the description covers the core intent but is silent on collision behavior, return value (e.g. resulting project path), and whether the copy is deep or shallow. Adequate as a minimum viable definition, not fully 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 0% for both parameters, so the description must carry the load; it partially does. 'Project bundle to a fresh destination' implies projectPath is the source bundle and that destinationPath should be a new/non-existing location, which is added meaning beyond the bare minLength:1 schema. It does not clarify path formats, relative vs absolute, or copy semantics.

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

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

The description gives a specific verb ('Copy') and resource ('project bundle') plus the destination concept, so the operation is immediately identifiable. It does not name or contrast with any sibling such as screenstudio_editor_save or screenstudio_editor_restore, so sibling differentiation is left to inference.

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 clause 'to keep the original untouched' implies the intended scenario — duplicating before making changes — which is genuine implied usage guidance. However, there is no explicit when-to-use/when-not-to-use statement and no named alternative (e.g. editor_save vs duplicate) for an agent to route between.

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: it discloses the side effect of closing the local automation connection, explains that the app handles the unsaved-changes prompt itself, and flags the recording guard condition. This is exactly the behavioral context an agent needs for a destructive 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?

Two dense sentences with the operation front-loaded and no filler. Every clause (analogy, connection closure, unsaved changes, recording refusal) carries information.

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

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

For a no-param, no-output-schema tool, the description covers the operation, side effects, and refusal condition completely. Nothing an agent needs in order to invoke it correctly is missing.

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

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

The tool takes no parameters, so the schema baseline of 4 applies. There is nothing to document and the description appropriately spends no words on parameters.

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 (Quit) and resource (Screen Studio), and the Cmd+Q analogy makes the operation unambiguous. It is clearly distinguishable from siblings like screenstudio_launch or screenstudio_status without needing 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 usage condition ("when the work is done") and states a precondition (refuses while recording). It does not name alternatives, but there is no obvious sibling that arbitrates the quit decision, so context is adequate.

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/destructive=false/closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: what each call mode returns (list with when-to-use notes, full recipe with overrides merged and explained in plain words, brand kit overlaid) — useful since there is no output 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?

It is front-loaded with the resource, but the single dense paragraph packs three call modes plus a long parenthetical list into semicolon-joined clauses, making it harder to parse than necessary. Information-dense with little waste, yet structure could be cleaner.

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-shape burden and does describe all three modes' outputs. It omits edge cases such as invalid names or whether recipes are user-modifiable, but is otherwise sufficient for a read-only catalog tool with a nested overrides object.

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%, so the description must compensate, and it does: it explains that omitting 'name' lists all recipes, that 'name' returns the merged full recipe, and that 'brand' (or overrides.brand) overlays a saved kit. This maps each parameter to distinct behavior beyond the raw 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 concrete resource (named recipes) and explains it acts as a lookup of pre-built directions that feed into screenstudio_plan_edit. An agent can tell it apart from most siblings, though it never distinguishes itself from the very similar screenstudio_presets.

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 plainly: 'None is a default: pick the one that fits the content and where it will be watched, then pass it as recipe to screenstudio_plan_edit.' That is clear when-to-use context and names the downstream consumer, but gives no explicit when-not or alternative-tool comparison.

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 flag destructiveHint=true, and the description usefully disambiguates which actions are destructive: restart and cancel 'discard', while finish 'returns the saved project'. That is genuine added context beyond the annotation, though it omits what happens to a recording if you pause and never resume.

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

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

Two sentences, zero filler. The action enumeration is front-loaded and the trailing tip is a single clause that earns its place by preventing unnecessary pauses.

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 one param and no output schema, the description covers what an agent needs, including that finish yields the saved project. It could be slightly more complete about the prerequisite that an active recording must exist before any control action is valid.

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 single enum parameter carries no inline descriptions, so the description must compensate. It effectively does: every enum value is named and the ambiguous ones are clarified (restart = discard and record again, cancel = discard, finish = return the saved project).

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 resource (the active recording) and enumerates every action it accepts (pause, resume, addMarker, restart, cancel, finish), each with a parenthetical gloss. An agent can immediately distinguish it from siblings like record_start (begin) and record_state (query) without opening any schema.

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

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

It gives explicit when-not-to guidance: pausing for short thinking is unnecessary because idle time is trimmed later. It stops short of routing the agent to siblings (e.g., record_start to begin, record_state to poll), so the alternative-selection story is implicit rather than spelled out.

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 this is a non-read-only, non-destructive, non-open-world write, so the safety profile is covered. The description usefully adds that audio and camera default off and that area is measured in display points, but says nothing about what artifact is produced, where it is stored, or how the recording is stopped (record_control).

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

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

Three tight sentences with the primary action front-loaded and no filler. The mode/scope detail leads, followed by defaults and workflow, which is a sensible ordering.

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

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

For a mutation tool with 7 parameters at 0% schema coverage and no output schema, the description covers the recording modes and defaults but omits how a session is stopped, where output lands, and the meaning of several parameters. Adequate but with visible gaps.

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% across 7 parameters, so the description must compensate. It partially does by clarifying area semantics ('area in display points') and the three recording targets, but name, systemAudio, and the device IDs (cameraDeviceId, microphoneDeviceId) are left undocumented beyond the audio/camera-off default.

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

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

States a specific verb ('Start recording') and enumerates the exact target resources (one exact window, a display, or an area of a display), which lets an agent map it to windowId/displayId/area without opening the schema. It reads distinctly from sibling recording tools like screenstudio_record_control and screenstudio_record_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?

Offers workflow guidance ('Rehearse first; record each beat with screenstudio_desktop_perform') and routes the agent to a specific sibling, but never states when to use this versus record_control or record_state, nor any preconditions like app/editor state. Usage is implied 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral detail ('Null means idle') about the return state, but says nothing about what a non-null session object contains or whether it reflects a live vs. completed recording.

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 terse, front-loaded sentences with no filler; the core action comes first and the return-value caveat follows immediately.

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 full responsibility for explaining the return value, and 'Null means idle' only partially covers it - the shape and fields of a non-null session are unstated. For a simple zero-param read-only tool this is acceptable but leaves a 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 tool takes zero parameters, so there is nothing for the description to disambiguate; per the rubric, 0 params sets the baseline at 4.

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

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

States a specific verb (Inspect) and resource (current recording session), which distinguishes it from siblings like screenstudio_record_start and screenstudio_record_control. It does not, however, differentiate itself from the similarly-named screenstudio_status or screenstudio_editor_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?

There is no statement of when to call this versus siblings such as screenstudio_status or screenstudio_record_start. Usage is only implied by the tool name; no prerequisites or exclusions 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description adds value by disclosing output characteristics instead: a hard cap of 8 frames and the fact that clicks within 400ms are annotated with a red box. It stops short of describing error behavior for out-of-range source timestamps, which keeps it from a 5.

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

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

Two compact sentences with no waste; the purpose is front-loaded and the operational details (frame cap, click marking) follow in order of importance.

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

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

With no output schema, the description carries the burden of describing returns; it hints at visual output via the red-box annotation but never says what is actually returned (image data vs. paths) or the return shape. Combined with undocumented parameters, the definition is workable but incomplete.

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% for three parameters. The description partially compensates by implying the meaning of sourceMs ('source ms', 'up to 8 frames' matching maxItems=8), but projectPath and width are entirely unexplained in both schema and description, leaving the agent guessing at what width controls.

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 ('See raw recording moments (source ms)') and clarifies the scope is raw source material rather than edited output. It does not distinguish itself from sibling frame-producing tools such as screenstudio_editor_frame or screenstudio_export_frame, so sibling differentiation is left to inference.

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 phrase 'before deciding what to keep or where to zoom' implies a pre-edit review workflow, which is genuine usage context. However, no alternative tool is named and there is no explicit when-not-to-use guidance, so the agent must infer when this beats the other frame-related siblings.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful content detail (what categories of sources are listed) but says nothing about freshness, scoping or how identifiers should be consumed downstream.

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 tight sentence that front-loads the verb and immediately enumerates the return categories. There is no padding or restatement of the tool name.

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

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

For a no-argument discovery tool whose annotations already cover safety, the description is close to sufficient, and its enumeration partially compensates for the missing output schema. It could be strengthened by naming how the returned IDs feed sibling tools.

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

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

Zero parameters, so the baseline of 4 applies. The schema is an empty object and there is nothing further for the description to disambiguate on the input side.

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 ('List') and enumerates the exact resource types returned (capturable windows, display IDs, microphones, cameras), so an agent knows precisely what comes back. It does not, however, distinguish itself from related siblings like screenstudio_source_frames or screenstudio_desktop_inspect.

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?

No when-to-use guidance and no reference to alternatives such as screenstudio_source_frames, which also deals with sources. The agent must infer that this is a prerequisite enumeration step for discovery, but nothing in the text confirms that.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the tool works even when the app is closed, and it surfaces permissions/dependency diagnostics an agent would otherwise have to probe for. It does not, however, describe response format or failure modes.

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?

'Start here' is front-loaded and the enumeration that follows is dense but each item earns its place by telling the agent what state is available. The long comma-separated list is slightly run-on but not wasteful.

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

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

With no output schema and no parameters, the description carries the burden of describing what is returned, and it does so comprehensively across connection, version, editor state, recording state, dependencies, permissions, features, recipes, and brand kits. Annotations cover safety, so nothing material is missing for a status 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; there is nothing for the description to clarify on the input side. No parameter-related guidance is needed or missing.

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

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

The description states a clear entry-point purpose ('Start here') and enumerates the concrete state it reports: connection, app version/tested-build status, open editor windows, recording state, dependency helpers, permissions, supported features, recipes, and brand kits. An agent can distinguish it from siblings like screenstudio_recipes or screenstudio_brand because this is the aggregate diagnostic surface rather than a management tool.

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?

'Start here' explicitly tells the agent to call this first, and 'Works when the app is closed' gives a concrete condition under which it is the right tool. It stops short of naming explicit alternatives or exclusions, so it is clear but not exhaustive.

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

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

Annotations only supply readOnlyHint/destructiveHint/openWorldHint; the description goes further by disclosing that the edit applies live to the open editor and returns 'updated' or 'not-open', which tells the agent what success and failure look like. The leading-space caveat for corrected text is a real behavioral gotcha not derivable from 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?

Three compact sentences, front-loaded with the action and the operation types, then the index source, then the live-update outcome. The trailing clause about 'updated'/'not-open' is slightly awkward but carries information, so nothing is pure 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 output schema and only hint-level annotations, the description does supply the return statuses and the live-editor behavior, which is the critical missing piece. However it leaves the session parameter unexplained and doesn't clarify edit-array constraints (500-item cap, index bounds), so it is adequate rather than 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 0% and there are 3 parameters, so the description must carry the load. It does explain index provenance, the text leading-space rule, and the meaning of removal, but says nothing about the 'session' parameter (which session it targets, why default 0) or projectPath, leaving real ambiguity.

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 ('Fix the transcript the captions show'), enumerates the two supported operations (correct a word/name, remove words), and names the sibling that supplies the indexes (screenstudio_transcript_read). An agent can distinguish it from screenstudio_transcript_read and screenstudio_transcript_generate without opening any schema.

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

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

It gives the prerequisite for the index parameter ('Indexes come from screenstudio_transcript_read') and the two supported use cases, which is clear routing context. It stops short of stating when not to use it (e.g. regenerating the whole transcript vs. patching individual words), so it is clear but not exhaustive.

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

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

Goes beyond the annotations by spelling out exactly what is destroyed (the current transcript, including caption fixes made elsewhere), what the generator can trigger (a model download, consistent with openWorldHint), and what the caller gets back (editor is 'updated' or 'not-open'), which substitutes for the missing output schema. This is unusually rich for a destructive write.

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

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

Front-loaded with the action and default, then the override condition, then the destructive consequence, then the return value. Dense and mostly waste-free, though the return-value sentence about 'editor' reads as a trailing detail that could be tighter.

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, open-world tool with no output schema, it covers the destructive scope, the network side effect, the fallback/override behavior, and the return value. Remaining gaps are minor: locale semantics and any precondition that a recording/audio source exists.

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 carries the burden; it does well for generator, giving the shape {type:'whisper', model} and the model-download implication, but says nothing about locale or what projectPath must point to. Partial compensation for a 3-parameter, nested-object 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: transcribe the microphone using Screen Studio's own recognizer, and names the source of captions. It is clearly distinguishable from siblings screenstudio_transcript_read (reads) and screenstudio_transcript_edit (edits), and it explicitly situates itself in that family.

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 default ('on-device system recognizer, no upload') and the condition for overriding it ('pass a generator ... only when the person wants it'). It also flags the sibling interaction by warning that it replaces caption fixes made with screenstudio_transcript_edit, though it does not state prerequisites (e.g. an existing recording) or when not to run it at all.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that by describing the return contents (word indices, source ms, phrase segmentation by pauses, filler words), which is what an agent needs to know before calling.

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

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

Two tight sentences, front-loaded with the verb and the payoff (the transcript contents), then the negative scoping clause. Minimal waste.

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

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

No output schema exists, so the description correctly spends its words describing what is returned. Combined with annotations covering the safety profile, this is nearly complete — the only gap being the unexplained projectPath parameter.

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

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

There is a single required parameter (projectPath) with 0% schema description coverage, and the description says nothing about it — no format, no hint about which project. With coverage below 50%, the description was expected to compensate and does not.

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 ('Read the transcript') and details the returned content: word index, source ms, phrases, filler words. The closing 'Does not generate or upload anything' implicitly distinguishes it from transcript_generate/transcript_edit, though it never names those siblings 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 via the negation 'does not generate or upload anything', which hints this is the read-only path versus the generate/edit siblings. There is no explicit 'use this when you need X, otherwise use Y' routing.

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

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

Annotations only declare the safety profile (readOnlyHint false, openWorldHint true, destructiveHint false); the description adds material context beyond them — the edge-tts online dependency with the privacy note that 'the text leaves this Mac', the caching of clips, and reuse by screenstudio_narrate keyed on text/voice/rate. It also documents the return values, which no output schema supplies.

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

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

Front-loads the purpose and stays to one dense sentence with parentheticals. Efficient, though the parenthetical stack makes it slightly heavy to parse.

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

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

With no output schema, the description correctly supplies the return shape (durationMs, beatMs) plus the network/privacy and caching behavior, which is what an agent needs. Minor gaps remain on failure modes (e.g., what happens if edge-tts is unreachable), but the core 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 coverage is 67%: rate and voice already carry descriptions with defaults and re-sync behavior. The description only adds that the cache key is (text, voice, rate), which is useful but marginal, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Voice a script before recording, without a project') and names the return payload (durationMs, beatMs). It explicitly distinguishes itself from siblings screenstudio_desktop_perform and screenstudio_narrate, so an agent can route 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 clear context: voice a script BEFORE recording and without a project, so each beat can be recorded to match its line length. It names screenstudio_narrate as the tool that reuses the cached clips, implying the when-to-use split, but stops short of an explicit when-not-to-use rule.

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