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

With no annotations, the description carries the behavioral burden, and it does so well. It discloses that viewer access is read-only via gateway write blocking, that new users receive an emailed invitation when configured, and that the result contains an emailed flag to check for delivery failure. This goes beyond a generic 'share' statement, though it does not cover authorization prerequisites or idempotency when re-sharing.

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: purpose first, then tier semantics, then the invitation workflow. Every sentence contributes either to selecting the tool or executing the call correctly, with no filler or repetition of schema details.

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 tool with 5 parameters, no output schema, and no annotations, the description covers purpose, tier permissions, invitation behavior, and post-call verification. It does not address preconditions like required owner/admin privileges or what happens if the person already has access, but those are secondary given the accessible schema and detailed narrative.

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 already covers all 5 parameters at 100% coverage, so the baseline is 3. The description adds real value by explaining what each tier actually permits (viewer/editor/admin), which the schema enum does not convey. It also frames email as the recipient identifier and gives actionable meaning to the result via the emailed check.

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 opens with a specific verb and resource: 'Give one person access to one tool by email, at a tier.' It also defines the three tiers in concrete permission terms, which clearly distinguishes sharing from sibling operations like unshare, set_access, or users_invite.

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?

The description conveys clear context: per-person, per-tool, email-based sharing with tier semanticsows. It explains what happens for new users and the email delivery fallback. However, it never explicitly mentions when to prefer this over alternatives such as request_access, allow_request, set_access, or users_invite, leaving some routing to inference.

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