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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the irreversibility class is known without the description. The description adds one genuinely new behavioral fact, the ownership constraint ("your own jobs"), implying you cannot cancel others' jobs, but says nothing about what happens to a running job's output or whether it can be requeued.

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 the action and the scoping constraint front-loaded and zero filler. Nothing could be removed without losing 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?

Adequate for a one-parameter tool whose annotations carry the safety profile and whose schema fully documents the input. It still omits what state the job must be in and what the caller observes after cancellation, which for a destructive operation would be useful.

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?

Only one parameter and schema description coverage is 100%, so the schema already fully documents job_id including the array-task format '123456_7'. The description adds no syntax or format detail beyond that, which is the expected baseline when the schema does the work.

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?

Specific verb (Cancel) plus resource (job) scoped by ownership ("your own"), and it names the underlying SLURM command (scancel). It is clearly separable from siblings like hpc_hold_job or hpc_release_job, though it never explicitly contrasts itself 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 or when-not-to-use guidance, and no alternatives named. An agent cannot tell from the description whether a running job should be cancelled versus held/released via the sibling tools, so selection is left entirely 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 establish this as a safe, read-only, closed-world query. The description adds the useful behavioral detail of what the per_node mode expands to (CPUs, memory, GPUs) and that it is backed by sinfo, but says nothing about cost, caching, or failure modes for an HPC cluster query.

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 tight sentences, zero filler, with the core resource named first and the mode flag second. It could add one clause about the default output without bloating, but as written nothing is wasted.

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

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

For a one-parameter read-only tool with full annotation coverage and no output schema, the description covers what the tool returns at a high level in both modes. It is nearly sufficient; only the default view's fields remain 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 schema alone does not explain per_node. The description compensates for the true case ('shows CPUs, memory and GPUs for every node') but never states what the default false mode returns, leaving half the parameter's semantics implied.

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 (partitions and node availability) and cites the underlying command (sinfo), so the agent knows this is cluster-level inventory rather than job-level status. It does not explicitly contrast itself with sibling tools like hpc_queue, but the 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?

Usage is only implied by the purpose: you call it to inspect partitions/nodes, and per_node=true when you need per-node hardware detail. There is no explicit when-to-use or when-not-to-use guidance and no mention of the job-status siblings that could be confused with it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: the operation is an exact-string match, it fails when old_string is ambiguous, and it requires a writable path.

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, zero filler. The core action is front-loaded and the failure condition follows immediately, which is exactly the ordering an agent needs.

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 and only hint-level annotations, the description covers the essential contract: exact-match edit, uniqueness failure, writable-path requirement. It omits secondary behavior such as whether a missing file is created and whether the edit is atomic, which are minor for a straightforward string-replacement 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 coverage is only 25% (only path is documented), so the description must carry weight. It explains old_string as an exact match target, the uniqueness precondition, and the replace_all escape hatch, which is real added meaning. new_string's semantics remain unstated, though its meaning is largely self-evident.

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: 'Replace an exact string in a file in a writable location.' An agent can distinguish this from a whole-file write. It does not name or contrast any sibling (e.g. hpc_write_file), 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?

Usage is implied by the uniqueness rule and the 'writable location' constraint, which guides whether the tool will succeed. There is no explicit statement of when to prefer this over hpc_write_file or a create-if-missing alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — 'Returns paths only' — which tells the agent no metadata comes back. It omits permission/prerequisite context and any note on traversal cost or result 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?

Two tightly packed sentences that front-load the purpose and follow with the return contract. No wasted words and nothing buried.

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

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

With no output schema, the 'Return paths only' clause usefully pins down the return value, and the filter dimensions are surfaced. However, max_depth's default of 3 and the meaning of an empty result are undocumented, leaving real gaps for a 5-parameter 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 only 40%, so the description has to compensate. It does name the filter dimensions (name/type/size), which maps conceptually to name_pattern, file_type, and size_filter, but it omits base_path and max_depth entirely and adds no syntax 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 (Find) and resource (files), plus the filter dimensions (name/type/size) and the scoping constraint (under a directory). It does not explicitly differentiate from siblings like hpc_list_directory, but the 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?

No when-to-use guidance and no named alternatives, despite obvious siblings (hpc_list_directory for simple listings, hpc_get_file_info for metadata, hpc_search_in_file for content search). The agent must infer the selection criteria.

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

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

Annotations declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds only that the template references cluster data paths; it does not say whether a file is written to disk, whether output_dir must pre-exist, or what the generated content 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?

A single front-loaded sentence that states purpose without padding. It is efficient, though its brevity reflects under-specification rather than tight editing.

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 6 parameters (5 required), a 0% schema coverage, no output schema, and no parameter explanations, the description is too thin for an agent to call the tool correctly. It should at least explain output_dir and the analysis_type options.

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 6 parameters, and the description only gestures at 'data paths'. It adds no meaning for title, author, output_dir, r_packages, or the analysis_type enum values (QC, DESeq2, survival, scRNA, general), so it fails to compensate for the coverage gap.

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

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

The description names a specific verb (Generate), resource (R Markdown notebook template), and scope (references data paths on the cluster), which distinguishes it from hpc_generate_sbatch and hpc_generate_rmd_render_job. However, it never explicitly contrasts itself with those siblings, so an agent must infer the boundary.

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 tool versus hpc_generate_sbatch or hpc_generate_rmd_render_job, nor any stated prerequisites or context. The agent is left to infer usage entirely from the name and purpose sentence.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that the render targets a compute node, but it does not say whether a script is written to disk or merely returned, nor whether the job is submitted, which matters for a 'generate' 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 filler. It is efficient, though arguably under-specified rather than truly concise.

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 exists, so the description should clarify the return (script text vs. written file path) and the meaning of the five undocumented parameters. For a 7-param generator tool it leaves too much unstated.

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 only 29% (7 params), and only rmd_path and partition carry any schema text. The description adds nothing about cpus, memory_gb, walltime, email, or output_dir, so it fails to compensate for the coverage gap.

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 (generate) and resource (sbatch script that renders an R Markdown file), so the action is unambiguous. However, it does not differentiate itself from close siblings hpc_generate_sbatch and hpc_generate_rmd, leaving the agent to guess which generator 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. With siblings hpc_generate_sbatch and hpc_generate_rmd present, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description usefully adds that no file is written (returns text only) and that the script is validated against cluster limits, which is real behavioral context beyond the annotations; it omits what happens on validation failure.

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, front-loaded with the core action and immediately followed by the critical output-handling instruction. No filler.

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

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

With no output schema, the description correctly explains that the return value is script text and must be saved, which is the single most important missing structured field. However, for a 15-parameter, 6-required tool, it gives no guidance on validation errors or parameter usage, leaving meaningful gaps.

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 only 53% across 15 parameters, and the description provides no parameter-level guidance at all — nothing about which directives are required, valid QoS names, or how the partition/QoS validation consumes these inputs. The half of parameters lacking schema descriptions get no compensation from the text.

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 (generate an sbatch script) plus the distinguishing trait that it is validated against cluster partition/QoS limits. It also separates itself from siblings by noting the output is text only and must be saved via hpc_write_file, so it is clearly not hpc_submit_job or hpc_write_file.

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

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

The description makes the usage context clear: generate first, then persist with hpc_write_file. It does not state when NOT to use it (e.g., vs. hpc_submit_job directly) or note prerequisites like hpc_resolve_project, but the workflow routing is explicit enough.

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

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

Annotations already establish readOnlyHint and destructiveHint=false, so safety is covered. The description adds that content is not fetched, which is useful, but omits error behavior for missing paths, symlink handling, and 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 tight sentence that front-loads the purpose and metadata fields, with zero filler. It could be slightly more informative without bloat, but it is well-sized.

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?

Adequate for a single-parameter read-only tool whose annotations cover safety, but with no output schema the description should ideally specify the return shape or error conditions for a missing/inaccessible path.

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% with the path parameter fully documented ('Absolute path on the cluster'). The description adds no parameter-level detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (get) and resource (file info) and enumerates the returned metadata fields (size, type, permissions, mtime). It distinguishes from read_file/head_file/tail_file by clause 'without reading content', though it never explicitly names those siblings.

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

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

The phrase 'without reading content' implicitly signals when to prefer this over read_file/head_file, but no explicit when-to-use or when-not-to-use guidance is given, and no alternatives are named.

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

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

Annotations already establish the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior beyond that: it transparently decompresses .gz files across FASTQ/VCF/BED, which saves the agent from pre-decompressing. It does not state truncation/return format, but the added decompression context is meaningful.

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, zero filler, with the core operation front-loaded and the decompression caveat immediately following. Nothing needs to be cut or reordered.

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

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

For a simple read-only preview tool with no output schema, the description covers what the tool does and its key non-obvious behavior (gz decompression). The only minor gap is that it does not describe the return shape or whether output is truncated by line length, which is acceptable given the tool's simplicity.

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 50%: path is documented as an absolute cluster path, while lines only carries a default (50) and maximum (1000) with no prose. The description's "First N lines" loosely maps N to the lines parameter but adds no syntax or behavior detail beyond the schema. Baseline 3 is appropriate.

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

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

The description gives a concrete verb+resource ("First N lines of a file") that an agent can immediately map to the head operation, and the explicit gz-decompression scope further pins down behavior. It does not name sibling tools such as hpc_tail_file or hpc_read_file, so the differentiation from alternatives is left implicit 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?

Usage is only implied: an agent can infer this is the tool for peeking at the beginning of a file, and the .gz note signals it is safe for compressed genomic formats. There is no explicit when-to-use statement and no guidance on when to prefer hpc_read_file, hpc_tail_file, or hpc_search_in_file instead.

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

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

Annotations already establish this is a non-read-only, non-destructive, non-open-world mutation, which fits holding a job. The description adds the state constraint (pending) and ownership constraint, but does not state that the action is reversible via release or note any permission requirements beyond ownership.

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; every word (hold, own, pending, job) carries distinguishing 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?

For a one-parameter state-changing tool whose annotations cover the safety profile, the description is adequate but thin. It omits the reversibility relationship with hpc_release_job and any confirmation that the hold is idempotent, which would help correct invocation.

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

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

Schema description coverage is 100% with a single well-documented job_id parameter including SLURM ID format examples. The description adds nothing about the parameter, 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?

Specifies a concrete verb ("Hold") and resource ("pending jobs"), plus a scope constraint ("one of your own"). It is distinguishable from most siblings by the hold action, though it does not explicitly name the natural counterpart hpc_release_job.

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 constraints "pending" and "your own" — an agent can infer it only works on jobs it owns that are queued. No explicit when-to-use, prerequisites, or pointer to hpc_release_job for the inverse operation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context by revealing it combines live scontrol data with sacct accounting records, but it does not explain the return shape or what 'full details' encompasses.

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 short sentence, front-loaded with the purpose. It is efficient and wastes no words, though it is arguably too terse to be fully helpful for an agent deciding how to interpret results.

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

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

For a single-parameter read-only lookup with no output schema, the description is minimally adequate. It identifies the data sources but does not describe what categories of detail are returned (state, resources, timing, exit code), leaving some ambiguity about output.

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 at 100% schema coverage, the schema already documents the job_id format including example values. The description adds no additional meaning about the parameter, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Full details of one job') and even names the data sources (scontrol + sacct), which helps distinguish it from general queue tools. However, it does not explicitly differentiate itself from siblings like hpc_job_history or hpc_job_efficiency that might also return job information.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention hpc_job_history, hpc_job_efficiency, or hpc_queue, so an agent has to infer that this is for detailed single-job inspection rather than list or history queries.

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, non-destructive, closed-world), so the description is free to add behavioral context instead: it signals the tool applies only to a *finished* job, which is a real constraint (running/pending jobs won't yield efficiency data), and identifies the data source (seff/sacct). Good added value 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?

Two tight sentences: the first defines what is returned, the second states the use. Zero waste and the content is front-loaded.

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

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

For a one-parameter read-only query with no output schema, the description adequately conveys the metric returned and its purpose. It could go further by noting behavior for not-yet-finished jobs, but it is complete enough to invoke 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?

There is a single parameter with 100% schema description coverage, including format examples for both simple and array job IDs ('123456' / '123456_7'). The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource: it reports CPU and memory efficiency for a finished job, and names the underlying mechanisms (seff/sacct). An agent can distinguish it from generic job tools, though it never explicitly names siblings like hpc_job_details or hpc_job_history that might 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?

"Use it to right-size future requests" gives an implied purpose, which is a use case rather than selection guidance. It does not say when to prefer this over hpc_job_details or hpc_job_history, nor that it only applies post-completion as an explicit 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?

Annotations already declare the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the description's remaining job is extra context. It usefully discloses the data source (sacct) and the implicit scoping to the caller's own jobs, but says nothing about result volume, grouping, or time/state edge cases.

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, window, and filter all appear before any detail, and the parenthetical source note is compact.

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

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

For a two-parameter, no-required-arg read tool with a covering safety annotation and no output schema, the description is nearly sufficient: both parameters are addressed and the data source is named. It stops just short of full completeness by omitting any note on result size/ordering or the state-value format beyond what the schema shows.

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 50%: 'state' is documented in the schema with examples, while 'days' has no schema description. The description supplies the meaning of 'days' ('last N days') and confirms 'state' is an optional filter, so it partially compensates for the gap. It adds no syntax detail for 'days' (units beyond days, valid range, default of 7).

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+resource: retrieving the caller's own job accounting records over a day window, with the underlying source (sacct) named. It is clearly distinguishable from hpc_job_details, hpc_job_efficiency, and hpc_queue in practice, though it doesn't explicitly contrast itself with those siblings.

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

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

The phrase 'Your jobs from the last N days, optionally filtered by state' implies the usage context (historical accounting vs. live queue status), but there is no explicit when-to-use, when-not-to-use, or named alternative such as hpc_queue or hpc_job_details.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds that results are formatted like 'ls -lh', which hints at the return shape, but says nothing about pagination, truncation, or performance on very large directories.

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, the primary action front-loaded and the delimiting constraint second. Every clause carries information; nothing is 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 simple two-parameter read tool there is no output schema, and the '(ls -lh)' note gives the agent an idea of the return format. The only meaningful gap is behavior on very large listings or whether results are capped, which is minor for this tool's complexity.

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

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

Schema description coverage is 100%, so both 'path' (absolute path) and 'pattern' (glob example) are already documented in the schema. The description adds no syntax, default, or interpretation detail beyond that, 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 ('List a directory on the cluster'), with the '(ls -lh)' gloss making the operation concrete. The clause 'Does not fetch file content' separates it from file-reading siblings like hpc_read_file and hpc_head_file, though no sibling is named 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?

The negative scope ('Does not fetch file content') implies when to prefer a read tool instead, which is a useful usage boundary. However, no alternative is named and there is no guidance on required access, path validity, or what to do for large directories.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds the content scope (site rules + SLURM basics), which is useful, but says nothing about return shape or ordering. Acceptable but thin given the low bar set by 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?

A single tight sentence with the verb and scope front-loaded and no filler. Nothing could be removed without losing 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 no output schema, the description should hint at what the listing returns (doc names, paths, or identifiers) so the agent can chain into hpc_read_doc; it does not. It is adequate for a zero-parameter read, but leaves the discovery-to-read handoff unstated.

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 the baseline is 4 — there is no parameter semantics to document and nothing for the description to compensate for.

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 (cluster documentation) and even scopes the content to 'site rules + SLURM basics'. An agent can distinguish it from hpc_read_doc/hpc_search_docs by inference, but the description never names those siblings, so it stops 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?

Usage is only implied: 'List' suggests a catalog/discovery step before reading a specific doc, but there is no explicit when-to-use, when-not-to-use, or pointer to hpc_read_doc or hpc_search_docs. The agent must infer the routing itself.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds no behavioral context beyond that: no scope (user vs. cluster reservations), no filtering/pagination behavior, no output shape for a tool with no output schema.

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 short, front-loaded sentence with zero filler, appropriately sized for a zero-parameter list tool. It is efficient but offers nothing extra, so it stops short of a 5.

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

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

For a simple parameterless list tool the definition is minimally viable, but with no output schema the description should ideally indicate what a reservation record contains or how reservations relate to jobs. As written, the agent can invoke it correctly but cannot anticipate the result.

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 the baseline of 4 applies and there is nothing the description could add or omit.

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 ('SLURM reservations'), so the agent knows exactly what it returns. It does not differentiate itself from adjacent read-only listing tools such as hpc_queue or hpc_cluster_info, which is the only thing keeping it from 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?

There is no when-to-use guidance, no exclusions, and no named alternative. The agent must infer on its own that this is for reservation queries rather than job/queue queries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context (default filtering to the caller's own jobs) but says nothing about return format, columns, or pagination.

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 the scope qualifier front-loaded; nothing is wasted. It is arguably terse for a tool that lists structured output, but there is no filler.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description is minimally adequate. It omits what the queue listing actually contains and how the default scope can be changed, which an agent would benefit from knowing.

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 schema alone does not explain user_only. The parenthetical "(your jobs by default)" does convey the parameter's meaning and default behavior, partially compensating for the gap, but it never states the parameter name or the opposite setting.

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 ("Show") and resource ("SLURM queue"), which is clearly distinct from sibling tools like hpc_job_details, hpc_job_history, and hpc_list_reservations. It stops short of explicitly naming those siblings as alternatives, so it does not reach full 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?

"your jobs by default" implies the scope can be widened and hints at when the default is not what you want, but there is no explicit when-to-use/when-not guidance and no alternative tool is named. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral trait: fuzzy/partial name resolution, which is not derivable from the schema or annotations.

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

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

Two short sentences, zero filler, with the core action front-loaded and the partial-name behavior immediately after. Nothing could be cut without losing 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?

Adequate for a single-parameter read tool with no output schema, but it leaves gaps an agent would hit: how to enumerate valid doc names (presumably hpc_list_docs), and how multiple partial matches are resolved. The basics needed to call it are present.

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 schema only says 'string', so the description must carry the parameter burden. It partially does by explaining that partial names are accepted and giving two concrete examples, but it omits extension requirements, case sensitivity, and what happens on ambiguous matches.

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 (one documentation file), with the singular scope made explicit. It is clearly separable from hpc_list_docs and hpc_search_docs by the verb, though it never names those siblings or contrasts itself with hpc_read_file.

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

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

Usage is implied by the verb and the 'one file' scope, and it hints at the naming convention via examples ('slurm', 'storage'). It gives no explicit when-to-use vs hpc_search_docs/hpc_list_docs, and no guidance on discovering valid names 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavior: a 1 MB size threshold, head/tail preview fallback for oversized files, and outright refusal of binary files. That is meaningful operational context beyond the structured fields, though it says nothing about performance or encoding.

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, zero filler, with the core action and the size limit front-loaded before the edge-case behavior. 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?

No output schema exists, so the description is responsible for setting expectations, and it does so via the head/tail preview and binary-refusal notes. It stops short of describing the returned structure (line numbering, truncation markers), which would be the final missing piece.

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 at 100% schema description coverage ('Absolute path on the cluster'), the schema already carries the semantics, so the baseline of 3 applies. The description adds no path syntax, character-encoding, or relative-vs-absolute clarification 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?

Specific verb (read) plus resource (text file) plus scope (into context, ≤1 MB), so the purpose is unambiguous. It only partially differentiates from siblings hpc_head_file/hpc_tail_file and hpc_read_doc, mentioning head/tail preview as a fallback rather than naming the alternatives an agent should prefer.

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 — fetch a file's contents — but there is no explicit when-to-use/when-not guidance against hpc_head_file, hpc_tail_file, hpc_read_doc, or hpc_search_in_file. The size/binary caveats hint at boundaries without routing the agent to the right sibling.

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, destructiveHint=false, and openWorldHint=false. The description adds useful ownership and state context ('your own held jobs'), but it does not explain what releasing actually does, whether the job resumes automatically, or what errors may occur.

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 communicates the action, the object, and the ownership constraint immediately.

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

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

For a low-complexity mutation with full schema coverage and annotations covering safety, the description gives enough context to invoke correctly: the job must be held and owned by the caller. It could additionally clarify the effect of release, but no output schema means return values need not be described.

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 job_id parameter is fully documented in the schema with a SLURM job ID example. The description adds no additional parameter syntax or meaning beyond that baseline.

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 (Release) and resource (held jobs), and the scope 'one of your own' distinguishes it from generic job cancellation. An agent can tell it apart from hpc_cancel_job and hpc_hold_job based on the 'held jobs' qualifier.

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 'held jobs' implies the condition for use: the job must currently be held and owned by the caller. However, it does not explicitly say when to use this versus hpc_cancel_job or hpc_hold_job, nor does it state prerequisites 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description usefully adds the no-argument listing behavior (projects plus readable/writable roots), which is genuine context beyond the annotations, but says nothing about errors for unknown aliases or return format.

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 tight sentences with zero waste, and the primary resolve behavior is front-loaded before the fallback branch.

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

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

For a single-optional-parameter read-only tool, the definition covers both modes and hints at what is returned (directory, or project list with roots). With no output schema, a brief note on return shape is the only 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 description coverage is 0%, so the description must compensate: it explains that 'alias' is the project alias to resolve and that an empty alias triggers the listing mode, which is exactly the semantics the schema's bare string with default cannot convey.

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 (resolve) and resource (project alias to directory), plus the no-arg fallback behavior. It is clearly distinguishable from siblings like hpc_get_file_info or hpc_storage_usage, though it does not name any 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?

The dual-mode behavior is implied: pass an alias to resolve it, omit the alias to list projects and roots. There is no explicit when-to-use-vs-alternative guidance or mention of prerequisites, so usage must be inferred from the two branches described.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that the search covers 'all cluster documentation,' which is essentially a restatement of the tool name and does not describe return format, ranking, matching behavior, or result 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?

A single front-loaded sentence with zero waste. The verb, resource, and input type all appear immediately with no filler.

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

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

There is no output schema, so the description should at least hint at what a search returns (matching doc names, snippets, ranking), and it does not. For a simple read-only search tool this is adequate but leaves the agent guessing about results and about its place among the doc-related siblings.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single query parameter. It minimally clarifies that the value is a keyword or phrase rather than a path or regex, but adds no syntax, format, or matching-rule detail.

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 clear verb (search) plus resource (cluster documentation) and the input type (keyword or phrase). It does not differentiate itself from siblings like hpc_read_doc or hpc_search_in_file, so an agent must infer which is appropriate.

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 or when-not-to-use guidance is provided. Given the presence of hpc_list_docs, hpc_read_doc, and hpc_search_in_file, the description never tells the agent when this broad search is preferred over those 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new traits: streaming execution and the regex flavor supported for the pattern. It omits what the output looks like and any match-count or pagination behavior, which matters because no 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?

Two tightly packed clauses with no filler, and the core verb/resource is front-loaded ahead of the performance hint. Nothing in the text is 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?

Annotations cover the safety profile and the description covers scope and streaming, but with no output schema the agent still cannot tell whether results are raw matching lines, line-numbered, or truncated. The unexplained context_lines parameter is a second gap for a tool this simple to fully specify.

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 only 33%, so the description must carry weight. It clarifies that "pattern" is basic regex, but the whole context_lines parameter (with its default of 3) is never explained in either the description or the schema, leaving the agent to guess whether it means surrounding lines.

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 (grep) and resource (a file) with the matching mechanism (pattern, basic regex), which immediately separates it from content-reading siblings like hpc_read_file and hpc_head_file. An agent can identify the operation without opening the schema.

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

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

"Streams, so safe for huge files" gives a concrete condition that routes the agent here rather than to hpc_read_file or hpc_head_file. It does not name those alternatives explicitly or state when-not to use it, so it falls short of full explicit guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the scope of what is measured (configured filesystems, user quota), with no detail on output shape, units, or whether it reflects live or cached values.

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 fragment with no padding and the key resource front-loaded. The telegraphic '(df)' parenthetical and lacking verb cost it a point, but nothing is wasted.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it only gestures at the two categories (filesystems, quota) without saying what fields, units, or per-filesystem granularity to expect. Acceptable for a simple read, but incomplete for an agent that needs to interpret or parse the result.

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; there is nothing for the description to disambiguate and the empty schema is consistent with a no-argument status query.

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

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

The description names a concrete resource and outcome — free space on configured filesystems plus the user's quota — which no sibling tool covers (they are all file, job, or cluster oriented). It is a noun-phrase fragment rather than a verb+resource statement ('report free space...'), so it is clear but not maximally explicit.

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 alternatives, nor any prerequisite or context (e.g. 'use before submitting large jobs to check quota'). Usage must be inferred entirely from the topic.

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 and destructiveHint=false, so the mutation profile is covered. The description usefully adds that execution is via sbatch and that the working directory is the script's directory, but says nothing about the job being queued asynchronously, the returned job ID, or failure modes such as an invalid or non-writable script.

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, front-loaded with the action and mechanism (sbatch) followed by the key constraint. Every clause carries information and there is no filler.

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

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

For a one-parameter, non-read-only tool with no output schema, the definition covers the mechanics and precondition but omits what the call returns (a job ID?) and any note that the submission is asynchronous. With no output schema to fall back on, that is a visible gap, though the annotations adequately cover the safety profile.

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% for the single script_path parameter (documented as an absolute path on the cluster), so the schema does the heavy lifting. The description's writable-location constraint adds minor eligibility context but no format or syntax 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 (submit an existing batch script with sbatch), which is unambiguous. The word 'existing' implicitly distinguishes it from the sibling hpc_generate_sbatch, but the sibling is not named explicitly, so the differentiation is inferential 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 description gives one real precondition: the script must be in a writable location, and notes it runs from the script's directory. It offers no when-to-use vs. alternatives guidance, e.g. that hpc_generate_sbatch should be used first if no script exists yet, so the agent must 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds only the log-checking context, with no mention of truncation behavior, size limits, or error handling for missing paths.

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, front-loaded with the operation and followed by the use case. Every clause earns its place with no redundant restatement of the name.

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

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

For a simple read-only tool with no output schema and annotations covering safety, the description is nearly sufficient. Only minor gaps remain around default line count and behavior on invalid paths.

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 50%: 'path' is documented in the schema while 'lines' has only a default and maximum. The description's 'Last N lines' clarifies the semantics of the 'lines' parameter but does not state the 50 default or 1000 cap, so it only partially compensates for the gap.

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 operation and scope: 'Last N lines of a file.' Combined with the sibling set (hpc_head_file, hpc_read_file), the tail semantics implicitly distinguish it, but no sibling is named explicitly, so it falls 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?

'Ideal for checking live SLURM job logs' gives one usage scenario, which is more than nothing. However, there is no guidance on when to prefer it over hpc_read_file or hpc_search_in_file, and no stated exclusions or prerequisites.

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 and readOnlyHint=false, so the overwrite behavior is partially covered by structured data. The description does add real value by disclosing that it overwrites and that parent directories are created automatically, but the '(none configured)' note is ambiguous about whether the tool can actually run.

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 are efficient and front-load the core action. However the '(none configured)' parenthetical is confusing clutter that consumes space without earning it.

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

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

For a destructive write tool with no output schema, it conveys the key mechanics (overwrite, parent dir creation) but says nothing about permissions, size limits, or what happens on failure. It is adequate but leaves meaningful gaps for a mutation 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 coverage is only 50% — path is documented as an absolute cluster path, but content has no description anywhere. The description adds no format, encoding, or size semantics for content, so it fails to compensate for the coverage gap.

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 — create or overwrite a file — which is clear enough to distinguish it from read-side siblings like hpc_read_file. However it does not differentiate itself from the close sibling hpc_edit_file, and the parenthetical '(none configured)' muddies rather than clarifies the purpose.

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 mention of the obvious alternative hpc_edit_file for modifying existing content. The agent is left to infer the choice between creating/overwriting versus editing.

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