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

Far exceeds the annotations: it discloses server-side preconditions (expiry, cancellation, identity match, concurrent access via expectedRevision), the exact privilege granted by inviteAccept (whole-workspace email role only, no event role or marketing permission), and the irreversibility/replay behavior ('a replay cannot restore removed access'), consistent with destructiveHint=false and idempotentHint=false.

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?

Dense but front-loaded: the call recipe and required values come first, then the guardrails. Every sentence adds a distinct constraint, though the prose is packed enough that it reads more like a policy paragraph than a crisp tool blurb.

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 mutating, no-output-schema invitation tool, an agent has everything it needs: required arguments, identity requirements, what is granted, what is refused, replay behavior, and an escalation path when identity is 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 schema's payload is an unconstrained free-form object, so the description carries real load by naming workspaceId, inviteId, expectedRevision, and a stable UUID requestId, plus noting identity comes from the connected account. It stops short of full field-by-field semantics for the payload, which keeps it at 4 rather than 5.

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 (accept/decline) on a specific resource (workspace invitation) and names the exact action enum values (inviteAccept, inviteDecline), so it is distinguishable from siblings like accept_deal or cancel_team_invite 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?

Gives the precondition ('after the connected recipient inspects inviteView and explicitly chooses'), the identity fallback ('use the normal web sign-in/email-verification flow if identity is unavailable'), and an explicit prohibition ('never impersonate another account'), plus a pointer to the workflow guide resource.

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