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

No annotations are provided, so the description bears the full burden. 'Ensure' weakly implies idempotency, but the description never states whether it creates a directory that already exists, whether it mutates remote state, whether it needs auth/SSH access, or what a failure means. For a state-mutating setup tool this is a significant gap.

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 front-loaded sentence with no filler; the core action leads. It is efficient, though the terseness borders on under-specification for a mutating tool.

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

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

A mutating 'ensure/register' tool with no annotations, no output schema, and 0% parameter coverage should disclose far more: side effects, permission/connection requirements, and return/failure behavior. The one-line description is inadequate for the 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 0% for both parameters. The description mentions 'local project' and 'remote project directory', which loosely hints that local_root is a path and server_alias selects a target, but it adds no format, path style, or meaning for server_alias (default 'default') 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 states a specific verb and resource: register a local project and ensure its remote directory exists. It is clear what the tool does, though it does not distinguish itself from nearby siblings like project_sync or project_status, whose boundaries an agent must otherwise infer.

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 such as project_status or project_sync, and no prerequisites (e.g. that a server connection must exist). The 'ensure' framing implies first-time setup but this is left to inference.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the important trait that nothing is uploaded, but does not state whether the tool is read-only, whether it modifies local state, what permissions are needed, or what the response contains.

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 with no wasted words. Its extreme brevity is a structural strength, though it contributes to the information gaps captured elsewhere.

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 no annotations, the description is too thin: it omits usage guidance, parameter meaning, return format, and the full read-only safety profile. It provides only the 'no upload' constraint.

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 single required parameter project_id is undocumented in the schema. The description does not mention the parameter at all, though its name is fairly self-explanatory, leaving little added meaning 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 states two actions — plan synchronization and report remote changes — and adds the distinguishing constraint 'without uploading.' It is more specific than a tautology, but does not explicitly name the sibling project_sync as the upload alternative.

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 'without uploading' implies a dry-run use case, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many remote_* siblings. An agent must infer the context.

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?

No annotations are provided, so the description carries the full behavioral burden and falls short. It implies a read ("Return") but never states that explicitly, nor does it describe what gets returned, whether a missing/unregistered project_id errors or returns empty, or any auth or network requirement.

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 short sentence with no filler, and the purpose is front-loaded. However, brevity here is under-specification rather than economy: the sentence is too thin to be useful for a lookup tool.

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

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

With no annotations, no output schema, no param documentation, and an undefined "mapping," an agent has no way to know what it will receive or what state it will change. For a one-parameter lookup whose return value is the entire point, the description is materially incomplete.

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 the single project_id parameter and does not — no format, no source (local versus remote registration), no statement that it must reference an already-registered project. One trivially-named parameter keeps this above a 1, but the description adds no meaning beyond the key name.

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?

It has a verb and a resource ("Return the registered project mapping"), but "mapping" is undefined jargon and the description never distinguishes this from siblings like project_ensure, project_sync, or project_list_remote_changes. An agent cannot tell from the text alone whether this resolves local-to-remote project identity or merely echoes a stored record.

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 when-to-use, when-not-to-use, or alternative routing in the description. With seven project_* siblings, some criterion for choosing project_status over project_ensure or project_list_remote_changes is essential and entirely absent.

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?

No annotations are provided, so the description carries the full behavioral burden. It mentions incremental uploading and preserving conflicts, but omits whether synchronization is destructive, what permissions are required, how conflicts are represented, or whether the operation is idempotent.

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 with no wasted words. It is structurally clean, though its brevity contributes to the ambiguity around conflict handling.

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 a write-like sync tool with no annotations and no output schema, the description is too thin. It does not explain the sync direction, conflict semantics, prerequisite setup, or what an agent should expect after 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?

The schema has one required parameter, project_id, with 0% description coverage, and the description does not mention it at all. With low coverage, the description should compensate, but it adds no meaning beyond the schema's type and required status.

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

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

The description states a specific verb and resource: 'incrementally upload project changes.' It also adds the constraint 'preserving conflicts,' which clarifies the intended behavior, though it does not distinguish this tool from siblings like ssh_upload or remote_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?

There is no guidance on when to use project_sync versus alternatives such as project_list_remote_changes, ssh_upload, or remote_upload. The description implies a sync context but offers no explicit usage conditions or exclusions.

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

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

With no annotations the description carries the full burden, and it does disclose a genuinely important trait: edits are applied conditionally, gated on the expected revision hash and match counts (optimistic-concurrency / exact-match semantics). However, it omits what happens on mismatch (rejected or partial?), any permission requirements, and reversibility, so it falls short of full disclosure for a mutation 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?

A single front-loaded sentence with no padding or repetition, and the precondition is stated directly. It is efficient, though its brevity here signals under-specification rather than disciplined economy.

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 hash-guarded patch tool with a nested edit list, no annotations, no output schema, and 0% schema coverage, one sentence is far too thin. An agent cannot learn the failure/mismatch behavior, the semantics of expected_count, or what a successful application returns.

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 there are four required parameters including a nested edits array, so the description should compensate. It only obliquely implies 'remote revision' maps to expected_sha256 and 'match counts' to expected_count, leaving project_id, relative_path, old_text/new_text untouched and no format or matching rules explained.

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 ('Apply') and resource ('text edits') scoped to a remote target, which is enough to place it against the read-only siblings (remote_read, remote_stat, remote_list). It does not explicitly name a sibling or contrast itself with remote_upload/remote_download, but the patch-application purpose is 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?

There is no when-to-use guidance and no alternatives named. The clause 'only when the remote revision and match counts agree' is a precondition, not usage direction, and it never explains when to choose this over remote_upload or remote_execute for changing remote content.

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?

No annotations are provided, so the description carries the full behavioral burden and largely fails to. It does not say whether an existing local file is overwritten, whether the download is resumable, what permissions or connectivity are required, or what the call returns. Only the destination scope ('registered local project') is disclosed.

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 clean sentence with no padding, and the action is front-loaded. But the brevity comes at the cost of omission rather than efficiency; a single clause cannot cover destination-path behavior or overwrite semantics for a 3-parameter write tool.

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

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

With no annotations, no output schema, 0% schema coverage, and no sibling differentiation, the description is too thin for a tool that writes to the local filesystem. An agent would have to open the schema and guess at overwrite, path-defaulting, and return behavior.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and does not. 'remote file' loosely maps to remote_relative_path and 'local project' to project_id, but the optional local_relative_path — which clearly controls where the file lands and defaults to null — is never addressed, leaving its defaulting behavior unexplained.

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

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

States a specific verb (Download) and resource (a remote file) plus the destination (the registered local project), so the core action is unambiguous. However it does nothing to distinguish itself from the near-identical sibling ssh_download, leaving the agent to guess which download tool applies.

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 when-to-use guidance, no prerequisites, and no mention of alternatives despite ssh_download, remote_read, and remote_stat sitting right next to it in the toolset. The only hint is the phrase 'registered local project', which weakly implies a project must exist first.

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

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

With no annotations, the description carries the full behavioral burden. It mentions a 'command policy' constraint, which is a small useful hint that execution may be filtered, but it omits side effects, permission/auth requirements, blocking/timeout behavior (the timeout_seconds param implies blocking), and what is returned.

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?

It is a single clean, front-loaded sentence with no filler or redundancy. Its brevity is appropriate in form even though the content is thin.

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

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

For an execution tool with no annotations, no output schema, and 6 undocumented parameters, the description is far too sparse to let an agent call it safely. Nothing about side effects, return values, or parameter meaning is covered.

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

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

Schema description coverage is 0% across 6 parameters, so the description is the only place semantics could be supplied, and it fails to name or explain any of them. 'Program arguments' loosely gestures at program and args, but project_id, environment, relative_cwd, and timeout_seconds are entirely undocumented.

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 gives a verb ('Execute') and a resource ('structured program arguments under the remote project'), so the general purpose is discernible. However, 'structured program arguments' is jargon, and the description does nothing to separate this from the near-identical sibling ssh_execute, so an agent cannot tell the two apart from the text alone.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as ssh_execute, remote_apply_patch, or slurm_submit. The phrase 'under the remote project and command policy' hints at scoping but stops short of any when-to-use or when-not-to-use condition.

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?

With no annotations provided, the description carries the full behavioral burden and falls short. It never states that this is a non-destructive read, whether the path must exist, how errors or missing directories are reported, or whether results are paginated or recursive.

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 lean sentence with the operation front-loaded and no filler. Its brevity is a virtue structurally, even though the content is under-specified.

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

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

With no annotations, no output schema, and zero parameter documentation, the description needs to do considerably more work than one sentence. An agent lacks the return shape, the meaning of both parameters, and the relationship to the 'registered remote project' prerequisite.

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

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

Schema description coverage is 0%, so the description must compensate, and it does not. It never explains what project_id refers to or how a project is registered, nor does it clarify that relative_path defaults to '.' and is resolved against the project root.

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 (List) with a specific resource (a directory) and scopes it to a registered remote project, so the operation itself is unambiguous. However, it does nothing to distinguish this from siblings like remote_stat, remote_search, or remote_read, which an agent must choose between.

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 guidance on when to use remote_list versus remote_stat, remote_search, or remote_read, nor any stated prerequisites (e.g., a project must already be registered via project_ensure). The agent is left to infer the usage context entirely from the name.

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?

With no annotations, the description carries the full disclosure burden. It does add two real behavioral facts — reads are 'bounded' (implying truncation via limit/offset) and a SHA-256 revision is surfaced for optimistic concurrency — but omits error behavior for non-UTF-8 or missing paths, permission requirements, and whether the revision is usable in remote_apply_patch.

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 front-loaded sentence with zero filler; the resource and the revision behavior are stated immediately. Nothing is repeated from the name or title.

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 tool with fully undescribed parameters, no annotations, and no output schema, the description is too thin. It should at minimum define offset/limit semantics, clarify the return shape (text plus revision), and state how the revision feeds the editing tools.

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

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

Schema description coverage is 0% across 4 parameters, and the description never names or explains limit, offset, project_id, or relative_path. 'Bounded' is the only faint gesture toward limit/offset, leaving the two undocumented non-obvious parameters to guesswork.

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 verb and resource ('Read bounded UTF-8 text') plus a distinguishing characteristic (returned SHA-256 revision for optimistic editing). It never names or contrasts with the adjacent siblings (remote_stat, remote_list, remote_search), so an agent must infer which read tool applies.

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 when-to-use, when-not-to-use, or alternative routing is given. 'For optimistic editing' hints at the intended workflow but does not say when to prefer this over remote_stat or remote_search, nor what prerequisites exist.

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?

With no annotations, the description must carry the full behavioral burden. It adds that matching is literal and results are bounded, but it does not say whether the operation is read-only, what the default bound is, whether pagination exists, or what permissions are needed.

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 definition is a single front-loaded sentence with no wasted words. It could be slightly more precise about what 'bounded' means, but it is compact and easy to scan.

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

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

For a 4-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. It omits return format, pagination behavior, path semantics, and safety profile, leaving important operational details unspecified.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does. 'Literal text' maps to pattern, 'remote project' maps to project_id, and 'bounded results' maps to max_matches, but relative_path is never mentioned and matching semantics such as case sensitivity remain unspecified.

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 clear verb and resource: 'Search for literal text inside the remote project.' It distinguishes searching from reading a whole file or listing paths, though it does not explicitly name or contrast with siblings such as remote_read or remote_list.

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

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

There is no explicit guidance on when to use this tool versus remote_read, remote_list, or remote_stat. The phrase 'literal text' and 'bounded results' hints at scope, but no alternatives or exclusion conditions are given.

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?

With no annotations, the description carries the full behavioral burden and falls short. It does not say whether the call fails on a missing path, whether it follows symlinks, whether it requires a live connection, or what 'metadata' comprises (size, mtime, type?). Only the read-only nature is weakly implied.

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 tight sentence with the key scoping qualifier ('project-relative') front-loaded. No filler, nothing redundant.

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

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

No output schema, no annotations, and 0% parameter coverage leave too much unsaid. An agent cannot know what metadata fields come back or how failures present, which matters for a stat-style tool whose entire value is its return payload.

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% for both parameters, so the description must compensate and largely does not. It clarifies that relative_path is relative to a project, which is useful, but never explains project_id or any path format/error 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?

States a specific verb ('Return') and resource ('metadata for a project-relative remote path'), so the agent knows this is a stat/metadata lookup. However, it does nothing to distinguish itself from siblings like remote_list, remote_read, or remote_search, which all operate on the same remote namespace.

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 guidance on when to use this versus remote_list/remote_read/remote_search, nor any stated prerequisites such as requiring an established project connection. The only implied usage is 'you want metadata', which the agent must infer entirely.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the path-confinement constraint (a useful security trait), but says nothing about whether an existing remote file is overwritten, what permissions/auth are required, or what happens when remote_relative_path is omitted.

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 front-loaded sentence with no filler; the scoping constraint is stated up front. It is efficient, though the brevity borders on under-specification rather than tight conciseness.

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 3-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, this one-liner leaves too much unstated: default behavior of the optional remote path, overwrite semantics, and required auth are all missing.

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

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

Schema description coverage is 0%, so the description must compensate and largely does not. It implies path-like inputs and project scoping but never explains what project_id, local_relative_path, or the optional remote_relative_path (default null) mean or how the null default is resolved.

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 (upload) and resource (a file), plus the scoping constraint that both paths are confined to registered project roots. It does not, however, distinguish itself from the sibling ssh_upload, so an agent cannot tell which to pick from purpose alone.

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 when-to-use guidance is given. With ssh_upload and remote_apply_patch as siblings, the description never says when this tool is the right choice versus those alternatives, nor any prerequisites for the project being registered.

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?

No annotations are provided, so the description carries the full burden, and it does disclose the key behavioral trait: no connection is established, implying a local/offline read that needs no auth and is safe. It stops short of describing return format, ordering, or behavior when no servers are configured.

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 front-loaded sentence with no filler; the resource is stated first and the distinguishing constraint ('without connecting') closes it. 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?

For a zero-parameter, side-effect-free list tool with no output schema and no annotations, the description names both what is enumerated and the key execution constraint. It is nearly complete, missing only minor detail such as output ordering or the empty-list case.

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 takes zero parameters, which is the baseline-4 case; there are no arguments whose semantics need explaining. The description adds nothing here because nothing needs adding.

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 (List) and resource (configured SSH aliases and public endpoint information), which an agent can distinguish from file-oriented siblings like remote_list or remote_search. It implicitly separates itself from server_test_connection via 'without connecting', though it does not name that sibling explicitly.

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 only implied: 'without connecting' suggests this is the cheap, offline way to enumerate server definitions before deciding to test one. There is no explicit when-to-use statement or reference to the natural alternative (server_test_connection) for validating connectivity.

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?

With no annotations, the description carries the full burden, and it does disclose that the tool probes both SSH reachability and Slurm command availability, implying a read-only, non-mutating diagnostic. However, it says nothing about timeouts, failure behavior, or whether credentials/config are required, which matters for a connectivity test.

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 front-loaded sentence with zero filler that covers both checks. Nothing is 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?

For a one-parameter diagnostic with no output schema and no annotations, the description is only minimally sufficient. It omits what the check returns (e.g., which component failed) and how the caller should react to a failure, which an agent must know without a return schema.

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

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

Schema description coverage is 0% and the single parameter 'server_alias' (default 'default') is never mentioned in the description. The phrase 'configured SSH connectivity' hints at named configured servers but does not explain what a server alias is or how the default resolves.

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 ('Check') and two concrete resources ('SSH connectivity', 'Slurm command availability'), which tells an agent this is a diagnostic rather than an execution tool. It does not explicitly name alternatives such as ssh_execute or slurm_submit, so sibling differentiation is left implicit.

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 call this versus the many sibling tools (ssh_execute, slurm_submit, server_list). The diagnostic intent is inferable from the verb 'Check', but no context or exclusions are provided.

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?

No annotations, so the description carries the full burden. It helpfully discloses that data comes from both queue and accounting records (implying running and historical jobs), but says nothing about permissions, behavior for unknown job_ids, or whether job_id must be live or completed.

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 front-loaded sentence with no waste. It is efficient, though the brevity is partly why other dimensions are underserved.

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

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

No output schema and no annotations, so the description should do more. It does hint at the return sources (queue and accounting records), which is genuinely useful, but it omits identifier format and error/precondition behavior needed to call the tool correctly.

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

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

Schema description coverage is 0% for the single job_id param, so the description must compensate and does not: it never states the identifier format (numeric Slurm ID vs. name/string) or whether it must reference a currently active job. Only the implied 'one job' scope gives any meaning.

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

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

States a specific verb ('Inspect') and resource ('one registered job'), which cleanly distinguishes it from the list-oriented siblings like slurm_list_jobs and slurm_watch_job. 'Registered job' is slightly vague about whether registration is a distinct state, but the intent is clear.

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 guidance on when to call this versus slurm_list_jobs, slurm_watch_job, or slurm_read_log. The agent must infer from the name alone that this is the single-job detail lookup, with no stated preconditions or alternatives.

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?

With no annotations, the description carries the full behavioral burden and largely fails: it does not say whether the job must still be running, what "bounded" means (size/count caps), whether listing is read-only and safe, or what happens on an unknown job_id. Only the output-directory scope is disclosed.

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 tight sentence with the resource and scope front-loaded and no filler. It is arguably too terse for the information an agent needs, but it is not padded or repetitive.

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 annotations, no output schema, and an undocumented parameter, the description leaves too much open: return shape (file list? paths? sizes?), ordering, truncation behavior, and error conditions are all unspecified.

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

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

Schema coverage is 0% and the single job_id parameter has no description, so the description must compensate. "A registered job's" hints the ID must come from a prior submit/ensure call, but format, source, and validity expectations are not stated.

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 gives a specific verb ("List") and resource ("artifacts") scoped to a registered job's project output directory, which distinguishes it from log-oriented siblings like slurm_read_log. However, it never names or contrasts any sibling, and "bounded artifacts" is undefined jargon.

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 when-to-use guidance, no prerequisite (e.g. whether the job must be in a terminal state), and no mention of alternatives such as slurm_get_job or slurm_read_log. The only implicit cue is that a job_id is required.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It does not say what 'locally registered' means, whether results are paginated, filtered, or what state jobs are in when listed. The single scope word 'only' is the only behavioral content.

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 short clause, front-loaded, with no filler or redundancy. It is efficient, though its brevity borders on under-specification rather than genuine tightness.

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

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

With no parameters, no output schema, and no annotations, the description is the agent's only source of information about this tool. It omits what is returned, how 'locally registered' is determined, and how the result differs from other job-related siblings, leaving the agent unable to call it with confidence.

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 and the schema is trivially complete at 100% coverage, so there are no parameter semantics to convey. Per the rubric, a 0-parameter tool has a baseline of 4.

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?

It states a resource (jobs) and a scope qualifier ('locally registered ... only'), which separates it from remote-oriented siblings. However, the verb 'Inspect' is vague and even conflicts with the tool name's 'list', and it does not distinguish itself from close siblings like slurm_get_job, slurm_watch_job, or slurm_list_artifacts.

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 word 'only' implies a boundary (local jobs, not remote/unregistered ones), but there is no explicit when-to-use or when-to-prefer-an-alternative guidance. An agent has no signal for choosing this over slurm_get_job or the remote_* listing 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?

No annotations exist, so the description carries the full burden. It does disclose the single most important behavioral trait — that no job is submitted, i.e. no remote side effects — but says nothing about whether a remote connection is required, whether the script must exist, or what the preview returns.

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 front-loaded sentence with no filler or redundancy. It is efficient, though its brevity reflects under-specification rather than maximal information density.

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

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

With no output schema, no annotations, and 0% parameter coverage, the description should explain what a preview actually yields (rendered script, resolved directives, validation errors) and what the inputs must look like. Neither is present, leaving the agent guessing before 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 for both parameters and largely fails: "remote batch script" loosely maps to script_path and "remote" hints at the project context, but project_id and script_path formats (path relative to what? remote vs local?) are never clarified.

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 ("Preview") with a specific resource ("remote batch script") and explicitly contrasts itself with job submission, which separates it from sibling slurm_submit. It is clear but does not name siblings directly, so it lands just short of a 5.

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

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

"Without submitting a job" implies this is the safe dry-run path before slurm_submit, which is meaningful implied guidance. However, it never states explicitly when to prefer this over slurm_submit or what conditions make a preview unnecessary.

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?

With no annotations, the description carries the full behavioral burden and discloses only one trait: the default read is the log tail. It is silent on the size of the "bounded chunk", the interpretation of offset, error behavior for unregistered/missing logs, and any permission requirements.

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 well-formed sentence with the key scoping facts front-loaded and no filler. It is efficient, though the terseness is arguably part of why the gaps elsewhere go unaddressed.

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 3-parameter tool with no annotations and no output schema, the description is too thin. An agent cannot determine the bound size, offset units, stream options, or failure modes from 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 0%, so the description must compensate for three undocumented parameters, but it only faintly gestures at offset semantics ("bounded chunk", "tail"). The stream parameter and its stdout default are never mentioned, nor is what job_id must reference.

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 ... a registered job log") with scope qualifiers ("bounded chunk", "tail"). It is clearly distinguishable from adjacent Slurm tools like slurm_watch_job or slurm_get_job, though it never names a sibling or explicitly contrasts with them.

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 when-to-use, when-not-to-use, or alternative is given. The description implies it is for inspecting job log output, but nothing tells the agent how to choose this over slurm_watch_job or slurm_get_job.

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?

With no annotations, the description carries the full burden, and it does disclose one meaningful trait: idempotent submission keyed on the request UUID, plus retry semantics. It says nothing about permissions/auth, what happens on a duplicate UUID, queue/partition behavior, or the returned job identifier, so the mutation's effects remain largely opaque.

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 semicolon-linked sentence with the core action front-loaded and the idempotency/retry caveat following. Every clause carries information; nothing is 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 mutation tool with no annotations, no output schema, and 0% schema description coverage across three required params, the description is too thin. An agent cannot tell what project_id is, what happens to the existing job record, or what the call returns after success.

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% for all three required parameters, so the description must compensate, and it only partly does: 'request UUID on retries' explains request_id's role, and 'batch script' loosely implies script_path. project_id is never addressed, and there is no format or constraint detail for script_path (path relative to what?).

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 ('Submit') and resource ('batch script'), which is enough to distinguish it from read-only siblings like slurm_get_job, slurm_list_jobs, or slurm_read_log. However, it does not explicitly contrast with slurm_preview (the likely validation step) despite invoking 'validated', so sibling differentiation is only implied.

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 'validated batch script' implies the script must pass validation (presumably slurm_preview) before submission, and 'reuse the request UUID on retries' gives retry guidance. But neither is framed as an explicit when-to-use vs. alternative statement, leaving the agent to infer the workflow.

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?

With no annotations, the description carries the full behavioral burden and fails: it never says whether the tool blocks/polls, how long it waits, what 'handoff registration' means, or what a successful verification returns. The external-terminal prerequisite hints at hidden state but is not explained.

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, so it is structurally tight and front-loaded. However, the brevity reflects under-specification rather than economy—there is simply too little content for a tool with this much unexplained machinery.

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 Slurm job-watching tool with two fully undocumented parameters, no annotations, and no output schema, the description omits everything an agent needs: target resource, blocking behavior, return values, and parameter meaning.

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% for two parameters, and the description mentions neither job_id (the required parameter) nor server_alias. An agent gets no meaning for either argument from any source.

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 name implies watching a Slurm job, but the description says only 'Verify local handoff registration,' which is vague and never names the resource or what is being verified/watched. It gives an agent no way to distinguish it from slurm_get_job, slurm_list_jobs, or slurm_read_log.

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 an environmental prerequisite ('Run hpc-agent watch in the original Codex terminal first') but gives no guidance on when to choose this tool versus slurm_get_job or slurm_list_jobs. The prerequisite is opaque and reads more like an error-recovery note than a selection rule.

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

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

With no annotations, the description carries the full burden and does disclose two real behavioral traits: it overwrites ('replacing the destination') and it handles only one regular file (not directories, globs, or symlinks). However, it says nothing about authentication via server_alias, permission requirements, error behavior for disallowed paths, or whether the remote file is modified or removed.

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 sentence with zero filler, front-loading the action and its scope before the overwrite caveat. Nothing in it is redundant with the name or title.

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 three-parameter write-to-disk tool with no annotations and no output schema, this is thin: parameter meaning, alias/authentication expectations, and failure behavior are all absent. The overwrite and single-file constraints are the only behavioral details an agent gets beyond the bare name.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and largely does not: it never explains local_path, remote_path, or the server_alias default of 'default'. 'Configured allowed roots' weakly implies remote_path is resolved relative to a sandbox root, but no path format, direction, or alias semantics are given.

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 ('Download one regular file') and adds meaningful scope qualifiers: single file only, regular files only, and confined to configured allowed roots. It does not name or contrast with the obvious counterpart ssh_upload, so it stops short of full 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?

There is no explicit when-to-use guidance, no when-not-to-use (e.g., for directories or multiple files), and no pointer to alternatives such as remote_read or ssh_execute. The phrase 'configured allowed roots' hints at a precondition but never states the condition or the failure mode when a path falls outside those roots.

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?

With no annotations, the description carries the full burden, and it does add real behavioral context: commands must be config-allowlisted and run in an allowed directory, implying a permission/policy gate. It says nothing about return format, timeout defaults, failure modes, or whether commands are interactive.

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 compact sentence, front-loaded with the action and constraint, with the alternative appended. Very little waste, though the semicolon clause is dense enough to be slightly cryptic.

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

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

For an unannotated command-execution tool with four undocumented parameters and no output schema, the description omits too much: output shape, timeout semantics, error behavior, and the meaning of server_alias. The allowlist hint is useful but not sufficient.

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

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

Schema description coverage is 0% across four parameters, so the description must compensate and largely does not. 'Allowed directory' vaguely gestures at the directory parameter, but cmd_string, timeout_ms, and server_alias are never explained, nor is the default server_alias='default' behavior.

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 ('Run a ... command in ... directory') with a scope constraint that a bare 'execute' would lack. It does not, however, distinguish itself from the sibling remote_execute, which appears to overlap.

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 routes job submission to slurm_submit, which is a concrete alternative with a selecting condition. It stops short of stating when to prefer ssh_execute over remote_execute or what is disallowed.

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?

With no annotations, the description must carry the full behavioral burden. It discloses important traits: only one file, only regular files, restricted to allowed roots, and that the destination is replaced (an overwrite). However, it does not cover permissions, error modes, directory creation, transfer semantics, or authentication requirements.

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, front-loaded sentence with zero filler. Every phrase adds useful scope or behavior information 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?

For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too sparse. It leaves out parameter details, usage context, prerequisites, and most behavioral specifics an agent would need 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?

Schema description coverage is 0%, so the description must compensate for all three parameters. It implies path and destination concepts but gives no format, syntax, or constraints for local_path, remote_path, and completely omits server_alias.

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 clear verb ('Upload') and resource ('one regular file'), and adds scope ('between configured allowed roots, replacing the destination'). It does not explicitly name or distinguish itself from sibling tools like remote_upload or ssh_download, so it falls short of full 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?

There is no explicit guidance on when to use this tool versus alternatives such as remote_upload or ssh_execute. The phrase 'between configured allowed roots' implies a restriction but does not tell the agent when this tool is the right choice.

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