arsaze-mcp

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

Beyond the annotations, the description discloses meaningful runtime behaviors: confirm should be true only for destructive/credit-spending tools explicitly requested by the user; over-budget results are materialized as workspace files; and a bad call returns the exact signature so the agent can fix args. This is rich behavioral detail that the annotations alone do not 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?

The description is tightly organized: one purpose sentence followed by a compact parameter-by-parameter breakdown. No sentence is redundant, and the failure-mode note at the end earns its place by preparing the agent for the expected recovery action.

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 dynamic dispatcher with six parameters, no output schema, and a non-read-only, destructive-capable annotation, the description is unusually complete. It covers input semantics, output detail levels, oversized-result handling, pagination, field filtering, and the error contract, leaving little for the agent to guess.

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 there are six parameters, so the description carries the full burden. It explains every parameter: tool names from arsaze_tools with an example, args as an object, confirm semantics, response_detail options and defaults, fields as dotted paths, and cursor as pagination. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a specific verb and resource: 'Run any Arsaze tool from the catalogue by name.' It clearly identifies this as a generic dispatcher and distinguishes it from the specific Arsaze sibling tools by framing them as targets selected via the 'tool' parameter.

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

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

The description gives clear context for when to use the tool: whenever any catalogue tool needs to be invoked, with the tool name sourced from arsaze_tools. It also routes over-budget results to ws_grep/ws_read. However, it does not explicitly state when not to use this tool versus alternatives like run_timeline_batch or direct tool calls, so it stops short of a full when/when-not specification.

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 readOnlyHint=true and destructiveHint=false annotations, the description discloses that the call is a non-charging, non-reserving quote, that it reads the user's real plan and balance, and that it prices identically to the eventual generation. This is valuable behavioral context that annotations alone do not convey.

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

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

The description is front-loaded with the core action and result, followed by an explicit usage rule and a compact parameter legend. Every sentence carries necessary information, so the length is justified and 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?

With no output schema, the description's promise of an interactive card with a Generate button provides the needed output contract. The non-charge/reservation statement and complete parameter guidance give the agent everything required to invoke it correctly in context.

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

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

With schema description coverage at 0%, the description fully compensates by explaining every parameter: allowed kind values, provider sourced from real list_providers calls, duration_seconds only affecting duration-priced models, and quantity as the count of separate generations. Each schema field gains operational meaning.

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 precise verb and resource: show the user, as an interactive quote card, exactly what a generation will cost in credits before running it. It clearly frames the tool as a quote and distinguishes it from generation tools and the credits-display sibling arsaze_show_credits.

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

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

It explicitly says when to call: FIRST, before any generation, instead of asking a generic 'shall I generate?' or guessing rates. The rationale that rates are admin-set and change without code changes, plus the caveat that generation only starts if the user follows up, gives the agent a clear decision rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds useful behavioral context beyond annotations: it shows the 'real' credit balance, presents output 'as a card', and clarifies that rendering/export limits are displayed alongside but are not credit-based. This goes beyond simple annotation restatement.

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

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

The description is compact and front-loaded: the core purpose appears in the first sentence, followed by explicit usage triggers and a clarifying exclusion. Every sentence contributes useful information with no 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 zero-parameter, read-only information tool with no output schema, the description fully covers what the tool does, when to use it, and what it does not cover. An agent has enough context to invoke it correctly and set appropriate user 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?

The tool has zero parameters and 100% schema coverage, so there is nothing about parameters for the description to explain. The baseline of 4 applies because no parameter-semantic burden exists.

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 uses a specific verb ('Show') and clearly identifies the resource: the user's real credit balance, plan, and usage limits, presented as a card. It also distinguishes the tool's scope from rendering/export limits, which are separate hour-based limits, making the purpose unmistakable even among many siblings.

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

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

The description explicitly states when to use the tool: when the user asks what they have left, or when a generation was refused due to insufficient credits. It also provides a when-not case by clarifying that rendering/export is a separate hour-based limit, not credits.

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 user-facing behavior: inline player, real Download button, and live status for running jobs. It doesn't describe auth requirements or the returned object to the agent, but for a read-only display tool the added behavioral context is solid.

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

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

Three short paragraphs, each earning its place: purpose, main usage condition, and the sibling for the alternative case. Front-loaded with the core description; 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 tool with one required parameter and no output schema, the description covers the key decisions: what it does, when to use it, and how it differs from the sibling. The only notable gap is the absence of details about the MCP response format, but given the tool's display purpose and read-only annotations, it is 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?

The schema has zero description coverage for job_id, so the description must compensate. It does by explaining that the job is a video_gen/image_gen/voice job and that it can be running or done, giving a clear semantic anchor. It doesn't specify the format of job_id or how to obtain it, leaving some ambiguity, but the contextual mention of job types is meaningful.

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

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

States a specific action ('Display') and resource ('ONE finished generation') as a playable/downloadable card, and explicitly distinguishes from the sibling arsaze_show_generated_results. The description clarifies scope (one vs several) and even handles running jobs, so an agent can tell exactly what this tool does 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 an explicit 'use this instead of pasting a URL' rule for completed video_gen/image_gen/voice jobs, and explicitly names the alternative arsaze_show_generated_results for multiple results. Also clarifies behavior for running jobs. This is direct when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond annotations by disclosing that running jobs show as pending rather than being dropped, and that each result is downloadable. This gives behavioral context the annotations don't 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?

The description is two short paragraphs, front-loading the purpose and then adding usage context. The second paragraph is slightly verbose but each sentence earns its place by explaining when to use the tool and how it behaves with pending jobs. No irrelevant details.

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 read-only display tool with no output schema, the description covers the purpose, the when-to-use condition, and behavioral details about pending items. It gives an agent enough to decide when and how to invoke the tool correctly.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining the 'job_ids' parameter: 'Pass every job id from the batch; ones still running show as pending.' This directly clarifies the parameter's meaning and behavior, which the bare schema 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?

The description starts with a specific verb and resource: 'Display SEVERAL finished generations together as one grid, each downloadable.' It clearly distinguishes this from the sibling arsaze_show_generated_asset by emphasizing multiple results in a grid, so an agent can tell them apart without opening schemas.

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

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

The description explicitly states when to use the tool: 'whenever a single request produced more than one result — a batch image generation returns one job id per image.' It explains why (separate cards flood the conversation) and gives context about passing all job ids. It doesn't name the alternative for single results, but the condition is clear.

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

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

The description adds significant behavioral detail beyond the annotations (readOnlyHint, destructiveHint): the password is shown exactly once, only a hash is stored, and it cannot be recovered if not passed. These are critical operational constraints that the agent would not know from the schema or annotations alone.

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

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

The description is three short paragraphs: purpose first, then usage guidance, then constraints. Each sentence adds necessary information with no redundancy or filler. The structure is front-loaded and easy to scan.

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

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

For a read-only display tool with no output schema, the description provides sufficient context for correct invocation: what it displays, when to use it, and the password caveat. It doesn't describe return values, but that is not essential for a tool whose visible effect is the card itself. The missing piece, explicitly describing `share_id` as the share identifier, is minor.

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 schema description coverage at 0%, the description must carry the explanatory burden. It thoroughly explains the `password` parameter (passed from create_share, shown once, non-recoverable) and implies `share_id` is the ID returned by create_share. It compensates well, though `share_id` is not explicitly named as the create_share result, leaving slight 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?

The description states a specific verb ('Display'), a specific resource ('existing Remarker review link'), and the concrete output format (card with 'Open review page' button and copyable password). It explicitly differentiates from creation tools by noting it cannot create a share, making it easily distinguishable from siblings like remarker_create_share.

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

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

The description gives explicit when-to-use guidance: 'Use this right after remarker.create_share instead of typing the link and password out as chat text.' It also clarifies the boundary ('It cannot create one, and it cannot read back a password that was not handed to it'), telling the agent when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: on-demand serving, mode-dependent outputs, and the specific note that reads are not tools but files (ws_ls). This goes beyond annotation basics without 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?

The description is compact and well-structured, with each mode on its own line and the key fact (on-demand catalogue) front-loaded. Every sentence adds necessary information with no fluff.

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

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

Given the output schema exists, the description reasonably covers invocation modes and expected outcomes. The only notable gap is that it doesn't clarify whether names and query can be used together, which could confuse an agent. Overall it is nearly complete for a quick-reference 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?

Schema description coverage is 0%, so the description must fully compensate. It does: it explains the no-argument default, names mode returning signatures/param docs, query mode returning best-matching tools, and the `param?: type` optional-param notation. This is far beyond the bare schema.

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

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

The description clearly identifies this as an on-demand tool catalogue with three explicit modes: no arguments for a table of contents, names for signatures, and query for best-matching tools. It differentiates itself from operational siblings like arsaze_call and ws_ls by being a discovery/metadata tool, not an action 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?

It gives explicit context: use names before the first arsaze_call, use query for matching, and it distinguishes reads as files handled by ws_ls. However, it doesn't explicitly state when not to use this tool versus other siblings beyond reads, and it leaves the relationship between names and query (mutually exclusive vs combinable) unstated.

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/destructiveHint, and the description adds substantial behavior beyond them: results arrive as actual images, multiple frames are merged into a numbered contact sheet, sampling is capped at 12 frames, source-mode times are in source seconds while timeline-mode times are in timeline seconds, and each timeline frame is the top visible clip under the playhead. The max-12 and playhead semantics are non-obvious and materially affect invocation.

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 is front-loaded ('SEE the footage') and the mode/purpose/usage sentences each earn their place. The trailing boilerplate list 'response_detail (summary|compact|full), fields (dotted paths), cursor (next page) — see the server instructions' reads as template residue that belongs in the parameter layer rather than the description.

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

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

For a 10-parameter, no-output-schema tool the description appropriately explains the return shape (image frames / numbered contact sheet) and core timing semantics. It is weakened by leaving job_id undocumented, not clarifying the sheet flag, and deferring cursor pagination to server instructions, so an agent cannot fully resolve every parameter from the definition alone.

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 across 10 parameters, the description carries the burden and explains the important ones: asset_id selects source vs timeline mode, times gives exact moments, start_s/end_s/count sample a range with a max of 12, and it names response_detail (summary|compact|full), fields, and cursor. However job_id is never explained and sheet is only obliquely implied by 'contact sheet', leaving real gaps.

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 concrete verb+resource ('SEE the footage: decoded frames come back as an image') and immediately splits the tool into two distinct modes: asset_id for a single clip's source versus omitting it for the timeline. A reading agent can distinguish this from screen_look and the ws_*/arsaze_* siblings purely from the text.

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 when-to-use cases ('check who is on camera, framing, a bad frame, which angle is which'), an explicit when-not ('Check already_noted first: if another agent wrote down what's there, you may not need to look'), and a follow-up action (save findings with media_note). Nothing about routing is left to inference.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context: all-or-nothing execution, the ability to reference earlier step results, track ordering semantics, and the caveat about positional indexing. This goes 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?

The description is long but densely informative. It front-loads the core purpose, then systematically explains referencing, ordering, failure behavior, and usage guidance. Every sentence adds value, though it could be slightly more concise without losing essential details.

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 tool with dependencies and referencing, the description is remarkably complete. It covers the referencing syntax, track ordering, failure semantics, and how to inspect result shapes via timeline.txt. It also explains the all-or-nothing behavior and where to check step_results. Nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains the `steps` parameter: how to assign step_id, reference results with dotted paths, and the meaning of tracks.N ordering. It also implies usage of job_id through examples. It does not detail `fields` or `response_detail`, but those have defaults and are less critical.

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

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

The description clearly states the tool's purpose: running multiple timeline-tool calls in one request with cross-step dependencies. It names the specific resource (timeline tools) and the action (batch execution with referencing), and differentiates from the sibling add_clips_to_timeline by noting it's simpler for independent clips.

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

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

Explicitly states when to use: 'Use this whenever a plan has TRUE ordering dependencies' and when not to: 'for independent clips with no cross-references, add_clips_to_timeline is simpler.' Also provides guidance on referencing paths and the all-or-nothing failure behavior.

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?

Rich beyond annotations: discloses narration-as-caption behavior, camera zoom/hold semantics, rehearse mode (focus reports shot only before recording), hide-persists-until-unhide, app mode stopping on user mouse movement requiring resume=true. Annotations give safety/idempotency; description adds substantial runtime and editing semantics.

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

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

Dense but front-loaded with purpose; the long middle is packed with useful detail but runs as a monograph rather than structured bullets, making it harder to scan for a given action. Size is justified by tool complexity but structure 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?

Given 27 params, no output schema, and 0% schema coverage, the description covers most critical behavior: result fields (`shots`, `view`, `at`), steps chaining, recording narrations, resume semantics. Missing: explicit coverage of several params and no output schema means return values beyond mentioned flags are not fully specified.

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 description must carry param burden and does much of it: explains action, ref vs refs, x/y/w/h for areas, pad, zoom 1.1-4, seconds, text, color, lift, zoom_in, steps (max 40), resume, screenshot behavior. Some params (why, submit, amount, clear, key, url, cursor, fields, response_detail, direction) are only partially or implicitly covered.

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: performs an interaction action on the page/app with enumerated action set (click, type, scroll, focus, hide, etc.). It clearly distinguishes from screen_look (which is about observing) by the 'do one thing' framing, though it doesn't name siblings directly.

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

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

Provides clear contextual guidance: use ref over x/y, use 'say' while recording before each step, use 'focus' to show something off, 'hide' for privacy, rehearse framing before recording. Strong conditional guidance, though not explicit when-not or named alternatives for observation-first behaviors (screen_look).

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=false, destructive=false, idempotent=true, so the safety profile is largely covered. The description adds genuinely new behavioral context beyond the annotations: it releases held apps and warns that a still-recording take is thrown away, a data-loss consequence not expressed by destructiveHint=false.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence is terse to the point of being cryptic, but it is efficiently sized.

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 close/cleanup tool with no output schema, the essentials are present, but with 0% schema coverage the parameter documentation is thin and offloaded to "the server instructions," which the agent may not have in context. Adequate, not 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 carries the burden, and it does gloss all three parameters and even supplies the value set (summary|compact|full) for response_detail. However "fields (dotted paths)" and "cursor (next page)" are minimal, and it defers the rest to server instructions rather than explaining here.

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 ("Close the recorded browser") and adds scope ("let go of any app"), which separates it from open-oriented siblings like screen_open/screen_open_app. The parenthetical about discarding a recording further distinguishes it from screen_record_stop, though it never names that sibling explicitly, so it falls short of a clean 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 or when-not-to-use guidance. The parenthetical hints that an in-progress take is discarded, but the agent is not told to prefer screen_record_stop first or when this tool is the right choice versus simply ending a session, leaving usage 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?

Goes well beyond the annotations, which only say readOnlyHint=false and idempotentHint=true. It discloses the privacy model (typed values are secret in screen_look and shown as dots), the side-effect scope ('nothing is recorded meanwhile'), the exact return contract (done:true/false) and the cancel/timeout semantics. This is rich behavioral context an agent could not get elsewhere.

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

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

Front-loaded with the core action and only includes sentences that add behavior (security, return values, failure handling). The trailing parameter line is a slightly bolted-on appendix but is compact and useful.

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 contract and side-effect profile for a sensitive handover operation. The only real gap is the undocumented required 'reason' and the 'ref'/'seconds' parameters, which leaves the description not quite complete for a 6-parameter 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?

Schema description coverage is 0% across 6 parameters, so the description must carry the load. It explains only three (response_detail with its enum values, fields as dotted paths, cursor as next page) and leaves the required 'reason' plus 'ref' and 'seconds' entirely undocumented, so the agent cannot fully infer correct argument usage.

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 (hand over) and resource (the open page) with concrete examples of the triggering situations (sign in, enter a code, accept a prompt). However, it does not differentiate itself from the very similar sibling 'screen_login', which an agent could easily confuse with this 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 ('something only they should do') and a negative case ('in one of their own apps they simply type it themselves'), plus failure-handling guidance ('ask them before trying again' on done:false). It stops short of naming alternative tools by name, so it falls slightly 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 establish readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the returned fields and pagination via cursor, which is useful, but the Mac Meta/Command shortcut line describes keyboard behavior unrelated to listing apps and adds no transparency about this 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 first sentence conflates purpose, returned fields, use case, fallback, and platform behavior into one long clause, and the Mac Meta+C sentence does not earn its place for a listing tool. The parameter line is compact and front-loaded enough to be usable, but overall structure is loosely organized.

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 correctly enumerates return fields, and it covers purpose, consumer tool, fallback, and pagination. All three parameters are addressed, making it nearly complete for a simple read-only listing tool, with the only gap being detailed field-path availability.

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 it largely does: response_detail is given allowed values (summary|compact|full), fields is described as dotted paths, and cursor as next page. This meaningfully exceeds the bare schema, though it defers detail to 'server instructions' rather than fully documenting available field paths.

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

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

The description identifies the resource and scope precisely — the apps open on the user's computer — and enumerates the returned fields (hwnd, title, app, whether in front), which differentiates it from listing tools like ws_ls. It also names the consuming sibling screen_open_app, though the purpose is expressed as a fragment rather than a crisp verb+resource statement.

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

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

It states the downstream use case ('to pick one for screen_open_app') and a clear fallback when no match exists ('ask the user to open it'), which is genuinely actionable guidance. It stops short of explicit when-not-to-use or naming alternatives to screen_open_app, so it falls short of a 5.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) with three non-obvious behavioral facts: it runs in the recorded browser's own profile, the browser stays signed in afterward, and the agent never sees the user's keystrokes. The privacy and persistence details are exactly what an agent needs before invoking an interactive login.

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 purpose, then the procedural steps and privacy note, then a terse parameter glossary. The second sentence is load-bearing despite being procedural. The trailing parameter fragment is appended rather than integrated, a minor structural blemish.

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 interactive flow with no output schema and 4 undocumented params, the description covers the essential behavior: what the agent must tell the user, that credentials are never exposed, and that the session persists. What it returns and how the caller confirms completion are left implicit, but annotations cover the safety profile.

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. It lists response_detail (summary|compact|full), fields (dotted paths), and cursor (next page), which does supply semantics the schema lacks and adds enum values the schema omits. However, it defers to 'the server instructions' and says nothing about the required url parameter.

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 ('Open a window on the user's screen... for the USER to sign in to a site') and names the sibling flow it hands off to (screen_open). An agent can distinguish it from screen_open without opening either schema.

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

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

Provides an explicit workflow: open the window, tell the user to sign in and close it, then screen_open the page again. This gives clear when-to-use routing to the sibling. It stops short of stating when-not-to-use or edge cases, but the sequencing is unambiguous.

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

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

Annotations already declare readOnly, non-destructive, openWorld=false. The description adds real value beyond them: passwords are never returned, refs expire at the next look, screenshots are incurrable, and pagination is possible via cursor. This is meaningful behavioral disclosure despite annotations covering safety.

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

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

Front-loaded with what the tool returns, then parameter notes. Efficient, though the parameter sentence has a slightly telegraphic style ('response_detail (summary|compact|full), fields (dotted paths), cursor (next page) — see the server instructions.') that pushes detail off-doc.

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, and 0% schema description coverage, so the description needs to do more. It covers return content, ref lifecycle, and three of four params, but omits the screenshot param's semantics, any pagination size/limit detail, and defers heavily to 'server instructions' the agent may not have.

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 carries the burden. It names three of four parameters with hints: response_detail (summary|compact|full), fields (dotted paths), cursor (next page). The screenshot parameter is never explained despite being listed in the element inventory. 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?

The first sentence states a concrete verb+resource: 'See the page or app you opened', followed by a precise inventory of what is returned (actionable elements with ref/role/name/box, headings, scroll, screenshot). This clearly distinguishes it from siblings like screen_act, screen_open, and media_look.

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?

Implied usage only: 'the page or app you opened' anchors it to prior screen_open/screen_open_app, and the ref-validity note implies re-look workflow. But it never explicitly contrasts with screen_act (see vs act) or screen_result, and does not give explicit when-not-to-use guidance.

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

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

Adds real behavior beyond annotations: the browser has an isolated profile, the call returns page elements/headings/scroll/screenshot, and recording does not begin until screen_record_start. Missing details on the relationship to screen_act and whether the browser session persists after the call.

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

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

Front-loaded with what the tool does and its return shape, then param notes. The width/height/scale arithmetic example is a bit parenthetical but earns its place; no filler sentences.

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, but the description compensates by summarizing the return payload (elements with refs, headings, scroll, screenshot). Adequate for an 8-param open tool, with the main gap being the undocumented 'where' 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?

With 0% schema coverage across 8 params, the description carries the load well: it explains width/height as CSS pixels and the scale multiplier (1280x720 at 1.5 = 1920x1080), plus cursor (next page) and fields (dotted paths). It omits any meaning for 'where' and 'url', leaving two parameters 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?

Specific verb+resource: opens a web page in a dedicated browser on the user's computer, and clarifies it uses its own profile rather than the user's sign-ins, which distinguishes it from screen_open_app and screen_login. Doesn't explicitly name the sibling it replaces, but the browser-vs-app boundary is 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?

Implicitly tells you this is the entry point for browsing ('Nothing is recorded until screen_record_start' signals the follow-up recording tool), but gives no explicit when-to-use guidance against screen_open_app or screen_login, nor prerequisites like whether login is needed first.

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 (readOnly=false, idempotent=true, destructive=false), the description discloses rich behavioral context: real mouse/keyboard with the user watching, maximize-unless-disabled behavior, what is returned (refs, roles, names, pixel boxes, plus a screenshot), and the interrupt condition when the user takes the mouse. This is exactly the kind of context annotations cannot carry.

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

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

The main paragraph is front-loaded with the action and its consequences, and every clause carries information. The trailing dash-note on response_detail/fields/cursor feels appended rather than integrated, slightly hurting flow.

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-param, no-annotation-supportive tool with no output schema, the description covers the workflow, constraint, and return contents well. The one substantive gap is how the caller selects the target app (hwnd/title), which the description leaves unaddressed.

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

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

With 0% schema coverage across 6 parameters, the description must compensate. It explains maximize ('maximised unless maximize=false') and briefly annotates response_detail, fields, and cursor, but says nothing about hwnd or title — the very parameters that identify which app to open. Partial coverage of the critical parameters keeps this at 3.

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

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

The description states a specific verb and resource ('Take one of the user's apps for a demo... brings its window to the front'), plus the ongoing effect on sibling tools (screen_look, screen_act, screen_record_*). It fails to distinguish itself from the similarly named sibling screen_open, so it stops short of a 5.

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

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

It provides clear workflow context — this is the entry point that makes screen_look/screen_act/screen_record_* operate on the chosen app — and states a hard constraint ('If the user moves the mouse, you are stopped'). However, it never explicitly says when to prefer this over an alternative such as screen_open.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior — actions between calls are not recorded ('thinking time never shows') and the look is applied at stop but remains editable via screen_record_stop. It does not resolve the tension between 'start' semantics and idempotentHint=true, nor mention auth or what happens on a second start call.

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

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

Four sentences of heavily metaphorical prose precede a boilerplate footer. The operational content (start recording, settings applied at stop, editable later) is buried inside the metaphor rather than front-loaded, and the closing parameter hints are unrelated 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?

A 26-parameter tool with 0% schema description coverage, no output schema, and no annotation explanation of return values needs far more parameter documentation than one example list. An agent cannot know what most of the 26 flags do, what the call returns, or what state it must be in before calling.

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% across 26 parameters, so the description carries the full burden. It names only a handful of examples (style, aspect, cursor, highlight_color, auto_zoom, captions) and leaves the other twenty undocumented. The trailing 'response_detail... fields... cursor...' footer reads like generic boilerplate and actively confuses 'cursor' (a recording look parameter here) with pagination.

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

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

The opening sentence gives a specific verb and resource: 'Start recording the page or app you opened.' It also gestures at the sibling relationship ('screen_record_stop can still change any of it'). The remaining prose is metaphorical ('take', 'cut', 'editor') and obscures rather than sharpens the purpose, keeping it below 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?

'Rehearse the flow first' implies a when-to-use condition, and the mention that screen_record_stop can adjust settings later gives a weak alternative path. There is no explicit statement of prerequisites (does a page need to be open? does screen_open come first?) nor when-not-to-use 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?

Beyond the annotations (mutating, non-destructive, idempotent), the description discloses that the edit is rendered and final on return, that output lands on a NEW project on the user's own computer, that video/audio analysis is off, and exactly which identifiers the call yields. That is materially more than readOnlyHint/destructiveHint already 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?

Front-loaded with the essential 'Stop recording', but the remainder is one sprawling run-on thick with parentheticals. Content like 'plus what the edit did' and the closing dangling 'response_detail ... see the server instructions' fragment add bulk without adding precision.

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 high-complexity mutation tool with no output schema, the description does cover the return payload (project_id, job_id, asset_id, clip_id, editor link, steps, script) and the side effects. Its one real gap is the undocumented majority of styling parameters, which is a notable omission for a 25-parameter schema.

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

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

Schema description coverage is 0% across 25 parameters, so the description must carry the load. It names and even enumerates a subset (style: midnight|clean|bold|plain; aspect: 16:9, 9:16, 1:1, 4:3; callouts, title_card, cursor, highlight_color, auto_zoom, captions, response_detail, fields) but leaves roughly two-thirds of the styling parameters (radius, shadow, padding, backdrop, skip_idle, click_sound, cursor_size, motion_blur, click_ripple, zoom_strength, highlight_lift/zoom, hide_idle_pointer, frame) 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?

States a specific verb and resource ('Stop recording') and immediately names the sibling it complements by describing the recording pipeline begun at screen_record_start. An agent can distinguish this from screen_record_start, screen_status and screen_result without opening any schema.

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

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

Gives clear workflow context: it is the terminating call for a recording session and 'Continue editing that job with the usual timeline tools' routes the agent onward. It also states precedence ('The look is what you set at screen_record_start, with anything you set here over it'). No explicit when-not or named alternative is given, 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, destructiveHint=false, idempotentHint=false. The description adds useful behavioral context: the result is only meaningful for still-running calls and it returns what the original call would have. It does not explain polling behavior or what happens if the command completes.

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?

Efficient: the operative use case (still-running call) is front-loaded, followed by the required param and a terse list of optional controls. The trailing 'see the server instructions' is a minor deferral but not bloated.

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

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

Covers the core retrieval scenario but leaves gaps: no output schema, no pagination semantics for cursor, no guidance on whether to poll or wait, and it offloads parameter detail to unspecified server instructions. Adequate but visibly incomplete for a result-fetch 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It explains command_id as the way to identify the pending call and briefly names response_detail, fields, and cursor, but gives no value semantics for response_detail or cursor semantics beyond a hint. 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 role: it retrieves the result of a still-running screen_* call by command_id. Distinguishes it as the companion to the async screen_* family, though it doesn't name a specific sibling to reinforce boundaries.

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

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

Provides clear context: use when a prior screen_* call came back still running (awaiting user approval, or screen_record_stop still rendering). This tells the agent when to reach for it, but offers no explicit 'when-not' or direct alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds useful context: what the status reports, the overall recording pipeline, and importantly that 'the user approves in Arsaze before anything is opened' — a meaningful gating detail not in annotations.

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

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

The paragraph is reasonably sized but poorly front-loaded: it opens with a rhetorical question rather than the tool's function, and it spends significant space narrating the entire recording workflow, which is arguably out of scope for a status-check 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 read-only status tool with no output schema and three optional pagination/format parameters, the description supplies return-value semantics, parameter meanings, and workflow position. Nothing essential is missing, though pagination limits are left to server instructions.

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, and it does: 'response_detail (summary|compact|full), fields (dotted paths), cursor (next page).' It documents all three optional parameters, though the enum values for response_detail are only implied and it defers the rest to server instructions.

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 function: reporting whether the Arsaze desktop app is connected, its platform, and whether it can drive native apps versus only web pages. It is distinguishable from siblings like screen_open or screen_look. However, the actual purpose is buried mid-sentence behind a rhetorical question, slightly weakening immediate clarity.

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

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

Explicitly says 'Call first,' establishing this as the entry point before any screen action. It also routes among alternatives (screen_open vs. screen_list_apps + screen_open_app) within the described flow. No explicit when-not-to-use, but the ordering guidance is concrete.

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

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

The description discloses atomicity ('Applied as ONE undoable, all-or-nothing batch') and dry_run behavior, which are not present in the annotations. It also emphasizes the exact-match requirement for `old`. These details add valuable behavioral context beyond the sparse annotations.

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

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

The description is dense but purposeful: every sentence adds operational detail, organized by file type and then by global behavior. It front-loads the core purpose before diving into specifics, with no wasted words.

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

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

The description covers the tool's scope for each supported file type, batch behavior, and a critical prerequisite (fresh ws_read). Given no output schema, it does not detail return values, but it addresses the main decisions an agent needs to invoke the tool correctly. Minor gaps remain around `confirm` and `replace_all`.

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 parameter meaning. It clarifies that `old`/`new` are exact replacement strings and that `dry_run=true` returns operations without applying. However, it does not explain `confirm` or `replace_all`, leaving those parameters ambiguous.

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

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

The description opens with 'Edit the project by editing its files — exact old→new replacement, like editing code,' clearly stating a specific verb and resource. It then enumerates file types and operations, which distinguishes it from read-only siblings like ws_read and ws_grep.

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

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

The description gives a clear prerequisite: 'old must be copied exactly from a fresh ws_read,' linking to the correct read tool. It also explains dry_run for previewing. However, it does not explicitly mention when to use alternatives like run_timeline_batch, so it lacks explicit 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 already establish that the tool is read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral details beyond annotations: it returns path:line:text and explains that context controls the number of surrounding lines shown, capped at 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 dense sentences deliver the core operation, target, output format, and context parameter semantics without wasted words. The essential information is front-loaded.

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

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

With an output schema present and read-only/idempotent annotations, the description covers enough to invoke the tool correctly: required path and pattern, output format, and context semantics. The only meaningful gap is the undocumented ignore_case parameter, whose default is visible in the schema.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. It explains path (file or directory), pattern (regex), and context (lines around each hit, max 5), but omits ignore_case behavior. This is strong compensation, though incomplete.

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 ('Search'), a clear resource ('a workspace file or ... directory'), and the output format ('path:line:text'). This clearly distinguishes ws_grep from sibling tools like ws_read and ws_ls, which read or list rather than search.

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

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

The description gives clear context for when to use the tool: searching files or directories such as job/<job_id>/words with a regex. It does not explicitly name alternatives or exclusion conditions, but the intended usage is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds useful behavioral context beyond annotations by specifying how the path parameter changes the output granularity (whole layout vs. scope-specific files vs. one file per clip/link).

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

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

The description is three sentences, front-loaded with the core action, and every sentence contributes concrete path-scoping information. The parenthetical shorthand is compact and effective, with no redundant or filler content.

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

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

For a read-only list tool with a single optional parameter and an output schema, the description is complete. It explains all documented path patterns and leaves return-value details to the output schema, so nothing essential for invoking 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?

Schema description coverage is 0%, so the description carries the full burden of explaining the 'path' parameter. It does so thoroughly with three illustrative patterns, including the default empty-string behavior, which makes the parameter semantics clear and actionable.

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 'List workspace files,' a specific verb and resource, and then details the exact path patterns that control the listing scope. This clearly distinguishes it from sibling tools like ws_read (reading content) and ws_grep (searching).

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

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

The description provides clear context on how to use the tool through concrete path examples ('' for whole layout, 'job/<job_id>', 'project/<project_id>', 'job/<job_id>/transcript'). It does not explicitly name alternatives or say when not to use this tool, but the operation is clear enough that the intended usage is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral details beyond those: line-numbered output, a ~250-line limit per call, and 1-based inclusive start/end semantics. This is meaningful supplementary information.

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 convey action, output shape, range syntax, line limit, and an efficiency tip without filler. The structure is front-loaded and every phrase 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 low-complexity read tool with a rich output schema and safety annotations, the description covers the essential operational concerns: path examples, line cap, range semantics, and grep-first advice. A minor gap is not stating what happens if a range is omitted or if a file exceeds the line limit without a range.

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 explicitly explains start_line/end_line as a 1-based inclusive range, but the path parameter is only illustrated with examples rather than formally specified. The default behavior when start_line/end_line are omitted is also left implicit.

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

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

The description opens with a specific verb-resource pair, 'Read a workspace file with line numbers,' and reinforces it with concrete path examples. This clearly differentiates ws_read from its write/sibling tools like ws_edit, ws_grep, and ws_ls.

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

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

The description gives practical context: use it for reading specific workspace files, and 'Grep first on long files' explicitly steers agents toward the grep alternative for lengthy content. It does not enumerate exclusions for all siblings, but the read-only intent and line-range usage are clear enough.

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