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

Beyond the annotations (destructiveHint: true, readOnlyHint: false), the description explicitly labels it a 'destructive action' and mentions 'After authorization', providing additional context about the tool's side effects and prerequisite. It also discloses limitations on who can be removed, which is valuable behavioral information.

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?

The description is concise, consisting of two sentences with no redundant information. It front-loads the primary action and includes necessary constraints and authorization context without unnecessary elaboration.

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 tool with a single parameter and no output schema, the description is complete. It covers the action, the effect (revoking access), the constraint (owners/acting user), and the authorization requirement. No additional context is needed for an agent to use it correctly.

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?

The member_id parameter description adds meaningful context beyond the schema: it clarifies the parameter is a numeric ID, specifies it refers to a user/member, and advises using list-team-members first when the user provides a name or email. This directly helps the agent correctly populate the parameter.

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 clearly states the tool's purpose: to remove an existing teammate and revoke their access to team Spaces. It uses specific verbs ('remove', 'revoke') and the resource ('teammate', 'team Spaces'), distinguishing it from sibling tools like invite-team-member or update-team-member-role.

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 explicitly says 'Use this when the user explicitly wants to remove an existing teammate', providing direct guidance on when to select this tool. It also notes constraints (owners and acting user cannot be removed) and the parameter description advises using list-team-members first when given a name/email, offering clear alternative paths.

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