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

Annotations already declare readOnlyHint=true, and the description adds behavior beyond that: a hard 500-result cap, visibility-scoped filtering, and a deliberately minimal return shape (id, nickname, avatar only). Auth/permission requirements are also surfaced, which is exactly the kind of context annotations do not carry, though the meaning of 'member visibility' filtering is left unexplained.

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, zero filler, permission tags front-loaded and the workflow hint trailing. The telegraphic style is dense but every clause carries information; the catalog-style arrow sequence is compact rather than wasteful.

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 one-parameter, read-only list tool with no output schema, the definition covers the essentials: result cap, returned fields, auth permission, and where the output feeds into the draft workflow. Remaining gaps (ordering, what visibility tiers mean, relation to the pick-candidates tool) are minor for a tool this simple.

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 0% for the single organizationId parameter, so the description must carry the burden. It establishes the org context ('organization activity', 'set roster on the draft org') but never explicitly says the parameter is the organization whose visibility rules govern the list, leaving the parameter's scope to inference.

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 names a specific action and resource: list up to 500 candidate people by member visibility, returning only identifier, nickname and avatar. That is concrete enough to distinguish it from generic member-listing siblings, though it never names the closest alternative (list_organization_activity_pick_candidates) so the boundary is inferred rather than stated.

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 real context: login plus the publishActivities permission, and a workflow note (import_activity_draft → update_activity_draft → publish_activity_draft, setting the roster on the draft org). But it never says explicitly when to pick this tool over list_organization_activity_pick_candidates or list_organization_member_invites, so the when-to-use guidance is implied by workflow rather than stated as a selection rule.

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