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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial behavioral detail: deletion is immediate, idempotency is elaborated (already_deleted or never-existing returns success with already_absent: true), and the conditional connection deletion is explained. It also covers permission requirements and response contents, far exceeding annotation coverage.

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 information-dense but concise; every sentence contributes new value: purpose, side effect, permission, confirmation advice, idempotency, and response format. The core purpose is front-loaded, and there is no fluff. It reads cohesively and ends with a clear summary of return values.

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?

For a destructive tool with a single idempotent operation, the description covers all required context: what gets deleted, when the backing connection is deleted, permission requirements, the need to confirm via list_data, idempotent behavior, and the exact response fields. No output schema exists, but the description provides the return structure explicitly, making the tool fully usable without external docs.

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 sole parameter dataset_id is already fully described in the schema ('Dataset ID from connect_data or list_data.'), giving 100% schema coverage. The description does not add further parameter semantics, but the baseline of 3 is appropriate because the schema fully documents it and the description references it as 'dataset_id' consistently.

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 opens with a clear verb-resource pair: 'Delete a saved dataset and disconnect it from future use.' It then specifies a key side effect (connection deletion when unused) which distinguishes it from sibling delete tools like delete_connector and connects it to dataset-centric operations. The purpose is unambiguous and immediately actionable.

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 direct usage advice: 'Use list_data to confirm the dataset first — deletion is immediate.' It also states a prerequisite ('Requires manage permission on the dataset') and explains failure mode (access_scope_denied). It does not explicitly contrast with alternatives, but the guidance is sufficient for an agent to know when and how to invoke it.

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