edgegate_invite_member

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals important traits: the tool does not send emails, requires admin privileges, and has a role hierarchy (only owners can add other owners). This goes beyond schema definitions. However, it does not describe idempotency, error handling, or the return format, leaving some gaps for a mutation tool.

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 two sentences, front-loaded with the primary action and then providing essential caveats and permission requirements. No filler or redundant information—every sentence earns its place.

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 3 required parameters and no output schema, the description covers the essential aspects: purpose, scope (v1 limitation), permission model, and role constraints. It is sufficient for an agent to decide when and how to invoke it. Missing details like idempotency or error behavior are minor for this simple add-member operation.

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%, with role and user_email having detailed descriptions, but workspace_id has none. The description adds minimal parameter context beyond what the schema already provides, mostly rephrasing "by email at the given role." It does not clarify workspace_id semantics. Thus, the description adds some value but does not fully compensate for the missing workspace_id description.

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 clearly states the action: "Add an existing EdgeGate user to this workspace by email at the given role." It specifies the resource (EdgeGate user), the destination (workspace), and the mechanism (email + role). It also distinguishes itself from sibling tools by noting the v1 limitation (only attaches existing users, does not send invites), which separates it from invite-like functionality.

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 provides explicit usage context: "v1 only attaches existing users — does not send invitation emails to external addresses" and "Requires admin role; only owners can add other owners." This tells the agent when this tool is appropriate (existing EdgeGate users) and when it isn't (external invities), plus the permissions needed. It doesn't name alternative sibling tools directly, but the constraints clearly guide tool selection.

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