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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds the crucial detail that the first invocation is a non-mutating preview that returns a confirmToken, and that mutation only occurs on the second call with confirm:true. This reconciles the write semantics with the annotation profile. It stops short of covering token expiry, partial failures, or permission 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 tightly packed sentences. The action and scope come first, and the two-phase protocol follows immediately, with no filler.

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

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

With no output schema, the description usefully discloses that the first call returns a preview and a confirmToken. It could say more about what the preview contains or the blast radius of the bulk approval, which matters given destructiveHint=true.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains that confirm and confirmToken must be supplied together on the second call and that the token originates from the preview response. That clarifies the interplay between the two parameters rather than repeating them.

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 ('approve'), a specific resource ('every commission line'), and a precise scope condition ('whose hold period has passed'). This is clearly distinct from settle_commission and approve_referral without needing to open 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?

The description gives a clear usage context (bulk approval of due commissions) and an explicit two-step call protocol. It does not name a sibling alternative or state when not to use it, but the scope condition does most of the routing work.

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 description discloses the non-obvious two-call preview/confirmToken protocol, which is real behavioral context the annotations do not carry, and 'Write:' correctly matches readOnlyHint=false and destructiveHint=true. It does not say what approval actually changes or whether it is reversible, which is a meaningful gap for a destructive-flagged 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?

Two sentences, front-loaded with the action, no filler. Every clause (scope, write classification, confirm flow) carries information an agent needs.

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

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

For a destructive, three-parameter mutation with no output schema, the definition covers the essential call protocol and safety posture. Only the consequences of approval (what state changes, reversibility) are missing.

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

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

Schema coverage is 67% and the schema already documents confirm and confirmToken; the description adds the sequencing semantics that the schema alone leaves implicit (first call returns token, second call supplies confirm:true plus that token). referralId remains undocumented in both places.

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 ('Approve a referral') plus the qualifying scope ('held for review'), which distinguishes it from void_referral, pause_referral, resume_referral and approve_due_commissions. An agent can route correctly without opening 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 'held for review' clause gives a clear precondition for when this tool applies, and the second sentence prescribes the exact invocation sequence. It does not name an alternative tool or state exclusions (e.g., what to do if the referral is not held), so it stops short of full when/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?

Goes meaningfully beyond the destructiveHint=true annotation by disclosing that the first call is a non-mutating preview and that mutation only occurs with confirm:true plus the returned token. It does not say what the preview contains, whether the confirm call is idempotent, or what happens if the token expires.

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 primary purpose and the safety-critical write protocol front-loaded, and the confirming mechanism second. No filler.

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

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

For a destructive 5-parameter tool with no output schema, the description covers the confirm protocol but leaves the required identifiers and the preview's return contents unexplained, so an agent could still mis-invoke on the first call.

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 only 40%, and the description compensates only for confirm/confirmToken, which the schema already documents. The three required params (programId, partnerId, code) get no semantic explanation from either source — no format, uniqueness constraint, or referential requirement is stated.

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

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

States a specific verb and resource ("Create a coupon code") plus the scope detail that it attributes to a partner. No sibling creates coupons, so there is nothing to confuse it with, but it never contrasts with create_link or other creation tools, leaving differentiation implicit.

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

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

The description gives a clear invocation protocol for the two-call preview/confirm flow, which is real usage guidance. It never states prerequisites (must the program and partner already exist? must the code be unique?) or when to prefer this over create_link.

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 this is a write (readOnlyHint=false) and potentially destructive, and the description adds genuinely new behavioral context: the two-phase preview/confirm safeguard and the token dependency. It stops short of saying what confirm actually finalizes or whether the link can be revoked, which matters for a tool flagged destructiveHint=true.

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

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

Two short sentences, zero filler, with the purpose front-loaded and the operational protocol immediately after. Every clause earns its place.

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

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

No output schema exists, so the description should say more about what the preview returns and what state results after confirm. It covers the core write protocol adequately but leaves the 'code' parameter and post-confirm outcome undocumented for a 6-parameter mutation 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 only 33%, and the description explains the confirm/confirmToken pairing — but both of those already carry schema descriptions. The bare 'code' parameter (presumably a custom slug) is never explained in either place, and programId/partnerId/destinationUrl rely on name inference alone.

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

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

States a specific verb and resource ('Create a tracked link') plus its scope ('for a partner in a program'), which cleanly separates it from siblings like create_partner and create_coupon. An agent can identify the right tool without opening the schema.

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

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

The second sentence gives a concrete call protocol: first call previews and returns a confirmToken, second call with confirm:true executes. That is actionable guidance for how to use the tool, though it never states prerequisites (e.g., whether partner/program must already exist) or when-not-to-use it.

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

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

Annotations already mark this as a non-read-only, destructive write. The description adds critical behavior beyond annotations: the tool previews first and only executes on a second confirmed call with a token.

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 purpose and then the confirm flow. There is no filler.

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

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

Covers the unusual preview-confirm workflow needed to call the tool safely, but parameter meanings and preview/final return details remain thin given no output schema and low schema description 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 coverage is only 40% across five parameters. The description elaborates only on confirm/confirmToken and never covers the required email/displayName or optional externalRef, so it does not compensate for the low schema coverage.

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

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

States a specific verb and resource: "Create a partner." The action/resource is unambiguous, though it does not differentiate from sibling tools such as create_link or create_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?

Explains the two-step invocation clearly: the first call returns a preview and confirmToken, and the second call with confirm: true and that token performs the write. It lacks explicit when-not guidance or alternative tools, but for a unique create tool the required flow is clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds the genuinely useful two-phase preview/confirm protocol and the confirmToken requirement, which an agent would not infer from the schema alone. It does not explain what the preview contains or whether a created payout run can be cancelled or reversed, which matters for a destructive 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?

Two tight sentences with zero filler; the draft/no-money-moves clarification is front-loaded and the call protocol follows immediately. Every clause carries essential decision-relevant 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?

There is no output schema and no required parameters, so the description carries the burden of explaining the return-then-confirm flow, which it does well. Missing only scope detail — what a payout run encompasses (which commissions/partners) — for a destructive, money-adjacent 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 coverage is 100%, so the baseline is 3, but the description adds real value by explaining the dependency between the two parameters — confirmToken comes from a prior preview call and confirm must be paired with it. It stops short of describing token lifetime or what happens if confirm is sent without a valid token.

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

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

States a specific verb and resource ('Create a payout run') and immediately scopes it as 'a draft: it is not executed, no money moves,' then clarifies that the confirmed second call does execute. That resolves an otherwise confusing tension, though it never differentiates this tool from payout-adjacent siblings like approve_due_commissions or settle_commission.

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

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

Gives explicit call sequencing: first call without confirm returns a preview plus confirmToken, second call with confirm: true and that token performs the change. It does not name sibling alternatives or say when a payout run is preferable to settling commissions another way, so it falls short of full when/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?

readOnlyHint=true already tells the agent this is a safe read. The description adds one genuinely useful behavioral fact: only open, unreviewed cases are returned, so resolved cases are excluded. It says nothing about ordering, pagination, limits, or result volume, which matters for an unbounded list.

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

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

Five words with no filler and the scoping constraint front-loaded. It is efficient, though its brevity shades into under-specification rather than true economy.

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 parameterless read tool with no output schema, the description is close to sufficient but leaves open what a case record contains and whether the list is paged or capped. One more clause on the returned fields or result size would close the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. Schema coverage is 100% trivially, and no parameter meaning is missing.

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 phrase 'Open fraud cases awaiting review' identifies the resource and adds a scope qualifier (open, awaiting review), but it is a bare noun fragment with no verb, so the 'list' action comes only from the tool name. It is understandable but vague about what a call actually does — return a collection, a count, or a queue view.

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

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

There is no guidance on when to call this versus anything else, no prerequisites, and no note about what to do with the results. No sibling tool covers fraud cases, so there is no real alternative to point at, but the description still offers zero usage 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 tells the agent this is a safe read; the description only adds the organizational scoping. It says nothing about pagination, result limits, or whether inactive programs are included, which matters for a listing tool.

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

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

A single front-loaded sentence with no filler. Nothing could be trimmed without losing meaning.

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 zero-param list tool with readOnly annotations, this is minimally sufficient. However, with no output schema and no note on return contents or paging, an agent doesn't know what it will get back.

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?

The tool takes no parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond the implicit org scope it already mentions.

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 programs") and scopes it to "this organization." Clear enough to act on, but it never distinguishes itself from the sibling program_overview, which an agent could plausibly choose instead.

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?

No indication of when to use this tool versus program_overview or the referral-listing tools. The agent is left to infer selection purely from the name.

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 safety, and the description adds useful scope by saying these are recent referrals with attribution channel and status. However, it does not define 'recent', pagination, ordering, or result limits, so behavioral disclosure remains thin.

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

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

The description is very short and front-loaded, with no wasted words. It is a fragment rather than a complete sentence, but for a zero-parameter list tool that is mostly acceptable.

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 zero-parameter read-only list tool with no output schema, the description gives some return-field context ('attribution channel and status'). It still leaves important operational questions unanswered, especially what 'recent' means and whether results are paginated or limited.

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?

The tool has zero parameters, so there is no parameter semantics burden. The description appropriately avoids discussing nonexistent inputs.

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 identifies the resource (referrals) and scope (recent), and the tool name supplies the list action. It is clear what data is exposed, but it does not explicitly distinguish this from sibling list or referral-action 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?

There is no explicit guidance on when to use this tool, when not to use it, or which sibling to choose instead. The read-only nature is implied by the annotation and the word 'recent', not by stated usage rules.

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 covering the safety profile, the description adds useful behavioral context: it returns pending, approved, and paid balances, and amounts are in integer minor units of the given currency. It does not mention authorization requirements or response shape details, but the added return-value semantics are meaningful.

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

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

The description is a single dense sentence with no wasted clauses, and it front-loads the resource being described. Its compactness is appropriate, though the lack of an explicit action verb slightly reduces immediate scannability.

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 read-only, one-parameter tool with no output schema, the description adequately explains the return values and their units. It could be slightly more complete by clarifying that the result is a balance object and how the three buckets relate, but overall it is sufficient 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?

The single parameter is fully documented in the schema, including the meaning of partnerExternalRef. The description adds no parameter-specific information beyond referencing currency, so the baseline score of 3 is appropriate when schema coverage is 100%.

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 identifies a specific resource, the partner's own commission balance, and distinguishes the three balance buckets. It does not use an explicit retrieval verb or directly contrast itself with siblings such as my_next_payout, so it is clear but lacks sibling differentiation.

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

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

It implies the tool is for checking a commission balance, but gives no explicit when-to-use guidance, prerequisites, or alternatives such as my_next_payout. The agent must infer the usage context from the purpose alone.

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 already establishes the safe-read profile, and the description adds useful behavioral detail: the date format is YYYY-MM-DD, the tool returns null when no payout is scheduled, and the amount reflects approved commission that would be included. It does not explain amount formatting or error behavior, but with the annotation coverage this is above the 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?

The description is a single tight sentence with no wasted language. The key output concepts, date and approved commission amount, are 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 one-parameter read tool with no output schema, the description supplies the essential return semantics: next payout date, null behavior, and approved commission amount. Minor gaps remain around currency/decimal formatting and partner-not-found behavior, but the definition 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?

The single parameter, partnerExternalRef, is fully described in the schema at 100% coverage, so the schema already carries parameter semantics. The description does not add syntax or lookup rules beyond the schema, which is acceptable but not enhancing.

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 the specific resource (a partner's next payout run) and the two return values it exposes: the scheduled date and the approved commission amount. It is clear enough to separate this read preview from siblings like create_payout_run or approve_due_commissions, though it does not explicitly name those alternatives.

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 name and the description's focus on checking a partner's next payout, but there is no explicit guidance on when to use this tool versus my_balance, partner_performance, or the payout-mutating siblings. No exclusions or prerequisites are 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 establishes the safety profile. The description adds useful behavioral guidance about using a verified partnerExternalRef and never guessing it from an email, though it omits details like failure behavior if no link exists.

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

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

Two sentences, front-loaded with the resource and followed by the key usage and parameter warning. No wasted wording.

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 single-parameter tool, the description covers purpose, usage context, and the critical ID-verification warning. It does not specify what happens if the partner has no referral link, but annotations and schema cover most other needs.

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 schema already defines partnerExternalRef. The description adds meaningful constraints by calling it a verified ID and explicitly warning against deriving it from an email.

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 identifies a specific resource, 'a partner's own referral link,' and makes clear it is retrieval rather than creation. It does not explicitly name sibling alternatives like create_link, so it stops short of full differentiation.

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

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

It gives a clear use case: answering a partner in chat or an AI agent. It also warns not to guess the partner ID from an email, but it does not explicitly compare against sibling tools such as create_link or list_referrals.

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 tells the agent this is a safe read, so the description's only added obligation is behavioral detail — time range, aggregation window, whether all partners are returned or only active ones, ordering. None of that is present. The description is essentially a field list that adds almost nothing beyond 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?

It is one short fragment with no filler, so nothing is wasted — but it is under-specified rather than concise. There is no leading verb clause to anchor the reader, so the single sentence carries no structure.

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 parameters, no output schema and a readOnly annotation, the tool is low-complexity, so the bar is modest and the description conveys what fields come back. Still, an agent cannot tell what scope of partners or what time window the figures cover, which matters for a reporting tool. Adequate but with a clear 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?

The tool takes zero parameters, so per the baseline rule this scores 4; there is nothing the description needed to disambiguate. The absence of parameters is consistent with the field-list description.

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 fragment names the resource and the metrics returned (clicks, referrals, revenue, commissions) at the per-partner grain, which does distinguish it from aggregates like roi_summary or program_overview. However it is a bare noun phrase with no verb — it never says 'returns' or 'retrieves' — so the agent must infer that this is a read/retrieval tool rather than a computed or mutating one.

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 statement, no mention of alternatives among the many siblings (roi_summary, roi_trace, program_overview), and no indication of prerequisites or when this is the wrong choice. The agent only gets the implied guidance of a metric name.

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 description adds substantial behavioral context beyond the annotations: it clarifies that payments continue to be recorded but earn nothing until the referral is resumed, and it explains the preview/confirmToken flow. This aligns with destructiveHint=true and readOnlyHint=false without contradicting them.

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

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

The description is two tight sentences with the main effect front-loaded and the confirmation procedure following immediately. There is no wasted text.

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

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

For a mutation tool with no output schema, the description covers the important behavioral consequence, the confirmation requirement, and the preview/token return mechanism. An agent has enough information to invoke it correctly.

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?

The description meaningfully explains confirm and confirmToken by tying them to the preview workflow, which goes beyond the schema text. referralId is not explicitly described, but its meaning is clear from the tool name and required-parameter status.

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 and explains the effect: pausing a referral means its payments are recorded but earn nothing until resumed. It is clear, though it does not explicitly distinguish the tool from nearby siblings such as void_referral or resume_referral.

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

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

The description explains the two-step confirmation workflow well, but it does not state when to choose pause_referral versus alternatives like void_referral or resume_referral. Usage is implied by the effect, not explicitly guided.

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 operation, and the description adds the fixed 30-day scope and the funnel/revenue subject. It does not disclose return shape, aggregation level, or filtering behavior, which is a modest gap for a read-only report.

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?

Single sentence, front-loaded with subject then timeframe, with no filler. It is terse but not structurally wasteful.

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 zero-parameter read-only report, the description is enough to know it returns a 30-day funnel and revenue summary. However, with overlapping siblings and no output schema, it should say more about what the overview contains or how it differs from roi_summary to be 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?

The tool has zero parameters, so there are no parameter semantics to explain and the schema is empty. Baseline 4 applies.

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

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

States a specific resource (funnel and revenue overview) and a precise time scope (last 30 days), so the agent knows this is a reporting tool. It does not contrast with roi_summary or partner_performance, so sibling differentiation is missing.

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?

No when-to-use guidance and no mention of alternatives such as roi_summary or partner_performance. The fixed 30-day window is implied, but the description does not say when this overview is preferred over sibling reports.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is known. The description adds genuinely useful non-schema behavior: a preview-first, token-confirmed protocol. It does not explain why the operation is flagged destructive or what side effects resume triggers.

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

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

Two sentences, no filler: the action comes first and the non-obvious two-call protocol follows immediately. Every clause earns its place.

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

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

For a 3-parameter mutation with no output schema, the description covers the action, the precondition, and the confirmation workflow. It omits what a successful resume returns or does and how failures (not paused, expired token) behave.

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 67% and documents confirm and confirmToken individually, but the description adds the sequencing relationship between them and referralId (preview comes first, then replay with the token), which the schema alone does not convey. referralId itself remains undocumented anywhere.

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 ('Resume a paused referral') with the state precondition built in, which cleanly separates it from pause_referral and void_referral among the siblings.

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

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

The 'paused' qualifier tells the agent the condition under which this tool applies, and the two-step instruction explains how to invoke it. It stops short of explicitly naming alternatives or stating what to do if the referral is not paused.

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 behavioral context beyond that — the rule that only subjects with a fully elapsed evidence window are listed, so young customers are never flagged, plus the shape of each entry. It does not mention result size limits or ordering, keeping it short of a 5.

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

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

Front-loads the resource description, then the enum glosses, then the eligibility caveat in three tight sentences with no filler. The inline pattern definitions are dense but every clause carries semantic weight.

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 with no output schema, the description covers the enum meanings, the eligibility rule, and the per-entry fields (subject plus detail amounts in minor units). Only result limits/pagination are unaddressed, 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 0% and the schema only lists bare enum strings, so the description carries the full semantic load — it defines what each of the four patterns actually detects, which is the single most important fact for selecting the right call. It also clarifies that amounts are in minor units.

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

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

States a specific resource ('Customers or partners matching a named credit-ROI pattern') and then defines every enum value in plain language, so an agent knows exactly what is being retrieved. It does not explicitly contrast with roi_summary or roi_trace, leaving sibling differentiation implicit.

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 description explains what each pattern means, which hints at when an agent would pick one, but gives no explicit when-to-use, when-not-to-use, or pointer to alternatives like roi_summary, roi_trace, or list_fraud_cases.

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

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

Beyond the readOnlyHint annotation, it discloses two important behaviors: amounts are integer minor units in the reporting currency unless `currency` is set, and null profit/roi means unknown rather than zero, with explicit advice not to estimate. That is real value the annotations don't carry; only the return shape/pagination is left implicit.

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?

Metrics and their meanings are front-loaded, and the critical null/never-count-credit-as-revenue warnings follow before the filter list. It is a dense single block with almost no waste, though splitting the output-field glossary from the caveats would read more cleanly.

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 explaining return values and does so for the key fields and the roi ratio. It does not enumerate the full result set, so an agent still learns some fields only at call time.

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 60% and the description names all five filters plus the currency-unit rule, closer to compensating than merely repeating. However partnerId and programId are listed with no explanation of what they scope, and from/to semantics are already fully covered by 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+resource: it reports what granted credit cost versus what it earned back, and defines the core metrics (cashAfterMinor, creditCostMinor, profitAfterMinor, roi). It never names the adjacent roi_trace or roi_patterns tools, so an agent must infer the boundary from the names alone.

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

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

It gives a concrete conditional behavior: when profitAfterMinor/netMinor/roi are null, tell the user to set their margin rather than estimate. It also notes the filters are optional. But it never says when to use this summary versus roi_trace or roi_patterns, leaving the sibling choice unguided.

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 already covers the safety profile, so the description earns credit for adding semantics: distinguishing cash (real money) from credit (not), and the edge case that profit fields are null when no margin is set. These are real behavioral details an agent would otherwise have to discover at call time.

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

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

Front-loaded with the scope constraint, then the returned content, then the cash/credit and null-margin clarifications. Two short sentences plus a compact definition, with essentially no 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?

With no output schema, the description carries the burden of describing returns and does so (timeline of grants, credit used, subsequent cash payments, nullable profit). Missing is an explicit relationship to the sibling ROI tools, but all information needed to call it correctly 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 baseline would be 3, but the description adds a constraint the schema cannot express: 'pass exactly one' of customerRef/partnerId. Since neither parameter is marked required and nothing in the schema declares mutual exclusivity, this is meaningful added 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 resource (the timeline behind a credit ROI figure) and a clear scope: exactly one customer or one partner. It also names the contents it returns (grants, credit used, cash payments). It stops short of naming the sibling ROI tools (roi_summary, roi_patterns) so the boundary between them is left implicit.

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 'so you can explain why a number is what it is' implies a drill-down/explanation use case, which is useful but indirect. There is no explicit statement about when to pick this over roi_summary or roi_patterns, and no exclusion of other scenarios.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's real contribution is the two-phase preview/confirmToken workflow, which is essential and not encoded anywhere in the schema or annotations. It does not say whether a settled commission can be reversed or what a re-settle attempt does, leaving some behavioral 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 tightly written sentences: purpose first, then the write workflow. Nothing is redundant, and the safety-critical two-step requirement is presented before the agent could 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 5-parameter destructive mutation with no output schema, the description covers the irreversible-write protocol well but omits the meaning of the required 'reference' and of 'memo', and never states consequences or reversibility of settling.

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 only 40%; the description explains the confirm/confirmToken handshake but says nothing about the required 'reference' (minLength 1), 'memo', or 'commissionId', which the schema leaves bare. It partially compensates but leaves a required parameter semantically unexplained.

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

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

States a specific verb and resource ('Mark a commission line paid') and qualifies the scenario ('because you credited the partner yourself (store credit)'), which distinguishes it from approve_due_commissions and create_payout_run in the sibling list.

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 store-credit rationale tells the agent exactly when this tool applies and implicitly when it does not (payout-run flows). No explicit exclusion statement or named alternative, so it stops short of a 5.

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

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

Goes beyond the annotations by spelling out irreversibility and the mandatory two-step preview/confirmToken handshake — critical context an agent cannot get from destructiveHint alone. It stops short of naming required permissions or what the preview 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, front-loaded with the action and its irreversible consequence, then the procedural detail. No filler.

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

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

For a destructive write with no output schema, the description covers consequence, workflow, and confirmation. Minor gaps remain: what the preview shows, token expiry, and failure modes for an invalid or missing token.

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 67% and referralId has no schema description; the description compensates by explaining the confirm/confirmToken protocol and that the token originates from the preview call, which is the non-obvious coupling between the three 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?

States a specific verb and resource ('Void a referral') and the distinguishing effect ('future payments earn nothing'), which separates it cleanly from siblings like pause_referral, resume_referral, and approve_referral.

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

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

The permanence note implies this is a last-resort action, but the description never explicitly contrasts it with pause_referral or states preconditions (e.g., which referral states can be voided). Usage is inferable rather than stated.

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