OpenPanel: Assign group

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

Annotations already flag readOnlyHint=false and destructiveHint=true, so the description doesn't need to establish that this is a write. It does add genuinely new behavioral information — the device-ID fallback when profile_id is null — which the schema cannot express. However, it never explains why the tool is marked destructive: whether existing group memberships are replaced or merged, and whether the assignment can be undone. For a destructive mutation that omission is significant.

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?

Two short sentences, front-loaded with the action and immediately followed by the fallback rule. The '[UNIFIED]' prefix is unexplained noise that consumes attention without adding meaning, which is the only real waste.

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?

This is a destructive, non-idempotent mutation with no output schema and zero parameter documentation, so the description should be doing much more work. It leaves the group_ids payload shape, the meaning of `site`, and the overwrite-vs-append semantics entirely unspecified.

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 carry the full burden. It clarifies network profile_id (null triggers device-ID fallback), but says nothing about `site` or about what `group_ids` accepts — an untyped array whose element shape (string IDs vs. objects) is completely undocumented.

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: assign a user to one or more groups. The scope (single or multiple groups) is clear. It doesn't distinguish itself from the nearest sibling, openpanel_identify_user, which an agent might reasonably consider for the same task, 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?

Provides one concrete conditional: if no profile_id is supplied, the call falls back to device ID. That's useful routing information, but there is no guidance on when to prefer this tool over openpanel_identify_user or openpanel_create_group, and no prerequisites are stated.

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