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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context beyond annotations: phone numbers are deliberately stripped at the code layer even if the service layer would return them, membershipId is membership.id not userId, and pagination is capped at 200 with nextCursor. These are non-obvious behavioral traits that an agent must know to avoid errors.

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 compact and front-loaded: the auth requirement and core action appear first, followed by the chain usage, then the pitfalls. Every sentence earns its place—no filler. The use of numbered sections (① ② ③) makes the critical caveats scannable. It's dense but well-organized for an agent to parse quickly.

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 read-only list tool with 100% schema coverage and no output schema, the description covers everything an agent needs: auth role, pagination limit and cursor mechanics, the membershipId vs userId trap, and the phone-number privacy constraint. The chain guidance tells the agent what to do with the results. There is no output schema, but the description's mention of user.id and membershipId as outputs compensates for that gap.

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 100%, so the schema already documents all three parameters. The description adds value by clarifying the pagination semantics (一页最多 200, nextCursor 翻页) and the critical distinction that membershipId is not userId, which directly affects how the cursor and returned fields are interpreted. It doesn't add per-parameter syntax details, but the schema already covers those, so the description's marginal additions are meaningful.

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 and resource: '列在册成员' (list registered members) with a clear scope of organization members. It distinguishes itself from siblings like list_chain_group_members and list_my_organization_memberships by focusing on the organization roster. The title and description align, and the '组合链' section clarifies how this tool's outputs feed into other tools, making its purpose unmistakable.

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 states when to use this tool: requires login and OWNER/ADMIN role, and it's part of a chain (拿 user.id → get_creator / start_conversation; 拿 membershipId 做成员级操作). It also provides exclusions: phone numbers are never returned, so for contact info use in-app messaging. This is explicit when/when-not guidance with alternatives named.

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