cacheout_scan_caches

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that results are 'sorted by size (largest first)' and that it 'scans developer tool caches.' It does not disclose potential performance impacts, caching behavior, or authentication requirements. Given the strong annotation baseline, the additional context is modest but adequate.

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 extremely concise: three sentences plus a brief args/returns block. It front-loads the core purpose, then adds relevant detail (which caches, sorting), and ends with usage guidance. Every sentence is valuable. No repetition or 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?

Given the tool's moderate complexity (filter parameters, multiple cache categories) and the presence of an output schema (documented return format), the description covers the main intent and usage. It lacks nuance about the 'risk_level' and 'rebuild_note' fields in the return, but those are detailed in the schema. The description is complete enough for informed 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?

The tool description does not elaborate on the parameters. However, the input schema provides detailed descriptions for both 'categories' (list of slugs) and 'min_size_mb' (minimum size filter). Since schema_description_coverage is 0% (the description text covers none of the parameters), but the schema itself is comprehensive, the description adds no extra meaning. 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?

The description clearly states the purpose: 'Scan macOS cache directories and report their sizes.' It specifies the resource (macOS caches) and verb (scan/report). It lists which developer caches are scanned, distinguishing it from sister tools like cacheout_clear_cache (cleans) or cacheout_system_health (health check). The tool is unambiguously a read-only analysis 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?

The description explicitly says 'Use this to understand what's consuming disk space before cleaning.' This provides clear context for when to invoke the tool (pre-cleaning) and implies it's not for cleaning itself. However, it does not explicitly mention when not to use it (e.g., not for checking alerts or general health). But the guidance is direct and sufficient for most agents.

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