ReferralHero MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered by structured data. The description confirms the write nature and that it only appends (no removal), which adds a bit beyond annotations, but gives no info on duplicate handling, limits, or partial-failure behavior.

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?

Two short sentences with the operation type front-loaded ('WRITE:') followed by scope and endpoint. Every clause carries information and nothing is wasted.

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 3-parameter write tool with no output schema and full annotation coverage, the description gives enough to invoke it correctly. Missing only minor behavioral detail such as append-vs-deduplicate semantics and what the response returns, which the schema and annotations can't fully supply.

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%, so all three parameters (uuid, coupon_group_id, coupons) are already well documented, including cross-references to sibling list tools. The description adds no parameter-level detail beyond the schema, so 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?

States a specific verb and resource ('add coupon codes to an existing coupon group') and immediately distinguishes itself from creating a group with 'existing'. An agent can tell it apart from referralhero_create_coupon_group without opening either schema.

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?

'It only adds codes' clearly signals this is an append operation, not a create-group or replace operation, which routes the agent away from create_coupon_group. However, it never states when to use this versus other coupon tools or names any prerequisites/alternatives explicitly.

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

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 description's restatement of non-idempotency is confirmatory rather than additive. It does add real value by disclosing the downstream consequence — 'May unlock point-based rewards' — which explains why the operation is flagged destructive.

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?

A single compact line with the operation type front-loaded and zero filler. Every clause (mutation, idempotency, reward side effect, endpoint) carries information.

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?

With no output schema, the description should signal outcomes, and it does hint at reward unlocking. For a 7-parameter mutation, the description plus the rich schema and explicit annotations cover what an agent needs to call it safely, though it never clarifies which identifier field takes precedence.

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%, so the schema already documents every parameter, including the five mutually exclusive identifier fields. The description only adds the abstract notion that the subscriber is identified by the campaign's unique identifier, without mapping it to the specific identifier parameters; this is baseline-appropriate but no better.

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 ('add points to an existing subscriber') and front-loads 'WRITE:', making the mutation nature unmistakable. It also names the endpoint, which distinguishes it cleanly from siblings like referralhero_add_coupons or referralhero_update_subscriber.

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 clear context for when to invoke it (existing subscriber, campaign-scoped) and warns that repeated calls stack points. It does not explicitly rule out or compare against alternatives such as referralhero_add_coupons or referralhero_update_subscriber, so it stops short of full routing guidance.

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

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

Annotations already declare destructive=true, non-idempotent, and open-world. The description adds important behavioral context beyond annotations: by default ReferralHero emails the subscriber a confirmation and may trigger welcome automations, with double_optin=false to suppress the email. It does not discuss duplicate-subscriber behavior, but the external communication side effect is clearly surfaced.

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 front-loaded with 'WRITE' and four compact sentences, with no wasted filler. The parenthetical identifier list is confusing, but overall structure is efficient.

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 23-parameter mutation tool with no output schema, the description covers the critical operational details: default email/automation behavior, how to suppress it, and how to credit a referrer. The missing duplicate/idempotency guidance and the misleading identifier sentence keep it from being fully complete.

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%, so the schema already documents all 23 parameters thoroughly. The description adds little beyond the schema and contains a confusing/misleading statement: it calls email, phone, wallet, or custom id the 'campaign's unique identifier', while the schema says uuid is the 12-character campaign id and those other values are subscriber identifiers. This could lead an agent to misuse the uuid parameter.

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 states a specific verb and resource: 'WRITE: add a subscriber ... to a campaign', which clearly distinguishes it from read, update, or delete operations. It does not explicitly contrast with siblings such as update_subscriber or confirm_referral, so it is clear but lacks sibling differentiation.

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?

It gives useful default context: confirmation emails are sent unless double_optin=false, and referrer can be set to credit a referral. However, it does not say when to use this instead of update_subscriber or how to handle existing subscribers, leaving alternatives implicit.

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

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

Annotations already declare destructive=true, idempotent=true, openWorld=true and readOnly=false, so the safety profile is covered; the description adds real value beyond that by disclosing the concrete consequence (unlocking the referrer's rewards and triggering reward emails/texts) and the pre-condition that produces an error. It stops short of 5 because it doesn't explain whether a failed or repeated confirm is safe, despite the idempotent hint.

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?

Three tight sentences, front-loaded with the "WRITE:" marker, then the condition, then the side effects and identification strategy, then endpoints. No sentence is filler and the most decision-relevant information comes first.

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?

With eight parameters, no output schema and a 100%-documented input schema, the description covers the precondition, side effects, identification approach and error behavior, which is what an agent needs to call it correctly. The only remaining gap is guidance on choosing between this and the sibling qualify/unqualify operations.

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 already 100%, so a baseline 3 applies; the description earns a bump by explaining that the referral is identified either by subscriber_id or by the campaign's unique identifier, which frames the email/phone/wallet/custom-identifier alternatives in the schema as mutually exclusive lookup modes rather than independent fields. It still doesn't clarify precedence if multiple identifiers are supplied.

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 specific verb and resource ("confirm a verified referral") plus the exact gating condition (third conversion event) and the HTTP endpoints, so the operation is unmistakable. It falls short of a 5 because it never names or contrasts with adjacent siblings such as qualify_referral or unqualify_referral, which an agent may easily confuse with confirming.

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?

It states clearly when to call it (campaign goal tracks three events, third event has occurred) and that the API errors otherwise, which is actionable positive and negative guidance. It does not name an alternative tool or say when to prefer qualify_referral instead, so exclusion-based routing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the description's job is supplementary. It does add real value: 'WRITE' flags mutation up front, 'changes nothing existing' confirms the operation is purely additive, and 'POST /lists' names the underlying endpoint. It doesn't cover duplicate-name behavior or what happens on failure, but against the annotation baseline this is solid.

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?

Three short sentences with the operation mode (WRITE) front-loaded, followed by the effect and the endpoint. Every clause carries information; nothing is padded or repeated.

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 two-parameter, non-nested creation tool this covers the essentials: what it makes, that it is additive, and the HTTP verb/path. Since there is no output schema, a brief hint about what the call returns (e.g., a new campaign identifier) would have closed the last gap.

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 both parameters (name, website) carry their own descriptions with format and length constraints. The description restates them ('name and a default referral URL') without adding syntax or validation detail, so the schema does the heavy lifting and the baseline of 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?

States a specific verb and resource ('create a new ReferralHero campaign') and clarifies the campaign/list terminology, which distinguishes it from list_campaigns and the read-side sibling tools. It stops short of naming an alternative sibling to contrast with, so it is clear but not maximally differentiated.

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 only implied by the verb 'create' plus the WRITE marker; there is no explicit when-to-use statement, no prerequisites (e.g., whether the campaign must not already exist), and no pointer to alternatives. An agent can infer the context but must do the work itself.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description reinforces this with the "WRITE:" prefix and the add-only framing ("It only adds a group"), which tells the agent nothing existing is mutated or removed. It stops short of stating whether a duplicate name is rejected or what gets returned.

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?

Two short sentences, front-loaded with the WRITE marker and the core action, then the scoping clause and endpoint. No filler.

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 4-parameter additive creation tool with full annotation coverage and no output schema, the description covers what is created, that it is additive, and where it lives. The main residual gap is that it says nothing about the created group identifier or how initial coupon capacity works, which matters if the caller needs the new group's id for follow-up calls.

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%, so uuid, name, active and coupons are all documented with type and length constraints in the schema itself. The description only restates that the group belongs to a campaign and may include initial codes, adding no format or default detail beyond that (the default-true for `active` lives in 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 and resource ("create a coupon group for a campaign") plus the optional nested resource ("first coupon codes"), and scopes it with "It only adds a group." It never names a sibling such as referralhero_add_coupons or referralhero_get_coupon_group, so differentiation is implied rather than explicit.

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?

"It only adds a group" hints at an exclusion (adding codes to an existing group belongs elsewhere) and the endpoint anchors it to campaigns, but no alternative tool is named and no precondition is stated. Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds valuable consequences beyond annotations: deletion is permanent, cannot be undone, and removes referral standing. It does not contradict annotations.

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 front-loaded with WRITE, DESTRUCTIVE and the key consequence, then ends with the endpoint. Every clause adds useful information with no wasted text.

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?

Given the destructive annotations and fully described schema, the description is nearly complete. It covers irreversibility and collateral referral-standing deletion; the only minor gap is that it does not explicitly reinforce the user-approval requirement for confirm.

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%, so the schema already explains uuid, subscriber_id, and the mandatory confirm=true flag. The description adds the endpoint path and deletion scope but no additional parameter semantics beyond 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?

The description states a specific verb and resource — permanently deleting a subscriber from a campaign — and clarifies that referral standing is deleted too. It clearly distinguishes this from non-destructive subscriber tools such as update_subscriber or get_subscriber.

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 destructive wording and irreversible consequence imply careful use, but the description does not explicitly state when to use this tool versus alternatives or mention prerequisites such as obtaining user approval. The confirm parameter's requirement is only in the schema.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine value by disclosing the returned payload ('code, available, sent_at') and the underlying endpoint, but says nothing about auth, failure modes, or pagination of the embedded coupon list.

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?

Two tight sentences with the returned fields front-loaded before the endpoint reference. No filler, though the 'GET /lists/...' fragment is developer-oriented rather than agent-oriented.

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?

With no output schema, the description's enumeration of returned coupon fields is the main source of return-shape information and it delivers that. For a simple two-param read tool this is close to sufficient; only the size/ordering of the embedded coupon list is left unspecified.

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%: both uuid and coupon_group_id carry rich descriptions referencing the campaign and coupon-group listing tools. The description adds no parameter detail beyond echoing the endpoint path, so baseline 3 is appropriate.

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 clear verb+resource ('Get' + 'coupon group') and immediately signals scope by noting it returns one group with all its coupons, which implicitly contrasts with the plural list tool. It stops short of naming the sibling explicitly.

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 singular 'One coupon group' implies this is the single-record fetch versus referralhero_list_coupon_groups, and the schema description points to that list tool. But the description never states when to choose this tool or what happens if the id doesn't exist.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful context that the result is a bounded top-N slice (10-100) with three specific fields, but says nothing about ordering, tie handling, or behavior when the campaign has fewer than 10 subscribers.

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?

Two short sentences, zero padding, with the payload contents front-loaded and the endpoint appended as a compact identifier. Nothing to trim.

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?

With no output schema, the description carries the return-shape burden and does so reasonably: it enumerates the returned fields and the size bound. It falls short only on ordering of the ranking and small-campaign edge cases, which are minor for a read-only lookup 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 100%, so both uuid and count are already documented in the schema, including the 10-100 bounds and default. The description only restates the count range, adding no format or semantics the schema lacks. 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?

States a specific resource (campaign leaderboard) and specifies exactly what it contains: top subscribers with referral counts, points and position, plus the range 10-100. It's clear this is a ranking view rather than the flat roster returned by referralhero_list_subscribers, though no sibling is named explicitly.

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 by the content: you call this when you want a ranked top-N view for a campaign rather than a full subscriber list. However, there is no explicit when-to-use statement, no exclusion, and no pointer to referralhero_list_subscribers or referralhero_get_subscriber for other lookups.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false), and the description adds a genuinely useful behavioral constraint: 'Only verified subscribers are found', which tells the agent that unverified records will not be returned. It also discloses the shape of the returned payload, which matters given there is no output schema.

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?

A single front-loaded sentence opens with the scoping ('One subscriber by id') before the payload enumeration, and the endpoint is appended as a compact identifier. The dense field list is information-bearing rather than padding, though it reads as a run-on.

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?

With no output schema, the description compensates by enumerating the returned fields, and it flags the verified-only visibility rule that governs whether a lookup succeeds. What remains unstated is not-found error behavior and whether the returned referral tree is bounded, but the essentials for correct invocation are present.

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%, with the uuid parameter documented as the 12-character MF campaign id and subscriber_id given an example format, so the schema carries the parameter semantics. The description adds nothing about the parameters beyond the endpoint path template.

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?

Names a specific verb+resource ('One subscriber by id') and immediately enumerates what the record contains (contact data, referral code/link, points, position, referrals by level, status, fraud risk level, tags). The 'by id' qualifier cleanly separates it from siblings get_subscriber_by_email, get_subscriber_by_referral_code and list_subscribers.

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 through the 'by id' scoping and the endpoint, so an agent can infer it should pick this over the email/referral-code variants when it holds an id. However, there is no explicit statement of when to use this versus the lookup-by-email/referral-code siblings, or what to do when the id is unknown.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still contributes the non-obvious constraint that only verified subscribers are retrievable, which explains zero-result behavior an agent would otherwise misread as a bad email.

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?

Three short sentences: purpose, the key caveat, then the endpoint reference. The most decision-relevant information is front-loaded and nothing is 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?

With two fully-documented required parameters, no output schema, and annotations covering the read-only nature, the description supplies enough to invoke correctly. Only the absence of guidance on what to do when a subscriber isn't verified keeps it from a 5.

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?

Both parameters are fully described in the schema, including the MF-prefixed 12-character uuid format and a cross-reference to referralhero_list_campaigns. The description adds no parameter-level information beyond what the schema already provides, so 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?

States a specific verb and resource (find one subscriber of a campaign) plus the lookup key (email), which naturally separates it from get_subscriber, get_subscriber_by_referral_code, and search_subscribers_by_name. It stops short of naming those siblings explicitly, so the differentiation is implied rather than stated.

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 caveat 'Only verified subscribers are found' tells the agent when this lookup will fail, which is genuine usage context. However, it never points to an alternative such as get_subscriber or search_subscribers_by_name for unverified subscribers, so selection among the several subscriber-lookup siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds a genuinely useful behavioral constraint not present in structured data — only verified subscribers are returned — which changes how an agent should interpret a miss. It still says nothing about not-found behavior (empty result vs error) for an unverified or nonexistent code.

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?

Two compact sentences with the core definition front-loaded and the verification caveat immediately after it. The trailing GET path is low-value for an agent deciding whether to call the tool, but it is a single clause and does map the tool to its API endpoint.

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 two-parameter read lookup with full schema coverage, annotations, and no output schema, the description conveys what is returned (the owning subscriber) and the key filtering rule. The only meaningful gap is the response when no verified subscriber matches, which an agent needs in order to handle the result.

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%, so both parameters are fully documented, including the uuid format and the mwr interpretation of referral_code. The description's parenthetical about mwr restates what the schema already says and adds no syntax, format, or validation detail; baseline 3 applies when the schema carries the load.

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 concrete verb and resource (find the subscriber who owns a referral code) and disambiguates the lookup key by explaining that the referral code is the mwr value in a referral link. This distinguishes it in practice from get_subscriber_by_email and search_subscribers_by_name, though no sibling is named explicitly.

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 by the lookup key rather than stated: an agent must infer that this is the tool to use when it has a referral link's mwr value. The one real guidance signal is the caveat "Only verified subscribers are found," which tells the agent when this tool will fail to locate someone, but there is no explicit routing against get_subscriber or get_subscriber_by_email.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds real value beyond that by describing what the response conceptually contains (reward titles, descriptions, referral thresholds) and citing the underlying endpoint GET /lists/{uuid}/bonuses. It stops short of mentioning pagination or empty-result behavior, which 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?

Two short sentences plus the endpoint path, front-loaded with what the tool returns and immediately followed by the disambiguation. The raw REST path is optional metadata that slightly dilutes the phrasing, but nothing is wasted or buried.

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 single-parameter read-only list tool with a fully documented schema and no output schema, this covers everything an agent needs: what it returns, how it differs from the nearest sibling, and how to get the required id. No meaningful gap remains.

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 uuid property already explains the 12-character MF-prefixed campaign id, so the schema carries the burden. The description only reinforces the 'for a campaign' framing and adds no format or edge-case detail beyond the schema. Baseline 3 is appropriate.

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 (list the rewards configured for a campaign) and names the exact fields returned (title, description, referrals needed). It also explicitly distinguishes itself from referralhero_list_unlocked_rewards, so the agent can separate reward configuration from earned rewards without opening schemas.

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 routing sentence "This is the reward setup, not who earned what: see referralhero_list_unlocked_rewards for that" gives an explicit when-to-use and names the alternative tool by name. Only a campaign uuid is required, and the schema note points back to referralhero_list_campaigns for obtaining it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: page size (10 per page), the underlying endpoint (GET /lists), and the returned fields.

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?

Three short sentences, zero waste, front-loaded with the resource and payload fields before the pagination detail. Every clause earns its place.

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?

No output schema exists, but the description lists the return fields and explains pagination, which is enough to call the tool correctly. A minor gap is that it doesn't say whether 'active' excludes archived campaigns, but overall the definition is sufficient.

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%, so the single page parameter is already documented, including the next_page hint. The description meaningfully supplements this with '10 per page,' which tells an agent how pagination behaves.

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?

Specific verb (List) plus resource (ReferralHero campaigns/lists) and it enumerates the returned fields (uuid, name, subscriber count, creation time). It is clearly distinguishable from siblings like create_campaign or list_subscribers.

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?

States that 'the uuid is needed by every other tool,' which tells an agent this is the natural entry point for dependent workflows. It doesn't explicitly name alternatives or exclusions, but no sibling performs the same listing function.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond them: the page size and the exact shape of each returned record, which matters because there is no output schema. It omits ordering guarantees and what happens past the last page.

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?

A single dense sentence front-loads the resource, then the returned fields, then the paging rate, then the endpoint. Every clause carries information and nothing is repeated.

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?

With no output schema, the field enumeration in the description is what tells the agent what comes back, and the page-size note covers the main operational constraint. Minor gaps are ordering and end-of-list behavior, which are low-risk for a read-only listing 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 coverage is 100%, with the uuid format (12-char, MF prefix) and the page/next_page chaining already documented in the schema. The description's reference to the endpoint path merely restates the uuid parameter, adding no syntax or semantics beyond structured fields. 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?

Names the resource precisely (coupon groups of a campaign) and enumerates the returned fields (id, name, active flag, coupons with availability), which separates it from the singular referralhero_get_coupon_group. It never states an explicit verb like 'list', relying on the field enumeration and paging note to imply retrieval.

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?

There is no guidance on when to call this versus referralhero_get_coupon_group, referralhero_create_coupon_group, or the coupon-related siblings. The only usage hint is pagination ('50 per page'), which is already schema territory, so an agent must infer that this is the bulk-listing tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two genuinely useful behavioral facts the annotations do not: a 50-per-page page size and the existence of a next_page cursor. It says nothing about ordering defaults or error/auth behavior, so a 3 is right.

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?

Two sentences, no filler: the resource and page size come first, the scope semantics second, the endpoint last as a precise anchor. The long enum gloss is dense but every clause disambiguates a real choice the agent must make.

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 stating the page size and implying the cursor-based continuation documented on the page parameter. It stops short of describing the shape of a referral record, but for a read-only listing tool with a fully documented schema this is nearly sufficient.

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%, so the baseline is 3, but the description goes further by explaining what each scope value actually returns (confirmed-only vs all statuses per referral level) where the schema only says 'Which referrals (default all)'. Page, sort_by, uuid and subscriber_id are left entirely to the schema, which documents them well.

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 opens with a concrete verb-implied resource statement ('The people a subscriber referred') and pins the exact endpoint, so an agent can tell this apart from referralhero_list_subscribers. It does not explicitly name the sibling it differs from, which keeps it short of 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 context is only implied through the scope enumeration (e.g. level_2_all = 'every status at that level'), which tells the agent which scopes exist but not when to pick this tool over get_subscriber or the reward-listing tools. No explicit when/when-not guidance is present.

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

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

While annotations already declare this is a read-only, non-destructive operation, the description adds behavioral context by including the API endpoint structure (GET /lists/{uuid}/subscribers/{id}/rewards), which clarifies its technical implementation.

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 definition is highly efficient. It front-loads the core purpose, adds critical usage context, and includes the technical path in just two focused sentences.

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 description provides more than just a list of fields; it explains the utility of the data (linking reward IDs to update functions) and provides the API path. This provides a complete picture for agent 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?

Given that the schema coverage is 100%, the description meets the baseline expectation for parameter clarity. It reiterates the necessary contextual fields like 'status' and 'value' to reinforce the data returned.

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 it lists rewards for 'one subscriber,' which immediately differentiates it from sibling tools that might list rewards for an entire campaign or organization.

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?

It provides valuable usage context by explicitly linking the 'reward id' returned by this tool to a dependency in the write operation, `referralhero_update_reward_status`. This guides the agent on the tool's role in a workflow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real context beyond that with the page size (50) and the exact result payload. It omits how pagination ends or what next_page/total look like, a minor gap.

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?

Two tight sentences with the resource and page size front-loaded and no filler. The trailing 'Sort and filter by the extra fields' is imprecise phrasing that costs it a bit of clarity.

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?

With no output schema, the description usefully enumerates the returned fields and the page size, which is what an agent needs to call and consume it. It does not mention pagination termination or the endpoint's response envelope, a small residual gap.

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 each parameter is documented there, including the enum sort orders and the next_page hint, so baseline is 3. The description's 'sort and filter by the extra fields' is vague and slightly at odds with the enum (which sorts by email/name/position/points), adding little beyond 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?

Names a specific verb (List) and resource (subscribers of a campaign) and enumerates the fields returned, so the agent knows exactly what it yields. It does not explicitly differentiate from siblings like get_subscriber or search_subscribers_by_name, though 'of a campaign' implies a bulk listing.

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?

It states the pagination cadence (50 per page) and that sorting/filtering is available, which implies when to use it for browsing a campaign's subscriber base. However, it never says when to prefer this over search_subscribers_by_name or get_subscriber_by_email, leaving the routing to inference.

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

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

Annotations already establish read-only, non-destructive, open-world safety, so the bar is lower. The description adds genuine value beyond them by enumerating the returned fields (reward name, status, value, subscriber email/id, coupon code, transaction), which matters since there is no output schema.

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 resource, followed by a field list and a filter hint; every sentence contributes. The field enumeration is dense but earns its place given the absence of an output schema.

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?

Because there is no output schema, describing the returned fields is the key completeness contribution, and the definition does that. Pagination and filtering are covered by the schema, leaving little essential missing.

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%, so all four parameters (uuid, page, status, per_page) are already documented in the schema. The description restates the status enum and campaign-wide scope but adds no syntax or format detail beyond the schema, so 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?

States a specific verb (list unlocked rewards) with clear scope ('across a whole campaign') and distinguishes itself from per-subscriber scoping siblings like list_subscriber_rewards. It does not explicitly name the alternative tool, so sibling differentiation is implicit rather than stated.

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?

'Filter by status to find rewards still to pay out' hints at a use case, giving some when-to-use context. But it never explicitly names list_subscriber_rewards or list_campaign_rewards as the alternative, so the agent must infer which scoping tool to choose.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutation risk profile is covered structurally. The description adds beyond that: it explicitly labels the call a WRITE, discloses the verified-subscriber constraint, and warns that an already-promoted subscriber returns an error. The only mildly confusing point is that idempotentHint=true while re-promotion errors, but the description does not contradict the annotations outright.

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?

Three tight sentences: operation class first, then constraint and error behavior, then endpoint. No filler, no repetition of the title, and the most decision-relevant information is front-loaded.

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 3-parameter, fully-required mutation with no output schema, the definition covers what it does, the eligibility gate, and the failure mode. The main omission is what a successful response looks like and whether promotion is reversible (demote path), which an agent might want before calling a destructive tool. Annotations and the confirm parameter partially compensate.

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%, so the schema already documents uuid format, subscriber_id format, and the meaning of the confirm gate including its side effects. The description adds no parameter-level detail of its own beyond echoing the path shape. Baseline 3 applies when the schema carries the semantics.

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?

Specific verb ('promote') plus target resource ('subscriber to the campaign's winners list') and a scoping parenthetical clarifying it applies to contests and giveaways. The 'WRITE:' prefix immediately signals the operation class, and the endpoint path reinforces the resource hierarchy. An agent can distinguish this from read-side siblings like get_subscriber or list_subscribers without opening the schema.

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 gives valuable preconditions: only verified subscribers can be promoted, and re-promoting errors out. But it offers no guidance on when to choose this versus nearby mutating siblings such as unlock_promoted_reward or update_subscriber, nor does it say when in a workflow promotion is appropriate. Usage is implied by the precondition rather than stated as routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds little beyond that — it restates the write nature and the reward-counting consequence but says nothing about reversibility, errors, or what response comes back.

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?

Two tight clauses, front-loaded with the 'WRITE:' marker so the mutation nature is the first thing an agent sees. No filler or repetition of schema content.

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 3-parameter, fully documented mutation with no output schema, the description covers the state change and its consequence adequately. It omits what happens on success (return payload) and how it interacts with the similarly named confirm/unqualify operations, which keeps it short of a 5.

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%, so the schema already documents uuid, subscriber_id, and the confirm approval flag including its automation side effects. The description only adds the REST path showing how uuid and subscriber_id bind to the endpoint, which is marginal extra value.

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 ('mark a referral as qualified') plus the business effect ('counts toward the referrer's rewards'), so an agent knows exactly what state change occurs. It does not distinguish itself from near-siblings like referralhero_confirm_referral or referralhero_unqualify_referral, leaving that differentiation to inference.

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 gives no when-to-use guidance, no prerequisites, and never names the alternative tools (confirm_referral, unqualify_referral) an agent might confuse this with. The only approval context lives in the schema's 'confirm' parameter, not in the description.

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

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

Annotations already establish readOnly/non-destructive/openWorld, so the description's contribution is the page size (50 per page) and the account-wide scope, both of which are operationally useful and not in the structured fields. It does not mention matching semantics (partial vs exact, case sensitivity), which would be the next valuable disclosure.

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?

Two short sentences with the scoping detail front-loaded. The trailing 'GET /subscribers/search_by_name' is largely redundant for an agent and is the one element that doesn't clearly earn its place.

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 two-parameter read tool with full schema coverage and no output schema, the definition covers scope, page size, and pagination intent sufficiently to call it correctly. Only the match semantics of 'name' remain unstated.

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% — both 'name' and 'page' are documented, including the next_page chaining hint. The description adds only the implicit page size of 50; baseline 3 is appropriate where the schema does the work.

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 ('Search subscribers by name') and adds scope ('across all campaigns of the account'), which distinguishes it from list_subscribers and from the email/referral-code lookups in the sibling set. It stops short of explicitly contrasting itself with those 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?

The account-wide scope implies when to use it (a name search not constrained to one campaign), but there is no explicit when-not guidance or pointer to get_subscriber_by_email / get_subscriber_by_referral_code as alternatives for exact identifiers.

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

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

Annotations already declare destructive, open-world and idempotent; the description goes beyond them with the actual state machine (pending to confirmed at two events, pending to unconfirmed at three), the creation side effect when a referrer is present, and the reward-unlock consequence. It omits how repeated calls interact with event counting for a three-event goal, which is the main behavioral unknown for a mutation tool.

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 WRITE marker and the core effect, then state transitions, edge case, and side effect, ending with the endpoint. Six compact clauses with no filler; slightly dense but every clause carries information.

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 12-parameter mutation with no output schema, the description supplies the essential consequences an agent needs: what state the referral moves to, that missing referrals can be created, and that rewards and automations may fire. What is missing is return/response behavior and duplicate-event semantics, which matter for multi-event goals.

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%, so all 12 parameters including the required uuid and confirm are already documented. The description adds only the implicit point that referrer enables creation of a missing referral; otherwise it defers to the schema. Baseline 3 is appropriate.

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?

Opens with an explicit verb and resource ('WRITE: report a conversion event for a referral') and narrows scope to campaigns whose goal tracks two or three events, which separates it from generic siblings like confirm_referral. An agent can tell what this does and which campaign type it applies to without reading the schema.

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 parenthetical scoping condition ('campaigns whose goal tracks two or three events') gives clear context for when this tool is applicable, and the missing-referral behavior tells the agent it can be used on unknown referrals when a referrer is supplied. It never names the alternative tools (confirm_referral, qualify_referral) or states when NOT to use it, so no explicit routing.

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

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

Goes beyond the annotations by disclosing real side effects: confirming can unlock rewards and cause ReferralHero to email or text the subscriber or referrer. It also refines the idempotentHint=false flag with the concrete escape hatch (reuse transaction_id). Missing auth/permission requirements 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?

Front-loads the WRITE marker and the core action, then layers the required-amount and idempotency notes in one dense sentence, ending with the endpoint. Slightly packed with nested parentheticals but no wasted sentences.

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 an 11-parameter mutation with no output schema, the description covers the essentials an agent needs: required amount, identifier selection, confirm semantics, retry safety, and triggered side effects. The remaining optional numeric fields are documented well enough in the schema that nothing critical is missing.

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%, so the baseline is 3; the description adds meaning on top by flagging that amount is required and that the subscriber is located via the campaign's unique identifier, which explains why there are several mutually exclusive identifier parameters. It doesn't explain the reward_value vs lifetime_spend relationship.

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 ('WRITE: record a purchase/transaction for a subscriber') plus the downstream effect ('so revenue-based rewards and reports count it'), and names the endpoint. It does not explicitly contrast with near neighbours like referralhero_track_conversion_event or referralhero_add_points, so an agent must infer the distinction from the 'amount required' framing.

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 usage condition ('amount required') and an operational caveat ('not idempotent unless a transaction_id is reused'), which tells the agent how to make retries safe. It stops short of naming an alternative tool or an explicit when-not-to-use case.

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

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

Annotations already flag destructive/non-idempotent/open-world, and the description adds genuinely new side-effect detail the annotations cannot convey: it delivers the reward, may email the subscriber, and may consume coupon codes. It stops short of stating whether the action can be undone or what happens on an already-unlocked reward.

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?

Three short sentences, front-loaded with the 'WRITE:' signal and the effect before the endpoint path. The raw endpoint duplication is slightly redundant but cheap and useful for agents mapping to the API.

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 destructive, non-idempotent mutation with no output schema, the description covers the key side effects but omits what a successful call returns and what happens on repeat invocation (non-idempotent), which is exactly the risk an agent needs to weigh before calling with confirm=true.

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 every parameter is documented in the schema, including cross-references to the listing tools for obtaining uuid and reward_id. The description adds no parameter-level meaning beyond that, so 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 names a concrete verb (unlock) and resource (promoted-winner or one-off reward) and scopes it to a subscriber, plus the exact POST endpoint. It is clearly distinguishable from sibling `referralhero_list_unlocked_rewards` (a read) though it never explicitly contrasts itself with `update_reward_status` or `promote_subscriber`.

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 context is implied by 'delivers the reward' and the required `confirm` gate, but there is no explicit statement of when to choose this over `referralhero_update_reward_status` or `referralhero_promote_subscriber`, nor any when-not guidance (e.g. do not call if the reward is already unlocked).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the domain-level effect that matters most: the referral stops counting toward the referrer's rewards. It stops short of stating reversibility (whether qualify_referral can undo this) or what happens to already-awarded rewards.

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?

Two tight sentences: the action and its effect first, the endpoint second. Nothing is redundant and the key constraint is front-loaded.

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 3-required-param write tool with full schema coverage, no output schema and rich annotations, the description covers purpose, motivation and effect adequately. The one meaningful gap is irreversibility/re-qualification guidance, which an agent deciding between unqualify and delete would want.

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 schema itself explains uuid, subscriber_id and the confirm gate including its side effects. The description adds no parameter-level detail beyond the schema, so 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?

States a specific verb+resource ('mark a referral as unqualified') and immediately names the consequence ('no longer counts toward the referrer's rewards'), which cleanly separates it from referralhero_qualify_referral and from deletion tools like delete_subscriber. The 'WRITE:' prefix plus the endpoint make the operation type 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?

Gives concrete triggering cases ('fraud or a refund'), which is clear usage context. It does not, however, say when not to use it or point to sibling alternatives such as qualify_referral for reversal or delete_subscriber for hard removal.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, but the description adds the crucial side effect that sent/resent can fire the reward delivery email to the subscriber. It also surfaces the confirm gate, though it doesn't state whether a prior send can be cleanly undone.

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?

Three short sentences, front-loaded with the WRITE marker, followed by effects, then prerequisites, then the endpoint. No filler.

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 destructive mutation with full annotations and no output schema, the description covers side effects, the confirm requirement and id sourcing. Only failure behavior or reversibility of a send is left unstated.

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%, so baseline is 3; the description earns above that by explaining where reward_id must come from and framing status as the mutation target. It doesn't add format detail beyond the schema, which already documents uuid, status enum and confirm.

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?

Opens with a explicit write verb, the resource (an unlocked reward's status), and the exact allowed values (sent, resent, canceled). This clearly separates it from siblings like referralhero_unlock_promoted_reward or the list_* tools that only read rewards.

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?

It tells the agent the prerequisite for reward_id by naming two source tools (referralhero_list_subscriber_rewards, referralhero_list_unlocked_rewards) and explains the practical difference between the sent/resent and canceled paths. It stops short of an explicit 'do not use this when...' exclusion.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the bar is lower, yet the description still adds value: patch semantics ('Only fields you pass change'), the verified-subscriber gate, and a pointer to automation side effects (email/text to subscriber or referrer) that can unlock rewards. It stops short of stating irreversibility or what happens on unverified subscribers.

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?

One tight block, led by the 'WRITE' severity marker, followed by fields, overwrite semantics, precondition, and endpoint. Every clause carries distinct information with no repetition.

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 17-parameter destructive mutation with no output schema, the definition covers scope, patch behavior, preconditions, side effects and endpoint. Remaining gaps are minor: no note on error behavior for unverified subscribers or on what is returned after the update.

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%, so the schema already documents all 17 parameters; the description only groups them into families and restates the qualified/unqualified enum and the contest-only constraint on points. With full schema coverage the baseline of 3 is correct.

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 ('change fields of a subscriber'), enumerates the mutable field families, and pins the exact endpoint POST /lists/{uuid}/subscribers/{id}. The 'WRITE' prefix and 'overwrites the given fields' make clear this is a partial-update mutation, not a create.

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 real preconditions: only verified subscribers can be updated, and points only apply to contest campaigns. It does not, however, route the agent away from near-neighbors such as referralhero_add_points or referralhero_qualify_referral/referralhero_unqualify_referral for the same effects.

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