tidy_vault

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

With no annotations provided, the description carries the full burden. It discloses that sub-steps are non-fatal and that failures are logged. However, it does not clarify the destructive potential of the 'apply_cleanup' parameter (whether it actually deletes data) or describe the preview vs. apply modes in detail. The return structure is stated, providing moderate transparency.

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 exceptionally concise: two short sentences covering purpose, sub-steps, behavioral traits, and return format, plus a usage line. Every sentence adds value, and the structure is front-loaded with the main action.

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 (multi-step maintenance, one parameter, return structure), the description covers the main points: sub-steps, non-fatal behavior, usage triggers, and return format. It lacks details on prerequisites or side effects, but overall is sufficiently complete for an agent to use correctly.

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 coverage is 0%, so the description must compensate. It mentions 'cleanup_preview_bytes' in the return but does not explain the 'apply_cleanup' parameter. It fails to clarify that setting apply_cleanup to true triggers actual cleanup vs. preview-only. This is a significant gap given the parameter's crucial role.

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 tool's purpose: 'One-shot vault maintenance' with specific sub-steps (doctor autofix, dedup rebuild, bases refresh, cleanup preview). It effectively distinguishes itself from more specific sibling tools like run_doctor and cleanup_garbage by being a combined maintenance action.

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 provides usage triggers: 'Use when: user says 'tidy', 'maintenance', 'vault health check'.' This gives clear guidance on when to invoke. However, it lacks explicit exclusions or comparisons to sibling tools, which would improve differentiation.

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