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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's mutation nature is consistent. It adds the admin scope requirement and clarifies role semantics, which is useful beyond annotations. However, it does not disclose potential side effects (e.g., notification emails, irreversible removal) or what happens on invalid input. Given annotation coverage, this is a moderate contribution.

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 cover the core actions, roles, and admin requirement without redundancy. The front-loaded action list immediately orients the agent, and no filler exists.

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?

With a 100% schema coverage and an output schema present, the description covers the necessary invocation logic: actions, roles, and authentication scope. It doesn't explain error handling or edge cases, but for a mutation tool with clear schema documentation, this is adequate. Slightly more on expected outcomes would push it to 5, but it's already strong.

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%, so all parameters are documented. The description adds value by linking parameters to actions (email for invite, target_user_id for set_role/remove) and defining role values, which the schema lists but does not explain in context. This goes beyond simple repetition of 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?

The description clearly identifies the tool as managing org membership with three specific actions (invite, set_role, remove) and defines the role options. This distinguishes it from other org-related tools like configure_organization or list_organizations, making its purpose unambiguous.

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 explains when each action is appropriate (invite adds a member, set_role changes, remove removes) and lists the valid roles for organizations and families. It also notes the admin scope requirement, giving the agent context for invocation. It could be more explicit about when not to use this tool in favor of siblings, but the action-oriented guidance is strong.

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