post_group_offsets

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

The annotations already declare readOnlyHint=false and idempotentHint=false, and the description adds no behavioral context beyond the word 'Update'. It doesn't disclose whether existing offsets are overwritten wholesale, whether the group must be stopped, what side effects occur, or any auth requirements — a real gap for a mutation tool. No contradiction with annotations exists.

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 four-word sentence with zero wasted words and the verb front-loaded. It is appropriately terse, though it is also the bare minimum — no secondary context is included, which is more a completeness issue than a conciseness one.

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 write operation with no output schema, the description is incomplete: it doesn't explain what the response looks like, what success means, what offsets get committed, or any prerequisites. An agent calling this tool cannot predict the call's outcome beyond 'offsets get updated.'

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 cluster, groupName, and offsets are each already documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, 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 states a specific verb ('Update') and resource ('consumer group offsets'), making the tool's purpose immediately clear. It implicitly contrasts with sibling get_group_offsets, which reads the same resource, though it doesn't explicitly name the alternative, so it stops short of a 5.

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 on when to use this tool versus siblings like get_group_offsets (read) or delete_group (remove). No prerequisites are mentioned, such as whether the consumer group must exist or be inactive, and no exclusions or alternative conditions are stated.

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