things_preview_destructive

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: it never grants permission, cannot enumerate checklist/heading/repeat-template content, lacks atomic scope locking, and requires health checks for native execution gates. These disclosures do not contradict the annotations.

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 compact and front-loaded: the first sentence states the operation, then the second adds return/behavior info, and the third adds limitations and gating. Every sentence earns its place; there is no fluff or redundant restatement of the schema.

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 annotations and an output schema present, the description does not need to explain return values in detail, and it covers the tool's purpose and limitations well. However, it is not fully complete because it does not clarify the relationship between the action enum and the target object, which is important for a tool with nested input and conditionally relevant parameters.

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 the description needed to explain action and target semantics. It mentions the three action categories in prose, but it does not map them to the 'action' enum or explain the optional 'target' object, its kind/id fields, or when target is required. This leaves the input semantics under-specified for an agent.

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 leads with a specific verb ('Inspect') and a concrete resource ('the exposed scope of project/area/tag deletion, emptying Trash, or logging completed items'). It also states it returns a scope revision and never grants permission, which clearly separates it from things_apply_destructive despite not naming that sibling.

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 gives useful context: this is an inspection/preview operation, not a permission-granting one, and it tells the user to 'Check health for native execution gates.' However, it does not explicitly name the alternative execution tool or state when not to use it, so alternatives are left implied rather than fully specified.

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