create_referral_invites

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'records' implying a write operation, but gives no details on idempotency, authentication requirements, whether emails are sent, or error handling. The return value is mentioned, but broader side effects and constraints are absent.

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 a single sentence, which is efficient, but it is truncated ('per p...') and awkwardly combines two clauses. While not verbose, the incomplete ending and lack of structure prevent it from being more polished.

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 is simple (no parameters, no output schema), and the description covers the core action and return value. However, it lacks context about preconditions (e.g., how colleagues are chosen), relationship to list_referral_candidates, and error behavior, leaving it incomplete for a mutation-type tool.

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?

The input schema has zero properties, so there are no parameters to describe. With no parameters, the baseline is 4, and the description adds context by explaining the tool's behavior (recording invites and returning a unique link), which compensates for the lack of explicit parameters.

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 tool 'records referral invites' and 'returns a unique referral link per person' (assuming 'per p...' means per person). This specifies the action and result, and it is distinguishable from the sibling tool list_referral_candidates which lists candidates rather than recording invites.

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 does not mention when to use this tool versus alternatives such as list_referral_candidates, nor does it give exclusions or prerequisites. It only implies usage after the user has chosen colleagues to invite.

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