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 real context by revealing it works off seff/sacct output, implying it analyzes completed jobs, but omits prerequisites (job must have finished, accounting data available) and the profile/auth requirement.

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

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

A single front-loaded sentence with no filler; the core action and both operand modes appear 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?

With no output schema, the description should at least sketch what a right-sizing recommendation contains and what preconditions exist; it does neither. It is minimally adequate for a three-parameter analysis tool but leaves notable 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 33% (jobId and lastN are undocumented in the schema), so the description must compensate. It partially does by mapping 'a job' to jobId and 'your recent runs' to lastN, but never explains mutual exclusivity, precedence, or the jobId pattern format.

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 outcome ('recommend right-sizing') plus the resources it works on ('a job or your recent runs'), and names the underlying mechanisms (seff/sacct). It is clearly distinct from pre-run siblings like ris_estimate_resources, though it never says so 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 phrase 'for a job or your recent runs' implies the two usage modes, but no when-to-use/when-not guidance or named alternative (e.g. ris_estimate_resources for pre-run planning) is given. Usage must be inferred from the parameter hints.

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. The description adds real value by disclosing the deep=true escalation (runs the decisive key-only login test) and the openWorld reach implied by host/user/profile, but says nothing about return contents or side effects of the probe.

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

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

One dense sentence plus a second for the deep=true escalation, front-loaded on what the snapshot contains. No filler, though the parenthetical list is slightly cramped.

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, so the description should carry more about what the snapshot returns and what 'hands-free' verdicts look like. It covers the diagnostic intent and the deep flag but leaves four of five parameters unexplained and the return shape unspecified.

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

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

Schema coverage is 20%: only 'profile' is documented. The description covers 'deep' implicitly but says nothing about host, user, or alias and how they interact with profile selection. The description does not compensate for the four undocumented parameters.

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

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

States a specific resource (local SSH-auth state) and enumerates what is snapshotted (key, managed config, mux master) plus the agent-runnability verdict. It doesn't explicitly name the close sibling ris_check_ssh_master or ris_test_key_only_auth, so differentiation is left to inference.

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 routing to alternatives. Given siblings like ris_check_ssh_master and ris_test_key_only_auth, the description fails to say why an agent would call this aggregator instead of them.

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 a non-read-only, non-destructive, open-world operation; the description usefully adds that it creates directories, submits a persistent daemon that polls jobs, and that dryRun defaults to a preview. That dryRun-default safety disclosure is valuable context beyond the annotations. It stops short of stating permissions, idempotency, or re-run 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?

A single dense, front-loaded sentence that packs the setup action, the resource, the mechanism, and the dryRun default without waste. Dense but every clause earns its place.

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

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

For a mutating, no-output-schema tool with five params at 20% coverage, the description covers the high-level action and the safety default but leaves the remaining parameter semantics and post-bootstrap state (how to then enqueue/monitor) unexplained. Adequate but with 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 coverage is only 20% (just the profile field), so the description is expected to compensate and does not. It reinforces the dryRun default but says nothing about account, walltime, or pollSeconds (which has a 5-600 range the agent should understand).

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 (Set up/bootstrap) and resource (per-user RIS worker), and details the two concrete actions: creating control-plane dirs under <workspace>/.risbridge and submitting a low-resource general-cpu daemon. It is clearly the setup tool among the worker siblings (status/cancel/enqueue), though it never names those alternatives explicitly.

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

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

Usage is implied (you bootstrap the worker so it can submit/poll jobs and avoid repeat Duo logins), and the 'dryRun preview by default' note signals a safe first-run pattern. However there is no explicit when-to-use guidance relative to ris_worker_status or ris_worker_enqueue, nor stated 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?

Adds real behavior beyond the destructiveHint=true annotation: ownership is verified before cancellation, and a confirm=true flag gates the action. It does not state whether the cancellation is reversible or what happens on confirm=false, but the confirmation gate is valuable context the annotations don't provide.

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

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

Two tight sentences, front-loaded with purpose, then the two key invocation constraints. No wasted words.

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

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

For a destructive, annotation-covered mutation with no output schema, the description supplies the ownership check, the confirm gate, and the jobId/project fallback logic. Adequate; only the outcome/return behavior and profile handling are left 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 coverage is only 50%, but the description compensates by explaining the conditional relationship between jobId and project (jobId optional only when project scope given, else latest job). Only 'profile' goes undocumented, and that is covered by the schema description.

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 ('Cancel one of YOUR jobs') with a scoping qualifier (ownership verified first). It implicitly distinguishes itself from hold/release/worker_cancel siblings by emphasizing ownership and project scoping, but never names an alternative tool 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?

Gives concrete preconditions: confirm=true is mandatory, and jobId is optional only when a project scope is supplied (in which case the latest job in that project is cancelled). It stops short of saying when to prefer this over ris_hold_job or ris_worker_cancel.

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 read-only safety is covered. The description adds meaningful methodology detail: it uses both `ssh -O check` control-socket inspection AND a functional `ssh true` probe, implying a two-part verification. But it does not describe the outcome semantics (e.g., what constitutes pass/fail, how a stale socket differs from no master).

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, tightly packed sentence with no filler. The core action and the two verification methods are front-loaded and both earn their place.

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

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

For a read-only diagnostic tool with no output schema, the description explains the mechanism but not the result interpretation (e.g., success/failure distinction, connection prerequisites) or the alias/profile usage, leaving meaningful gaps for an agent needing to act on 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?

Schema coverage is 50%; the 'profile' parameter is documented in the schema, and 'alias' is left undocumented. The description mentions neither parameter, so it does not compensate for the 50% coverage gap. 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?

States a specific verb+resource ('Check the ControlMaster') and specifies exactly how the check is performed ('via ssh -O check AND a functional ssh true probe'). This distinguishes it from siblings like ris_open_ssh_master or ris_repair_stale_socket.

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

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

The description implies this is a diagnostic/detection tool for the SSH multiplexing master, which places it relative to open/repair siblings. However it does not explicitly say when to use it versus ris_open_ssh_master or ris_repair_stale_socket, nor any 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 readOnly, non-destructive, and open-world, so safety is covered. The description adds that it is a side-by-side multi-run view with specific dimensions (resources, exit state, elapsed, efficiency), but says nothing about ordering, scale limits, or failure handling for missing jobs.

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 comparison dimensions in a parenthetical. Nothing wasted, though the parenthetical carries more weight than the main clause.

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 comparison tool with no output schema, the definition is adequate but thin: an agent learns what is compared but not how jobs that are still running, missing, or beyond the max are handled.

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%: jobIds is inline-documented via pattern and bounds while profile has its own description. The description's '2+' maps to minItems=2 but adds no detail about the id format, max of 10, or profile preconditions, so it does not compensate 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 specific verb (compare) and resource (runs/jobs) with the enumeration of compared attributes, which is more than a bare restatement. It distinguishes itself reasonably from siblings like ris_explain_job or ris_job_history, though it doesn't name those alternatives 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 '2+' phrasing implies the minimum of two jobs required by the schema, but there is no guidance on when to choose comparison over ris_explain_job or single-run analysis, nor any exclusions. 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds meaningful behavior beyond them: submission is draft-by-default and requires explicit confirm, and stages are linked by afterok dependency ordering. It omits auth/profile requirements and what happens after confirm.

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, front-loaded with the action and the dry-run safety behavior. No filler or redundancy.

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

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

For a mutating, no-output-schema tool with 6 parameters and thin schema coverage, the description covers the dry-run/confirm gate but leaves open what is returned on submit (job IDs?), stage-count limits, and resource defaults. Adequate minimum but with 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 only 33%, so the description must carry weight, and it only clarifies dryRun and confirm semantics (already implied by schema defaults) plus the stage-chaining notion. The nested stage fields (cpus, memGb, gpuCount, walltime, partition, script) get no explanation in either place, so it does not fully 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 ('Submit a chain of Python jobs') plus the defining mechanism (--dependency=afterok between stages), which distinguishes it from single-job siblings like ris_submit_python_job. It doesn't name those siblings explicitly, 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?

Gives the operational flow ('dryRun preview by default; confirm to submit the chain'), which tells the agent how to sequence dry-run vs. real submission. It says nothing about when to choose a chained pipeline over a single submit tool or ris_plan_run, and no prerequisites are stated.

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

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

Annotations declare it is a mutation (readOnlyHint=false, destructiveHint=false) and openWorldHint=true. The description adds that the tree is the 'standard' one and goes under the user's /storage workspace, plus mentions a dryRun-capable schema, but doesn't say whether directories are skipped/overwritten if they already exist, which matters for a repeated-scaffolding 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?

One dense, front-loaded sentence with no filler. The directory listing is information-dense rather than padding, and the workspace location is stated at the end where it belongs.

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

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

For a scaffolding mutation with no output schema and partial schema coverage, the description covers what gets created well but is silent on idempotency/idempotent re-runs, permission needs, and how dryRun interacts with the tree. Adequate but leaves gaps an agent 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 coverage is 67%, above the midpoint. The description implies the project parameter names a directory and that a storage workspace is the root, adding marginal meaning, but says nothing about dryRun or profile beyond what schema already documents.

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 ('Create the standard project directory tree') and even enumerates the exact directories created. This distinguishes it from sibling setup tools, though it doesn't name any alternative directory-oriented tool.

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

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

No when-to-use guidance, no prerequisites, and no mention of related tools like ris_list_project_files or ris_plan_run. The agent gets no help deciding when this scaffolder is the right call vs other workspace operations.

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

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

Annotations already carry readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely valuable behavioral context: workspaces are derived from groups AND live-tested, and the tool never auto-selects, requiring confirmation. This is more than annotation repetition.

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, front-loaded with the read-only nature and scope, then the confirmation behavior. No padding, though the parenthetical is slightly compressed.

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 discovery tool with no output schema, the description covers scope, derivation method (groups + live test), and interaction model. It could note what happens if no writable workspaces are found, but it is essentially complete.

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 already 100% and documents the single profile parameter with its source file and default behavior. The description mentions no parameters, so it adds nothing beyond the schema; 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 (probe/read) and resource (RIS identity), and enumerates exactly what it returns: username, Slurm accounts/QOS, and writable storage workspaces. An agent can distinguish this from siblings like ris_auth_status or ris_show_config 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?

It describes the interaction contract ('presents candidates and asks you to confirm') but never explicitly states when to reach for this over ris_auth_status or ris_show_config. Usage is implied by 'discover your identity' but no alternatives or exclusions 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 declare the operation is not read-only but not destructive, and the description adds meaningful context beyond them: the default PyTorch CUDA-12.4 wheels choice, that the build happens automatically with zero manual steps, and that a preview/confirm gate protects the mutation. It omits anything about duration, failure modes, or what the confirm gate returns.

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

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

A single front-loaded sentence with zero waste, and the key operational facts (auto-build, default wheels, dry-run/confirm flow) are packed in ahead of any detail 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?

For a mutation tool with no output schema and 9 low-documented parameters, the description covers the overall flow and safety gate but leaves the majority of parameter semantics unaddressed. It is adequate to know what the tool does, but not complete enough to call it well without opening the schema.

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

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

Schema description coverage is only 22% across 9 parameters, so the description must carry the semantic load. It clarifies dryRun, confirm, and the framework default (PyTorch CUDA-12.4), but says nothing about python, account, envName, packages, or profile, leaving most parameters undocumented in both places.

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 ('ensure exists'), the resource (conda environment for a project), and the auto-build behavior when missing. This clearly distinguishes it from siblings like ris_list_conda_envs, ris_inspect_conda_env, and ris_submit_conda_env_job, which list, inspect, or run in an env rather than create one.

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 describes the two-phase workflow: 'dryRun preview by default; confirm to build,' which tells the agent how to invoke it safely. It does not, however, state when to prefer this over alternatives such as ris_create_project or a conda-env submission job, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description meaningfully adds that the result is 'heuristic' and 'offline', signaling the output is an advisory estimate rather than an authoritative allocation. It does not, however, describe return shape, accuracy limits, or what happens when inputs are sparse.

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, front-loaded sentence with no filler; the action and subject come first. It is arguably under-specified for a 7-parameter tool, but on the conciseness axis itself it is efficient.

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 7-parameter tool with no output schema and 14% schema coverage, the description is far too thin: it neither explains the input parameters nor describes the returned estimate in any detail. It does nominally name the five output fields, but leaves the tool under-documented relative to its 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 only 14% (only 'profile' is documented), so the description carries the burden of explaining the other six parameters, and it does not. The fields it lists (cpus/mem/gpus/walltime/partition) are outputs, not inputs, so it adds no meaning to inputs like jobType, framework, epochs, modelParamsB, or datasetSizeGb.

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 clear action (suggest/estimate) and the resources it targets (cpus/mem/gpus/walltime/partition), so the core purpose is discernible. However, it frames the input as 'from a description' while the schema exposes only structured fields (jobType, framework, gpuCount, etc.) with no free-text description parameter, creating a mismatch. It also gives no differentiation from plausible siblings like ris_plan_run or ris_generate_sbatch_template.

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 mention of prerequisites, and no exclusions or alternatives. The agent must infer that this is a pre-submission planning step, with nothing pointing it away from overlapping siblings.

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=true, so safety is covered. The description adds real behavioral context beyond that: it discloses the return shape (state + reason + seff + log tail + suggested fix) and the defaulting behavior when jobId is omitted, which is more than the annotations 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?

A single dense sentence plus a short defaulting clause; the output contents are front-loaded before the optional-argument note. No filler, no repetition of the tool name or title.

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

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

There is no output schema, so the description carries the burden of describing results, and it does so by naming the five things returned. For a read-only diagnostic with zero required parameters, that is nearly sufficient; only the tailLines control and any auth/profile prerequisite go unaddressed.

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

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

Schema description coverage is 50% — profile and project are documented in-schema, while jobId and tailLines have only patterns/defaults. The description compensates meaningfully for jobId by explaining it is optional and defaults to the most recent job, or the latest in a given project, which the schema does not say. tailLines is never mentioned, leaving one parameter's purpose to inference.

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 ('explain' a 'job') and enumerates the payload an agent gets: state, reason, efficiency (seff), log tail, and a practical fix. That combination distinguishes it cleanly from siblings like ris_get_job_logs, ris_tail_job_logs, and ris_analyze_efficiency, which each cover only one of those facets.

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 'why-pending / why-failed' framing gives clear context for when this diagnostic is the right call, and the note that jobId is optional with a most-recent-job default tells the agent it can invoke with no arguments. It stops short of naming alternatives or stating exclusions (e.g., when to prefer raw log tools), so it is clear context without 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description reinforces this with 'Generate only — never submits,' which is meaningful for a tool sitting next to 10 submit_* siblings, but it says nothing about the return shape (raw script text? file path?) despite there being 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?

Two short sentences, zero filler, with the core capability front-loaded and the critical non-submitting constraint placed immediately after. Nothing could be trimmed without losing signal.

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 9-parameter tool with 22% schema coverage and no output schema, the description is too thin: it explains neither how the parameters shape the rendered script (e.g., how partition/jobType interact) nor what the caller receives back. The generate-vs-submit distinction is well covered, but the operational detail an agent needs to call it correctly is missing.

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

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

Schema description coverage is only 22% — just 'profile' and 'project' are documented, while cpus, memGb, account, jobType, gpuCount, walltime, and partition are bare. The description adds no parameter meaning at all beyond a generic nod to 'job type,' so it fails to compensate for the coverage gap on a 9-parameter tool.

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 ('Render a ready-to-edit sbatch script') and immediately scopes it with 'for any job type.' The clause 'Generate only — never submits' explicitly separates it from the many ris_submit_* siblings, so an agent can route correctly 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?

The 'never submits' clause implies the intended situation (you want to inspect/edit a script rather than launch a job), which is useful context. However, it never names an alternative tool (ris_plan_run, ris_run, ris_submit_python_job, etc.) or states the explicit condition for choosing generation over submission, leaving the agent to infer the routing.

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=true, destructiveHint=false and openWorldHint=false, and the description is consistent with them. It adds genuine context beyond the annotations: the block includes multiplexing settings, a diff is produced, and nothing is written. Missing detail on multiplexing parameters or diff format keeps it from a 5.

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

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

Two tight sentences with no waste; the non-writing constraint is front-loaded right after the rendered artifact, which is the most decision-relevant fact.

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

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

The description covers the return artifact (config block plus diff) in lieu of an output schema, which is helpful. However, for a 5-parameter tool with no required fields and almost no schema documentation, the description leaves how host/user/alias/controlPath shape the output entirely 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?

Schema description coverage is only 20% (just 'profile'), leaving host, user, alias and controlPath undocumented in both schema and description. The description adds no semantics for any parameter, 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 gives a specific verb (render/propose) and resource (the managed ~/.ssh/config block plus a diff), and the phrase 'Does NOT write anything' implicitly separates it from the write counterpart ris_write_ssh_config. It stops short of naming that sibling explicitly, so it is clear but not maximally 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?

There is no explicit when-to-use statement or named alternative, but 'Does NOT write anything' strongly implies this is the preview path and that ris_write_ssh_config applies the change. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior ('byte-capped, restricted to its log files'), but says nothing about truncation handling, pagination, or how to obtain the full log beyond the cap.

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 no filler, and the resource plus its constraints are front-loaded ahead of the parameter note. Slightly telegraphic in the parenthetical, 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 should describe what comes back and how large/truncated logs behave, especially given a 200KB default cap. It covers the safety/scope side but leaves return shape, stream selection, and truncation recovery to inference.

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

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

Schema coverage is only 40% (jobId, stream, maxBytes undocumented), so the description should compensate more than it does. It does add real value by stating jobId is optional and defaults to the most recent job, and hints at the byte cap, but never explains the stdout/stderr/both stream enum or the maxBytes limit.

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?

Names a specific verb (Fetch) and resource (a job's stdout/stderr) with clear scope. However, it does not distinguish itself from the close sibling ris_tail_job_logs, so an agent still has to guess which log-reading tool applies.

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

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

It gives one routing clue ('jobId optional — defaults to your most recent job'), which implies usage when the specific job is unknown. It offers no explicit when-to-use guidance versus ris_tail_job_logs or any other alternative, leaving selection 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, indicating a safe, read-only operation that may access external resources. The description adds that it cross-references local run history, which implies data may be combined from multiple sources, but it does not disclose where manifests are stored beyond 'project/manifests', whether profile affects storage location, or any rate limits or return format details. With annotations covering safety, this is a moderate addition.

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 compact sentence that front-loads the primary action and mentions the secondary listing behavior. It is efficient but could be slightly clearer without being verbose.

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 does not explain what the manifest JSON contains or what the list of manifests looks like. For a tool with three parameters, partial schema coverage, and no annotations on return values, the description should provide more context about the expected outputs and how to interpret them.

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 67%, and the description does not add any parameter-level meaning beyond what is in the schema. The schema describes 'profile' and 'project' but leaves 'runId' undocumented; the description does not compensate. Baseline 3 when schema does most of 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?

The description says it reads a run's manifest JSON or lists available manifests, which is a specific verb and resource. However, it does not clarify how it differs from many other sibling tools that deal with runs or job history, and the phrase 'manifest JSON' assumes domain knowledge. The dual read/list behavior is mentioned but not clearly separated.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. The description does not explain when to use this tool versus alternatives like ris_job_history or ris_list_my_jobs for accessing run information. The dual mode (read manifest vs. list manifests) is noted but without conditions for choosing one over the other.

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=true, so the safety profile is covered. The description does add scope constraints (full H100s only, MIG slices excluded) which is behavioral context. It does not cover return format or whether data is cached/realtime, hence a 3.

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 front-loaded resource and a parenthetical scoping clause. No 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?

No output schema, so the description should describe return shape (per-node values, granularity) and profile/partition meaning. It omits both, leaving key calling details undocumented for a 2-param 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 50%. The description never mentions profile or partition, or the default partition=general-gpu, and doesn't clarify the meaning of partitions like general-preempt-gpu vs the default. With half the parameters undocumented, the description fails to compensate.

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 (per-node H100 free/used) and scope (GPU partition, full H100s only, MIG excluded). Clear verbless but useful read. No explicit sibling differentiation, though among many siblings (ris_worker_status, ris_list_partitions) this reads distinctly about H100 availability.

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 mention of alternatives such as ris_list_partitions or ris_worker_status, and no conditions for choosing this tool. Only implied usage from the purpose.

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, yet the description adds genuinely new behavior: ownership verification and a confirm gate before the action takes effect. It stops short of saying what holding actually does to the job's scheduling state, how long it persists, or how it is undone.

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

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

Three short sentences with zero filler. The action and its scope come first, followed by the confirm prerequisite and the conditional jobId rule, so nothing important is 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?

For a destructive, no-output-schema mutation tool the safety essentials (ownership, state, confirm) are covered, which is the critical part. What is missing is the operational meaning of a hold — whether the job stays queued, whether it is reversible, and how it relates to the release sibling.

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% — jobId and confirm have no schema descriptions — so the description has to carry them, and it does: confirm must be true, and jobId is optional only when a project scope is supplied. That clarifies both undocumented parameters and their dependency, though the jobId pattern/format is not explained.

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

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

States a specific verb (Hold) plus resource (one of YOUR pending jobs) and adds a scope constraint (ownership verified), which implicitly separates it from cancel/release siblings. It does not, however, name or explicitly contrast against any sibling such as ris_cancel_job or ris_release_job, 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?

"Requires confirm=true. jobId optional only with a project scope." gives concrete preconditions for a successful call, which is real usage guidance. It still never says when to reach for hold versus cancel or release, so the when/when-not framing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the named-vs-path scoping dimension but says nothing about return format, whether packages include versions, or how an unreachable/remote env is handled — with annotations doing the heavy lifting, this is adequate but thin.

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 operation and its target are stated before any qualifier.

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 4 parameters, no output schema, and only 50% schema coverage, the definition is minimal. It never says what a package entry looks like (name only, name+version, channel) or whether profile/project scope the inspection, leaving the agent to discover the result shape by calling it.

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

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

Schema coverage is only 50% (envName and envPath carry regex patterns but no prose). The description compensates by clarifying that the two selectors are a name or a path, signaling they are alternate ways to target the same env rather than independent options — meaningful semantics not present in 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+resource: 'List packages' scoped to 'a named or path-based conda env'. This implicitly separates it from ris_list_conda_envs (which enumerates envs, not their contents), but it never names or explicitly contrasts that sibling, 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 when-to-use guidance, no statement of prerequisites (e.g., that the env must exist or be reachable), and no guidance on choosing between the two env selectors. The word 'or' hints the selectors are alternatives, but no usage rule is stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results are finished jobs merged from sacct and local history, which is useful source-of-truth context, but it doesn't cover ordering, truncation via limit, or what merging implies for duplicates.

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 zero waste, front-loading the resource and scope. Appropriate for a read-only listing tool.

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

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

With 4 params, no output schema, and full annotation coverage, the description is minimal but functional. It leaves the agent to infer ordering, the effect of limit/sinceDays, and how sacct vs local history records are reconciled, which matters for interpreting results.

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 50%, with only profile and project described in-schema; limit and sinceDays are undocumented. The description mentions neither, so it fails to compensate for the half of parameters lacking schema documentation. Baseline 3 for adequate schema 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 and resource: 'Recent finished jobs via sacct, merged with local run history.' This tells the agent it's a read that combines two sources. It doesn't distinguish itself explicitly from siblings like ris_list_my_jobs or ris_analyze_efficiency, 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?

The word 'finished' implies scope (completed jobs rather than running or held), which is a partial when-to-use signal. There's no explicit guidance on when to prefer this over ris_list_my_jobs or ris_explain_job, so usage remains inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuine fact beyond them: the result spans base plus project-local environments. It says nothing about return shape, ordering, or cost of an open-world 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?

A single front-loaded sentence with the verb and resource first and the scope qualifier trailing; every word earns its place and nothing is 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 low-complexity, read-only, zero-required-parameter listing tool with full schema coverage and annotations covering safety, the description is nearly sufficient. The only real gap is that no output schema exists, so the agent gets no hint of what a returned environment entry contains.

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

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

Schema description coverage is 100% with only two optional parameters (profile, project), each already documented in the schema, so the baseline of 3 applies. The parenthetical "project-local" loosely hints that the project parameter scopes the listing, but no format or default information is added.

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 ("conda environments") plus a scope qualifier ("visible on RIS (base + project-local)"), so the agent knows it enumerates environments rather than inspecting one. It does not name the closest sibling ris_inspect_conda_env, so the plural-vs-singular distinction is left to be inferred from the name.

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: the plural "environments" and scope note suggest this is the discover-everything call versus a per-environment inspection. There is no explicit when-to-use, no mention of when to prefer ris_inspect_conda_env, and no prerequisite 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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds little behavioral context beyond 'available' (presumably only currently available modules) – it does not mention auth needs, pagination, or return 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?

A single, front-loaded sentence that states the verb and resource with zero filler. It is appropriately sized for the scope of the tool.

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

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

For a simple read-only list tool with annotations and partial schema coverage, the description is minimally adequate. However it omits profile usage and filter semantics, and with no output schema it does not clarify return values.

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%: profile has a schema description, but filter only has a regex pattern with no description. The phrase 'optionally filtered' hints at the filter's purpose but does not explain what it matches or how profile changes the listing, so it fails to compensate for the undocumented filter parameter.

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

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

States a specific verb ('List'), resource ('Lmod modules'), and scope ('on RIS') with optional filtering. The sibling list contains many job/env/SSH tools, so module listing is clearly distinct, but the description does not explicitly differentiate from any sibling or explain what an Lmod module 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?

Only 'optionally filtered' hints at usage. There is no when-to-use, when-not-to-use, prerequisites, or mention of alternatives, even though many sibling tools exist for adjacent RIS operations.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful scope context by specifying 'current' jobs and running/pending states, but does not disclose return format, pagination, or authentication requirements.

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

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

A single, front-loaded sentence that states the core action and optional filters with no wasted words. It is appropriately sized for a simple list operation.

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, read-only list tool with annotations covering safety and schema descriptions for two of three parameters, the description is nearly sufficient. It could better address the omitted 'profile' parameter or clarify that results are scoped to the caller, but the essential purpose and filters 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?

The description mentions filtering by 'state or project,' which aligns with two of the three schema parameters, but it omits the 'profile' parameter entirely. Schema coverage is 67% and the state enum values are self-explanatory, so the description adds only modest value beyond what the schema already provides.

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

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

The description gives a specific verb (show) and resource (current Slurm queue) and narrows scope to running/pending jobs, which implicitly separates it from ris_job_history. However, it does not name any sibling tool (e.g., ris_job_history or ris_worker_status) to make the distinction explicit, 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?

The phrase 'Show your current Slurm queue' implies the use case, and 'optionally filtered by state or project' hints at how to narrow results. But there is no explicit when-to-use versus alternatives, no when-not-to-use, and no named sibling, leaving usage guidance at an implied level.

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=true, so the safety profile is covered. The description adds useful output context (availability, MIG vs full H100, preempt notes), but says nothing about authentication/profile resolution behavior despite the open-world hint.

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 wasted framing. The parenthetical is terse to the point of being hard to parse, but the size is appropriate for a list tool.

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

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

For a read-only tool with no output schema, the description does sketch the return contents (availability, MIG vs full H100, preempt notes), which is the right instinct. However, the undocumented 'partition' enum leaves a real gap in how to invoke it correctly.

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

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

Schema description coverage is only 50%: 'profile' is documented in the schema, but the 'partition' enum carries no description of what each value means (general-short, general-bigmem, etc.). The description does not compensate at all, so an agent cannot infer what filtering by a given enum value returns.

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 ('RIS Compute2 partitions') and adds that the output includes availability and plain-English notes. An agent can tell it is a listing tool, though it does not explicitly contrast itself with siblings like ris_list_modules or ris_list_conda_envs.

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

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

No guidance on when to call this versus other list/discovery tools, and no explanation of when to supply the 'partition' argument versus omitting it. The 'no plain general' aside hints at scope but is cryptic rather than instructive.

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 readOnly, non-destructive and openWorld, so the safety profile is covered. The description adds that results are bounded by depth and entry caps, which is useful behavioral context, but says nothing about pagination, truncation signaling, or the return shape.

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

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

A single front-loaded sentence with no filler; the scope qualifiers (subdir, caps) are stated efficiently. Slightly terse given the undocumented parameters, 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?

For a read-only listing tool without an output schema, the description conveys scope and bounds but omits return format, truncation behavior, and usage context. Adequate but with clear gaps given the 5 parameters and 40% schema coverage.

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 40%, and the description does touch on subdir, maxDepth and maxEntries, adding some intent beyond the raw schema. However, it leaves maxDepth/maxEntries numeric behavior (defaults, hard limits) and the profile parameter unexplained, so it only partially compensates 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 (list) and resource (files in a project), and clarifies scope with the optional subdir and depth/entry caps. It is distinguishable from sibling listing tools like ris_list_partitions or ris_list_my_jobs, though it doesn't name 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?

The description gives no when-to-use guidance, prerequisites, or alternatives. With ~50 sibling tools, nothing tells the agent when this listing tool is the right pick versus ris_list_my_jobs or ris_get_result_manifest.

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 say the call is not read-only, is open-world and not destructive, so the description carries most of the burden and it does add real operational context: the open is best-effort, it may return an interactive command for a real terminal, Duo must be approved once, and the socket is then reused by the agent. It still omits what a best-effort failure looks like or whether a stale socket must be cleared first.

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 covering the primary behavior and the notable Duo exception, with essentially no filler. Slightly dense with the parenthetical, 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 should explain what the tool yields and the failure path; it names the Duo return value but says nothing about the non-Duo return, socket lifetime, or teardown. Adequate for a setup-style tool, but a caller still has to guess at the alias parameter and the failure semantics.

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 50% — only 'profile' is documented, while 'alias' carries nothing in either the schema or the description. The description never mentions alias or explains that it is an SSH host alias, so it does not compensate for the coverage gap on a parameter the caller must supply correctly.

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 ('open') and resource ('ControlMaster session'), making the multiplexing purpose clear. It does not, however, differentiate itself from close siblings like ris_check_ssh_master or ris_repair_stale_socket, which an agent browsing the list could confuse it with.

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

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

The phrase 'best-effort open' and the Duo workflow imply a pre-flight/setup role, and the Duo branch tells the agent what to do on hosts requiring interactive auth. But there is no explicit statement of when to call this versus ris_check_ssh_master, nor any stated prerequisite or follow-up ordering.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is known before reading. The description reinforces this with 'Does NOT submit' and specifies the advisory content of the output, but adds little beyond the annotations about side effects, permissions, or limits.

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

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

Two tight sentences with the core promise front-loaded and the scope-limiting clause ('Does NOT submit') at the end where it is most needed. No filler, though it could be slightly more structured for a tool with nine 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 a tool with nine parameters, zero required fields, 22% schema description coverage, and no output schema, the description is thin on the input side: it never explains what an 'intent' is, how the parameters shape the plan, or how defaults apply. It does at least sketch the expected output, but overall it leaves too much unspecified for correct invocation.

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

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

Schema description coverage is only 22% (just profile and project), so the description must carry parameter meaning, yet it explains none of the nine inputs. It lists plan outputs (partition, cpus/mem/gpus/walltime) that loosely correspond to parameters like gpuNeed, maxGpus, dataSizeGb, and expectedRuntimeHours, but never maps them or describes format, defaults, or units.

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 (turn an intent into a resource plan) and enumerates exactly what the plan contains (CPU vs GPU, partition, cpus/mem/gpus/walltime, smoke-test recommendation) and its form (plain English). 'Does NOT submit' implicitly separates it from the many ris_submit_* siblings, but it never names the closest alternative (ris_estimate_resources) or any other tool, so sibling differentiation is only partial.

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 rather than stated: by describing a 'safe, validated' plan that 'Does NOT submit,' an agent can infer this is a pre-submission planning step. There is no explicit 'use this when' clause, no exclusion of alternatives such as ris_estimate_resources or ris_generate_sbatch_template, and no stated 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 openWorldHint=true, so the safety profile is covered. The description adds meaningful context beyond annotations: that ownership is verified and that confirm=true is mandatory, which the schema's default-false boolean does not 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?

Three short, front-loaded sentences with no filler; the ownership/scope constraint leads and the confirmation requirement follows 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 4-parameter, zero-required mutation tool with no output schema, the description covers the key behaviors (ownership, confirmation, conditional jobId). It stops short of describing the return value or what state change 'release' produces, but no output schema exists to carry that.

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 50% (jobId and confirm are undocumented). The description compensates by clarifying that confirm must be true and that jobId is optional only when a project scope is supplied, filling the two gaps left by the schema.

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

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

The description states a specific verb (release) and resource (held job) plus the ownership constraint, which implies the inverse of ris_hold_job. It is clear what the tool does, though it never names the sibling it complements.

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 an actionable condition (requires confirm=true; jobId optional only with a project scope), which is useful context. However it never states when to reach for this tool versus ris_cancel_job or other job-state tools, leaving alternatives to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds that it removes ONLY the verified stale socket and that five safety guards are involved, which is useful context beyond the annotations, though it does not detail what the guards check or what permissions are required.

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 the scoping constraint and usage condition front-loaded. Every clause earns its place 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 destructive socket-repair tool with no output schema and only 50% schema description coverage, the description omits what the five guards verify, whether ris_check_ssh_master should be run first, and the roles of alias and profile. The annotations cover the safety profile, but the definition is not complete enough for fully confident 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 coverage is 50%: the alias parameter has no description, and the description never mentions either alias or profile. It therefore does not compensate for the undocumented alias or explain how the parameters identify the target socket, adding no meaning beyond the schema.

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

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

States a specific verb ('Remove') and resource ('ControlPath socket'), scoped to 'exact, verified stale' with five safety guards. The second sentence distinguishes the scenario from siblings like ris_check_ssh_master and ris_open_ssh_master by naming when the master is gone and a dead socket blocks reconnection.

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 an explicit when-to-use condition: 'Use when the master is gone but a dead socket blocks reconnection.' It does not state when not to use it or name an alternative tool to run first, 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description's 'Does NOT submit' explicitly confirms no side effects, which is the key behavioral fact here. It does not describe the shape of the returned plan, though no output schema exists to carry that either.

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 the scope and the negative constraint front-loaded; every clause earns its place 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?

For a 7-parameter tool with 29% schema coverage and no output schema, the definition omits both the optional-parameter semantics and any hint about what the plan contains or how it maps to the recommended ris_submit_* call. What is present is accurate but leaves 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 29%, so the description must compensate, and it largely does not: it names 'goal' implicitly and lumps all six optional fields into 'a few optional hints.' Nothing explains what needsGpu, framework, dataLocation, project or approxRuntimeHours imply for the generated plan (only profile has a schema description).

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 transformation (plain-English goal + optional hints -> safe plan + exact next ris_submit_* call) and explicitly distinguishes itself from the submit siblings with 'Does NOT submit.' An agent can identify this as the planning entry point 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?

Scopes the audience ('For non-HPC users') and routes the agent toward the ris_submit_* family as the follow-up action, so the when-to-use context is clear. It stops short of stating exclusions, e.g. when an HPC-experienced agent should skip straight to ris_plan_run or ris_submit_python_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 flag it as a non-read-only, open-world, non-destructive operation. The description adds real value beyond that: it discloses that the tool auto-builds a missing PyTorch/TF environment and that execution is gated behind dryRun=false plus confirm=true, so an agent understands the mutation actually requires an explicit second call.

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 ('One call: ensures...') and the safety gate, with no filler sentences. The em-dash-heavy packing is dense but each clause conveys distinct 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 an 11-parameter, low-coverage, no-output-schema orchestration tool, the description captures the high-level flow and the critical confirm gate but omits meanings for several resource-shaping parameters (walltime, gpuCount, account, envName). Adequate but with 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 coverage is only 18%, so the description must carry param meaning, and it only partially does. It clarifies script submission, dryRun/confirm gating, GPU-vs-CPU (needsGpu), and framework selection (PyTorch/TF), but leaves account, envName, gpuCount, walltime, and the profile/account relationship 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?

States a specific verb+resource ('run a script') and clarifies scope by describing the orchestration: ensures project+env exist, auto-builds the env, then submits. This distinguishes it from the narrower ris_submit_* siblings as an all-in-one path, though it never explicitly names an alternative.

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

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

Gives clear operational guidance on the two-step gate ('dryRun preview by default; re-call with dryRun=false, confirm=true to run'), which is genuinely useful. However, it never states when to prefer this over ris_plan_run, ris_ensure_env, or the specific ris_submit_* job tools, so its role as an alternative is only implied.

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 this as a non-read-only, destructive write to ~/.risbridge-mcp/config.json. The description adds real context beyond that: it validates account ownership and workspace writability, that force skips validation, and that confirm=true is mandatory.

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 the core action and destination front-loaded, followed by the validation and confirmation conditions. No filler; 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?

Covers the write target, validation behavior, and the confirm/force gates, which is solid for a mutation tool. It still omits the three non-required parameters and says nothing about the default profile or behavior when a config already exists.

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 username, slurmAccount, workspace, force, and confirm, but omits profile, sshAlias, and gpuRequestMode entirely, leaving 3 of 8 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?

States a specific verb and resource: saves username, Slurm account, and workspace to a named config file. The target path makes the effect concrete, though it does not explicitly distinguish itself from siblings like ris_show_config or ris_discover_profile.

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

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

Gives a precondition (confirm=true) and notes force bypasses validation, implying when to use it. However it never states when to prefer this over ris_discover_profile, ris_setup_wizard, or ris_write_ssh_config, leaving alternatives 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 declare destructiveHint=true, and the description usefully scopes that destructiveness: replacement only happens with overwrite=true, and the private key is never returned. It does not cover permissions needed or where the key lands on disk, but it adds meaningful behavioral context 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?

Two tight sentences that front-load the create-if-absent behavior, then the returned output, then the overwrite escape hatch. 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 the return surface (public key + install command) and explicitly states the private key is never returned. It also covers the mutation consequence of overwrite. Only the 'comment' parameter is unaddressed.

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

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

Schema description coverage is only 33% (just 'profile'), so the description must compensate. It does explain overwrite=true (replace an existing key) well, but the 'comment' parameter is left undocumented in both the schema and the description, leaving the coverage gap only partly filled.

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 ('Create the dedicated ed25519 key'), plus concrete side effects (chmod 600, show public key + install command). This clearly distinguishes it from siblings such as ris_show_public_key and ris_generate_ssh_config, which do not create keys.

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 conveys implicit usage conditions: the key is only created 'if absent', and 'Pass overwrite=true to replace an existing key'. However, it never names an alternative tool for the cases it does not cover (e.g. viewing vs. regenerating vs. writing ssh config), so routing between the many ssh-related siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces this ('Read-only — it never changes anything') and adds genuinely useful behavior: it does not perform fixes, it points to the exact tool or command to run next. That routing behavior is not captured by any annotation.

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

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

Two compact sentences, front-loaded with the plain-English checklist framing and immediately followed by the key constraint (read-only) and the payoff (next step). No filler, though the state list is slightly dense.

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

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

For a read-only wizard with no output schema, the description adequately conveys what is inspected and what the agent gets back (a recommended next step). It falls short on the three undocumented parameters and on how this tool relates to the many adjacent validation/status 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?

With 4 parameters and only 25% schema description coverage, the description must compensate but does not. Only 'profile' is documented (in the schema itself); host, user, and alias are never explained in the description, so an agent cannot tell when to supply them or whether they narrow the inspection scope.

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-and-resource picture: it inspects setup state (username, SSH key/config, Duo, account/workspace) and reports the single next step. That is more specific than most siblings, though it never names an alternative tool, so differentiation from ris_validate_config or ris_auth_status is left to inference.

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 (run this when you're setting up or stuck), and the phrase 'tells you the single next step' suggests it acts as a router. However, it never states when to prefer it over ris_validate_config, ris_auth_status, or ris_researcher_wizard, and gives no 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 and destructiveHint=false, so the safety profile is covered. The description adds that it shows both the active resolved profile and the saved profiles, which is useful context about the return content, but it doesn't mention whether it reads from disk, errors when config.json is absent, etc.

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

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

One tight sentence that front-loads the active profile and then notes the saved profiles. No wasted words.

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

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

For a simple read-only tool with a fully documented single parameter and no output schema, the description covers the essentials. It could be more complete by noting when to prefer it over ris_validate_config or ris_auth_status and by hinting at the return shape, but nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter's schema description already explains the named profile and default behavior. The description adds no extra meaning about the profile 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?

States a specific verb (Show) and resource (active resolved profile and saved profiles in config.json), and enumerates the fields returned. It is clear enough, though it doesn't explicitly distinguish itself from siblings like ris_validate_config or ris_set_profile.

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

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

No guidance on when to use this versus alternatives such as ris_validate_config, ris_auth_status, or ris_discover_profile. The description only says what it shows, not when an agent should reach for 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=true, destructiveHint=false, and openWorldHint=false, so the safe-read profile is covered. The description adds one useful disclosure beyond that – 'The private key is never read' – which reassures the agent about sensitive-data exposure, but it offers no further operational detail (output format, key type, fingerprint algorithm).

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 action front-loaded and the safety caveat following. Every sentence earns its place.

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

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

For a one-optional-parameter read-only tool with no output schema, the description adequately conveys what is returned (public key plus fingerprint). It could go slightly further on the return shape, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single 'profile' parameter is fully documented in the schema, so the baseline of 3 applies. The description adds nothing about the profile parameter or how omitting it behaves.

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: 'Print the dedicated public key and its fingerprint.' An agent can tell this reads a key rather than creating or configuring one. It does not, however, explicitly distinguish itself from nearby siblings like ris_setup_ssh_key or ris_show_config.

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, prerequisites, or alternatives are given. It never says e.g. 'use this to retrieve a key for authorized_keys' or how it relates to ris_setup_ssh_key. Usage must be inferred entirely from the 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds a genuine constraint not in the schema: the 10000 total-task cap (which reconciles the arrayEnd max of 100000). However it omits the critical two-step dryRun-then-confirm behavior, so the description is only partially carrying the mutation burden.

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 written clauses with zero filler, and the core purpose is front-loaded. It is efficient, though arguably undersized for a 21-parameter tool where more guidance would have earned its place.

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

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

For a 21-parameter, non-read-only submission tool with no output schema and low schema coverage, the description leaves major gaps: the dryRun/confirm gating, partition and resource selection, and what the confirmation summary returns. It is not sufficient for an agent to invoke this safely without opening the schema.

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

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

Schema description coverage is only 29% across 21 parameters. The description adds meaning for essentially one concept (the array task ID env var) and the 10000 cap, leaving partition, walltime, cpus, memGb, gpuCount, maxConcurrent, modules and condaEnv unexplained in both schema and description.

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 project script across a bounded Slurm array') and clarifies the array semantics by noting the script reads $SLURM_ARRAY_TASK_ID. The 'array' framing implicitly separates it from the other submit_* siblings, but it never names an alternative or explicitly contrasts with them.

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

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

No when-to-use guidance and no mention of the dryRun/confirm submission workflow that governs this tool. An agent gets no signal about when an array job is preferable to ris_submit_python_job or ris_run, nor about 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?

With annotations already declaring readOnlyHint=false, destructiveHint=false and openWorldHint=true, the description adds useful detail about resource locality (CPU only, never /home, never a GPU). However, it omits the critical two-step safety flow (dryRun defaults true, confirm must be set) that governs whether a job is actually submitted.

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 wasted words; the scope and key constraint appear immediately. It is arguably terse for a 12-parameter submission tool, but nothing in the 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 mutation tool with 12 parameters, 33% schema coverage and no output schema, the description is under-powered: it never explains the dryRun/confirm submission gate, the required inputs, or how packages/envFile interact. An agent could call this incorrectly despite the clear opening sentence.

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 33% across 12 parameters, so the description must compensate — and it does not. It says nothing about packages, envFile, python version, walltime, or the required project/envName, leaving most parameters to a sparse schema.

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

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

The description names a specific verb (build/update), resource (conda environment), target location (project's envs/) and execution mode (CPU job, no GPU/home). It clearly separates this from read-only siblings like ris_inspect_conda_env, though it never names the closest alternative ris_ensure_env.

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 over ris_ensure_env, ris_submit_python_job, or ris_submit_r_job, and no mention of prerequisites or exclusions. The only constraint given is environmental (CPU/no GPU/no /home), which is context rather than 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, and the description is consistent with a job-submitting tool. It adds the useful resource-profile behavior, but omits the most important behavioral trait: that submission is gated behind a two-step dryRun(default true)+confirm flow, so the agent is not told the default call does NOT actually submit.

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 front-loads what the tool does, the second delivers the resource-selection rule. No filler, no redundancy.

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

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

No output schema exists, and for a submit tool the description may reasonably omit return values. Combined with annotations that carry the safety profile and a schema covering the required project and the dryRun/confirm gating, the description supplies what the agent needs: purpose and resource targeting.

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 67%, so the baseline is 3. The description adds meaning for fullH100 and the default profile targeting, which the schema leaves blank, but it says nothing about dryRun, confirm, account, or profile interplay, so it only partially compensates for the uncovered parameters.

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

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

States a specific verb and resource ('Submit a tiny GPU validation job') with the exact payload (nvidia-smi + torch CUDA check). It clearly separates itself from the many ris_submit_* siblings by being a validation job rather than real work, and from ris_gpu_status by being a submission, not a status read.

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 explains the resource selection logic (MIG slice on general-short by default, full H100 on general-gpu when fullH100=true), which implies when the full-GPU variant is appropriate. However, it never states the scenario for using this tool versus a real submission (e.g. 'run before allocating GPU work'), nor does it surface the dryRun/confirm prerequisite workflow, leaving usage largely implicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is known. The description adds one genuine behavioral fact beyond the annotations — it does not open the tunnel itself — but it omits the critical dry-run-by-default workflow (dryRun defaults to true, confirm required for a real submit) despite the name implying submission.

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 waste, with the core action and the key constraint front-loaded. Nothing redundant.

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

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

For a 10-parameter mutation tool with no output schema and 40% schema coverage, the description is far too thin. It should explain the dry-run/confirm submission flow and at least gesture at resource parameters; as written, an agent could call it expecting a synchronous launch.

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 10 parameters and only 40% schema description coverage, the description contributes nothing about parameters — no mention of gpu, cpus, memGb, walltime, profile, or the dryRun/confirm submission gate. The untyped fields like gpu, cpus, memGb, walltime, port, and account are left entirely to an under-documented schema.

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

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

The description states a specific verb and resource (launch JupyterLab on a compute node) plus a concrete return (SSH tunnel instructions). The closing sentence 'Never opens a tunnel itself' differentiates it from tunnel-oriented siblings like ris_open_ssh_master, though it does not distinguish it from ris_submit_notebook_job or ris_submit_python_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 only implied: the mention of returned tunnel instructions suggests a follow-up step, but there is no explicit when-to-use statement and no routing against the many sibling submit_* tools. An agent must infer this is the JupyterLab-specific variant.

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 destructiveHint=false and openWorldHint=true, so the agent knows this is a non-destructive write that hits external systems. But the description omits the critical safety workflow: dryRun defaults to true and confirm must be true with dryRun=false to actually submit. That two-step confirmation gate is a major behavioral trait conveyed only by inline param descriptions, not the tool description. No mention of auth requirements, scheduling semantics, or consequences of submission.

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 tightly-packed sentence with no filler. Front-loads the operation, scope, and default in a scannable form.

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 18-parameter submission tool with no output schema and a non-trivial two-step confirm workflow, the description is far too thin. It doesn't warn about the dryRun/confirm contract, doesn't clarify that the default only permits validation, and provides no scheduling guidance. The agent is left to discover the submission gate from individual parameter descriptions.

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 33% (6 of 18 params documented inline), so baseline 3 applies. The description adds one default value (H100) but explains nothing else about the many parameters (gpuCount, partition, walltime, modules, condaEnv, etc.). It does not compensate for the low coverage; the schema is the primary documentation here.

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 (submit), resource (multi-GPU PyTorch training job), and mechanism (torchrun, typed H100 by default). It distinguishes itself from sibling ris_submit_python_job, ris_submit_r_job, etc. via the multi-GPU/torchrun framing, though it doesn't name a sibling directly.

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 exclusions, no alternatives named. An agent must infer from the name that this is for multi-GPU PyTorch specifically versus ris_submit_python_job or ris_submit_gpu_smoke_test. No mention of the dryRun/confirm submission workflow that the schema implies is mandatory.

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=false, destructiveHint=false, openWorldHint=true, covering the basic safety profile. The description adds that execution is headless via nbconvert, which is useful behavioral context, but omits the critical fact that dryRun defaults to true so the tool builds/validates rather than submits unless confirm is also set.

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 and no redundant restatement of the tool name. It is efficient, though its brevity is achieved partly by omitting information the 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?

For a 17-parameter submission tool with 35% schema coverage, no output schema, and no annotation detail on the submit gate, one sentence is far too thin. It does not explain the dry-run default, resource/partition semantics, or what the job returns.

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

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

Schema description coverage is only 35% across 17 parameters, so the schema does not carry the load. The description names no parameters (cpus, memGb, partition, gpuCount, walltime, modules, account, etc.) and adds no format or defaulting guidance 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+resource ('Execute a project .ipynb headlessly ... as a batch job') and names the mechanism (nbconvert), which distinguishes it from ris_submit_python_job and ris_submit_jupyter_job. It does not explicitly name or contrast those siblings, 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?

No when-to-use guidance, no prerequisites, and no mention of the dryRun/confirm two-phase pattern that governs whether a job actually goes out. The agent must open the schema to learn that the default call does not submit.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds the dryRun-by-default preview behavior and the gpuCount>0 GPU trigger, but omits that an actual submission also requires dryRun=false plus confirm=true, and says nothing about auth/profile or side effects on the cluster.

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, front-loaded sentences with no filler. The terseness is appropriate to the format, though it sacrifices coverage for a tool with 17 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 a 17-parameter, non-read-only submission tool with no output schema and 35% schema coverage, the description is far too thin. An agent must reconstruct most of the invocation semantics from the schema alone.

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 35% across 17 parameters, so the description must compensate, yet it only touches gpuCount and implicitly dryRun. Nothing is said about args, cpus, memGb, walltime, partition, modules, condaEnv, or allowUntypedGpu, leaving most of the surface 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 — run a project .py file as a batch job — and notes the CPU/GPU branch. It is clear enough to distinguish from ris_submit_r_job or ris_submit_notebook_job, but it does not name those siblings 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?

Beyond stating that dryRun previews by default, there is no guidance on when to pick this tool over ris_run, ris_plan_run, or the many other ris_submit_* variants. No prerequisites or exclusions are given.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds no behavioral context beyond the CPU/Rscript framing and does not disclose the dry-run-first workflow or that confirm+dryRun=false are required to actually submit. Nothing contradicts the annotations, but the description carries little weight.

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, which is well structured. The economy here is partly under-specification rather than tight editing, but as written it is concise and readable.

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 17-parameter submit tool with no output schema and sparse schema descriptions, the description is far too thin. An agent cannot determine submission semantics, resource defaults, or the dry-run confirmation contract from the description alone.

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 17 parameters and only 35% schema description coverage, the description is expected to compensate heavily, and it does not. It mentions only 'project .R file', loosely implying the project and script parameters, and says nothing about cpus, memGb, partition, modules, condaEnv, walltime, or gpuCount/gpuType.

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 ('Run'), specific resource ('project .R file'), and a stated mechanism ('via Rscript') plus scope ('CPU batch job'). This clearly distinguishes it from siblings like ris_submit_python_job, ris_submit_gpu_smoke_test, and ris_submit_array_job without needing to open 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?

No when-to-use, when-not-to-use, or alternative guidance is given. Critically, the description omits the dryRun-defaults-true / confirm-must-be-true gate, so an agent reading only the description has no idea a submission requires an explicit two-flag request.

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=false, openWorldHint=true, destructiveHint=false, which already conveys a mutating open-world operation. The description adds nothing about the critical dryRun=true/confirm=true submission gate — by default this tool builds and validates but does NOT submit, which the description's 'serve a model' phrasing actively obscures. It also omits resource/lifetime behavior (walltime, GPU allocation, what happens after the job ends).

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 the verb, resource, hardware scope, and return value; every clause earns its place 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?

For a 14-parameter mutation tool with no output schema and low schema coverage, the description is far too thin. It does not explain the dryRun/confirm safety flow (the most decision-relevant fact), resource requirements, or the meaning of the many unlabeled parameters, leaving an agent to guess its way through 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 only 29% across 14 parameters, so the description is expected to compensate — and it mentions none of them. Only dryRun, confirm, profile, and project carry inline schema docs; cpus, port, dtype, memGb, model, account, condaEnv, gpuCount, walltime, and maxModelLen are undocumented, and the description does not clarify any of them.

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 (serve a model via vLLM), the resource (an OpenAI-compatible API), the hardware target (full-H100 node), and the return value (tunnel instructions). This clearly differentiates it from the many other ris_submit_* siblings, but it does not explicitly contrast itself against any of 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?

Usage is only implied: an agent can infer this is for hosting an inference server rather than a notebook, batch, or training job. There is no explicit when-to-use statement, no preconditions (e.g., model must be downloadable or present on the node), and no named alternative for related needs.

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=true, covering the safety profile. The description adds the default-resolution behavior for jobId, which is useful, but says nothing about whether the log view is a snapshot, whether it blocks, or rate/refresh 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?

Two tight sentences with the return contents and the jobId default front-loaded. Nothing is wasted, though it is telegraphic enough that some meaning must be inferred.

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, no-output-schema read tool, the description gives the return shape ('logs plus current state') and the jobId default, which is a reasonable start. It falls short on stream/profile/project semantics and the relationship to sibling log tools.

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

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

Schema coverage is only 40% across 5 parameters, so the schema does not fully carry the load. The description explains jobId's optionality and default plus the N-lines concept, but is silent on stream, profile, and project semantics, leaving half the surface 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?

States a specific action and resource: the last N lines of a job's logs plus current state. It distinguishes scope ('tail', bounded line count) but does not name the closely related ris_get_job_logs sibling, leaving the agent to infer the difference.

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 note that jobId is optional and defaults to the most recent job implies a quick-look use case, but there is no explicit when-to-use versus ris_get_job_logs, and no exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and external-interaction profile is covered. The description usefully adds the execution mechanism (BatchMode, no interactive auth) and that it classifies an outcome, but it does not describe the returned classification or any side effects, so it adds only moderate value 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?

Two sentences, front-loaded with the action and mechanism, with no filler. Efficient and easy to scan, though the second sentence's 'Classifies whether...' clause could be tightened.

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 SSH auth diagnostic with 5 parameters at 20% coverage and no output schema, the description explains the purpose and the two possible outcomes but leaves both the parameters and the result structure underspecified. It is adequate but not complete for the 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 only 20% (just 'profile' is documented), so the description must compensate for the other four parameters, yet it mentions none of host, user, alias, or timeoutMs. With low coverage and no parameter guidance in the description, an agent gets no help on how to target the test.

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 ('Run the decisive key-only SSH test') and even specifies the mechanism (BatchMode, no password/keyboard-interactive). It clearly conveys what the tool does, though it never names which sibling (e.g. ris_check_ssh_master, ris_auth_status) it replaces or complements, so differentiation is left to inference.

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 rather than stated: 'decisive' and the mention of the 'multiplexing fallback' hint at a workflow position, but there is no explicit when-to-use or when-not-to-use versus the many other auth/SSH siblings. The agent must guess where this fits relative to ris_check_ssh_master and ris_auth_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?

Adds behavior beyond annotations: the subdirectory allowlist, the refuse-to-overwrite default with the overwrite escape hatch, and the binary-unsupported limitation. Annotations cover the destructive/mutating profile, so this is solid supplemental context. It does not mention permissions or content-size limits.

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

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

Three tight sentences, front-loaded with the operation and the scope constraint. No filler; each sentence carries an independent fact (allowlist, overwrite, format limit).

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, so the description should convey what happens on success/failure, and it does not. Five parameters at 40% coverage leave profile and project semantics undocumented; the description is adequate but has clear gaps for a write 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 40%, so the description should compensate. It clarifies the overwrite parameter's semantics (refuses unless true) and the accepted directory set relevant to relPath, but says nothing about project, profile, or the 1,000,000-char content cap.

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

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

States a specific verb and resource ('Write a text file') plus a precise scope constraint: it must live in one of six enumerated safe subdirectories. This distinguishes it cleanly from sibling file tools like ris_list_project_files or ris_get_result_manifest.

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 the constraint (safe subdirectory allowlist) and the overwrite refusal, which implies when to set overwrite=true. But it gives no explicit when-to-use versus siblings and no prerequisites such as authentication or project existence.

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, so the safe-read profile is covered. The description adds the concrete check set (username, account/workspace, partitions), but says nothing about what the result looks like or whether it merely reports or also repairs issues.

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

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

A single sentence, front-loaded with the verb and scope, with the three checks listed crisply. No filler or redundancy.

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

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

With no output schema, the description should convey the shape of the verdict (pass/fail, list of failures), and it does not. The check list is adequate for a lightweight validator, but the result contract is missing.

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

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

Schema coverage is 100% and the single optional 'profile' parameter is fully documented there, so baseline 3 applies. The description's phrase 'the current profile' hints at the profile-selection concept but adds no syntax or fallback 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 ('Check'/validate) and resource ('the current profile against RIS facts') and enumerates the three things verified: username set, account/workspace configured, partitions valid. It is clearly distinguishable from display-oriented siblings like ris_show_config or ris_auth_status, though it never names them explicitly.

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

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

Usage is only implied: validating config before running jobs or after setup. There is no explicit when-to-use, no ordering relative to ris_set_profile / ris_show_config / ris_auth_status, and no statement of what to do when validation fails.

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 safety profile is covered structurally. The description adds real value by clarifying the mechanism — 'appends a cancel request' — telling the agent this is a soft/cooperative cancellation rather than a guaranteed immediate kill. It omits what happens if the run is already running, whether the request can be revoked, and any permission requirements.

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

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

A single tight sentence with the action front-loaded and the mechanism parenthetically appended. No wasted words, though it is arguably under-specified rather than 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?

For a mutation tool with no output schema and two undocumented parameters, the description should explain return behavior (e.g., whether a cancel request ID is returned) and how it relates to sibling cancellation tools. It covers intent only, leaving the agent without enough to invoke confidently.

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 33% — the required 'id' and the 'jobId' parameter have no descriptions anywhere, only regex patterns that do not explain their meaning or relationship. The description contributes nothing about parameters, so it fails to compensate for the coverage gap on a 3-parameter tool.

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 ('cancel a queued/submitted run') and scopes it to queued/submitted states, which is more precise than the title alone. It does not, however, distinguish itself from the sibling ris_cancel_job, so an agent reading only this description cannot confidently choose between the two.

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 'queued/submitted run' implies the applicable state condition, which is useful implied guidance. There is no explicit when-to-use, no prerequisites, and no mention of when to prefer ris_cancel_job or ris_hold_job 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds useful process detail (builds/validates sbatch, appends to queue), but doesn't mention whether it waits, how failures surface, or queue semantics. Adds some value beyond annotations, hence a mid score.

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, front-loaded with the core action and benefit, 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?

An 8-parameter mutation/queue tool with no output schema and 25% param coverage needs more: the description omits resource-param meaning, queue/failure behavior, and interaction with the submit 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?

Only 2 of 8 parameters have schema descriptions (profile, project), and the description adds no parameter meaning at all (cpus, memGb, walltime, gpuCount, account, script are all unexplained). With 25% coverage, the description fails to compensate.

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 (Queue) and resource (Python job for the per-user worker), plus the motivating benefit (agent need not stay connected). It is somewhat distinguished from submission siblings like ris_submit_python_job by mentioning the worker queue, but it doesn't explicitly say how it differs from those submit tools.

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 'so the agent need not stay connected' implies async/deferred usage, but there's no explicit when-to-use-this-vs-ris_submit_python_job or ris_run guidance despite several closely related submission siblings.

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