resources

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

Annotations already establish readOnly, idempotent, non-destructive semantics, so the bar is lower. The description adds real behavioral context: output is compact/per-partition by default, node-level detail is returned only when a filter or include_nodes is supplied, and large clusters should combine filters to avoid heavy detail payloads.

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 structure is well front-loaded — purpose, then scope filters, then the Args list. There is minor redundancy, since the flt values and their meanings are stated both in prose and again in the Args block.

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-shape documentation is not required, and annotations cover the safety profile. The description supplies everything needed to filter and size the query correctly; only marginal details such as connection prerequisites or failure behavior are absent.

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

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

With 0% schema description coverage, the description carries the full burden and does so: it enumerates every optional parameter, spells out the accepted flt values with their meanings, notes that gpu_only stacks with other conditions, defines partition scoping, and warns about include_nodes cost on large clusters.

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

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

The opening sentence names a specific verb and resource — querying cluster resource headroom — and enumerates exactly what is returned (per-partition CPU/GPU total/used/free plus node counts). This is clearly distinguishable from siblings like jobs, status, or alloc.

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 explains when to apply each filter (flt=cpu_free / cpu_gpu_free / fully_idle, gpu_only, partition) and explicitly tells the agent not to assemble sinfo/scontrol itself, which routes it toward this tool over exec. It does not, however, contrast against sibling tools such as status or jobs, so the guidance stops just short of fully explicit alternative selection.

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