Invite TestFlight tester

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

Goes beyond the annotations by disclosing the real side effect — an invitation email is sent — and the upsert behavior when the tester already exists, neither of which appears in the structured hints. It does not address the destructiveHint=true annotation's implications (e.g. whether re-invites or group additions can be undone) or partial-failure behavior when some betaGroupIds are invalid.

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?

Three tight sentences with the core behavior front-loaded and the guardrail placed last where it reads as a caution. No filler, though the create/add sentence and the guardrail could be merged without loss.

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 non-idempotent write tool with no output schema, the definition covers the essential agent-facing facts: required inputs, the email side effect, the upsert semantics, and the group-ID source via list_beta_groups. First/last name omission is minor and low-risk for correct invocation.

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 50%: email and betaGroupIds carry their own descriptions (including the pointer to list_beta_groups), while firstName and lastName are undocumented in both schema and description. The description reinforces 'by email' and 'one or more groups' but adds no new meaning, so it neither compensates for nor worsens the coverage gap.

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 ('Adds a tester to one or more TestFlight beta groups by email') plus the consequence ('giving them access to pre-release builds'), which cleanly separates it from list_beta_testers and remove_beta_tester_from_groups.

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 line 'Only invite addresses the user gave you' is a genuine usage guardrail, and the create-or-add sentence clarifies the two invocation paths. But it never names alternatives, e.g. checking existing testers with list_beta_testers first or resolving group IDs via list_beta_groups, so the when-to-use decision is left implied.

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