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

Annotations already declare readOnly=false, idempotent=true, openWorld=true and destructive=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: a 25-person cap, that existing members keep their decision and notes while a new reason replaces the old one, and that the role persists the reason and provenance for display in the web app and get_role. It does not cover failures, permissions, or what happens with an unknown username.

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?

Dense but front-loaded: the action and its required reason come first, then limits and merge semantics, then the next tool. A few clauses about display surface ('shown in the web app and in get_role') are borderline but still informative.

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 3-parameter mutation with annotations and no output schema, the description covers the essentials agents get wrong: reason quality, the 25 cap, re-adding an existing person, and the follow-up scoring step. Missing only error/permission behavior and role_id sourcing, which is a modest gap.

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 33%, so the description has to carry weight: it explains that each person needs a one-line plain-words reason and gives a concrete example ('Wrote the MVCC layer of turso: 103 merged PRs titled mvcc'), and it clarifies found_via as 'the search that surfaced them' / 'how they were found'. However role_id is undocumented in both schema and description, and there is no mention of the people array structure beyond the reason.

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?

Specific verb + resource ('add people ... to a role') with clear scope ('up to 25 at a time'). It implicitly separates itself from the discovery siblings by framing the input as people 'you chose (from any search, or ones you know)', and explicitly hands the next step to score_role_person, though it never names find_people_for_role or search_people as the alternative to use instead.

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?

Clear context for when to call it (after you have chosen candidates, whether surfaced by a search or known directly) plus an explicit forward reference: 'Then score_role_person scores them.' It stops short of stating exclusion conditions, e.g. that this is not the tool for finding people in the first place.

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