Remove a user from a team to revoke access while preserving audit history.
Remove a user from a team (destructive write — admin role). The membership row is deleted; the audit trail keeps the history.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | Organization UUID — obtain from scf_list_organizations | |
| team_id | Yes | Team UUID — obtain from scf_list_teams | |
| user_id | Yes | User UUID — obtain from scf_get_team |
Changes observed during successful MCP inspections.
v3.4.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds meaningful behavior beyond that: it specifies admin-role authorization, explains that the membership row is deleted rather than the user record, and clarifies that the audit trail preserves history. This gives the agent a clear picture of the action's blast radius and accountability.
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 no filler: the first names the action and key constraints, the second explains the precise effect and audit behavior. Everything included earns its place, and the most important operational warnings ('destructive write — admin role') are front-loaded.
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 simple three-UUID destructive mutation, the description covers purpose, permissions, effect, and audit trail. No output schema is present, but return-value semantics are not needed to call the tool correctly. Given the large sibling list, the unambiguous naming and clear effect make this sufficiently complete.
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 100%, with each UUID parameter already described via 'obtain from' pointers to list/get tools. The description does not add parameter-specific semantics, but it doesn't need to because the schema fully documents how to source values. This is the appropriate baseline for full schema coverage.
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?
The description opens with a specific verb and resource: 'Remove a user from a team.' It further clarifies that this removes the membership row, distinguishing it from sibling tools like scf_update_team or scf_add_team_member. The tool name and description align exactly, leaving no ambiguity about what this operation does.
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?
It clearly signals that this is a destructive admin-only action, telling the agent when it is appropriate to invoke it. It doesn't explicitly name alternatives or exclusions, but among the sibling tools, the inverse operation is obvious from the name and the description's 'remove' language. The 'admin role' note provides useful context about who can perform this action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.