Update group rule

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

Adds real context beyond the annotations: patch semantics ("fields you leave out stay"), a return-value note ("Returns the whole new list" — important since there is no output schema), and that it "Runs without asking first: nobody is notified," which confirms no confirmation prompt and no fan-out. The only weakness is the unexplained tension between partial-update semantics and idempotentHint=false.

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?

Short and front-loaded, leading with what changes and who may do it. The redundant repetition of "Admins only" in a four-sentence description is wasted space but not enough to break readability.

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 output schema, the description covers the permission requirement, the mutation semantics, the response shape, and the absence of notifications or confirmation prompts. An agent has everything needed to call it correctly and predict the effect.

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 meaning about omitted fields ("fields you leave out stay"), explaining the optional title/description behavior that the schema alone does not state. It also names the two editable fields, tying them to the patch model.

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 ("Change the title or text of a group rule") and grounds it in a concrete UI analogue ("as Settings, Rules, Edit does"), so an agent knows exactly what is modified. It does not explicitly distinguish itself from siblings like add_group_rule or delete_group_rule, though the verb makes the separation 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?

"Admins only" gives a clear prerequisite and "Edits one rule" bounds the scope to a single rule, both of which gate correct invocation. No alternatives or when-not conditions (e.g., use add_group_rule to create) are named, leaving routing to inference from the tool name.

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