modx_update_group_member

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing. It does not state that this mutates persisted permission data, whether elevated permissions are required, what happens if role is omitted, or whether changes take effect immediately or via a cache flush.

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?

One front-loaded sentence with no filler, and the clarifying example is placed usefully at the end. It is efficient, though its brevity edges into under-specification for a permission-mutating tool.

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 zero annotation coverage, no output schema, and 0% parameter documentation, the definition is far too thin. An agent can guess intent but cannot reliably determine prerequisites, effects, or parameter formats from this description alone.

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 0%, so the description must compensate for three undocumented parameters, and it largely fails. It implies role is the mutable field, but never says user and usergroup are numeric IDs, nor clarifies that role is optional or what omitting it does (e.g. reset to no role).

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?

"Update a user's membership in a group" names a specific verb and resource, and the parenthetical "(e.g. change role)" clarifies what an update means in this domain. It is distinguishable from siblings like modx_add_user_to_group and modx_remove_user_from_group by implication, but it never names them explicitly.

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?

The only usage signal is the example "change role", which hints at intent but gives no when-to-use conditions or exclusions. Nothing tells the agent to prefer add_user_to_group for new memberships or remove_user_from_group for deletion, which is the most likely selection error given nearly identical siblings.

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