Referral Rock MCP by usefulapi

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

Annotations already declare non-idempotent, destructive and open-world, but the description adds real substance beyond them: the duplicate-on-retry consequence, the POST /api/members endpoint, the returned referral code/share URL, and the crucial fact that send_confirmation_email sends a message to a real person with a false default. That last point is exactly the kind of side effect an agent needs before invoking a destructive 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?

Leads with a 'WRITE:' marker, then packs return behavior, idempotency risk, the email side effect, and the endpoint into a compact block. No sentence is filler and the highest-risk information is not 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?

Despite having no output schema, the description names what comes back (member plus referral code and share URL). It covers the mutation's risk profile, the one parameter with human consequences, and the underlying endpoint, leaving nothing an agent needs before calling it.

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 goes further by framing send_confirmation_email as an outbound message to a real person rather than just a boolean, which raises the stakes of a parameter the schema treats mechanically. It does not discuss program_id, external_id, or custom referral_code, but those are already well documented 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 ('creates a new member (advocate) in a referral program'), plus the return payload (member with referral code and share URL). This clearly separates it from referralrock_update_member, referralrock_list_members, and the referral-creation sibling.

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?

Makes clear this is the path for adding a brand-new member and warns that a repeat call may duplicate or fail, which steers the agent away from blind retries. It does not explicitly name update_member as the alternative for existing members, so it stops short of full when/when-not 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?

Beyond the annotations (destructive, non-idempotent), the description discloses the critical consequence: setting status to qualified or approved can trigger configured rewards, described as a financial commitment. It also explains the safe default (new referrals start as pending) and notes the endpoint, which is exactly the extra context annotations cannot carry.

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 sentences, front-loaded with a WRITE marker and the core warning; every clause carries information (subject, risk, default, idempotency, 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 12-parameter write tool with full schema coverage, the description covers purpose, risk, and defaults adequately. The only gap is return behavior — with no output schema, it does not say what identifier or object comes back after creation.

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 adds operational meaning by framing status as a dangerous parameter that should be omitted by default, reinforcing the confirm coupling described in the schema. Most remaining parameter detail is already 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 ('WRITE: adds a referral (a lead)') plus the exact scoping condition: it attaches to the member who owns the given referral code, as if the lead used that member's link. This cleanly separates it from siblings like create_member and record_customer.

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 explicit when-to-act guidance ('leave status out unless you mean it') and points to referralrock_list_members as the source for referral_code. It does not explicitly rule out alternatives such as record_customer or update_referral, so it falls short of a full 5.

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 contributes the concrete returned metric set and the time-window scoping, which is genuine added context. It says nothing about behavior for unknown members, empty periods, or whether the time_period applies uniformly to all metrics, so it stops short of a 4.

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 dense sentence front-loads the metric payload, then a period qualifier, then the endpoint. Every clause carries information and there is no filler; the trailing endpoint reference is mildly redundant but useful for tracing.

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 burden of describing return content and does so by naming the metric categories and status breakdowns. For a two-parameter read-only tool with full schema coverage, that is nearly enough; only the identifier-resolution and empty-result behavior 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 coverage is 100%, so both parameters are already documented, including the member identifier types and the enum values for time_period. The description only restates that results are bounded by a time period, adding no format or semantics beyond the schema, which is the correct baseline of 3.

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 (get statistics of one member) and enumerates the metric families returned: views, shares, referrals by status, reward amounts, and last share/activity dates. The 'one member' scope clearly separates it from list_members and list_referrals, which operate over collections.

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 scope ('one member over a time period') implies when to choose this over the list_* siblings, but no explicit when-to-use/when-not or alternative is named. An agent can infer it needs an identifier for a single member, but nothing tells it how to resolve a member first or what to do if the identifier is ambiguous.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /api/program/getsingle) and the returned field set, but says nothing about exact-match failure behavior, case sensitivity, or permissions — meaningful gaps for a lookup that can miss.

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 terse fragments with zero padding, and the identifying scope ('by its exact name') is front-loaded ahead of the endpoint. The telegraphic style borders on under-specification but wastes nothing.

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 one-parameter read tool with full annotation coverage, the description is nearly sufficient, and it usefully compensates for the absent output schema by naming the returned fields. The only real omission is behavior on a missing or non-exact name.

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 'name' parameter is fully documented, including the cross-reference to referralrock_list_programs. The description's 'exact name' phrasing reinforces the exact-match semantics but adds little beyond what the schema already states.

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 ('One referral program by its exact name') and enumerates returned fields (id, active flag, offers, URLs), so the agent knows exactly what comes back. It implicitly distinguishes itself from referralrock_list_programs by emphasizing a single exact-match lookup, but never names the sibling tool.

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: fetching one program requires knowing its exact name, and the pointer to referralrock_list_programs for discovery lives in the schema's parameter description rather than the tool description. There is no explicit when-not-to-use guidance or statement of what happens on a failed name match.

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 the returned field set and the at-least-one-key constraint, but is silent on not-found behavior and on whether an email lookup can return multiple referrals — meaningful gaps for a lookup-by-key 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?

A single dense sentence front-loads the lookup keys and the cardinality constraint, then lists returned fields. The trailing 'GET /api/referral/single' is mild surplus REST trivia but costs little.

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 does the right thing by enumerating the returned fields, and it covers the empty-required-list ambiguity. What remains missing is error/not-found behavior and multi-match semantics, which for a three-optional-key lookup tool is a real but modest 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 coverage is 100% and all three keys are documented in the schema, so the baseline would be 3. The description earns an extra point by stating that at least one of the keys is required — a constraint that is NOT expressed in the schema (required list is empty) and that an agent could otherwise miss.

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 ('One referral') and enumerates the fields returned (status, amount, referring member, notes, custom fields, dates), which lets an agent distinguish it from referralrock_list_referrals. It does not name the sibling alternatives explicitly, so it stops 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?

'at least one is required' gives a real usage constraint for the lookup keys, and the singular framing implies single-record retrieval. However, there is no explicit guidance on when to prefer this over referralrock_list_referrals or what to do if a lookup key matches nothing or multiple records.

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 value beyond them: it discloses the default ordering ('newest first by default'), names the returned fields in the absence of an output schema, and identifies the underlying endpoint. It omits pagination behavior and any rate-limit or result-cap context, which keeps it below 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 dense sentences with zero filler; the identity of the resource and the default ordering come first, then the filter set, then the endpoint. Every clause carries information an agent would otherwise have to infer.

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 correctly compensates by summarizing return fields, and all 8 optional parameters are covered by the schema. Annotations handle the safety profile. Minor gaps remain around result-set size and paging semantics, but nothing essential to calling it correctly 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 description coverage is 100% and every parameter carries its own explanation, including paging via next_offset, so the schema does the heavy lifting. The description restates the filter categories (program, query identity, date range, active/disabled) without adding syntax or edge-case detail. 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 and resource ('List members'), parenthetically disambiguates what a member is ('the people who refer others'), and enumerates the returned fields (referral code, share URL, counts, rewards, activity dates). That is enough for an agent to distinguish it from list_referrals, list_rewards, or get_member_stats without opening a 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 does establish usable context by listing the available filter axes (program, email/id/external id/referral code, created date, active vs disabled). However, it never states when to prefer this over sibling tools such as get_member_stats or list_referrals, and offers no exclusions. Usage is implied rather than directed.

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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real value beyond them: the response content (type, amount, date, status, destination, vendor errors) plus the returned account balance for pending payouts, and the underlying endpoint.

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 with the resource and returned data front-loaded and the endpoint trailing; nothing is redundant. The parenthetical field list is dense but each item 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?

With no output schema, the description usefully describes what comes back, including the balance for pending payouts, so an agent knows what to expect. Only pagination/result-size behavior is unaddressed.

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 filters are already documented as 'only this recipient/transaction'. The description adds only the notion that both are optional and mutually narrow the result set, which is marginal over schema text — 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 ('Payout transactions already transferred to program participants') and even enumerates the fields carried. The 'already transferred' phrasing implicitly separates it from referralrock_list_pending_payouts, but the sibling is never named outright.

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?

'Optionally for one recipient or one transaction' communicates how the filters scope the call, which is useful context. It does not say when to prefer this over list_pending_payouts or when a filter is recommended, so usage is only implied.

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, and the description confirms it is a plain GET. It adds useful context on the pending/eligible distinction and the shape of the results, but says nothing about pagination, result limits, or ordering for what is clearly a list endpoint.

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 resource definition and returned fields come first, then the optional filters. The trailing endpoint path is low value but small, 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 no output schema, the description compensates by enumerating the returned fields, and all two optional parameters are covered. The remaining gap is list-level behavior (pagination, volume expectations), which is minor for a zero-required-parameter read 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%, so both parameters are fully documented in the input schema (recipient_id scoping and include_ineligible's default false). The description restates those two behaviors in prose but adds no format, id-source, or default detail beyond the schema — 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?

Names the specific resource (payouts owed but not yet transferred) and enumerates the returned fields (recipient, program, reward count, total amount). It implicitly separates itself from referralrock_list_payout_transactions by emphasizing 'not yet transferred', but never names that sibling explicitly, so differentiation requires the agent to infer.

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?

'Payouts that are owed but not yet transferred' implies when the tool applies versus a transaction-history listing, and the two optional scoping phrases hint at narrowing use. However, there is no explicit when-to-use, when-not, or named alternative (e.g. list_payout_transactions for settled payouts).

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, openWorldHint=true, so the safety profile is covered. The description adds value beyond them by disclosing the return payload (id, name, type Web/Form, active flag, title, member and referral offers, share/widget URLs) and the underlying GET endpoint, though it says nothing about pagination ceilings or rate limits.

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 with zero filler: capability first, then the downstream usage hint, then the endpoint. The field enumeration is dense but every item tells the agent what it will get back.

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 annotations plus a fully documented schema cover safety and pagination. The only remaining gap is explicit routing versus the get_program sibling for single-record reads.

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% with full detail on count, offset and program, so the schema already does the heavy lifting. The description only echoes the id/name filtering idea and adds no format or syntax detail beyond the schema, making baseline 3 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 and resource ('List the referral programs in the account') and enumerates the fields returned, plus the backing endpoint GET /api/programs. It is distinguishable from the singular referralrock_get_program by the 'List' framing, but the description never names that sibling explicitly, so differentiation is inferred 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?

Gives a concrete downstream usage rule: 'Use the ids (or names) to filter members, referrals and rewards,' which tells the agent why to call this first in a workflow. It does not state when to prefer this over referralrock_get_program for a single program, nor any prerequisites/exclusions.

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 value beyond that by disclosing default ordering (newest first), the record shape returned (status, amount, referring member, notes, dates) and the underlying GET /api/referrals call — useful for a tool with 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?

Two dense sentences: the first front-loads what the resource is and what comes back, the second enumerates the filter surface. No filler, though the trailing 'GET /api/referrals' is of marginal value to an agent.

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 enumeration of returned fields and default sort ordering fills an important gap, and the enum statuses are named. Pagination semantics are handled purely by the schema and not echoed in prose, which is a minor omission but acceptable given 100% schema coverage.

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%, with defaults, enums, bounds and pagination guidance (next_offset) already documented in the schema. The description only restates that filtering is possible across those dimensions and adds no format or syntax detail, 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 (list referrals = people members referred) plus default ordering and returned fields, which disambiguates it from get_referral. It does not explicitly name a sibling tool, so it falls just short of 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?

The listed filters (program, status, member, query, created date) imply when to use this listing tool, but the description never says when to prefer get_referral, list_members, or list_rewards instead, nor any prerequisite context. Usage is inferable rather than stated.

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 needs no restating. The description adds genuine substance with no output schema present: it enumerates the returned fields (trigger type, fixed vs percent amount logic, payout type, delivery delay), letting the agent know what data it will get. It omits multiplicity/pagination and empty-result behavior, keeping it short of 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?

A single dense sentence front-loads the resource and then lists the returned fields, followed by the endpoint for orientation. Nothing is padded, though the field list is somewhat compressed and the parenthetical qualifiers add length without much disambiguation.

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 no output schema, the description covers what the tool returns and what scopes it, while annotations cover the safety profile. Only minor gaps remain: whether multiple rules can be returned and how they are ordered.

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 program_id is documented as a GUID with a cross-reference to referralrock_list_programs. The description reinforces scoping ('of one program') but adds no format or constraint 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?

The description names the resource precisely (reward rules of a program) and enumerates its content — trigger conditions, amount calculation, payout type, delivery delay — which separates it from sibling tools returning actual reward or payout records. It lacks an explicit verb like 'list'/'retrieve', so the read action is inferred from the noun phrase plus the endpoint, but the scope is 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?

Usage is implied: this is the per-program configuration lookup, referenced implicitly against siblings like referralrock_list_rewards and referralrock_list_pending_payouts, which return transactional data. However, no explicit when-to-use or when-not-to-use statement or named alternative is given, leaving the agent to infer the config-vs-transaction distinction.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered; the description adds the sensible default sort, the field set returned, and the available filtering dimensions. It doesn't discuss pagination mechanics beyond the schema's next_offset note, but the added context 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?

One sentence front-loads the action and default, then the returned fields, then the filters, then the endpoint – dense but every clause carries a distinct piece of information with 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?

With no output schema, the description compensates by naming the fields a reward record contains, and it covers the full filter surface. An agent can invoke this confidently without additional context.

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 essentially 100%, so all nine parameters (sort, count, offset, query, status, dates, program, member_id) are already documented. The description echoes the filter list and the default sort but adds no format or edge-case 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?

The description uses a specific verb+resource ('List rewards') and then enumerates the returned fields (recipient, amount, status, payout type, eligibility/issue dates, member, referral) plus filters, making clear how it differs from siblings like referralrock_list_payout_transactions or referralrock_list_reward_rules.

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 default behavior ('newest first by default') and enumerates every filter dimension (program, member, status, recipient query, created date), giving clear context for when this tool applies. It stops short of explicitly naming when to prefer list_pending_payouts or list_reward_rules instead, so no true exclusions are given.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description goes well beyond them: it discloses that approval triggers configured rewards that may be paid out automatically (a real financial commitment), that a non-matching customer is written into every Preload-enabled program, and that per-customer outcomes are returned. That is exactly the side-effect detail an agent needs before invoking a destructive write.

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 'WRITE:' and the endpoint, then layers consequence and return shape in a tight paragraph. Slight redundancy with the annotations on 'Not idempotent' and the raw POST path keeps it from being maximally efficient, but nothing is padding.

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, and the description compensates by naming the return outcomes (ReferralApproved, MemberPreloaded, Skipped). Combined with the destructive/financial consequences and the confirm gate, an agent has everything needed to call it safely.

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 inline, including the match-key role of email and the confirm gate. The description adds no syntax, format or default detail beyond that, 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?

Opens with an explicit verb-and-resource statement ('WRITE: reports a paying customer to Referral Rock') and immediately distinguishes the tool from sibling create_member/create_referral by describing the referral-matching behavior that only this tool has. An agent can tell exactly what this does 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?

Describes the two decisive branches — matching email converts a pending referral, non-matching email preloads a member — which gives an agent the context needed to pick this over create_member or create_referral. It stops short of naming those siblings or stating explicit when-not-to-use conditions.

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 and idempotent; the description adds real context on top: only passed fields change (partial-update semantics) and the concrete effect of disabling (member can no longer participate in programs). It does not describe the failure mode when the member is not uniquely identified, nor what the response contains.

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 sentences, front-loaded with the WRITE marker and the capability, then update semantics, then identification rules. 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 12-parameter mutation tool with no required params and no output schema, the description covers mutation semantics and lookup requirements well. Gaps remain around ambiguous-match behavior and confirmation of what is returned.

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 nevertheless synthesizes the identifier combinations into one rule (id, referral code, or email/external_id + program), which is more than restating individual field docs. It still leaves the current-vs-new field pairing (e.g., email vs new_email) to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb class ("WRITE") plus the resource and scope: changing contact details, or disabling/re-enabling a member. It is clearly separable from sibling create_member (creation) and update_referral (different resource).

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 the identifying conditions (id, referral code, or email/external id plus program_id/program_name) and that the member must be uniquely identified. It does not explicitly name create_member or list_members as alternatives for when the member does not yet exist or must be found first.

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 well past the annotations: discloses the reward side effect of qualified/approved, that denied halts rewards, that partial updates only touch passed fields, and the endpoint used. destructiveHint/idempotentHint are already declared, and the description adds the concrete financial consequence the agent must reason about.

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 and the highest-risk information (reward triggering and user confirmation) before lookup mechanics. 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?

Covers safety profile, side effects, partial-update semantics and record lookup for a 10-parameter mutation with no output schema. Minor gap: nothing about invalid status transitions or what the response confirms.

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 lookup semantics (referral_id preferred, or external_id/email paired with program_id/program_name) and the partial-update rule, but leaves per-field meaning (note vs public_note, amount for percentage rewards) entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('changes the status, amount or notes of an existing referral') and leads with a 'WRITE:' marker that separates it from the read-oriented siblings (get_referral, list_referrals) and from create_referral.

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?

Explicitly warns that qualified/approved transitions can trigger payouts and instructs 'confirm with the user first', which is a real usage gate. It stops short of naming alternatives (e.g. use create_referral to make a new one), so it is clear context without full sibling routing.

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