diagnose_disk_pressure

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

With no annotations, the description carries the full behavioral burden and does disclose the critical safety property: it never deletes or modifies files. However, it does not state permission requirements, expected runtime, or whether any privileged access is needed, leaving meaningful behavioral gaps for a system-level disk 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?

Two compact sentences, front-loaded with the tool's purpose and followed immediately by the safety guarantee. 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 zero-parameter tool with no output schema, the description adequately covers what the report includes and the read-only guarantee. It could add expected output format or runtime details, but the essential information needed to invoke it correctly is 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 tool has zero parameters, so the baseline is 4. The description correctly implies a no-input invocation and focuses on what the report contains rather than misrepresenting any parameter behavior.

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

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

The description states a specific verb and resource: it 'Creates a read-only macOS disk triage report' and enumerates the report contents (available space, developer-data/cache sizes, risk labels, next steps). It is clearly distinguishable from siblings like analyze_caches and find_large_files, though 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?

Usage is implied by the diagnostic framing ('disk triage report') and macOS scoping, but there is no explicit when-to-use, when-not-to-use, or routing guidance versus analyze_caches or find_large_files. An agent can infer this is for overall disk pressure assessment, but the alternative tools are not addressed.

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