Share a build with groups and testers

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

Annotations cover the safety profile (not read-only, open-world, idempotent, non-destructive), so the bar is lower, but the description still adds meaningful behavior: a human-confirmation gate enforced by confirm: true, outbound email of an install link, and a plan/role requirement. It does not explain the notify flag's effect or what happens when only some recipients are valid.

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 short sentences, front-loading the action and audience before the confirmation requirement and access tier. The telegraphic fragment 'Team, Developer role.' is dense but slightly cryptic about what it constrains.

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 write operation that fires external emails with no output schema, the definition covers the confirmation gate, permissions, and recipient formats. What it leaves open is the notify parameter's semantics, idempotency in practice (does a repeat call re-send email?), and any notion of partial success — gaps that matter for a 5-parameter outbound tool.

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 only 20%, so the description has to compensate and partly does: it tells the agent groups are names and testers are emails, which the schema leaves undocumented, and reinforces confirm must be true. However, notify and the build identifier's accepted forms (id vs install-link slug) are not clarified beyond the schema, so a fifth of the parameter space stays ambiguous.

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 a specific verb (share/give) and resource (a build's project plus its install link) and states the two target audiences, tester groups by name and testers by email. It is clear enough to distinguish from a generic tester-management tool, though it never names a sibling to contrast against.

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 gives a real precondition: ask the person first and pass confirm: true, plus an access requirement (Team, Developer role). What is missing is routing guidance — with siblings like add_testers and email_build_link present, the description never says when this tool is the right pick versus adding testers or merely emailing a link.

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