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

Annotations already flag readOnlyHint=false, so the agent knows there is a side effect; the description goes further and explains exactly what that side effect is (starts the tunnel if down), its rate limit (at most once a minute), and its statefulness (first call of a run carries a banner to show the human once). The only missing piece is what happens on failure — whether an expired certificate or failed SSH test is reported versus raised — which matters for a pre-flight check.

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 critical instruction ('Call first in every session') is front-loaded in sentence two, and every clause carries real information: side effect, rate limit, recovery scope, banner. The nested parenthetical with wireproxy/recovery jargon is dense and slightly hard to parse, but it is not 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?

With no output schema, the description should say what the agent gets back so it can act on it — it mentions the one-time `banner` but not how tunnel/certificate/SSH results are presented or what a failing result looks like. Combined with the undocumented `probe` parameter, an agent can invoke this correctly but cannot fully interpret or configure 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?

There is one parameter, `probe` (boolean, default true), with 0% schema description coverage, and the description never mentions it. An agent cannot tell whether setting probe=false suppresses the tunnel start, skips the SSH test, or disables the recovery side effect — a meaningful ambiguity given the tool's mutating 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?

The opening line names the three things checked (tunnel, certificate expiry, SSH test), which is specific enough that an agent knows this is the health/readiness probe rather than a job or file tool. It stops short of a clean verb+resource statement — the noun-phrase style ('Tunnel, certificate expiry and an SSH test') requires the reader to infer that this is a diagnostic status call — and it never explicitly contrasts itself with siblings like run_command or cluster_load.

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?

'Call first in every session' is an unusually direct when-to-use instruction, and the parenthetical explains the recovery side effect so the agent knows the call is safe to make proactively. It also carves out a scope exclusion (recovery does not yet apply to push_files/fetch_files). No explicit alternative tool is named for the case where the check fails, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuine context beyond that: the data comes from sacct, CPU nodes are included, B200 is counted in node-hours with no published price, and without a configured account the scope collapses to the caller's own jobs. It stops short of stating freshness/caching or whether counts are eventual, but the provenance and scope caveats are unusually informative.

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

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

One sentence carries a lot of load, but the nested parenthetical about CPU nodes and B200 pricing disrupts parsing and pushes the key caveat about account scoping to the end. Every clause earns its place, yet the front-loading of the main purpose is weakened by the digression.

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 does explain the shape of the result (per-user usage, remaining budget) and the fallback scope. It does not say what happens when no budget is configured at all versus what the per-user breakdown looks like, but for a one-parameter read tool with readOnlyHint this is close to 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?

The single 'since' parameter has 0% schema description coverage, and the description only says 'since a date' without specifying format or whether the default is inclusive. The schema's default value implies a date format, so the description adds scope meaning but not format 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?

It clearly states the resource and metric: tokens/credits consumed per user since a date, plus remaining configured budget, sourced from sacct. It is not framed as a clean verb+resource and never distinguishes itself from the sibling ledger_entries, which plausibly covers adjacent credit data, so an agent can tell what it does but not decisively why to pick it over that sibling.

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 or when-not guidance and no alternative is named. "The projects portal is authoritative" hints at a trust boundary but does not tell the agent when to call this tool versus ledger_entries or access_status.

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 openWorldHint=true, so the safety profile is known. The description adds important context beyond annotations by explaining the human-approval requirement for jobs not submitted through this server and naming the approval field.

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

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

The description is two tightly written sentences with the scope and approval condition front-loaded. There is no redundant or wasted text.

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 tool with no output schema and zero schema description coverage, the description covers the key approval rule but omits parameter meanings for job_id and reason and does not describe return behavior. It is adequate but has clear 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 0%, so the description must carry parameter meaning. It explains the `approval` parameter's role for non-server jobs, but it says nothing about `job_id` or `reason`, leaving two required parameters 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 specific verb and resource: "Cancel a job." It is clear enough to distinguish cancellation from siblings like update_job or submit_job, but it does not explicitly contrast itself with any sibling.

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 clearly states when cancellation is direct versus when human approval is required: jobs submitted through this server can be cancelled directly, while any other job needs approval. It does not mention alternative tools such as update_job or wait_for_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?

The annotations already mark this as read-only and open-world, but the description adds substantial behavioral detail: what rules are checked, that missing paths cause submit_job refusal unless a dependency exists, that test-only start time is unreliable, and what asc and expected_minutes mean. This goes well beyond the annotations and helps the agent predict side checks and refusal behavior.

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

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

The description is front-loaded with the core purpose and remains information-dense rather than padded. It is long and somewhat run-on due to multiple parentheticals and semicolon-separated clauses, but the length is largely justified by the tool’s complexity.

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 six parameters at 0% schema description coverage and no output schema, the description covers most behavior but leaves script_args unexplained and does not describe the overall return structure beyond mentioning missing_paths and asc. It is adequate for invocation but has clear completeness gaps for a complex check 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 0%, so the description must carry parameter meaning, and it mostly does: it explains script as a cluster-relative path, script_text as inline content, cwd as the run location, sbatch_args as separate list items, and expected_minutes as a runtime estimate. It does not explicitly explain script_args, leaving one of six parameters 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 states a specific verb and resource: checking a job before submission, with concrete checks like runbook rules, cost estimate, approval requirement, and sbatch --test-only. It is clearly distinct from submit_job and draft_job by framing the tool as a pre-submission validation step.

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 usage context is explicit: use it before submitting. It also clarifies the script vs. script_text usage patterns and notes that script_text can be used for a draft_job result without pushing first. It does not explicitly name when not to use it or fully compare it to alternatives, so it falls short of a 5.

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

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

Annotations only establish that this is a safe, open read; the description goes much further by warning that 'planned' nodes look idle in plain sinfo %A/%F but are not available to new jobs except via short backfill. That caveat preempts a concrete misreading of the output, and the fair-share/4× heuristics add decision-relevant context the schema cannot carry.

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

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

It is front-loaded with 'Nodes per partition' and every clause carries new information, with nothing redundant. It loses a point for density: an 80-word sentence with a nested parenthetical (backfill exception) is hard to parse on a first read when it could have been split into shorter clauses.

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?

Zero parameters, no output schema, and read-only, so the only thing an agent needs is what comes back and how to interpret it — the description enumerates every bucket (allocated, idle, planned, other, total, states, jobs, fair-share) and explains the non-obvious one. Nothing material is missing for correct invocation.

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

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

The tool takes no parameters, so there is no parameter semantics to document; a baseline of 4 applies. The description's detail goes into output fields instead, which is the right allocation of space for a zero-argument call.

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 enumerates exactly what the tool reports: per-partition node counts by allocation category, per-state node counts, job counts, and the caller's fair-share/priority factors. That is a precise, verifiable resource breakdown rather than a tautology. It never names a sibling, though, so an agent must infer on its own why this differs from access_status or list_jobs.

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 'use this when...' or exclusion statement; the fit is only implied by phrases like 'job next in line' and 'low fair-share means long waits,' which suggest the tool serves pre-submission timing decisions. The closing note that idle GPU nodes can take CPU work at 4× hints at an actionable interpretation, but the agent is left to derive that this is the tool to reach for before submitting rather than, say, check_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?

Annotations already declare readOnlyHint=true and the description corroborates and enriches it: no cluster contact, job-start existence checks that exit 2, HF_HUB_OFFLINE=1 and OMP_NUM_THREADS=1 side effects, the failure semantics for parallel runs, run_minutes being refused when the slowest exceeds time, and load_cap_s dropping a stalled vLLM server. This is exactly the beyond-annotations context the dimension rewards.

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 purpose and the 'nothing is sent to the cluster' guarantee are front-loaded, and nearly every clause maps to a parameter or behavior, so the extreme density is largely earned by a 25-param tool. Readability suffers somewhat from prose-embedded enumerations and heavy parenthetical nesting, but there is little outright waste.

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 25-parameter tool with no schema descriptions and no output schema, the description supplies the return contract ('Returns the script, the static check (estimate, approvals needed) and notes') and hands off to check_job for cluster-side validation. An agent can call this correctly without opening any other field, with only minor param gaps (stage_model) remaining.

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 25 parameters and 0% schema description coverage, the description carries the whole burden and does so for most of them — kind variants and their dependent params, gpus, nodes, command scoping ($NODE_RANK/$NNODES/$HEAD), time formats, array syntax with $TASK, array_args/$OUT convention, vllm_preset flag inheritance. Gaps remain: `name`, `description`, and `stage_model` are never explained, and `array_throttle`'s 'approval limits' is left vague.

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 ('Draft a Slurm job script for MUSICA from the runbook's tested patterns') and immediately bounds the scope with 'nothing is sent to the cluster', which cleanly separates it from submit_job. It also names the natural follow-up (check_job) and implies the draft→check→submit pipeline without ambiguity.

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

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

Gives concrete usage guidance: 'dev=True uses the dev QoS ... test there first' and an explicit exclusion ('array_args ... not together with `array`'), plus the next step via check_job. It does not state when to prefer this over job_templates or explicitly say 'call this before submit_job', so it stops just short of full routing 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?

With destructiveHint=true and openWorldHint=true already declared, the description still earns credit by naming the mechanics (tar over SSH), the retry behavior, and the concrete destructive consequence ("overwrites files of the same name"). It stops short of disclosing auth/login prerequisites for `host`, which matters given the `start_login` sibling.

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

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

Three compact sentences, front-loaded with the core action and scope, with parentheticals carrying secondary constraints. No sentence 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 transfer tool with no output schema and zero schema coverage, the description covers mechanics, overwrite hazard, retries, and the size cap well. It leaves open what the call returns (copied paths? byte counts?) and the host-omitted behavior, which an agent would still have to discover.

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 carries the burden and does reasonably: `max_mb` is given meaning as a refusal threshold, `local_dir` as the destination, and `host` is cross-referenced to `push_files`. It does not explain what a null/omitted `host` means (default null in schema) or the units/naming of remote vs local, leaving one real 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 (copy) and resource (file or directory) with explicit directionality: from the cluster into `local_dir` on `host`. The reference to `push_files` plus the directional framing lets an agent distinguish it from the reverse-transfer sibling without opening either schema.

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

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

The parenthetical "fetch subdirectories of big results" is genuine routing advice for the max_mb failure case, but there is no explicit statement of when to pick this over `run_command` or how it relates to the login/cluster siblings. Usage is implied by "from the cluster" rather than spelled out.

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 and openWorldHint, so safety is covered; the description adds substantive behavior beyond that: the 20-file cap on log tails, that tails are 'cleaned', the scope spanning every array task and requeue attempt, and what the diagnosis contains (categories, signatures, transient meaning). It does not disclose cost/latency of scanning many logs or behavior on an unknown job_id.

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?

Dense but efficient: every clause corresponds to actual returned content, and the diagnosis sentence is dedicated to the failure case. It is slightly front-loaded as a field list rather than an opening verb+resource statement, which costs a little scannability.

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, and the description more than compensates by describing the returned fields and the structure of the diagnosis object in detail. Combined with read-only annotations, an agent has enough to call it correctly; the only residual gap is parameter-level guidance, scored separately.

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, so the description must carry the load and does not. job_id is never characterized (format, whether array task IDs are accepted) and log_lines — the parameter that most affects output volume, default 30 — is not mentioned at all, even though the 'at most 20 files' cap implies per-file tails.

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 enumerates precisely what is returned for a job: state, exit code, times, time limit, nodes, cost, sbatch command line, pending reason/dependency, and log tails, plus a failure diagnosis. That is a specific, differentiated resource. It stops short of naming siblings such as job_log or list_jobs, so the agent must infer the boundary from content 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?

Usage is implied by the diagnosis clause ('An ended job that failed... gets a diagnosis'), which tells the agent this is the tool for post-mortem inspection. There is no explicit 'use X instead when…' guidance against siblings like check_job or job_log, and no statement of prerequisites, though the sibling overlap is real.

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 only declare readOnlyHint/openWorldHint, yet the description discloses real behavior: text is cleaned (ANSI colours and binary bytes removed, \r progress lines collapsed), benign lines are dropped and counted in benign_hidden, and a missing log while pending is normal due to node prolog. That last negative-case caveat is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the resource statement and no filler sentences; each option sentence adds information. However it is a single dense paragraph with options (grep, progress, hide_benign, raw) run together, which hurts scannability for a tool with eight parameters.

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 eight-parameter, no-output-schema tool, the description covers input semantics and output transformations well, but nothing is said about truncation or output size limits (despite a 20-file cap and a default 100-line tail). An agent could still call it correctly, but size expectations remain unset.

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

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

With 0% schema description coverage, the description carries the whole burden and does so for 7 of 8 params, including glob syntax with %j/%x/%A/%a substitution, a 20-file cap, extended-regex grep matched per line, and progress field semantics. The `lines` parameter is never mentioned, leaving the tail size 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?

Opens with a specific verb+resource: 'Tail of a job's stdout (stream='out'), stderr ('err') or of `file`', which tells an agent exactly what comes back and from where. It is clearly distinct from siblings like job_details or check_job, which describe jobs rather than emit their log text.

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

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

Gives concrete selection conditions for each mode: 'For array jobs pass the task id (123_4) to see one task', progress=True to get progress bars instead of text, hide_benign=True to drop harmless noise. It never explicitly routes to a sibling or states when not to use the tool, so no exclusions are present.

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 openWorldHint=false, so safety is covered. The description adds the two-mode behavior (list vs. single-script-with-helpers) and that list entries carry summaries from comments and resources, which is useful extra context. Nothing about caching or scale limits, but the bar is lower with annotations present.

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?

Opens with what the templates are, then the no-name/with-name behavior, then the routing advice — a sensible front-loaded order with no filler sentences. It is dense and slightly run-on in the parenthetical lists, but every clause carries information.

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

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

With no output schema, the description does the work of explaining what is returned in each mode (summaries plus resources for lists; script and helper scripts for a named lookup). Given read-only annotations and a single optional parameter, that is close to sufficient, with only name-format details 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 coverage is 0%, so the description must carry the lone parameter, and it does: no name yields the list, with name (as listed or as a file name) yields the script plus its helper scripts, and it notes the accepted forms. That meaningfully exceeds the bare `name: string` schema, though it doesn't specify name format or ambiguity rules.

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 (tested job scripts / templates from jobs/ and config directories) and implicitly the action of listing or retrieving them via the name/no-name dual behavior. It distinguishes itself from draft_job by naming it explicitly, though the verb itself is never stated outright.

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 says 'Prefer draft_job for a new job; use these for patterns it does not cover' and then names concrete uncovered patterns (vLLM multi-node benchmarks, DDP training, CPU-node arrays, container pulls). This is a clear when/when-not/alternative rule an agent can act on directly.

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, so safety is covered; the description's added value is that this reads a *local* ledger at ~/.local/state/amadeus/jobs.jsonl overridable via AMADEUS_LEDGER, which is genuinely useful. It does not disclose ordering, freshness, or whether entries exist only for commands issued from this machine.

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 compact sentence with no filler, and the core content (what the ledger contains) is front-loaded. The lack of a leading verb and the parenthetical path make it read as a fragment rather than a directive.

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, yet the description never characterizes the records returned (fields of a submission/update/cancellation entry), leaving the agent unable to anticipate the response shape. For a history-inspection tool with zero annotation detail beyond read-only, this leaves a meaningful gap.

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

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

Schema coverage is 0%, so the single `last` parameter (default 20) is undocumented anywhere. The phrase 'the last submissions' hints that it bounds recency/count, but no maximum, default, or ordering behavior is stated, so the description fails to compensate for the schema 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 the resource and its contents (a ledger of recent submissions, updates, cancellations, approved commands), so the agent can infer it returns a command history. However it is a noun phrase with no verb ('Lists'/'Returns'), and it never contrasts itself with the many similar siblings (job_log, list_jobs, job_details), which makes selection ambiguous.

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 call this instead of job_log, list_jobs, or check_job, and no prerequisites or exclusions are stated. The agent must infer usage purely from the noun phrase.

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 openWorldHint=true, so safety and scope are covered, and the description adds genuinely new context about where issues originate (report_issue or automatic creation). It says nothing about ordering, pagination, or how large the result set can be, which matters for an open-world list.

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 clauses with no filler, and the resource identity plus provenance come first. The status enumeration is compressed into a single line, though the leading fragment lacks a verb, making it read more like a label than a description.

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 list tool with annotations covering safety, the description plus the value set is nearly sufficient. It still omits the default filter behavior, result ordering/paging, and any indication of what an issue record contains, which an agent listing issues would reasonably want.

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% — the 'status' property has no description and no enum — so the description is the only place the accepted values (open, in-progress, needs-human, fixed, wontfix, duplicate, all) are documented, which is substantial added value. It does not restate the schema's default of 'open' or explain what 'all' returns, leaving a small 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 the resource (issues) and its provenance (filed via report_issue or automatically), which is enough to tell it apart from the sibling report_issue (which files them) and from unrelated siblings like list_jobs. It never states the verb 'list' explicitly, relying on the tool name to carry that, so it falls short of a full verb+resource statement.

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 implicit pairing with report_issue hints at where issues come from, and the status list implies the tool can be filtered, but there is no explicit 'use when you need X' or 'do not use for Y' guidance. The agent must infer that this is the read-side counterpart to report_issue.

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 this is read-only and open-world, so the safety profile is covered. The description adds useful behavioral context: arrays are collapsed to one row, purpose is present only when submitted through this server, node/token limit information is included, and pending-job start estimates are explicitly described as unreliable. It does not describe ordering, pagination, or scope limitations beyond 'my' jobs, but it adds substantial 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?

The description is front-loaded with the core action and resource, then adds only relevant output details and caveats. Both sentences earn their place by clarifying array handling, included job metadata, and pending-job caveats without unnecessary 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 input parameters and no output schema, the description carries the burden of explaining what the listing returns. It covers the relevant returned information and caveats, including pending-job start estimates and reasons. Annotations cover read-only/open-world behavior, leaving no major contextual gap for invoking the tool.

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

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

The tool has zero parameters, so the baseline is 4. The empty schema requires no parameter explanation, and the description appropriately focuses on output content instead.

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

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

The description clearly states the verb and resource: listing the caller's running and pending jobs. It also adds specific output semantics such as arrays shown as one row, purpose, node/token limits, and pending-job fields. It does not explicitly name sibling alternatives like job_details or check_job, 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 scope 'My running and pending jobs' and by the note about pending-job fields. However, there is no explicit guidance on when to use this instead of job_details, check_job, wait_for_job, or other job-related siblings. The agent can infer a basic use case but must choose among alternatives without help from the description.

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 flag destructive/openWorld, and the description adds substantially more: it explains the resource-sharing execution model, the approval mechanism for deletions and process signalling, and — critically — that the approval check resolves the command word even when wrapped in timeout/nice/env/xargs/bash -c, and that os.kill inside `python -c` is also gated. That is exactly the kind of circumvention detail an agent could not infer from the annotations.

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

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

Front-loaded with the action and the transport rationale, then examples, then constraints, then the approval rules — a sensible ordering with little filler. The nested parentheticals around the approval-check circumvention make the final third dense enough to require a second read.

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 ideally say what comes back (stdout, exit status, truncation on long output, behavior on timeout), which it omits. Everything an agent needs to invoke the tool correctly — preconditions, node selection, timeout bounds, approval requirements — is otherwise 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%, so the description must carry the load, and it mostly does: `node` is defined as one of the job's nodes with first-node default, `timeout_s` is bounded 5–120, `approval` is defined as the human's own words for destructive/signalling commands, and `job_id`/`command` are constrained by the RUNNING-job and diagnostic-only framing. It stops short of stating the job_id format or whether `node` accepts a short hostname versus FQDN.

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 short diagnostic command on a compute node of one of the user's RUNNING jobs — and immediately distinguishes itself from ssh and from login-node execution via the `srun --jobid=<id> --overlap` mechanism. An agent can tell this apart from `run_command` and `job_log` without opening any schema.

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

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

Gives concrete typical invocations (nvidia-smi, top, free, py-spy, tail of node-local log, df -h /local) that define the intended use envelope, plus explicit exclusions: no background processes, no srun, timeout bounded 5–120s, and only for RUNNING jobs. It references `run_command` for shared rules but never explicitly says when to pick that sibling over this one, so it stops short of full routing 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?

Goes well beyond the destructiveHint=true annotation: it discloses that a failed push changes nothing (staged), that it overwrites same-name files but never deletes others, that operations are retried, and that it warns when pending/running Slurm jobs occupy remote_dir. This precisely scopes how destructive the tool actually is, which the annotation alone cannot convey.

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

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

Front-loaded with the core action and dense with useful facts; every clause carries information. It is a run-on paragraph with stacked parentheticals, though, and bullet points per parameter would scan faster for an agent parsing constraints.

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 5-parameter mutating tool with no parameter descriptions and no output schema, the description covers almost everything an agent needs: path restrictions, mode semantics, overwrite behavior, and job-conflict warnings, even pointing at the result's 'host' field. Only the `exclude` parameter remains unexplained.

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

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

With 0% schema coverage the description carries the load, and it does so for host (including '' semantics and the default client machine), mode (both enum-like values explained), and the path constraints for local_dir and remote_dir. The `exclude` parameter is never mentioned or exemplified, leaving one of five parameters undocumented anywhere.

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?

Opens with a precise verb+resource+destination: "Copy a directory to the cluster", and adds the mechanism (tar over SSH, retried, staged). Directionality ('push' to cluster) makes it unmistakable against the sibling fetch_files without needing to name it.

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

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

Gives explicit when-to-use guidance for both modes (tracked = code repositories; all = everything except .git/venvs/caches/*.sif) and an explicit when-not: "Code only: big data is fetched in jobs." That constraint steers the agent away from using this for data transfer.

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?

Adds context beyond the annotations: it discloses the return value ('Returns the issue id'), imposes a 'No secrets' constraint, and clarifies severity semantics. The annotations already cover the mutation/open-world safety profile, so this supplementary guidance is meaningful without needing to restate it.

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?

Four dense lines, front-loaded with purpose, then value enumerations, then required content, then the safety constraint and return value. Every clause carries information an agent would otherwise have to guess.

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 8-parameter write tool with no output schema and no schema descriptions, the definition covers the important pieces, including what is returned. It could say more about where the report is sent (openWorld behavior) and what happens to the stored issue, which keeps it at a 4.

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 there are no enums in the schema, yet the description supplies the closed value sets for kind and severity and maps the narrative fields (tool name, arguments used, actual result, expected, project) to parameters. Only 'reproduce' and the role of 'title' remain implicit, keeping it just short of a 5.

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 ('Report a problem with this server or the cluster interface') and scopes it to the maintainer session that fixes issues. It distinguishes itself from the sibling list_issues, which is described as the read-side counterpart for checking status.

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

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

Gives concrete filing guidance (include tool name, arguments, actual vs expected result, project), defines the kind values and severity levels including what 'high' means, and redirects to list_issues for status tracking. It does not explicitly say when *not* to file an issue or name alternative channels, so it stops short of a 5.

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

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

Annotations already declare destructiveHint and openWorldHint, but the description adds substantial context beyond them: the explicit refusal list, the human-approval gate for rm/mv/rsync --delete, the fact that a command is not re-run after SSH failure, and the recovery case where re-running is safe. These are operational behaviours the annotations cannot express.

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

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

Front-loaded with the core purpose, then layered constraints, all in imperative sentences with no filler. The parenthetical sacctmgr example and the recovery note add length but are each actionable, so density is justified rather than 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 destructive, open-world execution tool with no output schema, the description covers safety, refusal policy, approval flow and failure semantics extremely well. What it omits is the return shape (stdout/exit code handling) and the meaning of timeout_s, which an agent managing long commands would want.

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 load; it explains lmod=True (initialises Lmod for `module`) and approval (the human's own words), covering two of the non-obvious parameters. timeout_s is never mentioned and command's semantics are only implied through the env-expansion note, so a small gap remains.

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 plus execution context ('Run a shell command on the login node (bash, non-interactive)'), which immediately separates it from node_exec (compute nodes) and submit_job. The env-var expansion note ($DATA, $SCRATCH, $USER) further pins down what kind of shell it is.

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

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

Explicit when-to-use ('light work only: no compute, builds or big downloads') and names the correct alternative for each excluded case: submit_job, cancel_job, update_job, node_exec. It also flags the approval precondition for destructive file operations and the sacctmgr read-only exception, leaving nothing to inference.

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

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

Beyond the annotations, it discloses important behavior: the returned link expires after about 60 seconds, must be shown immediately, and only one login runs at a time. These are operationally critical details an agent would not infer from readOnlyHint/openWorldHint/destructiveHint alone.

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 front-loaded with the core action and return value, then layers on expiry, concurrency, and call-context constraints. Every sentence carries actionable information without waste.

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 appropriately states that it returns the device link and explains its short expiry. It also covers the concurrency limit and when the tool should be invoked, making it complete for a zero-parameter login-initiation tool.

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

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

The tool has zero parameters, so parameter semantics are inherently minimal and the baseline is 4. The description does not need to explain any arguments.

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

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

The description names a specific action and resource: start a certificate login or early renewal, returning a device link. It is clear what the tool does, though it does not explicitly differentiate from the related access_status sibling.

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

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

It gives explicit call conditions: only when answering a message from the human, and not from cron, /loop, or stop-hook turns. It also notes that only one login can run at a time, which further scopes correct invocation.

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?

Goes well past the annotations by disclosing the submit-on-hold → validate-against-Slurm → release-or-cancel sequence, the refusal conditions (missing model/container/env/input), the --dependency and allow_missing=True warning paths, and how the approval gate is enforced. These are operational behaviors an agent could not infer from readOnlyHint/destructiveHint/openWorldHint.

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

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

Front-loads the core action and secondary effect in the first sentence, then documents parameters in order. Every clause is substantive, but the heavy parenthetical nesting and run-on enforcement clauses (approval thresholds, dependency/allow_missing carve-outs) make it denser than needed.

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 8-parameter mutation tool with no output schema and 0% schema coverage, the description covers submission flow, validation, refusal conditions and the approval gate thoroughly. Gaps are minor: `script_args` is undocumented and it does not say what comes back (job ID, ledger entry) on 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 coverage is 0%, so the description must carry the load and it mostly does: `script` (path semantics, relative to `cwd`, default workdir, text refused), `purpose`, `approval` (detailed thresholds), `sbatch_args` ('pass each sbatch option and its value as separate items'), `expected_minutes`, and `allow_missing` are all explained. `script_args` is never mentioned and `cwd` is only referenced obliquely, so it falls short of full coverage.

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 ('Submit a batch job') and adds the two secondary effects: runbook validation and recording in the local ledger. It also names the related sibling ('see check_job'), so an agent can distinguish this from check_job and draft_job without inspecting either schema.

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

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

Explicitly routes away from wrong usage: 'script text is refused (check a draft with check_job(script_text=...), then save it in the project, push_files, submit)' names the alternative tools and the ordering. It also gives concrete when-required conditions for `approval` (node count, token threshold, B200/long/priority QoS, headsup_nodes).

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 flag destructiveHint=true and openWorldHint=true, but the description adds context those fields cannot: MUSICA rejects raising a running job's limit while lowering works, and the new limits are re-validated like a submission. Authorization requirements (approval for >20 tokens and for jobs not submitted via this server) are also disclosed, which is meaningful beyond the annotations.

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

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

It is compact and front-loads the action and the mutable fields before moving to constraints and approval rules. The parenthetical example is efficient; a few clauses are dense but none are 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 destructive six-parameter mutation with no output schema, the description supplies the prerequisite conditions, validation rules, and approval gating an agent needs before calling. What remains unstated (return value, whether hold/release are mutually exclusive with the other fields) is minor.

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

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

With 0% schema coverage, the description must carry parameter meaning, and it largely does: it gives a format example for time_limit ('02:00:00'), restricts nodes to pending jobs, and explains what approval represents (the human's words) and when it is required. Only job_id and the default-empty semantics of hold/release are left implicit.

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

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

The description opens with a concrete verb-plus-resource ('Change a job') and enumerates the mutable fields (time limit, node count, hold/release), which clearly separates it from submit_job, cancel_job, and job_details. It stops short of naming the sibling alternatives explicitly, so it is clear but not fully differentiated.

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

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

It states a real precondition ('pending jobs only' for node count and for raising a limit) and explains the lowering exception, giving the agent enough to decide when the call will succeed. It does not, however, say when to prefer cancel_job or hold over this mutation, leaving one routing decision implicit.

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

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

Beyond the readOnly/openWorld hints it discloses durable, non-obvious behavior: state lives in Slurm, so after a restart or dropped connection you just call again with the same ids, and alarms already returned come back as info without ending the call. It also bounds the call (max_wait_s 10–3600) and explains that 'a COMPLETED state can hide a failed run,' which is exactly the kind of nuance an agent cannot infer.

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

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

The core behavior is front-loaded in the first two sentences before the option-by-option detail, and every clause carries real meaning (event names, tuning thresholds, failure diagnosis). It is dense to the point of reading as a wall of text, but there is no filler to cut.

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 nine-parameter blocking tool with no output schema, the description covers what an agent needs: the returned event vocabulary (STARTED, ENDED, FAILED, MILESTONE, LATE, QUIET, OUTPUTS_MISSING), the tri-state 'finished' return including the not-found case, and cursor reuse. Only the poll_s interval is left unaddressed.

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

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

With 0% schema description coverage the description must carry all nine parameters, and it does: 'until' modes, the milestone object shape {pattern, within_s, file}, quiet_alarm_s values with tuning advice (300 for big runs, 120–180 for testing), expect globs with %j/%x/%a, and log_cursor round-tripping. The only undocumented parameter is poll_s, leaving a small tuning 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 — 'Wait for one job (job_id) or several (job_ids) and return at the first event that matters' — plus what comes back (new log lines since the last call). This clearly distinguishes it from passive siblings like job_log, job_details, check_job and list_jobs by establishing that it blocks until a condition is met.

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?

'Never build sleep/sacct watcher loops or background monitors. Each poll is one SSH command for all jobs' gives explicit negative guidance that routes the agent away from manual polling. The 'until' mode list clarifies which condition to select for which outcome, though it never names a sibling tool as an alternative for non-blocking queries.

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