submit_pipeline

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

Annotations only say readOnlyHint=false and destructiveHint=false. The description adds substantial behavior: server-side ordering and per-stage validation, automatic placement of --dependency, arch inheritance across stages (with the x86_64/aarch64 failure case it prevents), and the critical dry-run-by-default gate. This is exactly the context annotations cannot supply.

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?

Purpose is front-loaded, then mechanics, with the simulation warning placed last where it is most likely to be read before calling. Dense but each sentence adds a distinct fact; slightly longer than strictly necessary.

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

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

An output schema exists, so return values need not be described. For a mutation tool, the simulate/confirm contract and the dependency/arch behaviors are covered well. The main gap is the three undocumented parameters (name, modules, spack_packages) that an agent may need to populate.

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

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

Schema description coverage is 0%, so the description carries the burden. It meaningfully documents stages (intention: command, time, resources, dependencies), arch (inherited across the chain), and confirm (the submit gate), covering half the parameters with real semantics. It leaves name, modules, and spack_packages undocumented, but the coverage it does provide is substantive rather than restating field names.

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+resource: submitting a chain of jobs linked by SLURM dependencies, with a clear lifecycle (prepare, compute, gather). It even references submit_job as the validation reference. It does not, however, disambiguate against submit_array_job or submit_resilient_job, which are the closest siblings.

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

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

It clearly explains the operational flow: simulation is the default, and the caller must re-invoke with confirm=true to actually submit. That is strong actionable guidance. It stops short of saying when to prefer this over submit_job or submit_array_job for dependency-free work.

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