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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds that links can be revoked and members managed, which explains where the destruction lies. However it does not say that revoking a link or removing a member cuts off live access irreversibly, nor does it flag that a single tool mixes read ops (list, list_members) with destructive ones. That mixed-mode caveat is the notable missing context.

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?

It is a single dense sentence with no filler, and the primary operations are front-loaded. The trailing clause 'or list and manage the people who joined' is vague, and 'manage' has to stretch to cover both remove_member and set_member_role. Slightly awkward coordination of unlike operations weakens an otherwise compact line.

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?

This is a seven-operation, six-parameter destructive tool with no output schema, so the description carries real weight and leaves gaps: no explanation of what list/list_members return, no permission model, and no consequence statement for revoke or remove_member. The link-versus-member distinction (two separate access-granting mechanisms) is only obliquely conveyed. Adequate to select the tool, thin for invoking the destructive branches confidently.

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 67% and the role, label, link_id, and member_id fields already carry descriptions, including idempotency on label+role and where IDs come from. The description adds only the loose mapping of 'change a link's role' and 'manage the people who joined' to the relevant ops, and says nothing about op itself or the anyOf conditional requirements. Baseline 3 is appropriate when the schema does most of the work.

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 uses specific verbs tied to a concrete resource: 'create, list or revoke links', 'change a link's role', 'list and manage the people who joined'. That covers all seven ops conceptually and clearly separates this from map_create, map_edit_places, and map_update. It stops short of naming the exact op values (set_role, list_members, set_member_role) or naming a sibling to avoid, so it is clear but not maximally distinguishing.

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?

There is no explicit when-to-use versus when-not guidance, no mention that map_save or map_create must precede sharing, and no statement about permissions needed to issue a link. Usage is only implied by the enumeration of sharing actions. The one useful hint, that a link can grant view or editor access, is restated from the schema rather than framed as decision guidance.

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