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

No annotations are provided, so the description carries the full burden. It discloses the informational read nature and the returned fields, which is helpful, but says nothing about permissions, whether it hits a live broker, latency, or failure behavior. For a zero-param read tool this is acceptable but leaves gaps.

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 the verb, resource and scope, and no filler. Every element 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?

An output schema exists, so return-value explanation is not required, and the tool has no parameters and no annotations to reconcile. The description is complete for such a simple read-only introspection tool.

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 tool takes zero parameters, so there is nothing to document; baseline 4 applies. The parenthetical content describes returned fields rather than inputs, which does not confuse the parameter story.

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 specific verb (获取) and a precise resource (Kafka 集群整体元数据与 Broker 节点列表), enumerating the returned contents (Cluster ID、控制器、节点地址). It is clearly distinguishable from the topic/message siblings, which all operate on topics or messages rather than cluster-level metadata.

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?

Usage is implied by the resource — an agent can infer this is the cluster-introspection tool — but the description never says when to choose it versus the topic-level siblings, and states no prerequisites or exclusions. Adequate but not explicit guidance.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one important trait not in any structured field: the tool is unavailable in read-only mode. But it omits other relevant behavior for a mutation tool, such as what happens if the topic already exists, permission requirements, or failure modes.

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 states the purpose first, then parenthetical details for tunables and the mode restriction. Nothing is wasted, though the parenthetical packs several distinct ideas together.

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. Still, for a mutation tool with zero annotations and 0% parameter description coverage, the description is thin: it does not cover error/conflict behavior or parameter constraints an agent needs to call it 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 coverage is 0% (properties have only titles), so the description must compensate. It does name the two tunable parameters (partition count and replication factor), but adds no semantics such as valid ranges, defaults, or the replication-factor-vs-broker constraint. It partially compensates but leaves real gaps.

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+resource ('create a new topic in the Kafka cluster'), which clearly distinguishes it from the list/describe/delete/produce siblings. It does not explicitly name alternatives, but the action is unambiguous.

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?

It provides one meaningful exclusion condition ('unavailable in read-only mode'), which is real usage guidance. However, it offers no when-to-use context relative to siblings and no guidance on prerequisites such as broker availability or existing topic conflicts.

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

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

With no annotations, the description carries the full burden and does disclose the critical trait: this is a destructive, high-risk operation that requires explicit confirm=True. It stops short of stating irreversibility, required permissions, or the effect on active consumers/producers.

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 carrying the action, the risk level, and the confirmation requirement with zero filler. Nothing to trim.

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 no explanation. The description covers the destructive nature and the confirm gate, but omits permissions/auth requirements and irreversibility, which matter for a destructive operation with no annotations.

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 0%, so the description must compensate. It fully explains the non-obvious `confirm` parameter (must be explicitly True), which is the semantically important one; `topic_name` is self-evident from its name. It adds real meaning beyond the bare boolean/default in the schema.

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 specific verb and resource ('delete topic from Kafka cluster'), which is unambiguous and inherently distinct from all siblings (list/describe/create/produce). An agent immediately knows what this tool 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?

The description flags the operation as high-risk and states the confirm=True prerequisite, which is useful gating guidance. However, it never says when to use this versus alternatives (e.g. kafka_describe_topic to verify before deleting) or when not to use it, so usage routing is only implied.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose what information is retrieved (partitions, leaders, ISR, config), which implies a read-only, non-mutating inspection, but it never explicitly states there are no side effects, nor does it mention error behavior for a non-existent topic or any permission requirements.

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 sentence with zero filler, front-loading the verb and resource before the parenthetical list of returned details. Every clause 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?

For a simple, one-parameter read tool with an output schema available, the description covers purpose and returned content adequately. The minor gaps are usage routing and explicit read-only/error behavior, which are not strictly required given the output schema carries return-value semantics.

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?

Only one parameter exists and the schema description coverage is 0% (just a 'Topic Name' title). The phrase '指定 Kafka 主题' implies the parameter identifies the topic to inspect, adding a little context, but it largely restates what the parameter name already conveys and gives no format or naming-convention guidance.

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 gives a specific verb (查询/describe) and resource (指定 Kafka 主题, a single named topic) and enumerates what it returns: partition distribution, Leader nodes, ISR replicas, and configuration. This implicitly separates it from kafka_list_topics (which enumerates topics) and kafka_cluster_info (which is cluster-scoped), though no sibling is named explicitly.

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 statement of when to use this tool versus kafka_list_topics, kafka_cluster_info, or the create/delete siblings, and no preconditions (e.g., topic must already exist) or exclusions are given. The agent must infer usage entirely from the purpose clause.

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

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.

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

No annotations are provided, so the description carries the full burden. It discloses the read-only-mode restriction and supported payload formats, which adds real context, but omits key behavioral traits for a write operation: required permissions, delivery guarantees, error behavior, and whether the write is idempotent/reversible.

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 that leads with the core action and then appends the mode restriction and format notes. No wasted words, though the parenthetical bundles several facts tightly.

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 the read-only caveat is helpful. Still, for a 5-parameter mutation tool with zero schema description coverage, the missing partition semantics and lack of operational context leave it only adequate.

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 mentions key, value/payload (clarifying JSON or text), and headers, adding format meaning beyond the bare schema. But it never addresses the partition parameter or what the key does with respect to partitioning, leaving a coverage gap.

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 specific verb and resource (send a message to a Kafka topic), which is clearly distinct from the sibling tools that only manage topic metadata (list/create/delete/describe). However, it does not explicitly name an alternative to route away from, so sibling differentiation is implicit rather than stated.

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?

Includes one useful condition — unavailable in read-only mode — which is a genuine 'when not to use' signal. It does not mention any alternative tools or when to prefer other approaches, and lacks prerequisites (e.g. topic must exist, broker connectivity).

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