compute.scan_storage

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

Annotations already declare readOnlyHint=true, so "read-only; never changes research files" mostly restates structured data. It does add the reassurance that research files are untouched, which is useful for a scan over project storage, but it says nothing about cost, scope limits, or what the scan produces despite there being no output schema to explain the return value.

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?

One compact sentence with the read-only guarantee front-loaded; nothing is wasted. It is under-specified rather than verbose, so the terseness is a clarity problem rather than a structural one.

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?

With no output schema, no parameter documentation, and only a single readOnlyHint annotation, the description needs to carry more weight than it does. An agent cannot tell from it what the scan reports, how node_id relates to project_id, or why to choose this over compute_check_storage or compute_report_storage.

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 0%, so both project_id and node_id are bare strings with no documented meaning anywhere. The description does not mention either parameter or whether node_id scopes which storage roots get scanned, leaving the caller to infer the relationship between a project and a node.

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 concrete verb and object: "Scan declared project storage roots," with the qualifier "read-only." That is more specific than the name alone, but it does not distinguish this from close siblings such as compute_check_storage, compute_report_storage, or compute_scan_storage's storage-plan relatives, so an agent must guess which storage tool to pick.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of the several sibling storage tools (compute_check_storage, compute_report_storage, compute_plan_storage_cleanup) that could plausibly be confused with it. The only inferred usage is that it is read-only, which the annotations already state.

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