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

Annotations already declare the operation read-only, idempotent, open-world, and non-destructive. The description adds value by specifying the output scope (brokers, controller, cluster id), which is especially helpful given there is no output schema. No contradiction with 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?

A single, front-loaded sentence with no filler. Every word earns its place, and the colon-delimited list makes the scope immediately scannable.

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 zero-parameter, read-only tool, this is complete: annotations cover the safety profile, and the description states the expected return scope. No output schema exists, but the enumerated components give the agent a clear expectation.

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 the description has no parameter semantics to add. The baseline of 4 for no-parameter tools applies, and the description's component list effectively clarifies what the call returns.

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 uses a specific verb ('Describe') and resource ('Kafka cluster'), and enumerates the exact components covered ('brokers, controller, and cluster id'). This clearly distinguishes it from sibling tools focused on topics, consumer groups, and offsets.

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 implies the use case by naming the cluster-level resource, but it does not explicitly state when to use this tool over siblings or mention alternatives for topic/group operations. Guidance is left to inference.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that lag is computed across topics, implying a heavier read, but says nothing about cost, latency, or what happens for a group with no active members – a 3 is appropriate given the structured data does most of the work.

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?

One tight sentence, front-loaded with the primary action and followed by the secondary computation. Nothing 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?

For a one-parameter read tool with full annotation coverage and no output schema, the description is adequate but leaves two gaps an agent would care about: no routing guidance versus list_consumer_groups, and no indication of what the response contains now that the lag computation is the distinguishing feature.

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% with a single groupId parameter documented in the schema, so the schema carries the meaning. The description adds no format or scoping detail (e.g. whether groupId is cluster-qualified), so the baseline 3 applies.

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 (describe) and resource (consumer group), plus a second capability (compute per-partition and total lag). It is clearly distinct from list_consumer_groups by being single-group and lag-aware, though it never names that sibling to make the distinction explicit.

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?

No when-to-use guidance and no alternatives named. An agent cannot tell from the description whether to reach for this or list_consumer_groups/describe_topic for a given question; the lag mention implies a use case but does not state it.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the only behavioral-adjacent context: which fields are returned (partitions, replicas, ISR, non-default configs). It says nothing about error behavior for a nonexistent topic or response format.

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?

It is a single short fragment with no wasted words and the key content is front-loaded. However, it is a fragment rather than a sentence, so brevity comes at the cost of under-specification rather than deliberate conciseness.

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?

With no output schema, the description is the only source of return-value information, and it does list the main categories of data returned. It is still incomplete for a describe-style tool, omitting leader/replication details, config value semantics, and behavior when the topic does not exist.

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?

There is a single parameter, and schema description coverage is 100% ('Topic name'), so the schema fully documents it. The description adds no extra meaning about the topic identifier (e.g., naming conventions or whether it must already exist), so the baseline of 3 applies.

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 is a noun-phrase fragment that enumerates the payload contents (partitions, replicas, ISR, non-default configs) for a topic, which implies what the tool returns. It never states a verb or explicitly says it retrieves topic metadata, so the purpose is inferred rather than declared. It does at least distinguish itself from siblings like list_topics by being clearly per-topic detail.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as list_topics or topic_offsets. An agent must infer from the name and siblings when this tool is appropriate.

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?

The annotations already cover safety semantics: read-only, non-destructive, idempotent, and open-world. The description adds that protocol types are included in the result, but gives no additional behavioral context such as pagination, ordering, or whether all known consumer groups are returned.

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 a single sentence that efficiently conveys both the operation and a useful piece of return data. Every word contributes value.

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 parameterless list operation, the description plus annotations are sufficient for an agent to select and invoke it correctly. No output schema exists, but none is needed to know how to call this 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 has zero parameters and the input schema is empty with perfect coverage. There is nothing for the description to add about parameter meaning, so the baseline of 4 applies.

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 action ('List') and resource ('consumer groups'), and names the return content ('protocol types'). It can be distinguished from siblings such as describe_consumer_group and list_topics because 'list' plus the resource clearly signals an overview operation.

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?

No guidance is given about when to use this tool versus describe_consumer_group for more detail, or when list_topics is more appropriate. The agent must infer the use case from the tool name alone.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral note that topics outside the allowlist are filtered out, but does not explain what the allowlist is or how results are ordered/limited.

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?

Two short sentences, both front-loaded with the essential facts, with zero filler. The filtering caveat follows immediately after the core purpose.

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, single-optional-param read tool with no output schema and full annotation coverage, this is mostly adequate. However, the allowlist constraint is stated without any indication of what governs it, and the internal-topic option is left entirely to the schema.

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 single parameter (includeInternal) is fully documented in the schema at 100% coverage, so the schema does the heavy lifting. The description adds no parameter-level detail, making the baseline 3 appropriate.

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+resource ('List topic names'), which clearly distinguishes it from describe_topic, topic_offsets, and list_consumer_groups. The resource (topics) is unambiguous, though it does not explicitly name a sibling it is not.

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?

No guidance on when to use this vs describe_topic (which presumably returns details for a single topic) or the other listing tools. Usage is only implied by the word 'list'; no alternatives or conditions are named.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description's contribution is naming the returned data (earliest/latest offsets per partition), which does add context annotations lack, but it says nothing about auth requirements, error cases, or whether offsets are live or cached.

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 tight sentence with the resource and the framing use case front-loaded. No wasted words, no repetition of the title beyond what is necessary.

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?

With no output schema, the description must convey return content, and it does name the key fields (earliest and latest offsets per partition). For a simple one-param read tool this is nearly sufficient, though it could state the response shape or ordering more explicitly.

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?

With a single parameter at 100% schema description coverage, the schema already documents 'topic' as the topic name. The description adds only that offsets are scoped 'per partition', which clarifies granularity but not parameter meaning itself. Baseline 3 applies since schema carries the semantics.

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 resource (earliest and latest offsets per partition for a topic) with a clear output-oriented purpose and a parenthetical framing as a backlog view. It is distinguishable from sibling describe_topic by its focus on offsets rather than topic metadata, though it never names an alternative outright.

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 phrase '(message backlog view)' implies the intended use case: gauging consumption backlog. However, it gives no explicit when-to-use/when-not-to-use guidance and does not reference siblings like describe_topic or describe_consumer_group, leaving the agent to infer the boundary.

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