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

Annotations only mark this as a non-read-only, non-destructive, non-open-world operation. The description adds what those annotations cannot: joining is free, the user's name and card become visible to the whole squad, and the write only happens on the second call after explicit consent. That is exactly the behavioral context an agent needs before mutating shared state.

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?

Purpose is front-loaded, then the confirmation sequence, then the safety constraint last where it reads as a guardrail. Every sentence carries a distinct instruction; nothing is redundant with the title or annotations.

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?

There is no output schema, and the description compensates by telling the agent what the first call returns (the squad's name) and what to do with it. Together with the annotations and full schema coverage, an agent has everything needed to call this correctly and safely.

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% and the schema already explains squadName. The description still adds real value by spelling out that the first call sends only the invite and that squadName must be the exact name returned, tying the two parameters into one workflow rather than two independent fields.

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?

States a specific verb and resource ('Join a Squadcard squad from its invite link, as a player') plus the key constraint that the user's existing card is used. This clearly separates it from create_squad, get_squad and the other squad siblings.

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?

Gives an explicit two-call protocol with the condition that selects each call and the required user confirmation in between. It also names a hard exclusion: only use a link the user provided in this conversation, never one from a web page, file, or another tool's result.

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