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 the confirm gate, that no change happens unless confirmed, that the batch is non-atomic with no rollback after partial success, that keyed-message ordering can break, and that Kafka ALTER permission is required. It also states duplicate topic names are refused before anything changes.

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?

Purpose and scale are front-loaded and every paragraph carries real information about risk or gating. Phrasing is slightly awkward ('increase the partition count of 1 to 1000 topics in one call through items') and the trailing note on acknowledge_key_ordering reads as an afterthought rather than integrated with the confirm discussion.

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 with no annotations, the description covers permission needs, gating, atomicity limits, and ordering hazards. An output schema exists, so the brief note about per-item results carrying index with result or error is sufficient rather than a gap.

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% and the per-item fields are already well documented, so the schema does the heavy lifting. The description reinforces batch semantics ('one confirm covers the whole batch', 'results follow items order, each carrying index with result or error') but adds little that the schema does not already say.

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 ('increase the partition count') plus an explicit scale ('1 to 1000 topics in one call through items'), and clarifies that a single-topic change is just an items array of length one. Combined with the 'Kafka cannot remove partitions' constraint, an agent can tell this is the in-place resize operation, distinct from siblings like create_topic or alter_topic_config.

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 operational context: batch via items, a dry-run default when confirm is absent, and the requirement to set acknowledge_key_ordering for keyed topics. It never names a sibling alternative (e.g. create_topic for new topics), so the exclusion side of the guidance is missing.

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 so: non-atomic batches, incremental merge semantics, duplicate-topic refusal, per-key source reporting (DYNAMIC_TOPIC_CONFIG vs inherited), retention.ms deletion side effect, warnings for cleanup.policy/retention.bytes, and the required Kafka ALTER_CONFIGS permission. These are exactly the traits an agent needs and none are in structured fields.

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 purpose and incremental semantics, and nearly every sentence carries a distinct behavioral fact with no filler. It is dense but slightly sprawling: warnings and atomicity could be grouped more tightly, and the permission requirement sits at the very end.

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 mutation tool with no annotations and a nested items array, the description covers safety (confirm gate), failure modes (non-atomic, per-item errors), side effects (retention eligibility, cleanup.policy warnings) and permissions. An output schema exists, so return-value shape is correctly left to it.

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 schema already documents items, set, delete, topic and confirm. The description still adds value by clarifying that one confirm covers the whole batch, that per-key results carry index in items order, and that set/delete are mutually exclusive at the key level.

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 (Change) and resource (topic-level configuration) with the exact scale (1 to 1000 topics) and the two per-item operations (set/delete). No sibling tool touches topic configs, and the description makes the boundary with add_partitions/create_topic obvious.

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 payload shape, that changes are incremental rather than full replaces, that one topic is an items array of length one, and that nothing happens unless confirm is true, which effectively describes a preview mode. It stops short of naming explicit alternatives (e.g. server_config for broker-level defaults), but the when-to-use context is unambiguous.

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 well: it explains what each problem flag means operationally, that acks=all producers fail with NOT_ENOUGH_REPLICAS, and that under_replicated during a reassignment is expected rather than an outage. It still never states explicitly that the call is read-only or comment on cost on large clusters.

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 a one-sentence summary of what one call returns, then a bulleted glossary of issue types that genuinely aids interpretation. The reassigning and min_isr_unknown paragraphs are useful but push the length past what an agent strictly needs.

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 two-parameter, fully optional-input diagnostic with an output schema, the definition covers interpretation of the results and edge cases (reassigning brokers, min_isr_unknown topics). Only the explicit read-only/no-side-effect assurance is missing, which matters given the absence of 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 100% and both parameters are already described there with the same case-insensitive substring and default-false semantics, so the description largely restates the schema. The only added value is the 'brokers and the controller are always reported' scope note and the usage framing for include_internal.

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 ('Check the health of the cluster') and immediately enumerates the payload (cluster id, controller, per-broker details, summary, problem partitions), which cleanly separates it from siblings like list_clusters or describe_topic.

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 concrete scoping guidance ('Use search to limit the check to topics whose name contains a substring') and a decision rule for internal topics (include them when consumer groups fail across the board). It never names a sibling alternative or states when a different tool would be a better choice.

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 so: it is a dry-run by default ('No change is made unless confirm is true'), one confirm covers the whole batch, applying is non-atomic and earlier commits cannot be rolled back, results follow items order with index, active groups are refused for a stated reason, and Kafka offset-commit permission is required.

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 action and the three targets, then the safety/confirmation behavior, then the active-group caveat. Slight redundancy with the schema in the parameter enumeration, but each paragraph carries distinct operational information.

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 shape needn't be spelled out, yet the description still signals the preview (per-partition and total skipped/replayed counts), the confirm gate, and the per-item result/error structure. Nothing an agent needs to invoke this mutation 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 description coverage is 100%, so the baseline is 3, and most of the description's parameter detail (offset meaning, timestamp semantics, position values, allow_active_members rationale) restates what the schema already documents. It adds only marginal framing, like 'Moving one offset is an items array of length one' and the exactly-one-target rule.

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 with scope: 'Move 1 to 1000 consumer group positions in one call through items.' No sibling tool (describe_consumer_group, delete_consumer_group, consumer_lag) does offset mutation, and the batch/replay framing makes the domain unmistakable.

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 precisely which of the three mutually exclusive targets to use and under what conditions: offset for a single partition, timestamp 'to replay since a moment', position for earliest/latest, and omit partition to move all partitions. It also describes the single-item case. It stops short of naming sibling alternatives such as describe_consumer_group for inspection.

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, yet the description covers the critical behavioral facts: it is non-mutating, only explicitly-set topic configs are compared (not inherited broker defaults), internal topics are excluded by default, and results come from the client metadata cache so recently created topics may appear missing. It even warns to repeat the comparison rather than double-create, which is exactly the kind of guidance an agent needs.

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 compare semantics and the report contents before details. It runs five paragraphs, and while most sentences carry information (cache staleness, config comparison rules), the create_topic hand-off and the cache caveat could be tightened.

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 description still summarizes the shape (which topics, partition count, RF, explicit configs). For a non-trivial multi-cluster comparison with no annotations, the description covers safety, staleness, filtering defaults, and follow-up actions with nothing material 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, but the description adds real meaning: a single comparison is an items array of length one, results follow item order, and an unreachable cluster is reported against its own item. The include_internal and search semantics are largely covered in the schema itself, so it sits just above baseline.

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 (compare), resource (topics/items across clusters), and scope (1 to 1000 other clusters against the one this endpoint serves). It explicitly enumerates what the report contains (only-here topics, only-there topics, disagreeing topics, broker/topic counts), which distinguishes it from siblings like describe_topic or list_topics.

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?

Names concrete scenarios ('find what preproduction has that production does not', 'check whether two environments still match') and hands off the follow-up action explicitly: missing topics go to create_topic, which previews against the broker first. It also states the tool creates nothing and points to list_clusters for valid names.

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 so: it discloses that the call blocks, why (Kafka stores no commit history), the concurrency ceiling (4 windows), the resulting latency model ('about sample_seconds per 4 items'), per-item error reporting via index, and the conditional ETA. This is exactly the behavioral context an agent needs before committing to a blocking call.

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?

Purpose is front-loaded in the first sentence, then output shape, then cost model, then the opt-out flag — a sensible order. Slight redundancy: the '4 windows at a time / sample_seconds per 4 items' fact is stated twice and is also repeated in the schema's 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 single batched parameter with an output schema present, everything an agent needs is covered: batch limits, ordering contract, failure isolation per item, latency, and the flag to skip sampling. Return-value internals are correctly left to the output 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?

Schema coverage is 100%, so baseline is 3; the description adds value beyond the schema by tying items ordering to results, clarifying the length-one case, and reinforcing the wall-clock cost of sample_seconds. It stops short of describing the group-resolution default in prose, leaving that to 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+resource ('Measure consumer lag') with explicit scope (1 to 1000 topics in one call) and enumerates the outputs produced (production/consumption rates, backlog state, ETA). However, it never names an overlapping sibling such as describe_consumer_group or list_consumer_groups, so sibling disambiguation is left to inference.

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?

Clear operational guidance: 'Set skip_consume_rate for an immediate result without an ETA' and 'Measuring one topic is an items array of length one' tell the agent how to size and configure calls. It lacks explicit when-not-to-use or alternative-tool routing, so it falls short of a 5.

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 so well: it discloses the non-atomic batch write behavior, that confirm gates all writes, result ordering, index/error reporting, permission requirements, read-only source allowance, and schema-ID translation implications.

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 front-loaded with the core operation and organized into short paragraphs covering batch behavior, confirmation, permissions, and schema handling. It is appropriately sized for a complex batch-copy tool, though it repeats the single-message case already covered by the items schema 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?

Given the batch complexity, cross-cluster behavior, confirmation gate, and schema registry nuances, the description is complete enough for an agent to invoke it correctly. An output schema exists, so return-value details need not be explained further.

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 parameter schema already documents fields in detail. The description still adds useful semantics beyond the schema, especially that one confirm covers the whole batch, that duplicate source/destination pairs are refused up front, and how translate_schema affects registry writes and ID rewriting.

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 opens with a precise verb and resource: copy 1 to 500 existing messages, identified by topic/partition/offset, to an existing topic. It distinguishes itself from read or produce siblings by emphasizing existing-message copying, provenance headers, and optional cross-cluster destination.

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 clearly establishes usage context: batch copying, how to copy a single message, the confirm requirement, and destination/source permission constraints. It does not explicitly name alternatives such as get_message, produce_message, or transform_messages, nor state when not to use 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?

With no annotations, the description carries the full burden and does it: confirm gating, non-atomic creation with partial failures that are not rolled back, refusal of existing topics and duplicates, broker defaults for omitted values, and the Kafka CREATE permission requirement. The irreversibility warning that partition counts cannot be reduced later is exactly the kind of consequence an agent must know before mutating.

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 scope, then layered semantics (confirm gate, atomicity, ordering) in short declarative sentences. No filler sentences and no restatement of the title.

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 destructive-capable batch write with no annotations, the description covers gating, failure modes, permissions and parameter defaults, and an output schema exists to explain return values. Nothing an agent needs in order to invoke it 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 description coverage is 100%, so the baseline is 3. The description adds some framing around the items array and confirming the whole batch, but it largely restates what the schema already documents for items, confirm, partitions and replication_factor.

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 (create Kafka topics) with explicit batch scope of 1 to 1000 and per-item fields. The line 'Existing topics are refused rather than modified' cleanly separates it from alter_topic_config, add_partitions and delete_topic without the agent needing to infer.

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 concrete selection guidance: 'Creating one topic is an items array of length one', and confirm=false as a validate-only dry run versus confirm=true to actually create. It never names a sibling tool for adjacent needs (e.g. changing existing topic configs), so it stops short of explicit alternatives.

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: confirm-gated preview, refusal of groups with active members, offset reset behavior for a reused group id, batch-level confirm, non-atomic partial failure, ordered per-item results, and the required Kafka DELETE permission. These are exactly the consequences an agent needs before calling a destructive 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?

Front-loaded with the action and the cancel-by-default confirm gate, then each subsequent paragraph earns its place by covering preview contents, refusal, consequences, and partial-failure ordering. It runs long for a tool description, but there is almost no filler.

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?

The output schema covers the per-item index/result/error shape, and the description covers everything else an agent needs: batch limit, confirm gate, preview payload, refusal conditions, non-atomicity, and permissions. Nothing material is left for the agent to guess.

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% and the schema already documents items, the one-group-as-array-of-one convention, duplicate-name refusal, and confirm semantics. The description restates those rather than adding new meaning such as validation rules, size limits per item, or error formats not in the schema, so 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 and resource (delete consumer groups), the scope (1–1000 per call via items), and the concrete side effect (committed offsets removed). It also disambiguates from sibling operations like describe_consumer_group or consumer_lag by framing this as the cleanup path for abandoned groups.

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 gives a clear when-to-use condition — decommissioned consumers whose stale commits report lag that will never drain — and a when-not case (groups with active members are refused). It does not name a sibling alternative such as resetting offsets or describing the group first, so usage routing is inferred rather than explicit.

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 so thoroughly: two independent gates (confirm and acknowledge_data_loss), preview contents including per-consumer-group data-loss exposure, irreversibility ('Kafka cannot restore deleted records'), non-atomic batch failure semantics, result ordering, duplicate item refusal, compacted-topic caveat, and the required Kafka DELETE permission.

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 operation and scope in the first sentence, then layers gating, preview, and failure semantics in short paragraphs that each carry distinct information. Length is justified by the destructive nature of the tool; nothing is padding.

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 exists, yet the description still summarizes the preview payload (start/end offsets, message counts, affected consumer groups). Combined with permissions, irreversibility, and partial-failure behavior, an agent has everything needed to call this safely.

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, but the description adds genuine cross-parameter meaning: one confirm covers the whole batch, all_partitions resolves a single moment per partition, and before_offset/before_timestamp are mutually exclusive. It does not add much to individual fields beyond what the schema already states.

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 the oldest messages of 1 to 1000 partitions') and immediately bounds the scope with 'without deleting the topic', which cleanly separates it from delete_topic in the sibling list. An agent knows exactly what operation this performs 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 concrete motivating scenarios ('purge test data, or a run of bad messages at the head of a partition, while keeping the topic, its configuration and its consumer groups') and clarifies the single-partition case. It never names a sibling alternative explicitly, relying on the implicit 'without deleting the topic' contrast with delete_topic, so it falls short of a full when/when-not/alternatives statement.

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 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.

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

With no annotations, the description carries the full burden and does well: it explains 'has_commit false' semantics, what an Empty group means, that sample_seconds blocks the call while observing, and that members/partitions are sorted with results returned in items order plus index. It omits cost/read-only framing and limits on describing 1000 groups at once, so it stops short of full disclosure.

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 verb, resource, and payload, then usage, then edge-case semantics. Mostly earns its length, though a few clauses (sorting, result indexes) are minor and the second paragraph could be tightened.

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 already exists, yet the description still explains the domain interpretation of results (has_commit, Empty groups, rebalance detection), which is genuinely useful for a Kafka operator. Gaps are minor: no statement of read-only safety or the latency cost of large items arrays with sample_seconds.

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 baseline is 3, but the description adds real meaning: it explains what sample_seconds observation reports (states passed through, members joined/left) and how to read it as a rebalance signal. Items ordering and per-item result/error behavior are also clarified beyond the schema text.

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 ('Describe 1 to 1000 consumer groups in one call') and immediately enumerates the returned facts (state, assignor, coordinator, members, offsets, lag), which clearly separates it from list_consumer_groups or consumer_lag. An agent can identify the tool 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 an explicit operational scenario: 'Use it to find which consumer instance owns a stuck or lagging partition, so the operator knows which pod or host to inspect.' However, it never names alternatives (consumer_lag, list_consumer_groups) or states when to use those instead.

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 burden and does well: it discloses per-item error isolation (a missing topic is reported against its own item instead of failing the call), result ordering by items index, and the important caveat that message counts are offset spans that may overcount after retention or compaction. It stops short of stating that the operation is read-only or of any permission/auth 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?

Front-loaded with the core action and scope in the first clause, then layered detail on return contents and caveats. The return-field enumeration (size_bytes, replicated_size_bytes, inherited vs topic-specific config) is dense but each item earns its place by disambiguating the payload.

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, yet the description adds genuinely useful semantics (offset-span overcounting, config inheritance) that a schema alone would not convey. For a single-parameter read tool, the only real omission is an explicit statement that the call is non-mutating.

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% at one parameter, so the schema already documents `items` and exact/case-sensitive topic matching. The description restates the 1-to-500 bound, the single-topic-is-length-one convention and the error-isolation behavior, which mostly duplicates the schema's own items description rather than adding new 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 verb and resource ('Describe ... topics') plus the batching scope (1 to 500) and enumerates exactly what is returned: partitions, offsets, sizes, timestamps, effective config. It is clearly distinguishable from mutation siblings, but it never names list_topics or explains how 'describe' differs from 'list', leaving that inference to the agent.

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 rather than stated: the batching range and the note that 'describing one topic is an items array of length one' tell the agent how to call it, but there is no explicit guidance on when to reach for describe_topic over list_topics or when to split into multiple calls.

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 it well: it discloses the decoding pipeline (Schema Registry ids, configured topic formats, format/schema_id/message_type fields), the text/base64 fallback for undecoded bytes, decode_error, truncation via max_value_bytes, and per-item error isolation so one bad address doesn't fail the call. It omits permission/auth requirements and any rate or cost characteristics, which keeps it off a 5.

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 payload, then organized into addressing, decoding, and error-order paragraphs. It is four paragraphs long but nearly every sentence contributes new information (decoding rules, binary fallback, per-item error semantics); only the closing 'items array of length one' sentence is close to redundant with the schema.

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 the description doesn't have to explain return shape, yet it usefully flags the envelope fields and decode metadata that matter for interpreting results. Combined with 100% schema coverage and detailed error-isolation behaviour, an agent has what it needs; only permissions and any preconditions for reading a topic are unaddressed.

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% and every nested field (topic, partition, offset, context, max_value_bytes) has its own description, so the baseline is 3. The description adds meaning about result ordering and index-keyed error reporting for items, but it doesn't restate the 1-500 bound or detail how context interacts with max_value_bytes beyond what the schema already says.

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?

Opens with a specific verb and resource ('Read 1 to 500 Kafka messages at exact addresses ... through items') and pins the scope to exact partition/offset addressing plus optional context neighbours. It implicitly contrasts with sample_messages/search_messages by stressing 'exact addresses', but never names those siblings, so an agent must infer the distinction.

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 rather than stated: 'at exact addresses' implies you already know the offset, and 'Reading one message is an items array of length one' covers the singleton case. There is no explicit 'use this instead of search_messages when you already have offsets' or prerequisite about discovering offsets first.

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 and does so: it discloses wholesale failure when the cluster has no schema_registry configured, partial failure semantics (results follow items order, each carrying index with result or error, a missing subject/id reported against its own item), that check_schema does not register anything, and that a subject lookup additionally reports the compatibility level in force.

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?

Purpose, return shape, usage trigger and failure behavior are all front-loaded before details, and each paragraph is topical. It is somewhat long, and the check_schema sentence reads like a separate tool blurb, which slightly blurs that it is an items-level option.

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?

Given an output schema exists, return values need not be spelled out, yet the description covers them; combined with the per-item error semantics, the Protobuf message_type hint for produce_message, and the subject naming convention, an agent has everything needed to call this correctly and interpret partial failures.

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; the description adds genuine semantics beyond the schema — the schema id is 'the schema id a message carries' (linking to get_message's schema_id), latest is the default unless version is given, version is ignored when id is used, and the <topic>-value subject naming convention. It stops short of elaborating on the check_schema result fields beyond what the nested schema states.

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 opening sentence names a specific verb (read), resource (schemas from this cluster's Schema Registry), scope (1 to 1000 in one call via items) and the two lookup keys (subject or schema id). It also enumerates what comes back — schema text, type, id, version, all subject versions, references, and the compatibility level. No sibling tool in the list does this, so the agent can route unambiguously.

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 gives a concrete trigger: read the schema before producing to a schema-encoded topic, because a sampled message may not reveal every field or enum — this implicitly positions it against sample_messages. It also clarifies that check_schema (a nested option here) verifies a candidate without registering it. It lacks an explicit 'when not to use' or a direct pointer to an alternative sibling for plain message inspection.

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 exist, so the description carries the full burden and does so well: it discloses the DESCRIBE permission requirement on the cluster, the SECURITY_DISABLED failure mode meaning no authorizer is present, that results are sorted, and the semantic rule that a deny overrides any allow.

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 what the tool does, then usage, then caveats. Mostly every sentence earns its place, though phrasing like 'so the answer covers what actually decides access' is slightly wordy for the value it adds.

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, and the description covers purpose, triggers, permission requirements, failure modes, and filter combination semantics. Nothing needed to invoke it 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, but the description adds real meaning: it explains that resource_name matches exact, prefixed, and wildcard entries and requires resource_type, and that a deny overrides an allow. That goes beyond the field-level schema text.

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 (List) and resource (access control entries/ACLs) plus the exact fields each entry contains (principal, host, resource_type, resource_name, pattern_type, operation, permission). No sibling tool covers ACLs, so the agent can route to it unambiguously.

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 an explicit trigger scenario (client fails with TOPIC_AUTHORIZATION_FAILED, GROUP_AUTHORIZATION_FAILED) and prescribes how to narrow: filter by the client's principal or by the refused resource. This is a concrete when-to-use with actionable filtering 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 burden and does well: it discloses that connectivity is checked at call time (a live probe, not cached data) and that broker and credential details are deliberately withheld, which is a meaningful security/data-exposure boundary. It doesn't cover call failure modes or whether the result is ordered, keeping it from a 5.

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?

Three tight sentences, front-loaded with what is listed, then the field semantics, then the gating rule and the disclosure boundary. Every sentence adds distinct information and none restates the name or title.

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 the description needn't re-explain return values, and with zero parameters the surface is small. It covers the field meanings, the liveness caveat, and the credential-exposure guard; only edge behavior (e.g., what a session-scoped writable=false implies for retries) is 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?

The tool takes zero parameters, so the baseline of 4 applies; there are no argument semantics that could be under-specified. The description correctly implies a no-argument, whole-server listing.

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 ('List the Kafka clusters this server serves') and enumerates the per-cluster attributes returned (reachable, read_only, writable). It is clearly distinguishable from sibling tools like cluster_health, list_topics, and server_config, which handle health metrics, topics, and server configuration respectively.

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 a concrete downstream usage rule: a cluster is only a valid copy_message or produce_message destination_cluster when writable is true, which tells the agent exactly why and when to call this first. It stops short of explicitly excluding alternatives (e.g., when to prefer cluster_health instead), so it lands at 4 rather than 5.

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 delivers two non-obvious behaviors: empty groups can still retain committed offsets and lag with no active consumers to drain them, and topic filtering may scan every group because Kafka lacks a topic-to-group index. That performance caveat is genuinely useful. It stops short of 5 by omitting any auth, pagination, or cost/limit disclosure.

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 returned fields, then the filtering and caveats. Four sentences with no filler; the final clause is slightly dense but each sentence carries information.

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 re-explained, and the description supplies the scope, filter semantics, and the empty-group/scan caveats. What is missing is routing guidance relative to the several sibling consumer-group tools, which an agent would still have to infer.

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 both parameters (topic, states) are already fully documented, including exact and case-sensitive matching. The description's 'filter by exact topic or group state' restates the schema, and the only added semantics concern the cost of topic filtering rather than the parameters themselves; 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 and resource ('List the consumer groups on the cluster') and enumerates the returned fields (state, member count, topics consumed). It distinguishes itself from describe_consumer_group and consumer_lag only implicitly, via the word 'list' and cluster scope, so it falls short of an explicit sibling contrast.

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 says which filters exist ('filter by exact topic or group state') but never says when to choose this tool over describe_consumer_group, consumer_lag, or delete_consumer_group, and gives no when-not guidance. Usage must be inferred from the 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?

With no annotations, the description carries the burden and does well: it discloses that topics whose predicate throws are tallied in script_errors rather than silently dropped, and explains why only self-set configs appear (inherited defaults would make every topic look configured). It omits any statement about read-only nature, permissions, or result size limits.

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 action and result shape, then filter guidance, then the two edge-case guarantees. Every sentence carries information, though the config-scoping rationale is stated in the description while also being restated in the schema's parameter text.

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 still covers the two things an agent could get wrong — filter expressiveness and silent-failure behavior via script_errors. No meaningful gap remains for a read-style listing 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?

Schema coverage is 100%, so baseline is 3; the description goes further by explaining the predicate's purpose, naming the readable fields (partitions, replication_factor, internal, configs), and clarifying the error-routing semantics of a throwing script. The timeout parameter is left to 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 ('List the topics on the endpoint's cluster') plus the exact shape of each row: name sort order, partition count, replication factor, and self-set configs. That is clearly distinguishable from siblings like describe_topic (single topic detail) or list_clusters (cluster inventory).

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 concrete usage context by showing what the optional predicate is for and contrasting it with a substring filter ('questions a substring filter cannot express, such as which topics have more than six partitions'). It never explicitly excludes or routes to a sibling such as describe_topic, so it stops short of a 5.

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 so well: it discloses required DESCRIBE permissions, per-item success/error behavior, exact output fields (last stable offset, high watermark, producer id/epoch, transactional id, state, timing, timeout), and broker timeout-abort behavior. It also warns that skipping offsets does not help, which is valuable operational context.

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 core action and diagnostic scenario are front-loaded, and nearly every sentence adds operational value about symptoms, output, remediation, or permissions. It is dense and somewhat long for a single-parameter tool, but the length is largely justified by the complexity of the failure mode.

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?

Given the tool's diagnostic complexity, an output schema exists, and the description reinforces the key return concepts, permissions, and remediation guidance. An agent has enough information to select and invoke the tool correctly, including why a stalled consumer is not the cause.

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 schema already documents the single items parameter and exact topic matching. The description still adds useful batch semantics: 1 to 1000 topics, result ordering following items order, and per-item error reporting for missing topics.

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 and resource ('Find open transactions') and precisely scopes it to read_committed consumers across 1 to 1000 topics via items. It explicitly distinguishes the symptom from consumer_lag's poison-message appearance, so an agent can route correctly 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?

It gives a clear diagnostic context (read_committed consumers stalled past the first message of an open transaction) and contrasts the presentation with consumer_lag. It also states the remediation path belongs to the producer, not the consumer. It stops short of an explicit 'when not to use' or a named alternative tool beyond the consumer_lag comparison.

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 so: nothing is written unless confirm is true, one confirm covers the whole batch, writes are non-atomic because Kafka cannot retract an earlier record, produced messages cannot be deleted until retention, the destination needs Kafka write permission while the called endpoint may be read-only, and upload files are read as they stream and never stored on the server. Provenance headers and the stdio-vs-HTTP upload difference are also disclosed.

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 capability and otherwise dense with useful facts, but it runs seven paragraphs and repeats the partition guidance and the items-vs-upload exclusion that already appear verbatim in the schema property descriptions.

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 multi-mode, high-risk write tool with a rich output schema, it covers invocation modes, confirmation gating, ordering of results, schema encoding requirements, and failure reporting (failing lines by number). An agent has everything needed to call it correctly without trial and error.

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 baseline would be 3, but the description adds non-obvious semantics: the items/upload mutual exclusion, that confirm gates the entire batch, that value_schema is required when existing messages carry a schema_id, and the partition/key-ordering tradeoff. These are decision-relevant facts not derivable from the schema text alone.

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?

Opens with a specific verb and resource plus capacity bounds: write 1 to 500 new messages via items, or any number from an upload, to existing topics on this or another cluster. It explicitly distinguishes itself from copy_message by noting the caller supplies key/value/headers so it can write content no producer ever sent.

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 explicit routing rules: use items vs upload (items for up to 500, upload for larger or pre-inspected sets), call get_message or sample_messages first to detect a schema_id, use value_schema when the topic's consumers read Avro/Protobuf/JSON Schema, and omit partition unless the exact partition matters. Exclusions and named alternatives are both present.

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 behavioral burden. It discloses decoding of Avro, Protobuf and JSON Schema values, how undecodable values are counted, per-message decode_error meaning, ordered results/errors, and the recency limitation; it does not explicitly discuss permissions or read-only side effects, but the sampling nature is clear.

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 front-loaded with the core purpose and follows with decoding semantics and result-order caveats. It is dense but every sentence contributes; only the long facet list in the first sentence slightly reduces crispness.

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?

Given an output schema and full input-schema coverage, the description supplies the missing behavioral context an agent needs: decoding/error semantics, recency limits, result ordering, and the key-handling caveat. No essential invocation guidance appears 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 description coverage is 100%, so baseline is 3. The description reinforces that items holds 1 to 500 topics and that sampling one topic is a length-one array, and it explains result order/error reporting, but it adds little beyond the schema's own descriptions for partitions, sample_size, and max_value_bytes.

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, and batch scope: 'Sample the newest messages of 1 to 500 topics in one call through items.' It also enumerates the summary facets returned and distinguishes the tool from search_messages by casting it as a predicate-design and schema-discovery step.

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?

Explicitly names search_messages as the downstream use case and says to use this to 'find the schema to produce against,' giving clear usage context. It also warns that the sample is recent-only and keys must not be used to guess partitions, though it does not state explicit when-not conditions versus get_message or get_schema.

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 zero annotations the description carries the full burden and does so well: it discloses that scans are bounded, per-partition reads are merged by timestamp, results have complete/stopped_reason/scanned_ranges to check, scripts past timeout_seconds are interrupted and counted in script_errors, and scripts are not memory-sandboxed. Download semantics are spelled out per transport (stdio writes the file immediately; HTTP returns a link and curl command, nothing stored server-side).

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?

Purpose is front-loaded and most paragraphs (bounded scans, partition merge ordering, DLQ/group_by examples) earn their place. However, the enumerated decoder variable list and the stdio-vs-HTTP download explanation duplicate the corresponding schema property descriptions almost verbatim, adding length without new information.

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 17-parameter, no-annotation tool with an output schema, the description covers the gaps that matter: what the script receives, how aggregation modes differ, scan bounds and the fields that signal them, and the transport difference for downloads. An agent has enough to call it correctly and to interpret truncated or empty results; return-value shape is left to the output schema, as permitted.

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 adds real meaning on top by explaining that group_by 'summarises instead of listing' with one example address per bucket, that direction chooses which matches survive truncation, and that every partition is read together ('newest in the topic rather than newest in one partition'). The script variable list and download explanation largely restate the schema text, limiting the added value.

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?

Opens with a specific verb, resource and mechanism ('Search message key, value, headers or metadata with a JavaScript predicate') and then delimits the two output modes (listing vs. group_by summarisation). An agent can tell what it does without opening the schema. It stops short of naming a sibling (e.g. sample_messages or get_message) as the alternative, so it is clear but not sibling-differentiated.

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 concrete when-to-use scenarios ('break a DLQ down by error header, find hot keys on a partition, or count messages per schema_id') and workflow advice ('Use count_only for large result sets', 'Use this first when a query may match a great many messages, then ask the user'). It also warns how to interpret results ('Check complete, stopped_reason and scanned_ranges before treating no matches as conclusive'). No explicit when-NOT-to-use or named alternative tool, which keeps it off the top score.

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 burden and does so well: it discloses that this is a read-only reporting call, that read-only policy is itself part of the payload, and that "Passwords are never returned" — a meaningful security guarantee an agent could not infer from the schema. It omits any statement about side effects or cost/latency, which keeps it from a 5.

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 action and the returned fields, then pivots to usage guidance and the security caveat. The field enumeration is long but each item is a distinct capability an agent may need to know exists, so little is wasted — though the run-on list could be tightened.

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 shape needs no explanation. For a zero-parameter read tool, the description covers what is reported, when to call it, the multi-endpoint-per-cluster nuance, and the password redaction guarantee — nothing an agent needs in order to call it 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?

The tool takes zero parameters and the schema is an empty object, so there is no parameter semantics to explain and no schema gap to compensate for. Baseline 4 applies; the description correctly spends no words on parameters.

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 ("Report") and then enumerates the exact resource fields returned: endpoint name, path, cluster, brokers, auth, TLS, read-only policy, destinations, Schema Registry, topic formats and exposed tools. An agent can immediately tell this is an endpoint self-description tool rather than a cluster lister or topic inspector, which separates it from siblings like list_clusters.

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 explicit timing guidance: "Use it to confirm the target and permissions before acting," plus a non-obvious caveat that several endpoints may target one cluster with different policies. It stops short of naming a specific alternative or a when-not-to-use condition, so it is strong but not a full routing statement.

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