rewardful

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

With destructiveHint=true already declared, the description adds a genuinely non-obvious behavioral fact: Rewardful sends NO welcome email for API-created affiliates. That is exactly the kind of consequence an agent should surface. It stops short of noting idempotency, duplicate-email handling, or auth requirements.

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 action and the referrer branch, and the API endpoint is appended after the substantive content. 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 10-param creation tool with full schema coverage and no output schema, the description covers identity, the referrer variant, and the email side effect. It leaves the success response shape and conflict behavior unaddressed, but as a create tool it is largely 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%, so all ten parameters including stripe_customer_id, state, and token are documented in the schema itself. The description only re-frames stripe_customer_id, adding little beyond structured data, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add an affiliate') plus a scoped variant ('customer referrer, by passing stripe_customer_id'). This clearly separates it from sibling creators like rewardful_create_affiliate_coupon and rewardful_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?

It signals one branch of usage (referrer vs affiliate via stripe_customer_id) but gives no guidance on when to prefer this over rewardful_update_affiliate or how to handle an affiliate that already exists. Usage is implied 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?

With only destructiveHint=true provided, the description adds genuine behavioral context by disclosing two external dependencies (existing Stripe code, campaign coupon configured in dashboard) that would otherwise be unknown. It does not explain what happens if a code is re-assigned or whether the assignment is reversible, which limits 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 front-loaded sentences carry the purpose and the prerequisites with no filler; the trailing 'Rewardful: POST /v1/affiliate_coupons.' is a useful API anchor but slightly redundant overhead.

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

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

For a two-parameter create tool with no output schema, the description covers purpose, required external state, and the source endpoint. Missing only return-value and conflict/overwrite behavior, which are minor for an agent deciding whether to call 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% and the token property already documents 'the exact coupon / promotion code as defined in Stripe'. The description largely restates that constraint, adding little syntax or format detail beyond what the schema provides, 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 states a concrete verb and resource ('Assign a coupon / promotion code to an affiliate') plus the business effect ('so sales using it are credited to them'), which clearly separates it from rewardful_create_affiliate_link and rewardful_create_affiliate. It never names a sibling, so differentiation is implicit rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies two real preconditions for use: the code must already exist in Stripe, and the affiliate's campaign must already have a campaign coupon set in the dashboard. That is strong when-to-use context, though no alternative tool or failure path is named for cases where those preconditions are unmet.

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 carry title and destructiveHint, so the description adds genuinely useful context: the plan gate and the token auto-generation default. It still omits the mutation's side effects, idempotency, and what the call returns, which is notable given the odd destructiveHint=true on a create operation.

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 core action front-loaded and no filler. The trailing "Rewardful: POST /v1/affiliate_links" is implementation detail that is marginally useful for an API-aware agent but is the weakest part of an otherwise tight description.

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

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

With no output schema, the description should say what a successful creation yields (the created link/token), which it does not. Plan gating and the token default are covered, so it is adequate but incomplete for a creation 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 the baseline is 3, and the description adds meaning beyond the schema by clarifying that the token parameter is optional and auto-produced when omitted. It does not, however, explain the affiliate_id semantics beyond what the schema already documents.

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 concrete action (create an additional tracking link) on a specific resource tied to an affiliate, which separates it from siblings like create_affiliate_coupon or create_campaign. It is clear without opening the schema, though it never explicitly names the create verb or names a sibling to disambiguate against.

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?

"Growth/Enterprise plans only" gives a real precondition, and "A token is generated if omitted" implies when the token param is optional. However, there is no explicit when-to-use vs alternatives guidance (e.g., when to add a second link vs rely on the default link), leaving selection implicit.

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

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

Annotations only supply destructiveHint=true, so the description must add context, and it does disclose that creation also creates the associated reward rule and that it maps to POST /v1/campaigns. It omits side effects beyond that, such as permission requirements, idempotency/duplicate handling, or whether the reward rule can be revised later.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences: purpose first, conditional parameter rule second, API mapping last. Every sentence carries information 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?

For a 9-parameter creation tool with full schema coverage and no output schema, the description covers the core risks: that it creates two entities (campaign + reward rule) and which parameters pair with which reward_type. It lacks any note on the returned object or on the meaning of optional fields like private/minimum_payout, but the schema carries those.

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 baseline is 3. The description's conditional guidance duplicates what the schema already states ('Required when reward_type is percent/amount'), adding no syntax, default, or format detail 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 gives a specific verb and resource ('Create a new affiliate campaign with its reward rule'), which cleanly separates it from the get_/list_/update_campaign siblings. It does not explicitly name a sibling it should be chosen over (e.g., update_campaign), 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?

It provides conditional usage for the reward parameters ('For reward_type percent pass commission_percent...'), which is genuine when-to-use guidance at the parameter level. However, there is no guidance on when to choose this tool versus rewardful_update_campaign or how it relates to the affiliate-creation siblings, so usage is only partially covered.

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

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

Annotations already cover the safety profile (readOnlyHint=true), so the bar is low. The description adds real value by disclosing the payload contents (campaign, links, coupon, visitor/lead/conversion counts) that an agent would otherwise not know without an output schema. Error behavior for a missing id is not addressed.

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 operation and its returned scope come first, and the endpoint reference is appended as supporting metadata. 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 single-parameter read tool with annotations carrying the safety profile and no output schema, enumerating the returned fields is the key missing piece and it is provided. Minor gaps (not-found/error behavior, naming the list alternative) remain.

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. The description only restates 'by id', adding no format, validation, or lookup semantics 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?

Specific verb and resource ('Fetch a single affiliate by id') with scope, plus a REST endpoint mapping. It implicitly contrasts with list_affiliates by saying 'single ... by id', but it never names the sibling explicitly, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'single affiliate by id' suggests use when you already have an id rather than needing a filtered list. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., list_affiliates for browsing).

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=true annotation already tells the agent this is a safe, non-mutating lookup, and 'Fetch' is consistent with that. The description adds the API endpoint reference but says nothing about error behavior for missing ids or the shape of the response, so it only marginally exceeds the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the action and resource front-loaded and zero wasted text. The endpoint reference is compact and informative rather than 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?

For a single-parameter read tool with no output schema and annotations covering the safety profile, the description supplies everything needed to invoke it correctly. Only minor gaps remain around failure modes for invalid ids.

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 coupon_id parameter is fully documented as a UUID in the schema. The description adds no format, constraint, or sourcing detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Fetch a single affiliate coupon by id') and notes the underlying endpoint, which distinguishes it from the sibling list_affiliate_coupons by the singular 'single' and the id-based lookup. It is clear without needing the schema, though it does not explicitly name the sibling it complements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no statement of prerequisites (e.g. needing a valid coupon id), and no contrast with list_affiliate_coupons or other retrieval tools. The 'by id' phrasing implies the caller already holds an id, but that is left to inference.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating read, so the description's added value is limited to the underlying endpoint (GET /v1/affiliate_links/:id). It says nothing about auth requirements, rate limits, or behavior for an unknown/nonexistent id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler; the purpose is front-loaded and the endpoint reference is a compact trailing detail.

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-by-id tool with full schema coverage and annotations covering the safety profile, the description is essentially sufficient. It could mention the not-found/error behavior, but nothing critical to correct invocation 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 in the schema as a UUID with minLength 1. The description adds no format or constraint 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?

States a specific verb (Fetch) and resource (a single affiliate link) plus the identifying key (by id), which cleanly separates it from the sibling list_affiliate_links. It does not name the alternative sibling explicitly, so it falls short of the 5 tier.

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' conveys that this is a point lookup requiring a known identifier. There is no statement of when to prefer this over list_affiliate_links or any prerequisite/error condition.

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 safe-read profile is covered. The description adds the underlying REST mapping (GET /v1/campaigns/:id), which aids error interpretation, but says nothing about failure modes (missing/invalid id) 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 short sentences, the action and resource front-loaded, with no filler. Every clause carries information.

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

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

For a low-complexity single-resource getter with annotations covering safety, the definition is adequate but thin: with no output schema, a hint at what a campaign object contains would have made it 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 already documented as 'The campaign's id (UUID)'. The description adds only the phrase 'by id', so baseline 3 is appropriate.

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

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

States a specific verb ('Fetch') and resource ('a single campaign by id'), and the singular scoping implicitly separates it from list_campaigns. It is clear about what it does, though it does not explicitly name the sibling it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'by id' suggests the caller must already hold a campaign_id, which distinguishes it from a list operation, but there is no statement of when to prefer rewardful_list_campaigns or what happens when the id is unknown. Minimum viable guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by enumerating what the response contains (campaign plus the earning sale with charge, refund, tax, referral, customer and affiliate), which is the only place this return shape is documented since there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences: the payload summary is front-loaded and the Rewardful endpoint reference is a useful trailing anchor. 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?

For a single-resource read with no output schema, the description partially compensates by sketching the returned fields, which is the key missing structured information. It stops short of describing error behavior for an invalid or unknown id.

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 commission_id parameter is fully documented in the schema as a UUID. The description only restates that lookup is by id, adding no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch a single commission by id') and scopes it to one record, which implicitly separates it from the sibling list_commissions. It never names that sibling explicitly, so it falls short of the highest tier of sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'by id' suggests you already hold a commission UUID, versus listing/querying for one. There is no explicit when-to-use statement and no named alternative such as rewardful_list_commissions.

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 readOnlyHint=true already declaring a safe read, the description still adds value by disclosing the response shape: the payout comes with the affiliate and the commissions it bundles. Since no output schema exists, that return-content detail is genuinely useful beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with the primary action ('Fetch a single payout by id') front-loaded and the response contents following. The trailing 'Rewardful: GET /v1/payouts/:id' is mildly redundant but maps the tool to an endpoint, which is a defensible use of space.

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 one-parameter GET with annotation coverage and no output schema, the description supplies the essential missing piece: what the returned payout includes (affiliate plus bundled commissions). Nothing critical to calling it correctly is absent, though return formatting and error 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?

A single parameter (payout_id) is documented at 100% schema coverage as a UUID, so the schema carries the semantics. The description only repeats 'by id' and adds no format, validation, or lookup nuance, 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 ('Fetch a single payout') and scopes it to one record by id, which implicitly contrasts with the sibling rewardful_list_payouts. It stops short of naming the alternative, so sibling differentiation is inferred rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by id' implies usage: fetch one payout when you already have its identifier. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative (e.g., list_payouts for enumerating payouts). 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?

readOnlyHint=true already covers the safety profile, and the description adds the actual returned fields (token, Stripe id, leads, conversions, archived), which is valuable because no output schema exists. It still says nothing about pagination behavior or result ordering, leaving a small 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?

A single dense sentence is front-loaded with the core action and includes the source endpoint and field list efficiently. The parenthetical field enumeration is slightly listy but earns its place given the absent output schema.

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

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

For a simple read-only list tool with fully documented params, the description covers purpose, filtering, and return fields. Pagination is handled by the schema, and no output schema means only ordering/pagination semantics are left implicit.

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, the schema already documents page, limit, and affiliate_id semantics. The description's 'optionally for one affiliate' merely mirrors affiliate_id without adding syntax or format detail, 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 gives a clear verb+resource ('List affiliate coupon / promotion codes') and enumerates the returned fields, so an agent knows exactly what it retrieves. It does not explicitly name the sibling 'get_affiliate_coupon' as the singular alternative, but the list-vs-get distinction is inferable from the name.

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 notes that results are 'optionally for one affiliate,' which implies when the affiliate_id filter applies, but there is no explicit when-to-use/when-not guidance or named alternatives among the many sibling tools. 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds useful context beyond annotations by disclosing the sort order ('newest first') and the returned field set, but says nothing about pagination behavior, result caps, or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no filler: the action and returned fields are front-loaded, followed by the 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?

For a simple two-param list tool with full schema coverage and no output schema, the description is nearly complete, covering action, ordering, and return fields. Minor gap: it does not characterize pagination or result limits, which the agent must infer from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (page, limit) are fully documented in the schema, so the baseline is 3. The description contributes no additional parameter meaning such as default page size or pagination interaction.

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 affiliate links'), enumerates the returned fields, and gives the underlying endpoint. An agent can distinguish this from rewardful_get_affiliate_link (singular fetch) and rewardful_list_affiliates 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?

Usage is only implied by the verb 'List' and the 'newest first' ordering; there is no explicit when-to-use, no exclusion of alternatives, and no mention of prerequisites. Adequate but leaves routing inference to the agent.

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

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

Annotations already declare readOnly hint, so the bar is lower; the description nevertheless adds ordering (newest first), the returned metrics, the zero-or-one semantics of the lookup filters, and that campaign/links/commission_stats can be expanded for depth.

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 clauses front-loaded with what/ordering, then filter modes, then expansion, closing with the underlying endpoint. 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?

With no output schema, the description usefully describes the returned fields and the zero-or-one case. It leaves pagination behavior and the default page size to the schema, which is acceptable but not fully complete for an agent unfamiliar with the endpoint.

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; the description only echoes campaign, email, stripe customer id, and expand without adding format or default detail beyond what the schema 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 and resource (list affiliates) plus what each row carries (visitors/leads/conversions) and the ordering (newest first). This differentiates it from the singular rewardful_get_affiliate and from the other list_* siblings by naming its own filter modes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear selection context: filter by campaign for a set, or use email/stripe_customer_id to resolve a single affiliate (returns zero or one). It never names get_affiliate as the alternative for a known id, so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context by enumerating the categories of data returned (reward rules and aggregate totals), which no output schema supplies. It stops short of mentioning pagination behavior or the backend endpoint semantics beyond the route reference.

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 that front-loads the resource and then the returned fields, followed by a compact API route reference. No redundancy or 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-parameter, read-only list tool with no output schema, the description supplies exactly what is missing: what the response contains. Pagination is fully handled by the schema, so nothing an agent needs to invoke this correctly is absent.

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% — page and limit are fully documented with ranges and defaults in the schema — and the description mentions neither. Per the rubric this is the baseline 3, since the schema carries all parameter meaning.

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) and resource (campaigns), and it goes further by naming the payload contents: reward rules (percent/fixed commission, payout minimum, referral expiry) and totals (visitors, leads, conversions, affiliates). It reads as a bulk/list counterpart to rewardful_get_campaign, but it never names that sibling, 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?

The description offers no when-to-use guidance, no exclusions, and no pointer to alternatives such as get_campaign for a single record. Nothing tells the agent when this list call is the right choice versus the many other list_* siblings.

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 goes further by disclosing result ordering ('newest first'), the shape of returned values (amount in cents, currency, state with enumerated values) and the underlying GET /v1/commissions endpoint. It stops short of discussing pagination behavior or default result limits, which is the remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences: the first leads with the core action and return shape, the second covers filtering and expansion. Every clause carries information and the endpoint is tucked at the end rather than 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?

With no output schema, the description carries the burden of describing returns and partially does so (amount, currency, state, ordering), plus filter and expand options. Pagination behavior and the unpaginated default are not addressed, which is a minor omission for a list 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 the baseline is 3, but the description adds meaning beyond the schema by enumerating the state values and clarifying what expand actually returns ('the sale (with referral, customer and affiliate) or campaign'). It does not mention page/limit, though those are self-describing 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 (list commissions) and immediately defines the domain term as 'rewards owed for referred customers' payments'. The explicit ordering ('newest first') and REST endpoint make the operation unambiguous and separable from siblings like get_commission or list_payouts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the filtering affordances ('filter by affiliate or state'), but there is no explicit when-to-use guidance and no routing to alternatives such as rewardful_get_commission for a single record. Adequate but leaves the agent to infer context.

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 establishes a safe read, but the description adds real behavioral detail beyond annotations: default sort order (newest first), the enumerated payout states, and the ability to expand nested affiliate/commission objects. It omits pagination defaults and result-size behavior, but those are covered by the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph that is well front-loaded: what it is, ordering, returned fields, filters, and the underlying API endpoint. Every clause carries information, though the trailing 'Rewardful: GET /v1/payouts' is marginally useful for an agent that cannot make raw HTTP calls.

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 and no nested object docs, the description usefully previews the return shape (amount, currency, state) and the default ordering, which an agent needs to interpret results. Pagination semantics are left entirely to the schema, which is reasonable given its full 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%, so every parameter (page, limit, state, expand, affiliate_id) is already documented in the schema. The description restates the state and expand filters but adds no syntax, format, or default value beyond what the schema provides, 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 payouts') and immediately defines the domain term ('bundles of an affiliate's payable commissions'), which distinguishes it from rewardful_get_payout and rewardful_list_commissions without opening a schema. Ordering ('newest first') and returned fields (amount, currency, state) are stated up front.

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?

Tells the agent when to reach for filtering by affiliate or state and when to use expansion ('expand affiliate or commissions'), which is genuine usage context. It never names the sibling it competes with (rewardful_get_payout for a single record) or states exclusions, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral context beyond that: results are returned 'newest first', and each row carries its conversion state, customer, and link. It stops short of describing pagination or auth behavior, but the ordering and row-shape disclosures are real value-adds.

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 resource definition and return shape, then the filter surface, then the endpoint reference. No filler and nothing 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?

This is a no-required-param, read-only list tool with a fully documented schema and no output schema. The description supplies the return field preview and sort order, which is enough for an agent to call it correctly; only the omission of pagination nuance keeps it short of a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all nine parameters (page, limit, email, expand, affiliate_id, updated_since/until, conversion_state, stripe_customer_id) are already documented in the schema. The description enumerates the filter axes but adds no syntax or format detail beyond what the schema provides — 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?

Specific verb (list) plus resource (referrals), and it goes further to define what a referral is — 'visitors who arrived via an affiliate link'. This definitional framing distinguishes it from sibling list tools like rewardful_list_commissions and rewardful_list_affiliates without the agent needing to open any 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 conveys the tool's scope (list referrals with filters by affiliate, state, email, Stripe customer, or updated-at window), which is enough to infer usage. However, it gives no explicit when-to-use/when-not guidance and never names a sibling as an alternative — nothing tells the agent to prefer this over, say, list_commissions for a given question.

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 supply destructiveHint=true with no explanation. The description adds real behavioral context beyond that: setting state to disabled halts tracking and earning, and the change is reversible ('set it back to active to undo'). It stops short of describing partial-vs-full update behavior or auth requirements, but it meaningfully enriches the safety picture.

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, front-loaded sentences covering fields and consequences, followed by an endpoint mapping. The 'Rewardful: PUT /v1/affiliates/:id' line is mild filler but useful for endpoint mapping; overall there's little waste.

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 tool with 10 parameters, only 1 required and no output schema, the description is decent but leaves a key gap: it doesn't state whether omitted fields are left unchanged or cleared (partial vs. full replace), which directly affects how an agent should call a PUT-style update. Auth/permission requirements are also 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%, so baseline is 3, but the description adds meaning the schema doesn't: noting that setting campaign 'moves them' and that 'payout emails' map to the wise_email/paypal_email fields. That is incremental semantic value on top of well-documented parameters.

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 ('Change') plus resource ('an affiliate's') with an explicit enumeration of mutable fields (name, email, payout emails, notifications, campaign, state). This clearly separates it from the sibling create/get/list affiliate tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the field list and by the state semantics, but the description never states prerequisites (e.g., needing an existing affiliate_id) or when to prefer create_affiliate versus this update. No explicit alternatives are named.

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, but the description goes further by explaining the concrete consequence: the old token stops tracking immediately and already-shared links break. This is exactly the operational detail an agent needs before invoking an irreversible mutation.

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 the destructive warning front-loaded right after the purpose statement, so the risk is seen before the alternative. The trailing 'Rewardful: PUT /v1/affiliate_links/:id' is minor implementation detail that earns its place only marginally.

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

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

For a two-parameter mutation with no output schema, the description covers purpose, consequence, and the recommended alternative, with the schema handling parameter syntax. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both link_id and token are fully documented in the schema, including the token pattern and example. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Change the token of an existing affiliate link'), naming the exact mutation being performed. It is trivially distinguishable from rewardful_create_affiliate_link and rewardful_get_affiliate_link 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?

Gives an explicit when-not and a named alternative: 'Prefer rewardful_create_affiliate_link to add a second token.' The agent knows both the right tool and the reason to avoid this one in the common case.

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

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

The destructiveHint annotation already flags this as a mutating operation, so the bar is lower. The description usefully clarifies that it is a partial update rather than a full overwrite, but says nothing about reversibility, permission/plan requirements, or what happens to fields left unset beyond that one clause.

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 field scope, followed by a compact endpoint reference. Nothing is padded, though the 'Rewardful: PUT /v1/campaigns/:id' line is informational rather than decision-relevant.

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 mutation tool with 10 schema-documented parameters, a destructive annotation and no output schema, the description covers the essential action and partial-update behavior. Side effects on downstream artifacts (affiliate links, coupons) and the response shape are unspecified, but the structured fields carry most of the remaining burden.

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 (including the conditional 'required when reward_type is X' rules) is documented in the schema itself. The description's field list merely restates a subset of those names, adding no format, unit, or constraint detail beyond what the schema 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?

Clear specific verb+resource ('Change a campaign's...') with an explicit enumeration of the mutable fields (name, URL, visibility, reward rule, payout minimum, coupon). The verb alone separates it from rewardful_create_campaign, rewardful_get_campaign and rewardful_list_campaigns, though no sibling is 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?

'Only the fields you pass change' communicates partial-update semantics, which tells the agent it need not supply all ten parameters. However there is no guidance on when to prefer this over create_campaign or update_affiliate, and no stated prerequisites (e.g. the Growth/Enterprise requirement that only appears in the schema).

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