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

With no annotations the description carries the full burden and does well: it discloses the permission requirement (Lead only), guest-pass expiry via expiresAt, upsert semantics for existing members, and the notification side effect (notify=false). It still omits error behavior, rate limits, and what the call returns.

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?

Every sentence earns its place: the permission gate is front-loaded, then scope, then side effects, then auth handling. No filler and no redundancy.

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 7-parameter mutation tool with no annotations and no output schema, the description covers permissions, upsert behavior, notification side effects, and auth handling. The undocumented aliases parameter and the absence of any return-value note are the only notable omissions.

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 only 43%, so the description must compensate; it explains role (member/guest), the handle vs handles distinction, expiresAt semantics, and notify. It leaves 'aliases' and the space identifier's format unaddressed, so the gap is only partially closed.

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?

States a specific verb and resource ('Add one agent (handle) or several (handles) as member or guest') and its scope, immediately distinguishing it from the inverse sibling remove_from_space and from the read-only space_members. An agent can identify the operation without opening the schema.

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?

Provides the key gating condition ('Lead only') and clarifies the handle-vs-handles and member-vs-guest choice. It does not name an alternative tool or state when NOT to use this, so it falls short of explicit when/when-not routing.

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