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

Beyond the annotations, the description discloses the admin-only requirement, the join-on-sign-in behavior, the pending state until first sign-in, and the key limitation that an invite alone conveys no ability to read values. It also states the exact pending object returned. No contradiction with the annotations exists; readOnlyfalse, destructivefalse, and idempotentfalse all align with an invitation-creating write that can be cancelled.

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 description is compact and front-loaded with the essential action, then adds use-case guidance, the security boundary, and return shape. Every sentence contributes distinct information without filler or repetition.

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 an invitation tool with no output schema, the description supplies the return shape, the sign-in semantics, the admin gate, and the relevant crypto-plane followup. Combined with rich input schema descriptions and annotations, this is sufficient for an agent to select and invoke the tool correctly.

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 description coverage is 100%, so the baseline is 3 and the schema itself already documents email, org, and role thoroughly. The description adds some behavioral context around the role and credentials, but it does not materially explain parameter syntax or formats beyond what the schema provides.

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 the exact action, target, and access level: 'Invite a human to the organization by email (admin only).' It clearly distinguishes this from related tools by explaining that the invite results in a pending record that appears in list_invites, not list_vembers, and that revoke_invite cancels it. It also clarifies the capability boundary: the invite itself grants no ability to read values, which sets it apart from crypto/decryption tools.

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 states a concrete scenario ('hand a project off to a person'), an admin-only precondition, and the necessary follow-up: grant decryption with grant_env on the LOCAL crypto plane. It also points the agent to revoke_invite for cancellation and to list_invites/list_vembers for pending versus active state, which is strong routing guidance.

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