x_list_delete

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

The description adds substantial behavioral context beyond the annotations: it explicitly says the operation is 'permanently delete' and 'Irreversible,' and details exactly what is destroyed ('the list, its member roster, and its followers'). It also notes a policy-based disablement ('disabled by policy read-only'), which is practical operational information an agent can act on. There is no contradiction with 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 with the core action and consequences. The first sentence is direct, the second explains what is lost, and the last provides policy context. The 'Standalone (never behind an enum)' phrase is somewhat meta and could be considered extraneous for an agent, but it does clarify why the tool exists separately for policy targeting, so it earns its place.

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 a single parameter, full schema coverage, an output schema, and annotations that already mark it as destructive and non-idempotent. The description adds the key missing context: irreversibility, what gets deleted, ownership restriction, and policy disablement. Nothing an agent needs to decide whether or how to invoke this tool correctly is missing.

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 schema already fully documents list_id, including the accepted forms (numeric id or list URL), so the schema coverage is 100%. The description adds an important semantic constraint: the list must be the authenticated user's own list, which is not stated in the schema. This extra ownership context meaningfully informs how the agent should choose a valid list_id.

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 begins with a specific verb and resource: 'permanently delete the authenticated user's own list.' It clearly scopes the action to the authenticated user's own list, which distinguishes it from list creation, updates, membership operations, and read-only list tools. The inclusion of 'X (Twitter)' also specifies the platform unambiguously.

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 provides a clear context for use: when the authenticated user wants to permanently delete their own list. It does not explicitly name alternatives or exclusion criteria, but the action is unique among the sibling tools and is unambiguous. It also warns that the deletion is irreversible, which helps an agent avoid unintended destructive calls.

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