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

Annotations already mark this as destructive, idempotent, open-world, and non-readonly, but the description adds crucial consequences: contactVisibleToManagers=true publicly exposes plaintext mobile numbers to OWNER/ADMIN and cannot be retracted once seen; private orgs force showOnProfile=false; per-org updated/failed results must be verified; rate limits require retrying only failed ids. This goes well beyond the structured hints.

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 a single dense paragraph that front-loads login/self constraints before purpose and usage. Every clause carries necessary information, but the semicolon-heavy run-on structure reduces readability and could be better organized with bullets.

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 an 8-parameter destructive mutation with no output schema and very low schema description coverage, the description covers the essential login/self scope, all major fields, prerequisite list call, batch semantics, critical safety warnings for phone exposure and contact sharing, private-org force-down, minimum-change constraint, per-org result verification, rate-limit retry, and role/kick exclusions.

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 only 13%, so the description must compensate. It maps human terms to several parameters (主页展示→showOnProfile, 组织撮合→matchingOptIn, 管理员联系方式→contactVisibleToManagers, 服务或推广通知→service/marketing notifications) and explains organizationIds batching behavior, but it does not define the contactSharing enum values or distinguish serviceNotifications from marketingNotifications fully.

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 states a specific verb (改/change) and resource scope (my membership settings in organizations), lists the exact fields controlled (profile display, matching, manager contact, service/marketing notifications, hideFromDirectory, contactSharing), and explicitly distinguishes itself from the sibling list_my_organization_memberships by instructing the agent to call that first.

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 gives explicit when-to-use steps (call list_my_organization_memberships to see current values), batch behavior (omit organizationIds to change all orgs), prerequisites for risky operations (name organizations for non-NONE contactSharing, confirm org ids individually for contactVisibleToManagers=true), constraints (private org showOnProfile forced false, at least one item), and exclusions (cannot change role or kick people).

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