kafka_list_topics

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

With no annotations, the description carries the full burden, and it does disclose one meaningful behavioral trait: internal system topics are excluded by default. However, it omits other behavioral context such as auth/permission requirements, result limits, or ordering. It adds some value but leaves notable gaps for a zero-annotation tool.

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?

A single front-loaded sentence with no wasted words, efficiently combining the core action with the two key behaviors. It is appropriately sized for a simple two-parameter list tool.

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?

An output schema exists, so return values need not be explained, and both simple parameters are touched on. For a low-complexity list tool this is nearly complete, with only pattern syntax and usage alternatives left implicit.

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 must compensate. It does map to both parameters, indicating that 'pattern' filters by name and that internal topics are excluded by default (matching include_internal's default), but it gives no pattern syntax (glob vs regex vs substring), leaving format semantics unclear.

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 states a specific verb (列出/list) and resource (Kafka 主题/topics) with scope ('Kafka 集群中的'), making the operation unambiguous. It does not explicitly differentiate itself from siblings like kafka_describe_topic or kafka_cluster_info, but the list operation is naturally distinct.

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?

There is no guidance on when to use this versus alternatives such as kafka_describe_topic for details or kafka_cluster_info for cluster metadata. Usage is only implied by the verb 'list', and no exclusions or prerequisites are given.

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