consumer_lag

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 the call blocks for sample_seconds, that sampling windows run concurrently so waits don't accumulate, why sampling is required (Kafka stores no commit history), that ETA appears only when lag is shrinking, and that per-item results/errors are indexed. It omits auth/permission requirements, which is the remaining gap.

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 output shape are front-loaded, followed by behavioral caveats in short paragraphs; nothing is filler. Minor redundancy appears where concurrency and the blocking sample wait are re-explained in both description and 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?

Given a rich input schema and an existing output schema, the description need not explain return values, and it covers the essential behavior: latency cost, concurrency, ETA conditionality, and per-item error handling. Only permissions and any rate limits 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%, so the schema already fully documents topic, group, sample_seconds and skip_consume_rate; the description largely restates these. It adds the outer 1–100 sizing constraint and the single-topic-array idiom, but that is marginal beyond 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?

The description states a specific verb and resource ('Measure consumer lag'), names exactly what is returned (production and consumption rates, backlog state, ETA), and scopes it to 1–100 topics. An agent can distinguish this from describe_consumer_group or list_consumer_groups without opening a 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 operational conditions ('Set skip_consume_rate for an immediate result without an ETA') but never states when to prefer this over siblings such as describe_consumer_group or sample_messages. Usage is implied rather than compared against alternatives.

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