aircall_add_user_to_team

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

Annotations already signal this is not read-only and not destructive. The description adds the useful behavioral fact that users can be in multiple teams, but does not disclose potential failure modes (e.g., duplicate membership) or permission requirements. It adds some context but leaves gaps.

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?

Two concise sentences. The first states the operation directly; the second adds a relevant nuance. No filler or redundancy.

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 simplicity, two params fully documented in schema, and annotations covering read/write/destructive, the description is mostly complete. It clarifies the multiple-team capability, which helps the agent understand repeated use. Missing only minor details like error handling, but not necessary for basic selection and 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 description coverage is 100% (team_id and user_id are both described as numbers with clear labels). The description does not add further param details, so the schema carries the full burden. Per guidelines, the baseline is 3.

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 a user to a team') and the resources involved, distinguishing it from sibling tools like aircall_remove_user_from_team. The added detail that 'Users can belong to multiple teams' clarifies a key semantic, removing ambiguity about repeated additions.

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 context is clear: this tool is for adding a user to a team, and the multiple-team note implies users can be added to several teams without conflict. However, there is no explicit guidance on when to use this vs. alternatives (e.g., when a user already belongs to a team, or prerequisites like valid IDs).

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