Layven

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

Annotations already declare readOnlyHint=true, and the description adds context about the content of activity (what/who/when) and the polling use case. It does not contradict annotations, but it doesn't detail pagination or result structure beyond schema hints.

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

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

The description is two sentences, front-loaded with the primary action, and every word adds value. No fluff or redundancy.

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 listing tool with 5 parameters, the description gives the essential behavior and return context (what/who/when), while the schema handles parameter details. It lacks explicit sibling differentiation, but overall it's sufficient for safe and correct use.

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

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

Schema coverage is 100%, so the parameters are fully documented in the schema. The description adds a use case for 'since' but does not add syntax or details for other parameters, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'List recent activity in the workspace' with specific details (what changed, who changed it, when). It is unambiguous but does not explicitly distinguish from sibling 'history', so it doesn't fully earn 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?

The description provides a clear usage pattern: 'Poll with since to see what happened since your last run.' This gives context for when to use the tool, though it does not mention alternatives or exclusions relative to siblings.

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

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

Annotations already indicate destructive and idempotent behavior, but the description adds the non-obvious tombstone/recoverable semantics and resurrection on subsequent writes. This goes beyond the annotations, providing critical safety-relevant behavior that an agent must know before calling delete.

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

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

Two compact sentences with high information density. Every phrase earns its place: what it does, the tombstone side-effect, recoverability via restore, and resurrection behavior. No fluff or repetition.

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

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

For a 4-parameter delete tool with no output schema, the description covers the core behavior and the most important side effects. It omits lock-related nuances and version conflict behavior, but those are already described in the schema. The tombstone and resurrection details make it sufficiently complete for safe invocation.

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

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

Schema description coverage is 100%, so all four parameters (path, workspace, override_lock, expected_version) are documented in the schema. The description adds no parameter-specific meaning, earning the baseline 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 opens with 'Delete a file' – a specific verb and resource. It further distinguishes from siblings by explaining the tombstone behavior, making it clear this is a recoverable delete, not a destructive erase. This clearly separates it from read, write, move, and restore.

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

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

The description implies use when you want to delete a file, and the note about resurrection hints at recovering via rewrite, but it does not explicitly compare to alternatives like move or restore. There is no direct 'use X instead' guidance, making the usage context clear but not deeply differentiated.

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

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

Beyond the annotations (readOnlyHint=false etc.), the description richly discloses behavioral details: exact matching requirements, ordering and atomicity of edits, error behavior (STRING_NOT_FOUND with whitespace hint), file size limit, and versioning/concurrency behavior. This significantly exceeds the minimal annotation information and provides critical operational context.

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 exceptionally concise yet information-dense: four sentences covering purpose, matching semantics, ordering, atomicity, error handling, size limits, and concurrency. Every sentence earns its place with no filler or redundancy, and the core purpose 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?

Despite having no output schema, the description covers all critical aspects for successful invocation: exact match requirements, replace_all usage, ordered/atomic commits, error recovery hints, size limits, and optimistic concurrency. It also references relevant failure modes and provides sufficient context to use the tool correctly without requiring additional documentation.

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?

While the schema provides 100% coverage of parameter definitions, the description adds substantial meaning beyond these structured fields: it clarifies that old_str must match exactly once unless replace_all is set, explains the order and atomicity of multiple edits, and elaborates on expected_version's role in failing on concurrent changes. This adds real value beyond the schema.

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

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

The description clearly identifies the tool's function: 'Edit a text file by exact string replacement.' It specifies a unique verb ('edit') and resource ('text file') and distinguishes it from read/write operations by framing it as a cheaper alternative for small changes, which differentiates it from sibling tools like write.

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 strong context for usage, indicating it is 'cheaper than read + write for small changes' and explains when to use expected_version for concurrency. However, it does not explicitly state when not to use it or mention alternatives beyond read/write, such as for large-scale edits, which would fully clarify selection among siblings.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-idempotent. The description adds useful context about the workflow step (after presigned PUT) and the 1-hour expiry of the upload row, which informs behavior beyond the hints. It does not explicitly state side effects or failure modes, but this is adequate given annotation coverage.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by crucial usage timing and expiry note. 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?

For a two-step workflow, the description explains when to call, the dependency on request_upload, and the expiry constraint. No output schema exists, but the description gives enough context for the agent to understand the operation. Minor omission: it does not state what the tool returns, but this is not critical given the simple commit operation.

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

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

Schema description coverage is 100%, and both parameters ('upload_id' and 'workspace') have clear descriptions in the schema. The tool description adds no extra parameter semantics beyond referencing that 'upload_id' is returned by request_upload, which is already in the schema. Baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Commit a file uploaded via request_upload.' It uses a specific verb ('Commit') and resource ('file uploaded'), and distinguishes itself from siblings by referencing the companion tool 'request_upload.'

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 usage guidance: 'Call this after the presigned PUT succeeds' and warns about the 1-hour expiry. This tells the agent when to invoke it and implies that it should not be called before the PUT succeeds or after expiry, effectively differentiating from alternative tools.

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

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

Beyond the readOnlyHint annotation, the description discloses return format (matching lines with 1-based line numbers and context), that line numbers are display-only and must not be used in edit, that matches are single-line only, and the RE2 syntax limitations. This adds substantial behavioral context not in 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 concise yet information-dense. Each sentence serves a purpose: main action, scoping modes, output format, and tool selection. It is front-loaded with the core purpose and does not waste 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?

With 7 parameters and no output schema, the description covers essential context: return shape, line-number safety, single-line matching, workspace-wide search behavior, and regex syntax. It also addresses the common usage pattern of locating text before reading surrounding context, making it complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the interaction between path and prefix ('Omit both path and prefix... pass prefix... path...'), which is not fully explicit in the schema, and reinforces RE2 constraints. It does not add semantics for max_matches or case_sensitive, but the schema handles those.

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: 'Search file contents with a regular expression'. It clearly distinguishes from siblings by adding 'Use grep to locate exact text; use read to view the surrounding region', and the line-number caveat separates it from edit.

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

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

Explicit scoping instructions are given: omit both path and prefix for whole-workspace search, use prefix for a folder, path for a single file. It also names an alternative tool ('use read') and warns against using line numbers in edit old_str, providing clear when-to-use vs when-not-to 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?

The description adds behavioral detail beyond the readOnlyHint annotation, such as the ordering (newest first) and the inclusion of purged status. It does not disclose error handling or auth requirements, but with annotations covering the read-only nature, the added context is valuable.

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

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

The description is a single, focused sentence that front-loads the verb and resource. It conveys the essential purpose and key return information without any waste or redundancy.

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 tool with a well-documented schema and no output schema, the description is sufficient. It clearly states what the tool does and the key aspects of the result. It lacks mention of pagination behavior or error cases, but these are not critical for selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself does not add detail about the parameters beyond the schema, but the schema already documents all four parameters clearly. No additional meaning is needed.

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 a specific verb ('List') and resource ('a file's version history'), with added specifics ('newest first', 'who wrote each version', 'purged by retention'). This distinguishes it from siblings like 'list' (listing files) and 'read' (reading content).

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 for when to use the tool (when you need a file's version history, including authorship and retention status). However, it does not explicitly mention when not to use it or name alternative tools for related tasks.

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, but the description adds substantial behavioral detail beyond this: non-recursive default, folder synthesis from paths, per-workspace result blocks and next_cursor, and pagination requirements. This is valuable context for an AI agent.

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

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

The description is a single focused paragraph with no redundant content. The first sentence states the core purpose, and subsequent sentences efficiently cover mode changes, multi-workspace behavior, and pagination. Every sentence earns its place.

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

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

With 7 parameters and no output schema, the description covers essential operational details: response structure (result blocks, entries, next_cursor), pagination, workspace behavior, and filter modes. It sufficiently explains the tool's behavior for an agent to use it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining implications of 'q' (implies recursive, case-insensitive full-path substring), 'cursor' requiring explicit workspace, and per-workspace limit semantics, which are not fully captured in the schema.

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

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

The description specifies a clear verb+resource ('List files and folders under a path') and differentiates from siblings by explaining the file-name search mode (q) that distinguishes it from grep, and the path-based listing vs read's content-focused behavior.

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 explicit guidance on using recursive, q, workspace omission, and paging behavior. It doesn't explicitly name alternative tools (e.g., 'use grep for content search'), but the parameter explanations clearly define when to use this tool for listing/name-filtering tasks.

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 provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: 5-minute expiry, renewal on repeated calls, and that locks never block reads. These go beyond the annotations without contradicting them.

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

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

Two sentences convey the core behavior, duration, renewal, and non-blocking nature. It is front-loaded with the verb 'Acquire' and contains 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?

The tool is simple and the description covers all essential aspects: purpose, duration, renewal, and non-blocking behavior. No output schema is needed for a lock operation, and the description is self-sufficient alongside the annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add additional parameter semantics beyond the schema; it merely references 'a path' which is already described in the schema. No extra value is provided.

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 action: 'Acquire an advisory lock on a path for 5 minutes to signal other agents you're editing it.' It specifies the verb, resource, and purpose, and distinguishes itself from sibling 'unlock'.

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

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

It gives clear context on when to use: 'to signal other agents you're editing it.' It also mentions renewal and non-blocking behavior. However, it doesn't explicitly state when not to use it or mention alternatives beyond implicit contrast with 'unlock'.

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 a key behavioral detail: it fails with destination_exists unless overwrite is set. This goes beyond the annotations, which only indicate readOnlyHint false and destructiveHint false. It does not disclose all behaviors (e.g., lock handling, version conflicts), but those are covered by parameter descriptions.

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

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

The description is a single sentence that front-loads the purpose (rename or move) and immediately states a critical failure condition. Every word earns its place, with no filler or redundancy.

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 rich schema and annotations, the description adequately covers the core purpose and a key failure mode. It does not explain return values or side effects like activity logging, but these are not essential given the context. The tool is straightforward and the description is complete enough for an agent to use it effectively.

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 input schema already provides full descriptions for all six parameters, including overwrite, workspace, and override_lock. The description's mention of 'unless overwrite is set' adds no new semantic meaning beyond the schema's parameter documentation. Baseline of 3 is appropriate.

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

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

The description clearly states the tool renames or moves a file to a new path, using a specific verb and resource. It distinguishes itself from sibling tools like delete, edit, and write by focusing on relocation rather than content modification. The failure condition adds further specificity.

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

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

The description implies use for renaming or moving files but does not explicitly compare with alternatives or state when not to use it. There is no mention of when to prefer this tool over write or delete. The usage context is clear but lacks explicit exclusions or alternative 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 the description adds useful behavioral context: large/binary files yield a download URL rather than inline content, and version can target a historical snapshot. It does not fully disclose error handling or URL characteristics, but with annotations present the added context is sufficient.

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

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

The description is two sentences, front-loads the core purpose, and every clause earns its place. It efficiently covers content reading, binary/large-file behavior, and version selection without unnecessary 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 simple 3-parameter schema and no output schema, the description is adequately complete. It explains the main return modes (content vs download URL) and version handling, though it leaves minor details like error cases or URL expiration unaddressed, which are not critical for this tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds slight value by clarifying the version parameter's effect ('read a historical version instead of the current one'), but this mostly restates what the schema already provides ('Version number from history. Defaults to the current version.').

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 reads a file's content or provides a download URL for large/binary files, which is a specific verb+resource purpose. It also distinguishes itself from siblings like list and grep by focusing on content retrieval and explicit download URL handling for large/binary files.

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 contextual guidance on when to use the tool: for reading content and for obtaining download URLs when files are large/binary. It also explains the optional version parameter for reading historical versions, though it does not explicitly name alternative sibling tools.

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

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

Annotations already indicate this is a non-read-only mutation. The description adds important behavioral context: it returns a presigned URL, requires a separate raw-byte upload, and depends on finalize_upload for commit. This goes beyond the annotation's binary safety flags and clearly explains the two-step workflow.

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

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

Two sentences, no filler. Front-loaded with the core action and a clear cap on size, followed by the essential next step. Every word contributes meaning.

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

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

For a 6-parameter mutation tool with no output schema, the description covers the critical flow: how to upload (presigned URL) and how to complete (finalize_upload). It does not mention error cases (e.g., lock conflicts, version mismatches), but those are partially documented in the parameter descriptions. Overall, it gives enough context for an agent to correctly invoke the tool.

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

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

The schema already describes all 6 parameters with 100% coverage, so the baseline is 3. The description adds value by stating the 1 GiB upload limit (clarifying the `size` parameter) and the binary nature (informing `mime_type`), which slightly exceeds the schema's generic 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 clearly states the tool starts a large or binary file upload (up to 1 GiB) and returns a presigned PUT URL. It distinguishes itself by mentioning the follow-up finalize_upload step, and implies a contrast with simpler write operations for small files.

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

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

The description gives clear usage context: use for large/binary files, then call finalize_upload to commit. However, it does not explicitly name alternatives (e.g., 'use write for small files') or state when not to use this tool, 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 indicate this is a non-read-only, non-destructive mutation, but the description adds no extra behavioral context such as whether the restore is recursive, how versions are referenced, or whether current state is overwritten. It offers no value 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 just two sentences, with the two main modes clearly front-loaded. There is no redundant information or 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?

The description covers the two core modes but lacks details on parameter formats, recursive behavior, error handling, or return values. Given no output schema and minimal annotations, it is adequate for a basic understanding but not fully complete for robust invocation.

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

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

Despite the input schema having zero properties, the description introduces and pairs the parameters (path with to_version, prefix with at), which is essential guidance. However, the mismatch between the described parameters and the empty schema could confuse an agent, preventing a perfect score.

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 precisely states the tool restores a single file to a previous version via path+to_version, or a folder to a point in time via prefix+at. This distinguishes it from siblings like delete, write, and edit, and clearly identifies the resource and action.

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 for both usage modes (file vs folder), making it obvious when to use the tool. It does not explicitly mention alternatives or when not to use it, but the intent 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the crucial ownership constraint and clarifies this is an advisory lock, which informs the agent about preconditions and lock 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?

Single sentence that is front-loaded with the action and resource, with no redundant 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?

For a simple two-parameter tool with full annotations and no output schema, the description provides the essential purpose and precondition. It could mention failure behavior, but the provided context is sufficient for selecting and invoking the 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 100%, with detailed descriptions for both path and workspace. The tool description itself adds no parameter-specific meaning beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb ('Release') and identifies the resource ('an advisory lock you own on a path'), clearly distinguishing it from sibling tools like lock (acquire) or delete.

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

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

The description implies usage is for releasing locks the caller owns, but does not explicitly state when to use it versus lock or what to do if the lock is not owned. Context is present but no exclusions or alternative references.

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 include destructiveHint=false, but the description explicitly says 'replace a file' and 'overwrite concurrent changes,' which are destructive behaviors. This is a direct contradiction with the annotation, so the score is 1 despite the useful size and concurrency details.

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

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

Three short sentences front-load the core purpose and then add key usage constraints. No filler, repetition, or unnecessary 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?

The description covers purpose, size threshold, and concurrency behavior, while the 7-parameter schema with per-parameter descriptions handles the remaining details. It differentiates from sibling tools effectively, though it omits return behavior and lock specifics.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: the 1 MiB inline limit and the conditional use of expected_version to produce a VERSION_CONFLICT, while 'replace' reinforces the full-content semantics.

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

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

The description starts with 'Create or replace a file,' a specific verb+resource statement that clearly identifies the tool's function. It distinguishes itself from sibling tools like edit, delete, and request_upload by emphasizing creation/replacement and large-file handling.

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 to use request_upload for content larger than 1 MiB, providing a clear alternative. It also instructs passing expected_version to fail on concurrent changes, giving actionable when-to-use guidance.

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