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

Annotations already declare destructiveHint/openWorldHint/idempotentHint=false, so the safety profile is covered. The description goes further with non-obvious behavior: no shell interpretation (metacharacters are data), default timeout 120 clamped to [1,1800], and lossy UTF-8 decoding to U+FFFD. It does not describe output shape, but an output schema exists.

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?

Telegraphic but zero-waste: the core contract is front-loaded in the first clause, then alternatives, then timeout semantics, then an edge case. Every sentence carries information.

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

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

With an output schema present, return values need not be explained, and the description covers invocation semantics, alternatives, timeout behavior, and encoding edge cases. Only blocking/streaming behavior is left implicit, a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real meaning beyond the schema by stating that argv is passed verbatim with metacharacters as data and reiterating the timeout default/clamp, which clarifies the semantic contract of the required parameter.

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

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

States the specific operation (run argv to exit, no shell) and its defining property (metacharacters are data), which instantly separates it from exec_shell. The sibling routing names make the distinction explicit rather than inferred.

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

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

Gives explicit when-not and alternatives: shell syntax goes to exec_shell, long-running or interactive goes to exec_start. Both branches an agent could misroute are closed off.

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 and idempotentHint, so the bar is lower, yet the description adds real value: it spells out the idempotent repeat-call contract (ok, already_closed=true) and the cross-request persistence trait of sessions. It does not mention permissions or error conditions beyond that.

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

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

Three tight sentences, front-loaded with the action and followed by the constraints. Every clause carries information an agent needs; 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 one-parameter lifecycle tool with an output schema and full annotations, the description covers the key behavioral facts (idempotency contract, session persistence). The only gap is routing relative to exec_kill, which is minor given the output schema handles return 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?

With a single parameter and 100% schema description coverage ('Positive id from exec_start'), the schema already carries the semantics. The description adds nothing about session_id, so the 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?

States a concrete multi-step operation ('kill if running, join threads, free the session') on a specific resource, which is far more informative than the title alone. It does not explicitly differentiate itself from the sibling exec_kill, which appears to overlap on the 'kill' 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?

'Close every session you start' gives a clear standing directive for when to call it, and 'sessions persist across requests' explains why closure matters. It stops short of naming exec_kill or exec_list as alternatives or stating when NOT to close.

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' destructiveHint, it discloses platform-specific kill semantics (process group SIGKILL vs. Windows job object), that calling on an already-dead session is harmless, and that output remains pollable afterwards. These are behavioral facts the structured fields do not carry.

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

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

Three short sentences, front-loaded with the core action, then safety, then cleanup routing. No filler or repetition.

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

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

Output schema exists, so return values need not be explained; the description still notes output stays pollable and points to exec_close for cleanup. For a one-parameter destructive tool this covers everything an agent needs before invoking it.

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 the single session_id parameter is documented as a positive id from exec_start. The description adds no further parameter detail, so the 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?

States a specific verb (kill) and resource (the session's process tree), with the exact mechanism per platform (POSIX SIGKILL to the process group; Windows job object). It also implicitly separates itself from the sibling exec_close by assigning cleanup of resources to that tool.

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

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

Gives clear operating context ("Safe on a dead session") and names the companion tool for freeing resources (exec_close), which routes the agent reasonably well. It stops short of an explicit when-to-use-this-vs-alternatives statement, e.g. kill vs. close vs. wait ordering.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the recovery use case but its field enumeration largely duplicates the existing output schema, and it says nothing about session lifetime, ordering, or limits.

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 terse clauses, front-loaded with the verb and resource, with no wasted prose. The only minor redundancy is re-listing fields that the output schema already defines.

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 the return values need not be explained, annotations carry the safety profile, and there are no parameters, so the description is nearly complete. The remaining gap is minimal: no mention of empty-result or error behavior for a session list.

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

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

The tool takes no parameters and schema coverage is 100%, so the required baseline is 4. 'No arguments' correctly confirms the empty-input contract and there is nothing further for the description to disambiguate.

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

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

States a specific verb and resource ('List live sessions') and enumerates the returned fields (session_id, pid, argv, done, exit_code, timestamps), which clearly separates it from the action-oriented siblings like exec_poll, exec_wait, and exec_kill. It stops short of naming an alternative sibling, so it is clear but not explicitly differentiated.

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?

'Recovers ids after a lost reply' gives a concrete when-to-use scenario, which is the key selection cue for a listing tool. It does not state exclusions or name named alternatives, so it is clear context rather than full 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 cover the safe read-only, idempotent profile, and the description is consistent with them (offset-based resume supports idempotency). It adds behavior the annotations cannot convey: that output is delivered as deltas from byte offsets, that truncation flags exist, and that offsets must be carried forward between calls.

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

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

Two dense sentences with zero filler; the read/delta semantics come first and the resumption instruction second, which matches how an agent needs the information.

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

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

An output schema exists, so return-value explanation is not required, and the description plus schema cover the polling loop adequately. The only gap is the missing routing decision against exec_wait, which is more a usage-guidelines issue than a completeness one.

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%: each parameter is documented, including offset defaults and origin from previous polls. The description reinforces the resume pattern but adds no syntax, format, or edge-case detail (e.g. behavior when offsets are stale or beyond the current buffer) 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?

States a specific verb and resource ('Read new session output from byte offsets') and enumerates the payload contents (stdout/stderr deltas, done, exit_code, truncation flags), which an agent can distinguish from write/kill siblings. The relationship to exec_wait is only hinted at via 'Same payload as exec_wait', so it stops short of a clear sibling differentiation.

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?

'Pass back the offsets from the previous reply to resume' gives real procedural guidance for repeated polling, but the description never states when to choose this over exec_wait (the obvious alternative in the sibling list) or when polling is unnecessary. Usage is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds real behavior beyond that: the timeout is defaulted at 120s and clamped to [1, 1800], and invalid UTF-8 in stdout/stderr is silently converted to U+FFFD — a data-mangling detail an agent could not learn elsewhere.

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

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

Three dense sentences, front-loaded with the verb and routing rule before the mechanics. No filler; the telegraphic fragments (timeout semantics, encoding note) each carry distinct, actionable information.

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

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

An output schema exists, so return values need no explanation, and annotations carry the destructive/open-world safety signal. Combined with shell selection, timeout bounds, cwd inheritance (via schema), and encoding behavior, nothing an agent needs to invoke this 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 100%, so the schema already documents all four parameters including shell defaults and the timeout range. The description largely restates those values; its only marginal addition is showing how the script string is handed to the shell (-c / /c), which is the baseline 3 case when the schema does the heavy lifting.

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 precise verb and resource ('Run one script through one shell') and immediately pins down the mechanism per platform (POSIX -c vs Windows /c / -c). It also names the sibling it is not for the non-shell case ('otherwise exec'), so an agent can route between exec_shell and exec without opening either schema.

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

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

Explicitly scopes usage to shell syntax (pipes, redirects, &&, globs) and names the alternative tool 'exec' for everything else — a genuine when/when-not pair. It does not, however, address the exec_start/exec_poll/exec_wait background family, so the agent must still infer whether long-running or interactive work belongs here.

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

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

Annotations declare readOnly=false, destructive=true, openWorld=true, idempotent=false, and the description adds behavior those annotations don't carry: asynchronous return of session_id, persistence across requests, and TTL-based reaping of finished sessions. It doesn't explain the destructive implications of spawning a process or any resource limits, which keeps it short of a 5.

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

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

Front-loaded with the core action and return value, then conditions, then lifecycle siblings, then persistence semantics. It is dense and telegraphic but essentially waste-free; the sibling enumeration sentence is the only part that reads as a list rather than prose.

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?

An output schema exists, so return shape needn't be restated, and the description still covers the async contract, session lifetime, and next-step tools. The one gap is the meaning of the destructive annotation for a process-spawning tool, but otherwise an agent has what it needs.

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 only two params, so the schema already documents 'cwd' (inheritance behavior) and 'argv' (verbatim passthrough with example). The description adds only indirect context via the stdin reference, so the 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?

States a specific verb and resource ('Start a process as a session') plus the immediate return ('returns session_id at once'). Together with the usage condition ('when it outlives the call'), an agent can distinguish this from the synchronous sibling 'exec' and from 'exec_shell' without opening any schema.

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

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

Explicit selection criteria: use when the process outlives the call, streams output, or reads stdin, with the stdin counterpart named (exec_write). It also routes the follow-up lifecycle through exec_poll, exec_wait, exec_kill, exec_close, so the agent knows both when to enter and how to proceed.

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 readOnly, idempotent, and non-destructive traits, so the description adds real value by disclosing blocking semantics, timeout bounds, and that the response is an exec_poll payload containing deltas relative to the supplied offsets. It does not describe behavior on session-not-found or timeout expiry, but the core blocking behavior is well conveyed.

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

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

Two sentences, zero waste, with the blocking contract and timeout bounds front-loaded and the return shape following. Nothing redundant or padded.

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

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

With an output schema present, the description need not detail return values, and it correctly focuses on blocking behavior and timing. The only omission is guidance on which sibling to choose for non-blocking reads, a minor gap for a well-annotated read 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%, so all four parameters are already documented in the schema, including defaults and ranges. The description adds only a mild framing benefit by explaining that offsets produce deltas rather than absolute output, so the 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?

States a specific verb and resource: blocks until the session exits or the timeout elapses, and frames the return as the exec_poll payload with offset deltas. This clearly separates it from siblings like exec_poll, though the contrast is implied rather than stated.

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

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

The blocking-versus-timeout framing implies when to use it (wait for completion), and referencing exec_poll's payload hints at the relationship to the polling sibling. However, it never says when to prefer exec_poll, exec_kill, or exec_close instead, leaving the exclusion to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description adds the eof side effect (closing stdin) and the interactive-program scope, but says nothing about blocking behavior when the stdin buffer is full or what happens if the session has already exited.

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, front-loaded with the action and immediately followed by the scoping condition. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the description covers purpose, target session type, and the eof side effect. It leaves a few operational gaps (buffer-full/blocking behavior, session-state requirements) that an agent might want to know.

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 all three parameters are documented there, including eof semantics and data_b64 format. The description restates the eof behavior but adds no encoding, size-limit, or session-state detail 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?

States a specific verb and resource ('Write bytes to session stdin') with a precise target ('session stdin'), and immediately ties the tool to sessions created by exec_start, distinguishing it from the sibling write_file which writes to 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 clause 'For interactive programs started by exec_start' gives clear context for when this tool applies, but it does not name an alternative or state when-not to use it (e.g., use exec_shell for one-shot commands).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes further by disclosing the 2000-entry cap and the truncation=true signal. That is a genuinely useful operational trait not present in annotations, though permission or path-error behavior is not addressed.

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

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

A single dense sentence that front-loads the action and packs output format, field list, and the truncation cap with zero filler. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, yet the description helpfully summarizes them plus the truncation flag. It is nearly complete for a one-parameter read; only error handling for invalid paths is unaddressed.

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

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

Schema description coverage is 100% and the single parameter already documents the '~' expansion and default working directory, so the schema does the heavy lifting. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List directory entries') plus the sort order, and describes the exact fields returned (name, type codes, size, mtime). This clearly separates it from siblings like read_file and the exec_* family without needing to read 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?

Usage is implied by the verb and resource, but there is no explicit guidance on when to prefer this over read_file or exec_list, and no mention of error conditions such as a missing path. The agent can infer intent but is given no routing help.

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, idempotent, non-destructive. Description adds encoding handling, size limit (64 MiB rejection), and offset/limit semantics—useful beyond 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?

Single efficient sentence, front-loaded with core operation and key constraints. 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?

Given annotations and output schema, description covers necessary behavioral details like encoding and character-based offset/limit. No major gaps for calling 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 parameters are already documented. Description adds that offset/limit count characters not bytes, and the default limit, but mostly repeats schema info.

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

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

States a specific verb (Read) and resource (text file) with the encoding and behavior (UTF-8, invalid bytes replaced). Clearly distinct from siblings like write_file and list_dir.

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

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

No explicit when-to-use or alternatives mentioned. Implied read usage, but no guidance on choosing over exec or other file operations.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful context beyond that: it is argument-free and the natural probe for verifying host reachability, and it surfaces the disk unit (bytes) that callers would otherwise have to infer.

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 dense sentence with the resource up front, the returned fields in the middle, and the primary use case last. Every clause earns its place; nothing is padded or repeated.

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 parameterless, read-only diagnostic tool with an output schema already present, the description supplies everything an agent needs: what it returns, that it takes no input, and the primary reason to call it. Nothing material is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description does not invent parameter guidance, and 'no arguments' correctly signals that invocation needs no inputs.

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 resource and enumerates exactly what the summary contains (hostname, OS, load, memory, root disk with units, uptime). It is trivially distinguishable from siblings like exec or read_file, which perform actions or fetch file contents rather than reporting host state.

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

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

Gives a concrete use case — 'use as a connectivity check' — and notes no arguments are needed, so an agent knows when to reach for it. It does not name an alternative tool or state when not to use it, which keeps it 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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description earns credit by elaborating the actual destructive mechanic (overwrites existing files) and the mkdirs-by-default behavior, plus what the response contains, though it omits permission requirements and symlink handling.

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 zero filler. The destructive write semantics are front-loaded in the first clause, and the return-value note is deferred to the end where it belongs.

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?

An output schema exists, so the tool needn't document return values in depth, and the description still notes size and sha256. Annotations cover the safety profile. The only real gap is the missing guidance on when to prefer exec_write over write_file.

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 (mode, path, mkdirs, content_b64) are already documented in the schema. The description reinforces base64 content and the parent-dir default but adds no format, encoding, or edge-case detail beyond what the schema provides, making the baseline 3 correct.

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 pairs a specific verb with a specific resource ("Write base64 content to a file") and discloses two consequential behaviors: overwriting and automatic parent-dir creation. It is clearly distinguishable from read_file/list_dir, but it does not explicitly differentiate itself from the sibling exec_write, which an agent could reasonably confuse it with.

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

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

There is no statement of when to use this tool versus alternatives. With both write_file and exec_write in the sibling list, the absence of any routing guidance or preconditions (e.g., requires an existing/local filesystem context) leaves selection to guesswork.

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