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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), yet the description adds substantial context: it is a server-side authoritative list, rows carry status invited|active|revoked, verification requires matching grant_id plus namespace_prefix plus grantor, and the downstream accept flow costs 30 free days then $19/30 days with a 402 on lapse. That is behavior an agent could not infer from the annotations or empty schema.

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 core scope and return fields are front-loaded in the first sentence, with verification and follow-up acts after. The pricing/402 detail and the docs URL are somewhat tangential to a read-only listing tool and arguably belong with accept_invite, so the last paragraph is slightly over-weighted.

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?

There is no output schema, so the description must explain return values, and it does so with a concrete field list and enum values. It also covers the verification question and the next step after listing, leaving nothing essential for a correct call missing.

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 tool takes zero parameters, which is the baseline-4 case, and the description correctly spends no words on arguments. It instead describes the output row shape, which is the only semantic surface available here.

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 gives a specific verb and resource ('List this account's namespace collaboration grants: incoming invitations and outgoing shares') and immediately enumerates the row fields, so an agent knows exactly what comes back. It is clearly distinct from invite, accept_invite, decline_invite, and revoke_grant, which mutate the same objects.

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 a concrete trigger case ('An invitation referenced anywhere else ... can be checked against this server-side list') and routes the agent to accept_invite and switch_workspace for the follow-up flow. It stops short of stating an explicit exclusion, such as when to prefer list_workspaces or get_stats instead, but the usage context is clear.

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