Plan a change to a ChurchTools group membership

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

Adds genuinely non-obvious behavior beyond the annotations: the call has no write effect ('Writes nothing'), it *returns a plan* rather than applying anything, and it patches only fields whose value actually changes (so an omitted field is not a clear, while an explicit null is). The diff-patch semantics is exactly the kind of detail an agent cannot recover from the schema. Minor tension with readOnlyHint=false, which is reconcilable if the generated plan/operation is itself persisted, but the description does not resolve it explicitly.

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?

A single dense sentence, front-loaded with the most decision-relevant fact ('Writes nothing') and structured with a colon before the field list. Nothing is wasted, though the extreme terseness is what leaves the usage/workflow gap.

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 fills that gap by stating the return value is a plan, and it explains the no-write and diff-only semantics. The one real omission is the downstream contract: nothing tells the agent how the returned plan is applied (presumably via ct_execute_plan), which matters for invoking the tool correctly as part of a workflow.

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 the schema already documents each field, including the enum meanings for groupMemberStatus and the 'null clears it' semantics. The description only recasts the fields in business language (role, status, comment, start/end date), which adds mild mapping value but no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 action and scope: it returns a *plan* that patches a defined set of membership fields (role, status, comment, start/end date). That is far more precise than a restatement of the name and implies update-of-existing rather than add/remove. It stops short of naming the sibling tools it is meant to be chosen over (ct_add_group_member, ct_remove_group_member, ct_execute_plan), so it is clear but not sibling-differentiating.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the plan/execute handoff that this server clearly has (siblings ct_execute_plan and ct_get_operation). An agent is left to infer from the name alone that this is the tool for changing an existing membership, and to infer on its own what must be done with the returned plan.

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