ghl_affiliate_update_referral_id

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

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=true. The description adds genuinely non-obvious context on top: the referral link is rebuilt around the new id (a real side effect), the id must be unique across the location, a Sub-Account token is required, and the affiliate-manager.write scope is needed. Only the absence of any note on failure behavior (e.g. what happens when the id collides) keeps it from a 5.

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 behavior and constraint lead, followed by endpoint, auth and scope on separate lines that are easy to scan. The endpoint and source-spec line is somewhat mechanical for an agent that only needs to call the tool, but nothing is redundant or padded.

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?

For a mutating tool with three parameters, a nested body and no output schema, the description covers purpose, uniqueness constraint, side effect, auth and scope — enough to invoke it correctly. What is missing is any hint about the response or how to confirm the link was actually rebuilt.

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%, and the nested body schema already documents campaignId and referralId individually, including the uniqueness rule and the 3-64 character pattern. The description's statement that the id 'must be unused across the location' reinforces rather than extends that. With the schema doing the heavy lifting, the baseline 3 applies.

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 gives a precise verb and resource: 'Set the referral id an affiliate is tracked by on a campaign.' That is far more specific than the tool name alone and clearly scopes it to a single field on a single affiliate-campaign link. It stops short of differentiating itself from the close sibling ghl_affiliate_validate_referral_id, which is the only thing keeping it off a 5.

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?

Usage is implied rather than stated: an agent can infer this is the tool for changing an existing referral id, and the 'must be unused across the location' rule hints at a pre-check. However, it never says to call ghl_affiliate_validate_referral_id first or explains when to prefer this over ghl_affiliate_move_campaign, so the agent must reason about sequencing on its own.

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