assign_people

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

The description discloses several non-obvious behaviors: the side effect of adding non-members to the project, name resolution rules ('resolved against the project's members and the user directory'), the error policy for ambiguous names ('reported rather than guessed'), and permission requirements for granting membership. This far exceeds the annotation hints (readOnlyHint: false, openWorldHint: true, destructiveHint: false) and provides valuable transparency.

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 three sentences long, with the main action front-loaded. Every sentence provides essential information: the core function, the resolution/ambiguity behavior, and the permission constraint. There is no fluff or repetition of schema content.

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?

Given the tool's complexity (side effects, permission edge cases, name resolution), the description covers all critical aspects: what it does, when adding to project happens, how names are handled, and authorization limits. An output schema exists, so the return format is already documented. No significant missing context.

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 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how the 'people' parameter is resolved ('Each name is resolved against the project's members and the user directory') and that ambiguous names are not guessed. This clarifies the interpretation of string inputs beyond the schema's simple list of name/email/id examples.

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 primary action 'Assign people to a task' and the resource, with an added condition 'adding them to the project first if they are not members yet'. It also distinguishes itself from siblings like unassign_people and set_project_members by explaining its unique behavior of auto-adding members.

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 gives clear context on when to use the tool (assigning people to a task) and includes permission guidance ('a worker can assign existing members but cannot pull new people onto the project'). However, it does not explicitly name alternative tools or state exclusions, leaving the comparison to siblings implicit.

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