delete_topic

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

With no annotations, the description carries the full burden and does it well: it discloses irreversibility ('Kafka has no undo: recreating the topic does not bring the data back'), collateral damage (consumer groups break), the two-stage confirm/acknowledge gating, non-atomic partial-batch failure, result ordering with index/result/error, refusal of internal topics, and the required Kafka DELETE permission. This is exactly the behavioral context annotations would otherwise supply.

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?

Front-loads the action and scale, then escalates to the destruction warning, then the confirm mechanics, then operational caveats. Dense but every sentence carries weight, with only slight redundancy against the schema (the 'array of length one' point is repeated in the items description).

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 high-risk mutation tool with two params, nested items, and a real output schema, the description covers safety gating, partial-failure semantics, permission requirements, and per-item result shape. Nothing an agent needs before calling 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?

Schema coverage is 100%, so the baseline is 3; the description nevertheless adds meaning by explaining that one confirm covers the whole batch, that acknowledge_data_loss is per-item and only needed when messages exist, and that results align to items order with an index. Minor overlap with schema text keeps it from a 5.

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?

States a precise verb and resource (delete Kafka topics), the batch shape (1 to 1000 via items, single delete = array of length one), and explicitly positions itself as 'the most destructive tool here', which separates it from siblings like delete_records or delete_consumer_group. An agent knows exactly what this does without opening the schema.

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?

Gives clear conditions for use: nothing is deleted unless confirm is true, and topics holding messages additionally require acknowledge_data_loss, plus the instruction to preview first for message_count. It does not name an alternative sibling (e.g. describe_topic or sample_messages) for pre-deletion inspection, so it stops short of explicit when-not/alternatives routing.

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