Update group membership

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

Goes well beyond the destructiveHint=true annotation by naming the exact failure mode (stale fingerprint returns 409), the validation rules that cause rejection, and the irreversibility of removals ("Removal changes no record and cannot be undone"). The return contract ("ids actually changed") is 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?

Four terse sentences, each carrying a distinct fact — operation, fingerprint requirement, input constraints, return/irreversibility. The highest-value constraint (stale fingerprint = 409) is front-loaded and nothing is padded.

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 correctly supplies the return semantics ("ids actually changed") as well as conflict, validation, and reversibility behavior. Only the optional farm_id/default-farm behavior and any group-level authorization requirements are absent.

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 only 20%, so the description must compensate, and it does for the two riskiest parameters: membership_fingerprint (source and staleness behavior) and add/remove_animal_ids (overlap, same-farm, active constraints). farm_id and its optional-default behavior go unmentioned, which is the one gap.

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 pair ("Add and remove group members") that is unambiguous and distinguishes this from update_group, which mutates group metadata rather than its roster. It doesn't name a sibling or an explicit alternative, but the resource scope alone separates it cleanly.

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 preconditions for correct invocation: pass a fingerprint from a fresh group read, add/remove ids must not overlap, targets must be same-farm, additions must be active. It doesn't say when to prefer this over siblings like create_group or update_group, but the operational guidance is clear.

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