create_topic

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

With no annotations, the description carries the full behavioral burden and does so richly: confirm=false means validation-only, one confirm covers the whole batch, creation is non-atomic with partial results persisted, results follow items order with per-item index, and the call requires Kafka CREATE permission. These are exactly the traits an agent cannot infer from the schema.

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-loaded with the core action and count range, then organized into short paragraphs on defaults, the confirm gate, non-atomicity, and permissions. Slightly redundant in restating the existing-topic refusal and the confirm rule that the schema also states, but no sentence is wasted.

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?

Output schema is present and the description still usefully notes that results mirror items order with index plus result-or-error. Combined with the permission requirement and partial-failure caveat, an agent has everything needed to invoke and interpret this batch mutation correctly.

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 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the batch-level semantics of confirm (one flag governs all items) and that omitted values fall back to broker defaults. It does not add new per-item syntax detail beyond what the schema already documents.

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 scoped to a batch ('Create 1 to 100 Kafka topics in one call through items'), and the scope immediately separates it from siblings like delete_topic, add_partitions and alter_topic_config. Adds the key constraint that existing topics are refused rather than modified.

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?

Explains the confirm-gate workflow and clarifies that a single topic is just an items array of length one, which tells the agent exactly how to invoke it. It notes partition counts can only grow, hinting at add_partitions as the later alternative, but never names a sibling tool or gives an explicit when-to-use-this-vs-that comparison.

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