growsurf_trigger_referral

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

Annotations already declare destructiveHint=true and openWorldHint=true, covering the mutation nature. The description adds useful context about the delayInDays behavior and campaign targeting (GROWSURF_CAMPAIGN_ID fallback), but does not disclose additional side effects such as irreversibility or interaction with growsurf_cancel_delayed_referral. Since annotations carry the safety profile, this is adequate but not rich.

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 well-structured sentence plus a brief second sentence on campaign targeting. Every clause adds value—the use case, the delay option, and the default behavior—with no redundant wording.

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 covered. However, the description omits important operational details such as error conditions, behavior when both participantId and participantEmail are provided, and the relationship with growsurf_cancel_delayed_referral for delayed credits. Given the complexity (anyOf, delay, campaign selection), more context would aid correct 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 only 25%, and the description only elaborates on campaignId and delayInDays. The participantId and participantEmail parameters, which are critical and mutually exclusive via anyOf, are left unexplained. The description mentions 'referred participant' but does not clarify which identifier to pass under what conditions, leaving a significant gap.

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 'Trigger referral credit for a referred participant' and specifies the exact use case (when trigger is Sign up + Qualifying Action). It distinguishes this from other sibling tools like growsurf_record_sale by referencing the specific trigger condition, making its purpose unambiguous.

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 provides a clear condition for use ('use when your trigger is Sign up + Qualifying Action') and explains the optional delayInDays parameter for refund windows. However, it does not explicitly mention when not to use it or alternative tools for other trigger types (e.g., growsurf_record_sale for purchase triggers), leaving some inference to the agent.

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