Update team member role

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

Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a mutation that isn't destructive. The description adds the constraint about non-owner members and UI-only ownership transfer, which is useful context. It doesn't disclose permission requirements, reversibility of the role change, or idempotency behavior, but the annotations carry the safety profile.

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 sentences with zero waste. The first sentence states the action with precise role values and target constraint; the second sentence provides the critical exclusion (UI-only ownership transfer). Every word earns its place.

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 and moderate schema coverage, the description covers the core action and a key constraint. However, it doesn't address the idempotency_key parameter at all, doesn't mention what happens to an owner if somehow targeted, and doesn't describe response behavior for a state-changing operation. Adequate but with gaps.

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 75%, with role having an enum and member_id/project_id having patterns and descriptions. The description reinforces the role values (admin, member, viewer) and the non-owner constraint that clarifies member_id scope. It doesn't explain the idempotency_key parameter, which is undocumented in the schema, but the description adds meaningful scoping context beyond the schema.

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?

Clear verb+resource+scope: "Change a non-owner project member role to admin, member, or viewer." It specifies the exact roles available and the constraint that the target must be a non-owner. It doesn't explicitly differentiate from siblings like remove_team_member or list_team_members, but the purpose is evident from the name and description.

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 description states what it does (change non-owner roles) and explicitly notes ownership transfer is UI-only, providing a clear exclusion boundary. This tells the agent when NOT to use this tool (for ownership transfer). However, it doesn't name alternative tools or describe when to prefer this over list_team_members/remove_team_member/edit flows.

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