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 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?

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.