local_ydb_storage_leftovers

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, fully covering the safety profile. The description adds value by specifying WHAT it scans (Docker volume names plus profile.storageSearchPaths) and reaffirms 'deletes nothing,' creating redundancy with annotations but reinforcing the safety property. It doesn't overstate beyond annotations. Given strong annotation coverage, a 4 is fair since it adds scanning-scope context.

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 a single focused sentence that packs purpose, safety guarantee, and usage guidance efficiently. No wasted words. It could arguably be improved by separating the usage guidance into its own sentence for clearer front-loading, but the current form is compact and effective, earning a 4.

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?

The tool has no output schema, but it's a read-only search tool that returns candidate leftovers, and the description adequately frames what it produces (candidate volumes and paths for cleanup decisions). For a non-destructive search tool with strong annotations and full parameter documentation, the description is complete. It doesn't need to enumerate return formats.

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 description coverage is 100%, so both parameters (profile and configPath) are already documented with meaning in the schema. The description mentions 'profile.storageSearchPaths' which relates to the profile parameter, adding slight context about what the profile accesses. However, this is marginal beyond what the schema provides, so the baseline 3 for high schema coverage is appropriate.

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 it is a 'Read-only search for candidate leftover local-ydb Docker volumes, dumps, and PDisk/data paths.' It specifies the verb (search), resource (leftover volumes/dumps/PDisks), and scope. It explicitly distinguishes itself from the sibling local_ydb_cleanup_storage by noting it 'deletes nothing' and should be used before deciding exact paths or volumes to remove.

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 says to use the tool 'before local_ydb_cleanup_storage to decide exact paths or volumes to remove,' which provides clear sequencing guidance with an explicit alternative tool. It establishes read-only usage context. However, it doesn't explicitly state when NOT to use it or mention sibling tools like local_ydb_inventory or local_ydb_list_dumps which have overlapping scopes, so a slight deduction.

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