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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: missing numbers are automatically created as contacts, and it clarifies that both contact IDs (ct_…) and phone numbers are accepted. This goes beyond the schema by explaining the side effect of creating missing contacts.

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 short and front-loaded with the core action. The second sentence adds a key behavioral detail. It's efficient, though the title 'Dodaj do grupy' is Polish and the description is in English, which is a minor inconsistency but doesn't hurt clarity for an English-speaking agent.

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?

The tool has an output schema, so return values are documented elsewhere. The description covers the essential input types (contact IDs and phone numbers), the source of group IDs, and the side effect of creating missing contacts. With annotations covering idempotency and non-destructiveness, the description is complete enough for an agent to invoke this tool correctly. A minor gap is not explaining what happens if a contact is already in the group, but idempotentHint=true implies it's safe.

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%, so the schema already documents all three parameters. The description adds a small amount of meaning by explaining that msisdns are phone numbers and that missing ones are created, but this largely mirrors the schema's own description ('Numery: brakujące kontakty zostaną utworzone.'). The description doesn't add significant new semantics beyond the schema.

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 states a clear action ('Add existing contacts or phone numbers to a group') and identifies the source of group IDs ('from list_groups'). It distinguishes itself from sibling tools like add_to_blacklist and upsert_contacts by focusing on group membership. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate itself from tools like upsert_contacts which also handle contact creation.

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 implies when to use this tool: when you need to add contacts/numbers to a group, and it references list_groups as the source for group_id. It also notes that missing numbers are created as contacts, which hints at a behavior relevant to choosing this over upsert_contacts. However, it doesn't explicitly state when not to use it or name alternatives like upsert_contacts for bulk contact creation.

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