Machine Disk

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

With no annotations, the description carries the full burden and does so: it discloses a 20-second per-call walk limit with continuation on the next call, warns that a whole-drive first look may take several calls, and clarifies that this tool is a read-only report whose fix is a separate move operation. It also documents the exact landing path and manifest.json side effect of that separate operation, which is what an agent needs to explain the outcome to a user.

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?

Content is front-loaded with the trigger condition ('Where the disk went, when the board says disk LOW...') and every clause adds a distinct item or constraint. It is dense and runs long as a single block, and the embedded CLI usage for reclaim.move is verbose, but little of it 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?

An output schema exists, so return formatting is covered, and the description nonetheless tells the agent what to expect from the walk (truncation across calls) plus the safety rule for acting on results. The single gap is the undocumented 'top' parameter, which is the only thing an agent could get wrong at call time.

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

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

There is exactly one parameter, 'top', and schema description coverage is 0% — neither schema nor description explains what it controls. The mention of 'the biggest folders under songs/' hints at a top-N limit but never names or bounds the parameter, so an agent must guess its meaning and acceptable range.

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

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

The description enumerates exactly what the tool returns: per-drive free space and pagefile, biggest folders under songs/ with growth, the _reclaim folder and its contents, stale per-song _reclaim folders, and non-songs/ folder growth. This is a concrete resource report, not a tautology. It does not explicitly contrast with the closest sibling machine_status, so it falls short of full differentiation.

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

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

It names the two triggering conditions precisely ('when the board says disk LOW or a heavy job waits on disk') and then routes to the correct alternative action for remediation (ismail.reclaim.move / the python -m CLI) rather than implying this tool frees space. It also states a hard prohibition — 'Tell the user; never delete' — leaving no inference about scope.

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