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

Goes well beyond the destructiveHint=true annotation by disclosing the SHA-256 verification, rejection of ambiguity, and rejection of conflicting edits. This explains failure conditions and safety behavior that 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?

Two sentences, no filler. The core behavior is front-loaded, and the second sentence adds critical rejection conditions without 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?

The description covers invocation and rejection conditions well, but with no output schema it does not state what happens on success (return value, confirmation, or updated content). Also omits edge-case behavior like empty new_text or missing file, leaving some ambiguity for an agent.

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

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

Despite 0% schema description coverage, the description compensates by clarifying semantic roles: old_text must be a unique literal fragment and expected_sha256 is verified before replacement. It does not explicitly map each parameter, but names plus schema patterns make the input understandable.

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 ('Replace exactly one literal fragment'), a resource (UTF-8 file), and a key precondition (SHA-256 check). This clearly distinguishes it from siblings like write_file and read_file.

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 conveys clear context—use this when you need to replace a single, unique literal fragment and verify content integrity first. However, it does not explicitly name alternatives (e.g., write_file) or state 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, idempotentHint, and destructiveHint, so the description does not need to restate those. It adds meaningful behavioral context by specifying the exact metadata fields returned and clarifying that contents are never included. Edge cases such as missing files or directory support are not covered, but the central behavioral boundary is clear.

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

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

The description is a single concise sentence with no filler. It front-loads the key behavior and includes only the information needed to distinguish the tool from content-reading siblings.

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, single-parameter metadata tool with strong annotations, the description adequately covers what is returned and what is not. It falls short of full completeness because it does not explain parameter path semantics or explicitly guide the agent toward read_file for content, but the core calling scenario is sufficiently 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?

The schema has one required `file` string with 0% description coverage, and the tool description does not clarify whether this should be an absolute path, relative path, file name, or whether directories are accepted. The parameter is obvious from its name, but the description adds no semantic value beyond the schema already provides.

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

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

The description clearly identifies the tool's purpose as returning file metadata (type, size, modified time, Unix mode) while explicitly stating it does not return contents. This distinguishes it from siblings like read_file, making the tool's role unambiguous.

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

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

The negative statement 'Does not return contents' implies this tool is for metadata lookups rather than content access, which helps route away from read_file. However, it does not explicitly state when to use file_info over alternatives like list_directory, nor does it name read_file as the sibling for content retrieval.

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

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

Annotations already cover read-only, non-destructive, and idempotent hints, lowering the bar. The description adds value by disclosing that it includes dotfiles and requires absolute paths, and the phrase 'Page through' hints at pagination behavior. This is meaningful context beyond the annotations, though it doesn't mention return format or error behavior.

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, efficient sentence with zero fluff. The core purpose is front-loaded, and each phrase (page through, authorized host, absolute paths, includes dotfiles) earns its place. No redundancy 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?

For a simple read-only listing tool with strong annotations and no output schema, the description covers the essential aspects: pagination, path type, and dotfile inclusion. It does not explain what happens on missing directories or output structure, but those are minor for this complexity level. Siblings are clear enough for an agent to differentiate.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meanings. It does not explicitly explain 'directory', 'limit', or 'offset'. 'Page through' weakly implies limit/offset but provides no syntax or format details. The schema's defaults and ranges are present, but the description adds minimal semantic value for the parameters.

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

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

The description clearly states the action: 'Page through a directory' on the authorized host. It specifies the resource (directory) and includes a key constraint (absolute paths, includes dotfiles). This distinguishes it from siblings like read_file (which reads content) and search_files (which searches), making its purpose unambiguous.

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

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

The description implies usage when listing directory contents but does not explicitly contrast it with alternatives or state when not to use it. Siblings like file_info and read_file are not mentioned, so an agent must infer the appropriate context. There is no guidance on prerequisites or exclusions, leaving usage somewhat implicit.

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

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

Annotations already indicate destructive, non-idempotent, non-readOnly behavior. The description adds valuable nuance: 'may execute instructions or change its state' and 'pipe-based, not a PTY'. This goes beyond the structured annotations.

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

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

Two concise sentences. The main purpose is front-loaded, the operational tip is secondary, and there is no redundant content. 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?

For a tool with no output schema and 0% schema parameter coverage, the description leaves too much unspecified: parameter semantics, the effect of close_stdin, and how output is retrieved (likely via process_read). It is not complete enough for an agent to confidently invoke it correctly.

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

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

Schema description coverage is 0%, and the description provides no explanation of parameters such as text, offset, wait_ms, session_id, or close_stdin. The only implicit hint is that 'input' likely maps to text, but that is not spelled out.

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

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

The description states a specific action, 'Send input to a process', and clarifies its effect, 'may execute instructions or change its state'. This clearly distinguishes it from sibling process tools (process_start, process_read, process_stop, process_list) by focusing on the input-sending function.

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 operational context: recommends 'python3 -u -i' for a persistent Python interpreter and notes that it is pipe-based, not a PTY. It does not enumerate alternatives or exclusions, but the context is sufficient to infer when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not fully burdened. It adds useful behavioral context beyond those annotations: 'Does not reveal command arguments or environment secrets.' This is valuable privacy-relevant information that an agent could not infer from the schema or annotations.

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

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

Two short sentences with no filler. The core action is front-loaded, and the second sentence adds a meaningful privacy guarantee without bloating the description. Every word earns its place.

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

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

For a zero-parameter, read-only list tool, the description covers the essential purpose and a key privacy limitation. There is no output schema, so some details about the returned session representation are absent, but the tool complexity is low and annotations already cover safety. It is largely complete, with only minor room for clarifying what fields a listed session contains.

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 the schema is empty, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, this is adequate; the description's scope note ('sessions created by this bridge') clarifies what the tool operates on but adds no param-specific detail because none 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 ('list') and a clear resource ('sessions created by this bridge'). This distinguishes it from sibling tools like list_directory (files), process_start (creating sessions), and process_stop (stopping sessions), without needing to open 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 makes it clear the tool is for listing sessions, and mentions the scope ('created by this bridge'). However, it gives no explicit guidance about when to prefer this over related process tools (e.g., process_read, process_stop) or what it is not for, leaving usage context implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by revealing that the result includes the true exit code, truncation, timeout, and more-output status, which are not visible in the schema or annotations. This goes beyond what structured data provides.

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

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

One sentence with no filler. The core action is front-loaded, and the appended status details earn their place by describing output semantics an agent needs to interpret the result.

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 tool with four parameters and no output schema, the description covers the essential return statuses and the precondition of an existing session. It does not spell out incremental offset usage or the output body format, but the byte-offset phrasing and status list are sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies offset via 'byte offsets' and indirectly references wait_ms and max_bytes through 'timeout' and 'truncation', but does not explicitly explain wait_ms behavior or the exact role of max_bytes beyond the schema names and defaults.

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

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

Description uses a specific verb ('Read') with a clear resource ('stdout/stderr of a previously started session'), and explains the byte-offset mechanism. This clearly distinguishes it from sibling tools like process_start, process_input, and process_stop, which write to or manage sessions rather than read their output.

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

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

The phrase 'previously started session' establishes the precondition that a session must already exist, and reading stdout/stderr is distinct from the write-oriented process_input. It provides clear context but does not explicitly name alternatives or state when not to use this tool.

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

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

The description goes well beyond annotations by explicitly warning that it can modify/delete files, access the network, and invoke installed tools. It also discloses that there is no command allowlist or hidden approval bypass, and it explains the asynchronous return/polling model. This is strong behavioral disclosure for a destructive, non-idempotent 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?

Every sentence earns its place: purpose, destructive capability, async behavior, and timeout semantics. The description is front-loaded with the action and uses short, direct sentences without redundancy or 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 complex execution tool with no output schema, the description covers the essential contract: session_id is returned immediately, output requires polling, long jobs need timeout_ms=0, and the operation is unrestricted and potentially destructive. It could be more complete by naming process_read/process_stop as the polling and stopping counterparts, but the sibling list supplies that context.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It directly clarifies command execution, target selection ('local Mac or an already authorized SSH alias'), and timeout_ms=0 behavior. However, it does not explain cwd, wait_ms, or shell semantics beyond what the schema names or defaults imply, leaving meaningful 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?

The description opens with a specific action and resource: 'Execute a shell command as the owner on local Mac or an already authorized SSH alias.' It clearly identifies this as a process-starting tool and distinguishes it from siblings like process_read, process_stop, and process_list. The additional safety warning and session_id return make the purpose unmistakable.

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

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

It gives clear context for use: local or already authorized SSH targets, and it explains that output should be polled after a session_id is returned. It also notes timeout_ms=0 for long-running jobs, implying process_stop may be needed later. It does not explicitly name alternatives or state when not to use it, 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 destructiveHint=true, so the destructive nature is known. The description adds value by scoping termination to 'only the specified bridge-owned process group' and disclosing the SSH-specific caveat that remote child shutdown needs independent verification. This goes beyond what annotations provide, giving the agent a clearer picture of side effects.

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 core purpose, and every sentence adds meaningful detail. There is no redundancy or filler, making it efficient and easy to parse.

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

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

For a simple one-parameter destructive tool, the description covers the key behavioral aspects: scope of termination and SSH nuance. It does not discuss error handling or return values, but since there is no output schema and the tool is straightforward, the description is adequately complete for an agent to call it correctly, especially with annotations covering the destructive nature.

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 description does not mention the session_id parameter at all. The schema provides a UUID format and pattern, but the description fails to explain what session_id refers to (e.g., that it identifies the process group to terminate). With 0% schema description coverage, the description should compensate but does not, leaving the agent to infer the parameter's role from context.

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

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

The description clearly states the verb 'Terminate' and the specific resource 'bridge-owned process group', making it unambiguous what the tool does. It also adds a distinct SSH nuance, differentiating it from sibling process tools like process_start, process_read, and process_list, which handle other lifecycle actions.

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 context that for SSH it stops the connection and remote child shutdown needs independent verification, which is useful guidance. However, it does not explicitly state when to use this tool versus alternatives (e.g., process_list for listing or process_input for sending input), nor does it give 'when not to use' exclusions. The usage guidance is implied by the verb but not explicit.

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

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

Annotations already mark the tool as readOnlyHint, idempotentHint, and non-destructive, so the bar is lower. The description adds valuable behavioral context: returned content is untrusted, next_offset must be followed, and full reads include SHA-256 for edits, which is genuinely useful 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?

Three short sentences front-load the core purpose and follow with essential operational details. Every sentence earns its place and there is no 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 paginated file-reading tool with no output schema, the description covers the main operational needs: paging via next_offset, encoding options, trust assumptions, and the edit-related SHA-256 behavior. It is slightly light on explicit parameter coverage, but the schema supplies the missing mechanical details.

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

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

Schema description coverage is 0%, so the description must compensate for missing parameter semantics. It covers encoding explicitly via 'Text or base64', pagination via 'byte pages' and 'next_offset', and the file target via 'explicit local file content'. However, it doesn't explicitly name offset or max_bytes, leaving some parameter behavior to be inferred from context.

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

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

The description uses a specific verb and resource: 'Read explicit local file content in byte pages', which clearly differentiates it from siblings like file_info, list_directory, and read_image. It also clarifies output formats ('Text or base64'), so an agent can select this tool without ambiguity.

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 when to use the tool—for reading explicit local file content with paging—but it never names alternatives or states when not to use it relative to search_files or file_info. The guidance is functional but 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the 4 MiB size cap and that image bytes are returned to the requesting AI. This adds meaningful runtime behavior. It stops short of describing error cases, but annotations already cover the safety profile.

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

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

Three short sentences, each carrying information: the action and formats, the size limit, and the return behavior. Nothing is redundant 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?

For a one-parameter read-only tool with strong annotations and no output schema, this description covers purpose, allowed inputs, size limitations, and return behavior. An agent has enough to invoke it correctly.

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

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

With 0% schema coverage, the description helps by listing accepted image formats and the size limit, but it never explicitly states that 'file' is a path/identifier to a local image file. The parameter name plus format list makes the meaning inferable, but the description does not fully compensate for the missing schema documentation.

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

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

The description names the exact verb ('View'), the resource (image files), and the supported formats (PNG, JPEG, GIF, WebP), and clarifies that the operation is direct rather than via public upload. This clearly differentiates it from siblings like read_file and file_info.

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: use this tool when an AI needs to see image bytes directly without public exposure. It does not explicitly list when-not conditions or name alternatives, but the scope is specific enough to route an agent correctly.

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 destructiveHint. The description adds useful context: it uses ripgrep or a fallback, returns paths/lines and an incomplete flag, and does not interpret regex. This goes beyond the annotations and helps the agent understand output and limitations.

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 concise sentences with the core purpose front-loaded. No filler or redundant information; every sentence adds value.

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 5 parameters and no output schema, the description covers the main behavior and output format (paths/lines and incomplete flag) but leaves parameter semantics and usage context unexplained. It is not complete enough to ensure correct invocation without additional inference.

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

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

Schema description coverage is 0%, and the description does not explain any of the five parameters. It mentions 'file-name or content search' which hints at query and files_only, but glob, limit, and directory are not addressed. The description fails to compensate for the lack of schema 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 states a specific verb (search) and resource (files), and specifies 'bounded literal' which distinguishes it from general search. It clearly differentiates from siblings like list_directory and read_file by focusing on search, not listing or reading.

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

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

The description implies usage for literal searches but does not explicitly mention when not to use it or alternatives. It says 'No regex interpretation' which suggests it's not for regex searches, but it doesn't name other tools or provide exclusion criteria.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by stating 'No credentials' and clarifying that the output reflects the current authorized host and user privileges, which helps set expectations about authorization scope.

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, front-loaded sentence that covers the purpose and a key behavioral constraint. Every word adds value, and there is no redundant restatement of the tool name or schema.

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

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

For a zero-parameter, read-only tool with rich annotations, the description is largely sufficient. 'Resource availability' is slightly vague and no output schema exists, but an agent can still correctly infer what information will be provided and that no credentials are needed.

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

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

The tool has zero parameters, so the description bears no obligation to explain parameters. The empty schema and 100% schema description coverage make this straightforward; the description still clarifies the kind of information returned.

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 resource: current authorized host, user privileges, and resource availability. It distinguishes this from file and process sibling tools by focusing on system environment state, though it does not explicitly name a sibling or use an action verb.

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

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

The description implies usage for checking system/environment context before other operations, but it gives no explicit guidance on when to prefer this tool over siblings. The 'No credentials' note hints at a low-barrier read operation, but no exclusions or alternatives are stated.

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

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

Annotations already mark this as destructive, and the description reinforces that with 'Changes actual files.' It adds non-obvious behaviors beyond annotations: parent directory must exist and a final symlink is not followed. These are exactly the side-effect details an agent needs before invoking a destructive write.

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

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

Three short sentences front-load the core behavior, then add two critical constraints. No filler or redundancy; every sentence contributes a distinct fact needed for correct invocation.

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

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

For a destructive write with no output schema, it covers creation vs replacement, the hash guard, side effects, parent existence, and symlink behavior. The only notable gap is an explicit statement of what happens when the hash does not match (e.g., no write occurs), though that is strongly implied.

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 meaningfully explains expected_sha256 (null creates, a value requires a current-file match) and implies file must be a path whose parent exists. However, it does not elaborate on content or encoding semantics beyond what the schema's type and enum already show.

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

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

The description names a specific action ('Create' or 'replace') on a specific resource (file) with a precise precondition (expected_sha256 null for create, matching SHA-256 for replace). This clearly differentiates it from sibling tools like edit_file by emphasizing its full-file, hash-guarded write semantics.

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 when to use the tool: create when expected_sha256=null and replace only when the current file hash matches. It also gives prerequisites ('Parent must exist') and a symlink caveat. It does not explicitly name alternatives or say 'use edit_file for...', so it falls just short of full usage guidance.

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