Rewardful MCP by usefulapi

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

The description discloses a non-obvious behavioral trait: 'Rewardful sends NO welcome email for API-created affiliates.' This is valuable context beyond what annotations provide. Annotations only signal destructiveHint=true, which is a generic safe-guess for a create tool and not contradicted. The description could mention rate limits or idempotency but does well on the welcome-email point.

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 terse sentences packed with distinct, useful information (affiliate vs referrer path, no welcome email, API endpoint). No filler; front-loaded with the primary action.

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 no output schema, the description doesn't explain what is returned on success or error. It does cover the key creation semantics and a behavioral quirk. For a create tool with a rich input schema, it's nearly complete but leaves return-value ambiguity.

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 fully documents all 10 parameters. The description only highlights stripe_customer_id's variant meaning, adding a bit of semantic layer, but otherwise relies on 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?

The description states a clear verb+resource ('Add an affiliate') and even clarifies a variant behavior ('customer referrer, by passing stripe_customer_id'). It distinguishes itself from siblings like create_campaign or create_affiliate_link, though the distinction is inherent in the name rather than explicitly called out.

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 implies when to use the stripe_customer_id variant, but offers no explicit guidance on when to use this tool versus update_affiliate, get_affiliate, or other creation tools. The usage context is only lightly 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?

With only destructiveHint=true declared, the description adds setup context (Stripe-side code existence, dashboard campaign coupon requirement) but never says what this assignment destroys or overwrites — e.g. whether an existing coupon mapping is replaced, or what errors surface on a mismatch. Adequate but leaves the mutation's blast radius unclear.

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 front-loading the action and effect, followed by prerequisites, then the endpoint. Nothing is padded and no sentence 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?

Covers action, effect, prerequisites, and the underlying endpoint for a two-parameter mutation with full schema coverage and no output schema. The one gap is conflict/overwrite behavior for a tool annotated destructive, which an agent would want to know before calling.

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 parameters are already documented; the description's statement that the code must match Stripe is essentially a restatement of the schema's 'as defined in Stripe' note. Baseline 3 applies since 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?

States a specific verb and resource ('Assign a coupon / promotion code to an affiliate') plus the effect (sales credited to them), which is more than a restatement of the name. It implicitly separates itself from rewardful_create_affiliate_link, but never names or contrasts a 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?

Gives two concrete preconditions for use: the code must already exist in Stripe and the affiliate's campaign must have a campaign coupon configured in the dashboard. That is real when-to-use context, though it offers no explicit guidance on when to prefer this over create_affiliate_link or other mapping tools.

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 only declare destructiveHint=true and a title, so the description carries most of the burden. It adds real behavioral facts the annotations do not: the token is auto-generated when omitted and the operation is gated to Growth/Enterprise plans. It does not say what happens to existing links, whether tokens must be unique, or what the call returns.

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, each doing distinct work: purpose, default behavior, eligibility constraint, endpoint. The key fact (additional link for an affiliate) is front-loaded 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?

For a create tool with no output schema, an agent would benefit from knowing that the returned link/token is the usable artifact, especially since the token may be generated server-side. Plan gating and token behavior are covered, but the result of the call 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%, so the baseline is 3, but the description adds the non-obvious behavior that the optional 'token' is generated server-side when omitted — something the schema's pattern/example text does not convey. That is meaningful added meaning 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 ('Give an affiliate an additional tracking link') and clarifies it is an *additional* link, which separates it from rewardful_create_affiliate and rewardful_create_affiliate_coupon. It also names the underlying API endpoint. It stops short of explicitly naming the sibling tools it differs from.

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 'Growth/Enterprise plans only' constraint is genuine eligibility guidance an agent needs before calling. However, there is no guidance on when to create a link versus creating an affiliate, coupon, or campaign, and no prerequisites 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 destructiveHint=true, lowering the bar. The description adds two useful behavioral facts — that a reward rule is created atomically with the campaign, and the underlying endpoint POST /v1/campaigns — but says nothing about permissions, uniqueness constraints on name/url, idempotency, 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 short sentences, front-loaded with the core action, and no filler. The trailing 'Rewardful: POST /v1/campaigns.' is marginally useful for traceability but adds little for an agent deciding how to call the tool.

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 9-parameter create tool with no output schema, the description covers the action, the coupled reward-rule semantics, the conditional field requirements, and the endpoint. It omits what the call returns and any error/permission conditions, which is a modest gap given annotations carry the safety profile.

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 'Required when reward_type is percent/amount' conditions. The description's conditional parameter routing largely restates what the schema says, adding little beyond the baseline.

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 ('Create a new affiliate campaign') and clarifies scope by noting the reward rule is created alongside it. An agent can immediately distinguish this from rewardful_get_campaign, rewardful_list_campaigns, and rewardful_update_campaign.

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 conditional invocation guidance (pass commission_percent for percent, commission_amount_cents/currency for amount), but offers no when-to-use context versus siblings such as update_campaign, and no prerequisites or exclusions. Usage is implied rather than framed.

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 cover the safety profile (readOnlyHint=true), so the bar is lower, and the description adds real value by disclosing the shape of the response: the affiliate's campaign, links, coupon, and visitor/lead/conversion counts, plus the underlying endpoint. It doesn't cover not-found behavior, but that is a minor gap for a read-only getter.

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 core action and returned fields come first, with the API endpoint reference trailing as supporting detail. No filler, nothing repeated from the title or 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?

For a one-parameter read-only getter with no output schema, the description is nearly complete: it names the entity, the identifier type, and the main fields returned. Only edge behavior (missing id, error response) is left unstated, which is acceptable at this complexity.

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 single parameter is fully documented as a UUID in the schema, so the baseline is 3. The description only reinforces 'by id' without adding format, validation, or alternate-lookup guidance.

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 ('Fetch'), resource ('a single affiliate'), and scope ('by id'), which cleanly separates it from rewardful_list_affiliates and from the narrower get_affiliate_coupon / get_affiliate_link siblings. An agent can distinguish it 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 'by id' framing implies the precondition (you must already have an affiliate id) and the lookup intent, but the description names no alternatives and gives no explicit when-to-use versus list_affiliates for discovering ids. Usage is inferable, not 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?

The readOnlyHint annotation already declares the safe-read profile, so the description's burden is lower, but it adds little beyond that: only the raw REST mapping (GET /v1/affiliate_coupons/:id). It says nothing about not-found/error behavior, whether the id must belong to the caller's account, or any rate limiting.

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 action and followed by the endpoint mapping. Nothing is padded and no sentence 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 single-parameter read tool with no output schema and annotations covering the safety profile, the definition is close to sufficient. The only genuine gap is error/not-found behavior, which is minor for this operation.

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 coupon_id documented as a UUID, so the schema carries the parameter meaning. The phrase "by id" corroborates but adds no new syntax, format, or lookup guidance beyond what the schema already states; 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 pair (fetch a single affiliate coupon) and scopes it to one record by id, which implicitly separates it from the sibling rewardful_list_affiliate_coupons. It stops short of explicitly naming that sibling or the other get_* tools, so differentiation is inferable 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?

"By id" implies the precondition that the caller already holds a coupon id, which is the only real usage signal. There is no explicit when-to-use/when-not statement and no pointer to rewardful_list_affiliate_coupons for the case where only an affiliate is known, so guidance is implied at best.

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, so safety is covered. The description adds the underlying REST endpoint (GET /v1/affiliate_links/:id), which is modest extra context, but says nothing about 404 behavior for a missing id or the returned shape.

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, front-loaded sentences with no filler; the action and identifier requirement come first. Efficient, though the trailing endpoint reference 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?

For a simple read-only getter with full parameter coverage and annotations covering the safety profile, the description is essentially complete. A brief note on not-found/error behavior would round it out, but 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 description coverage is 100% and the single link_id parameter is fully documented as a UUID in the schema. The description's 'by id' merely restates what the schema already carries, 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 concrete verb (Fetch) and resource (a single affiliate link), with the 'by id' scope implicitly distinguishing it from the sibling rewardful_list_affiliate_links. It stops short of naming that sibling explicitly, 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: it says 'by id,' which suggests you need a known link_id, but it never states when to choose this over list_affiliate_links or what to do without an id. No explicit when/when-not or alternatives.

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, so the safety profile is covered. The description adds the underlying API mapping (GET /v1/campaigns/:id), but says nothing about auth requirements, 404 behavior for an unknown id, or what the returned campaign object 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?

Two very short sentences with zero waste, and the action is front-loaded before the API endpoint reference. 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?

A simple single-parameter read tool with no output schema, where annotations handle the read-only safety signal and the schema fully documents the id. The description covers the core operation adequately, with only minor gaps around failure behavior.

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 'campaign_id' is already documented as the campaign's UUID in the schema. The description contributes no additional syntax or format detail beyond confirming retrieval is by id, 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 states a specific verb and resource ('Fetch a single campaign') and scopes it with 'by id', which separates it from list_campaigns. It does not explicitly name the sibling it contrasts with, but the singular 'single campaign by id' makes the distinction inferable.

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: the phrase 'by id' signals this is the retrieval path when the campaign's UUID is known. There is no explicit statement of when to prefer this over rewardful_list_campaigns, and no mention of error conditions such as a missing or invalid id.

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 only declare readOnlyHint=true, so the description carries the rest of the load and does so well: it discloses the expanded payload (charge, refund and tax amounts, referral, customer, affiliate) that a bare 'get by id' would not convey. No auth or rate-limit details, but for a simple read that is 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?

One front-loaded sentence captures purpose and return content; the trailing endpoint reference (GET /v1/commissions/:id) is mildly redundant but cheap and aids API mapping. 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 present, the description compensates by enumerating the returned sub-objects, which is exactly what an agent needs to decide whether to call it. Only the discovery path (how to get an id) is left 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 coverage is 100% and the single parameter is fully documented as a UUID, so the schema does the heavy lifting. The description's 'by id' adds no format or syntax detail beyond what the schema already provides; 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 (Fetch) plus resource (a single commission by id) and enumerates the related records returned (campaign, sale, referral, customer, affiliate). This clearly separates it from the sibling rewardful_list_commissions, which returns 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 'by id' phrasing implies this is the direct-lookup tool versus a list/search tool, so the usage context is reasonably inferable. However, it never names rewardful_list_commissions as the alternative for discovery, nor states any precondition for obtaining a commission_id.

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, so the safety profile is covered. The description adds real value beyond that by disclosing payload contents — the affiliate and the bundled commissions — which is behavioral context the agent cannot get from the annotations. It does not mention pagination or error behavior, but neither is relevant for a single-resource fetch.

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 tightly packed sentences with zero filler; the core action and its return contents come first, with the endpoint reference trailing as a low-cost anchor.

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 no output schema, the description covers the essentials: what is fetched, by what key, and what the response bundles. Only the missing explicit relationship to rewardful_list_payouts keeps 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 description coverage is 100% and the single parameter is fully documented as a UUID in the schema. The description's 'by id' adds no format or constraint detail beyond that, so the schema is doing the heavy lifting — baseline 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 (Fetch) and resource (a single payout by id) and names the sibling dimension that distinguishes it from rewardful_list_payouts — singular vs. collection retrieval. It also names the endpoint for traceability.

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: the phrase 'by id' suggests the caller must already have a payout_id, and the singular framing implies the use case is fetching one known payout. No explicit when-to-use or when-not-to-use against rewardful_list_payouts is 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, so the safety profile is covered. The description adds value by naming the returned fields and the underlying endpoint (GET /v1/affiliate_coupons), giving the agent a picture of the response shape not present in structured 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?

A single tight sentence, field list front-loaded, endpoint appended as a trailing reference. No padding or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description compensates by enumerating returned fields and scoping the operation. Combined with readOnlyHint and complete parameter docs, an agent has what it needs, though pagination behavior could be noted.

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 fully documents page, limit, and affiliate_id. The description only adds a light restatement of affiliate_id ('optionally for one affiliate'), 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?

Specific verb 'List' plus resource 'affiliate coupon / promotion codes' with an explicit enumeration of returned fields (token, Stripe id, leads, conversions, archived). An agent can distinguish this from rewardful_get_affiliate_coupon (singular fetch) and rewardful_create_affiliate_coupon.

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 phrase 'optionally for one affiliate' implies the filtering use case, but there is no explicit when-to-use vs when-not, no mention of prerequisites, and no routing to sibling tools like get_affiliate_coupon for single-record retrieval.

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 declare readOnlyHint=true, so the safety profile is covered. The description adds the sort order (newest first) and the underlying API endpoint, both useful context. It does not describe pagination behavior beyond what the schema notes (seen in the page param, referencing pagination.next_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?

Two compact sentences: purpose and fields first, endpoint reference second. No filler; 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 simple read-only list tool with no output schema, the description supplies purpose, fields, sort order, and endpoint. Enough to invoke correctly; pagination details live in the schema, so 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 description coverage is 100%, with page and limit fully documented in-schema. The description adds no parameter syntax or format details, 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 (List) and resource (affiliate links), and enumerates the returned fields. It's clearly distinguishable from sibling get_affiliate_link (singular retrieval) and create_affiliate_link.

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?

Implied usage as a listing/retrieval tool; the sibling list/get/create set makes the read-list role inferable. However, it gives no explicit when-to-use guidance such as distinguishing it from rewardful_get_affiliate_link or listing coupons.

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, so safety is covered; the description adds genuinely useful behavioral context beyond that: result ordering (newest first), the fact that email/stripe lookups return zero or one, what expand changes, and the underlying GET endpoint. It stops short of describing pagination/return envelope details, 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 dense sentences with the list/default behavior front-loaded, followed by filtering, lookup, and expansion, capped by the endpoint mapping. No filler sentences; each 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?

No output schema exists, so the description takes responsibility for signaling returned content (affiliates with visitors/leads/conversions) and the expandable nested objects, which is adequate for a list tool. Pagination behavior is only delegated to schema fields, leaving a minor 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%, so all six parameters are already documented; the baseline is 3. The description adds only marginal meaning for a few params (email/stripe_customer_id cardinality, expand rationale) and does not extend the schema's syntax or format guidance.

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 affiliates') plus scope details: sort order (newest first), returned metrics (visitors/leads/conversions), and the zero-or-one lookup modes. It differentiates itself from read siblings implicitly via 'List', but never names get_affiliate as the id-based alternative, so sibling routing is left 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?

Explains the in-tool usage patterns: filter by campaign, look up by email or Stripe customer id, expand for detail. However, it gives no when-to-use guidance relative to alternatives like get_affiliate (e.g. 'for a single affiliate by id, use get_affiliate'), so cross-tool selection 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?

readOnlyHint=true already declares a safe read, so the bar is lower; the description adds genuine value by disclosing what the payload contains (reward rules, totals), which matters because there is no output schema. It does not cover pagination behavior beyond what the schema states, hence not 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 tight sentences with the core purpose front-loaded and the returned fields grouped compactly. The trailing endpoint reference is slightly redundant, keeping it just short of a 5.

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 compensates by naming the returned reward-rule and total fields, and both optional parameters are covered by the schema. Nothing critical for calling the tool 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?

With 100% schema description coverage, page and limit are already fully documented in the schema. The description adds no syntax or formatting detail for these parameters, 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 ('List the affiliate program's campaigns') and enriches it by enumerating the reward rules and totals returned. This clearly separates it from rewardful_get_campaign by plurality/scope, though it never explicitly names that sibling as the alternative.

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 listing intent is implied and the endpoint (GET /v1/campaigns) confirms a read-all operation, but there is no explicit when-to-use guidance or routing away from rewardful_get_campaign for a single campaign. Adequate but with a clear gap.

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 only declare readOnlyHint=true, so the description must carry the rest – and it does add real context: newest-first ordering, amounts in cents, the full state vocabulary, expansion semantics and the underlying endpoint. It stops short of pagination behavior or result-size expectations.

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?

Densely front-loaded: resource, scope, ordering, fields and filters arrive before the trailing 'Rewardful: GET /v1/commissions' pointer. It is information-rich rather than padded, though the single long sentence is somewhat packed.

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 5-parameter, all-optional, read-only list tool with no output schema, the description covers scope, filters, expansion and returned fields adequately. Only minor gaps remain: no explicit note on the default page size or how the expanded payload nests.

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 earns a bump by explaining what 'expand' actually yields ('the sale (with referral, customer and affiliate) or campaign') and by naming the filterable dimensions, adding meaning beyond the bare enum lists.

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 commissions') and even defines the domain concept ('rewards owed for referred customers' payments'), plus ordering and returned fields. It implicitly separates itself from get_commission/get_payout via 'List', but never names an alternative 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 description tells the agent how to narrow results ('Filter by affiliate or state; expand the sale ... or campaign'), which is implied usage guidance. It does not say when to prefer this over get_commission (single commission) or list_payouts, nor does it give any exclusion criteria.

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 only declare readOnlyHint=true; the description adds real context beyond that, including default sort order (newest first), the returned field set, and the possible state values. It omits pagination behavior, but for a read-only list this is a solid addition over the annotation.

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?

Compact and front-loaded: purpose first, then return shape, then filtering/expansion options, ending with the backing endpoint. No filler sentences and 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?

With no output schema, the description usefully names the returned fields (amount, currency, state) and ordering. It covers filtering and expansion adequately for a read-only list tool, though pagination semantics are left entirely to the schema.

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 page, limit, state, expand and affiliate_id are all already documented. The description restates the filtering and expansion parameters and enumerates states, which are also in the schema, so it adds little beyond the 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?

States a specific verb and resource (list payouts) and even defines the resource parenthetically as 'bundles of an affiliate's payable commissions', so the agent understands the domain object. It adds ordering (newest first) and returned fields (amount, currency, state), which clearly distinguishes it from the singular rewardful_get_payout.

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 says what can be filtered and expanded ('Filter by affiliate or state; expand affiliate or commissions'), implying usage, but never states when to reach for this list tool versus rewardful_get_payout or rewardful_list_commissions. Guidance is implied rather than explicit.

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 readOnlyHint=true, but the description adds genuine behavioral context beyond that: default ordering ('newest first'), the conversion-state lifecycle, and the fields returned per referral. It does not mention pagination behavior or rate limits, but with annotations covering safety 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?

One front-loaded sentence stating resource, scope, ordering, return fields, and filters, followed by the underlying endpoint. Every clause carries information; 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 usefully names the returned fields (conversion state, customer, link), and pagination parameters are documented in the schema. It is nearly complete for a 9-parameter read tool, though it omits pagination/ordering caveats.

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 every parameter is already documented in the schema; baseline is 3. The description restates the filter categories and adds minor meaning (e.g., conversion states), but adds little beyond what the schema already provides.

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 referrals') and immediately defines the resource as 'visitors who arrived via an affiliate link', which distinguishes it from siblings like list_affiliates or list_commissions. The tool's scope and identity are 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?

It enumerates available filters (affiliate, state, email, Stripe customer, updated-at window), which implies when to use it for scoped queries, but gives no explicit when-to-use/when-not guidance or naming of alternatives among the many sibling list/get tools.

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 only declare destructiveHint=true; the description goes further by explaining the concrete consequence of the destructive path (disabled stops tracking and earning) and that it is reversible by setting state back to active. It stops short of noting partial-update semantics (which omitted fields are preserved) or response shape.

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, front-loaded with the mutable field list, followed by the key behavioral caveat and an API mapping. No filler or 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 10-parameter mutation with one required field and no output schema, the description covers the important knobs (identity, payout emails, notifications, campaign, state) and the destructive consequence. It leaves stripe_customer_id unaddressed and doesn't state that omitted fields are untouched, but the essential calling information is 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%, so the baseline is 3; the description adds meaning beyond the schema by clarifying that changing campaign_id reassigns ('moves') the affiliate and by tying state values to their earning/tracking effect. It omits stripe_customer_id, but the added semantics on campaign and state justify the bump.

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 (change/update) and resource (affiliate) and enumerates the mutable fields, including the notable '(moves them)' note for campaign. The sibling set is dominated by create/get/list variants, so the update verb is easily separable, 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?

Offers context on the effect of setting state to disabled and how to undo it, which implicitly tells the agent when this tool matters, but gives no explicit when-to-use vs. get_affiliate or alternatives, nor any prerequisites or permission requirements.

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 give destructiveHint=true, but the description goes well beyond that by naming the exact consequence: the old token stops tracking immediately and already-shared links break. It also discloses the rewardful API route (PUT /v1/affiliate_links/:id), which aids error diagnosis. This is real behavioral context the structured fields do not 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 short sentences, front-loaded with purpose and then the destructive warning at the point of highest salience, followed by the remedy and the underlying endpoint. Zero 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 two-param mutation with annotations covering the safety profile and no output schema, everything an agent needs is present: what changes, the destructive side effect, the safer alternative, and the API path. Nothing material 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%, so both parameters (link_id UUID, token pattern) are already documented in the schema. The description adds no parameter-level detail or format hints beyond it, which is the baseline when the schema does the heavy lifting.

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 ('Change the token of an existing affiliate link') and distinguishes itself from the create sibling, which the agent would otherwise confuse it with. The agent can select this over rewardful_create_affiliate_link 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?

Explicitly names the alternative ('Prefer rewardful_create_affiliate_link to add a second token') along with the condition that selects it, plus a warning about when this tool is the wrong choice. The when-not guidance is unusually concrete.

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?

With destructiveHint=true already declared, the description earns credit for disclosing patch semantics ('Only the fields you pass change'), which tells the agent unlisted fields are preserved rather than cleared — a real risk with PUT-style endpoints. It also pins the underlying operation (PUT /v1/campaigns/:id). It does not cover permissions, plan gating, or reversibility.

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 mutable-field list front-loaded and the key patch caveat second. The trailing 'Rewardful: PUT /v1/campaigns/:id.' is largely redundant with the already-namespaced tool name and adds little for an agent choosing a tool.

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 10-parameter mutation tool, the schema carries parameter detail, destructiveHint carries the risk profile, and the description adds the one thing structured data omits — that this is a partial update. Missing only error/permission behavior, which is minor given the rich schema and no output schema.

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 already documents each field's meaning, format and conditional requirements (commission_percent required when reward_type=percent, etc.). The description's field list mirrors the schema without adding syntax, units, or conditional logic, 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 ('Change') and resource ('a campaign'), then enumerates the exact mutable surface: name, URL, visibility, reward rule, payout minimum, coupon. An agent can immediately tell this is the partial-update counterpart to rewardful_create_campaign and rewardful_get_campaign 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 never says when to reach for this tool versus rewardful_create_campaign, rewardful_get_campaign or rewardful_update_affiliate, and lists no preconditions (e.g. campaign must exist, plan gating). 'Only the fields you pass change' hints at patch semantics but is a behavioral trait, not usage routing.

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