Trigger Referral

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation/irreversibility profile is covered. The description adds the delay semantics (credit held N days before awarding), but does not disclose auth needs, rate limits, or that the trigger itself cannot be undone beyond what annotations 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?

Front-loaded with the action and condition, three tight sentences with no padding. The final clause on campaignId largely restates the schema's own description of that field, a small 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?

An output schema exists, so return shape is out of scope, and the destructive/idempotency traits are carried by annotations. The description covers purpose, trigger condition, and the two non-obvious parameters, leaving only minor gaps (auth/rate-limit context) for a mutation 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?

Schema description coverage is low (25%), so the description must compensate, and it does for the key params: it explains delayInDays' 1-90 range and effect and campaignId's fallback to GROWSURF_CAMPAIGN_ID. It adds little for participantId vs participantEmail beyond 'referred participant', leaving the anyOf choice to 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?

States a specific verb+resource ('Trigger referral credit for a referred participant') and the triggering condition (Sign up + Qualifying Action), so the purpose is unambiguous. It does not name or contrast a sibling (e.g. cancel_delayed_referral), so sibling differentiation relies on the name alone.

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 a clear condition for use ('use when your trigger is Sign up + Qualifying Action') plus guidance on when to pass delayInDays (refund window). It stops short of stating when not to use it or naming the delayed-credit alternative.

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