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

Even though annotations already signal destructiveHint=true and idempotentHint=false, the description adds meaningful behavioral context: cancellation ends access, cannot be undone from here, and the tool refuses to run without confirm:true. It also warns against setting confirm merely to bypass a refusal, which is important ethical and operational guidance.

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 compact and front-loaded with the core purpose and irreversibility, then moves to the key alternative and confirmation constraint. Every sentence earns its place with no filler or redundant elaboration.

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

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

For a destructive mutation tool with no output schema, the description covers everything an agent needs to decide and invoke correctly: what it does, how it differs from the sibling, the irreversibility, and the confirmation gate. Required parameters are documented in the schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents account, confirm, and order_id. The description reinforces the confirm requirement but does not add new parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific action: permanently cancel a customer's subscription. It clearly distinguishes this from pause_subscription by emphasizing irreversibility and permanent loss of access. An agent can immediately understand what the tool does and how it differs from nearby 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?

It explicitly names pause_subscription as the right alternative when the customer might return, giving a concrete decision rule. It also clarifies the confirm:true requirement and instructs when that flag should be set, which is actionable guidance for correct invocation.

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 non-read-only and non-idempotent behavior, but the description adds meaningful context about the concrete consequences: duplicate records or rejection by ThriveCart. This goes beyond the binary flags and helps the agent understand the operational risk.

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, with the most important operational warning placed directly after the primary action. It earns every word and is easy to parse quickly.

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 creation tool with four flat parameters and full schema documentation, the description covers what the tool does, how to avoid misuse, and what risks exist. The only minor gap is that it doesn't describe the success response or how to verify the result, but this is not critical 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 schema already provides 100% description coverage for all parameters, including the note that email 'becomes their identity.' The description itself adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action — 'Register a new affiliate on a ThriveCart account' — which distinguishes it from sibling read/search tools like get_affiliate and search_affiliates. The verb 'register' plus the resource 'affiliate' makes the function's scope unambiguous.

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

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

It explicitly tells the agent to check with get_affiliate before creating, and explains why: creating an existing affiliate is not a no-op and may cause rejection or duplication. This gives direct, actionable guidance about when to use this tool versus the alternative.

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 read-only, idempotent, non-destructive behavior, so the description only needs to add context. It adds that the response includes referrals, commissions, and payout details, and that email is the sole identifier, which is useful beyond 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?

Two tight sentences: the first front-loads the verb, target, and outcome; the second provides essential domain context. No filler or redundant restatement of the 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 read-only single-record fetch, the description, combined with 100% schema coverage and safety annotations, gives an agent everything needed to call it correctly. It states what is returned and why email is required, with no output schema needing additional return-shape explanation.

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

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

Schema description coverage is 100%, so the schema fully documents both email and account. The description adds the identity rationale for email but no new syntax or parameter-level meaning, matching the baseline of 3 for complete 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?

The description begins with a specific verb and resource: "Get one affiliate's full record by email," and names the record contents (referrals, commissions, payout details). This clearly distinguishes it from siblings like search_affiliates and create_affiliate by making the retrieval scope 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 description establishes a clear usage context: this is the tool to use when you have an affiliate's email and want their complete record. It also states the identity model ('Email is the only way ThriveCart identifies an affiliate'), though it does not explicitly name alternatives such as search_affiliates for when the email is unknown.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about the return contents (offers and price), but does not disclose details like not-found behavior or possible null fields. This meets the minimum bar given the annotation coverage.

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 no filler: the first states what the tool returns, the second gives the fallback when the id is unknown. Every clause earns its place and the key information is front-loaded.

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

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

For a simple read-only get-by-id operation with strong annotations and fully documented parameters, this description is adequately complete. It tells the agent what data will be returned and how to obtain the required id. A more elaborate return contract would be nice but is not necessary for confident 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 the schema fully documents both parameters. The description reinforces that bump_id comes from list_bumps, which adds mild value, but it does not need to compensate for missing parameter information.

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

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

The description clearly states the specific action ('Get'), the resource ('one bump by id'), and the content ('full details... including what it offers and at what price'). This distinguishes it from list_bumps and get_bump_pricing, which are nearby 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?

It explicitly tells the agent to call list_bumps first if the id is not already known, which is practical usage guidance for the common prerequisite. It does not enumerate all sibling alternatives, but the single most relevant routing instruction is present.

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

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

Annotations already declare this read-only, idempotent, and non-destructive. The description adds useful behavioral nuance: the headline price is not necessarily what a buyer paid, and all configured price points are returned. This helps an agent interpret results correctly.

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

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

Two sentences with no filler, front-loading the purpose and following with an important interpretive caveat. Every phrase 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 single-required-parameter read tool with strong annotations and full schema coverage, the description is largely complete. The only meaningful omission is the absence of an explicit sibling comparison or output format, but neither is essential for invoking the tool 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?

Schema coverage is 100%, so both parameters are already well documented. The description adds no new parameter-level semantics beyond reinforcing that one bump is being queried, which is adequate given 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 uses a specific verb ('Get') and resource ('every price point configured on one bump'), making the tool's function unambiguous. It also implicitly distinguishes itself from get_bump by focusing on pricing rather than general bump data.

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 use case: read this before quoting what a buyer paid. It does not explicitly name when to use an alternative tool or exclude cases, so it falls just 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: email is the only customer identifier, there is no customer-listing endpoint, and the returned record contains purchases, subscriptions, and order ids.

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

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

Three sentences, each earning its place: the first defines the operation and result, the second connects the output to downstream tools, and the third gives routing guidance. No filler or redundancy.

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

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

For a simple read-only two-parameter tool with no output schema, the description fully explains what the caller gets back (purchases, subscriptions, order ids) and why it matters. It also covers the absence of a list-customers endpoint, which is essential context for an agent deciding how to use this 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?

Input schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics by stating that email is the only way ThriveCart identifies a customer, reinforcing why the email parameter is required and how it should be interpreted beyond the schema's "exactly as they bought with" phrasing.

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

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

The description opens with a specific verb and resource: "Get one customer's full record by email address," then enumerates the record contents (purchases, subscriptions, order ids). It is clearly distinguished from sibling tools like get_transactions by emphasizing that it retrieves a single customer by email.

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 explicitly states when to use an alternative: "there is no endpoint that lists customers, so use get_transactions when you need to see many at once." It also explains the tool's role as the source of order_ids for pause_subscription, resume_subscription, cancel_subscription, and refund_transaction, giving clear guidance on when this tool is required.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds that the response includes offers and price, which is content rather than behavior. No contradictions, but little added behavioral context beyond annotations.

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

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

The description is two sentences with no wasted words. The primary purpose is front-loaded, and the usage hint is a natural follow-up. Every element 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?

Given the tool complexity (simple get-by-id), the fully documented schema, and the absence of an output schema, the description provides sufficient context. It indicates the nature of the returned data (offers and price) and offers a practical usage tip. It does not mention edge cases or errors, but these are not critical for a read-only fetch.

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 downsell_id and account parameters are fully described in the schema. The description adds no extra parameter semantics beyond referencing the id via 'by id'. This meets the baseline for high coverage but offers no additional 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 clearly states the action (Get), the resource (a downsell), and the specific details returned (offers and price). It distinguishes itself from list_downsells (which lists all) and implies a contrast with get_downsell_pricing by mentioning price in the full details. This is unambiguous.

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

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

The description explicitly instructs to use list_downsells first if the id is unknown, which is a clear when-to-use guideline. However, it does not explicitly mention when to use get_downsell_pricing instead or how this differs from that sibling, so there is a minor gap in routing between alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds the behavioral nuance that the headline price is not necessarily what a buyer paid, which is critical context beyond annotations. No contradictions exist.

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

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

Two sentences with no fluff: the first states the purpose, the second provides the key caveat. Both are front-loaded, making it efficient and easy to scan.

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 getter with full schema coverage and comprehensive annotations, the only missing piece is the return format, which is not always necessary. The description is sufficient for an agent to call it correctly and understand its relevance.

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 covers both parameters with descriptions (downsell_id and account), and the description adds nothing beyond that. It doesn't elaborate on parameter meaning or format, so it sits at the baseline for high 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 it retrieves every price point configured on one downsell, and clarifies that the headline price may not reflect actual paid cost. This distinguishes it from simply getting downsell details and any sibling pricing tools, making its purpose unambiguous.

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

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

Explicitly instructs the user to read this before quoting costs, giving a clear when-to-use context. It doesn't explicitly list alternatives, but the phrase 'read this before quoting what it costs' implies it should be used when accurate pricing is needed, providing adequate 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 and idempotentHint, so the safety profile is covered. The description adds that this fetches full details for a single product, but does not describe edge cases or response behavior beyond that.

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 no filler. The core action is front-loaded and the usage note is immediately actionable.

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 single-resource read with strong annotations and full schema coverage, this is nearly complete. The only slight gap is that 'full details' does not specify which fields are returned, though no output schema exists to provide that.

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 schema already documents both parameters with 100% coverage, including the source of product_id. The description adds little semantic value beyond restating 'by id' and referencing list_products.

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

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

The description uses a specific verb ('Get'), names the resource ('one product'), and identifies the key input ('by id'). It also positions itself against list_products, so an agent can distinguish it from sibling listing 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?

It explicitly tells the agent to use list_products first when the id is missing, which is the relevant alternative and prerequisite. This is direct when-to-use 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful domain context about covering all price point types, but it does not disclose behavioral details such as return shape, pagination, or what happens when a product has no configured price points.

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, both purposeful: the first defines the tool's scope and the second gives the practical rationale for using it. No filler or redundant restatement of the title or schema.

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

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

For a read-only, idempotent tool with only two documented parameters, this is nearly complete. With no output schema, an agent might still want a hint about the response structure, but the description's scope statement and annotations make invocation safe and unambiguous.

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

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

Schema description coverage is 100%, so the schema already documents product_id and account. The description adds meaning around what the tool returns (one-time, split pay, subscription prices) and why it matters, but it does not add syntax or parameter-format details 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 names a specific resource (product pricing) and a precise verb (get), and expands the scope to 'every price point configured on a product: one-time, split pay and subscription.' It distinguishes itself from the simpler get_product by explicitly stating the headline price is not the only thing customers can pay.

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 an explicit use trigger: 'read this before quoting what something costs.' It does not explicitly name alternatives like get_product or get_bump_pricing, but the sibling context and the focus on a product's full pricing structure make the intended usage 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, idempotentHint, and destructiveHint=false, but the description adds valuable behavior beyond that: it walks every page (pagination), is the expensive call (performance cost), sums in integer cents (exact precision), and covers only one cart (scoping). No contradiction with 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?

Three sentences with zero waste: the first states the purpose, the second warns about cost and optimal usage, the third covers precision and multi-account caution. Every sentence contributes unique value and is front-loaded.

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

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

There is no output schema, so the description fully carries the burden of explaining the return: revenue grouped by product, sorted highest first, exact in cents. It also addresses the expensive pagination behavior and per-account scoping, making it complete for an agent to call 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 input schema documents all three parameters (account, date_from, date_to) with 100% coverage, so the baseline is 3. The description reinforces the date-range usage and single-account scoping but does not add new syntax or formatting details beyond what the schema already provides.

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

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

The description states exactly what the tool does: revenue for a date range, grouped by product and sorted highest first, for a single ThriveCart account. It clearly distinguishes this from sibling tools like get_transactions (transaction list) and list_products (product catalog) without ambiguity.

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

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

Explicitly tells agents to supply a date range rather than requesting all time, because it walks every page and is the expensive call. Also instructs running per account and never adding results together, providing clear when-to-use and when-not-to-use 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?

Beyond the readOnly/idempotent annotations, the description discloses a real API quirk (product_id silently returns rows for other products), defines matching semantics as case-insensitive contains on item_name, and explains fetch_all pagination behavior. No contradiction with 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?

Three dense sentences with no filler. The first sentence states the core purpose, and the following sentences provide high-value caveats and usage constraints without redundancy.

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

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

For a read-only retrieval tool with no required parameters and full parameter documentation, the description covers the important edge cases: filter reliability and fetch_all behavior. The lack of an output schema is acceptable because the returned resource is unambiguously transactions and the description provides enough 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?

Input schema already documents all 8 parameters with 100% coverage, so baseline is 3. The description adds semantic value by warning against ThriveCart's product_id filter and steering the agent to item_name as the reliable filter, which is not captured in any schema field.

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 operation and resource: 'Get transactions from a ThriveCart account', and names the filtering dimensions. The verb-resource pair clearly differentiates it from sibling list/get tools even without explicit exclusions.

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

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

Gives concrete usage guidance: 'Set fetch_all only when you need complete figures; it walks every page' and instructs using item_name because product_id is unreliable. It does not name sibling alternatives explicitly, but the context and API warnings are clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what details are returned (offers and price), which is a behavioral detail beyond a generic 'get'. It does not mention side effects or additional constraints, but that is acceptable given the read-only, idempotent nature.

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 sentences with no redundancy. The primary purpose is front-loaded, and the usage hint is concise. Every word 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 simple get-by-id tool with fully documented parameters and annotations covering safety, the description is largely sufficient. It mentions the return scope (full details, offers, price) and the prerequisite to obtain the id. It does not describe the exact response structure, but with no output schema and a straightforward fetch, this is 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 coverage is 100%, with both parameters fully described in the schema (account mentions list_accounts, upsell_id references list_upsells). The description repeats the id source but adds no new semantic nuance over the schema. Therefore the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'upsell', and specifies it returns 'full details' including 'what it offers and at what price'. It also distinguishes from list_upsells by implying single-item retrieval by id, and it names that sibling directly, so an agent can disambiguate.

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 explicit guidance to use list_upsells first when the id is unknown, which clearly establishes when to use this tool versus an alternative. It does not cover other potential alternatives (like get_upsell_pricing) or when not to use this tool, but the primary routing is addressed.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a behavioral nuance beyond annotations: the headline price is not necessarily what a buyer paid, which is critical for interpreting the returned data. This adds value and does not contradict any 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?

The description is two concise sentences with zero waste. The core purpose is front-loaded immediately, and the caveat is placed second, providing essential context without clutter. Every word 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 read-only tool with two parameters and no output schema, the description is sufficiently complete. It covers the tool's purpose and the critical caveat about actual cost. The origin of upsell_id is documented in the schema description, and annotations cover safety. There is no missing information that would prevent an agent from calling 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?

Schema description coverage is 100% – both account and upsell_id have detailed descriptions in the schema. The tool description does not add any additional parameter information, which is acceptable given the schema's completeness. The description implicitly relies on the schema for parameter details, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get every price point configured on one upsell.' It clearly distinguishes this from sibling tools like get_upsell (which presumably returns upsell details) and other pricing tools (get_bump_pricing, get_downsell_pricing) by focusing on upsell price points. The added caveat about headline price vs. actual paid further clarifies its unique purpose.

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 implicit usage guidance: 'read this before quoting what it costs.' This implies it should be used when accurate cost information is needed. However, it does not explicitly mention alternatives or when not to use it, such as pointing out that get_upsell is for other upsell details or that get_product_pricing is for products. The guidance is clear for its intended use case but lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context beyond those: 'Costs no network call' and the important fact that revenue, customers, and affiliates are entirely separate per cart. This helps the agent reason about multi-cart semantics.

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 tight, front-loads the core purpose, and every sentence carries distinct operational value: what it lists, how to use results, performance, and data isolation. There is no redundant 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 zero-input, low-complexity list tool, the description fully covers when to call it, what it returns at a practical level, and why that matters. The lack of an output schema is compensated by the clear 'returned name' wording and the explanation of cart separation.

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 and schema coverage is 100%, so there is nothing for the description to add about input parameters. It productively clarifies how the output should be used as the `account` argument elsewhere.

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: 'List every ThriveCart account configured on this server.' It is clearly distinct from sibling tools, which operate on products, customers, transactions, and affiliates rather than on server-level accounts.

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 explicit when-to-use guidance: 'Call this first whenever a request could plausibly mean more than one cart.' It also tells the agent how to use the result: pass a returned name as the `account` argument on other tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds contextual detail about what a bump is and that the listing spans all products on the account, but it does not disclose other behavioral traits such as result ordering, pagination, or whether deleted bumps are included. This is adequate but not rich.

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

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

Three sentences, each earning its place: the first states the operation, the second defines the domain concept, and the third explains practical use. The most important content is front-loaded, with no filler or redundancy.

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

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

For a simple list operation with one documented optional parameter and strong annotations, the description is nearly complete. It explains the purpose, the domain object, and the connection to get_bump via the id. The lack of an output schema is mitigated by the clear statement that the tool returns bumps with ids, though it does not specify other returned fields.

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 input schema has 100% description coverage for the single optional 'account' parameter, so the schema already documents its meaning and default behavior. The description does not add new parameter detail, keeping the score at the 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?

The description opens with 'List every bump across all products on a ThriveCart account', which is a specific verb, resource, and scope. It also defines what a bump is ('checkbox add-on shown on the checkout page itself'), clearly distinguishing it from main products and from other list 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?

The description explicitly states when to use it: 'Use this to see what a cart offers beyond its main products, and to get an id for get_bump.' It gives a concrete purpose and points to the follow-up tool, though it does not explicitly discuss when not to use it or contrast it with list_upsells/list_downsells.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by the framework. The description contributes the account-wide scope and the downsell definition, but adds no detail about response shape or edge cases.

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 crisp sentences front-load the action and scope, then define the domain term and state practical uses. There is no repetition of schema or annotations and no unnecessary 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 one-optional-parameter read-only list tool with strong annotations, the description provides enough context to call it correctly. It could be slightly more explicit about what the returned list contains, but the stated goal of getting an id for get_downsell compensates.

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 account parameter is fully documented in the schema (default behavior, list_accounts, account isolation), so the description does not need to add parameter detail. The description's mention of 'a ThriveCart account' aligns with the schema but adds no new parameter semantics.

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

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

The description names a specific action ('List every downsell') and resource ('across all products on a ThriveCart account'), and defines downsell as the fallback offer after an upsell is declined. This clearly distinguishes it from siblings like list_upsells and list_products.

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 explicitly says to use this to explore offers beyond main products and to obtain an id for get_downsell. It does not explicitly contrast with list_upsells or list_bumps, but the use cases are clear enough for selection.

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, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds scoping context by emphasizing 'every product' and the fact that ids and names are returned, which is useful beyond the annotations, but it does not disclose additional behavioral traits such as pagination or ordering.

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 sentences with no filler. The first sentence states the core function and output fields; the second sentence gives practical usage guidance. Every word contributes value.

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 listing tool with no output schema, the description plus the fully documented parameter and rich annotations provide everything an agent needs to select and invoke it correctly. The return shape is stated ('ids and names'), and the account scoping is covered by the schema.

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

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

Schema description coverage is 100%: the single 'account' parameter is fully documented in the input schema, including its default behavior and relationship to list_accounts. The tool description adds no parameter-specific meaning, so the baseline of 3 applies because the schema carries the explanatory burden.

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

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

The description uses a specific verb and resource: 'List every product on a ThriveCart account, with ids and names.' It clearly distinguishes this from sibling list tools like list_bumps, list_upsells, and list_downsells by focusing on products, and the 'Start here when you need a product id' phrasing reinforces its entry-point role.

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 provides clear context for when to use the tool: 'Start here when you need a product id for another tool, or to see what a cart actually sells.' It does not explicitly name an alternative to avoid or state when not to use it, so it stops short of a 5, but the guidance is unambiguous.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond these: it emphasizes 'every upsell across all products' (global scope) and defines what an upsell is. No contradictions detected, and the added scope helps an agent understand what the call returns.

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

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

Three compact sentences: the first states the action, the second defines the term, and the third gives concrete use cases. No extraneous information; every sentence 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 simple list tool with one optional parameter, no output schema, and read-only annotations, the description covers purpose, scope, and follow-up usage. The only minor gap is the absence of return structure details, but those are less critical given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema already documents the account parameter with example, default, and pointer to list_accounts. The description does not add parameter-level meaning, which aligns with the 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?

The description states a specific verb and resource: 'List every upsell across all products on a ThriveCart account.' It also distinguishes upsells from main products and related offer types by defining them as the offer shown after purchase completes, making sibling differentiation clear.

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?

Provides clear when-to-use context: to see what a cart offers beyond its main products and to obtain an id for get_upsell. It does not explicitly mention alternatives such as list_bumps or list_downsells or state when not to use this tool, 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavioral context beyond those annotations: the operation is reversible, it stops future billing, and it deliberately requires no confirmation because of that reversibility.

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

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

The description is three short sentences with no filler. The primary action and effect are front-loaded, followed immediately by the reversibility and guidance on when to prefer this tool. Every sentence 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 simple, reversible mutation with a fully documented schema and safety-related annotations, the description provides all necessary context: what it does, what it does not do, how to reverse it, and when to choose it over its main alternative. No critical information 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 both parameters (account and order_id) are already well documented in the schema. The description adds no additional parameter-level meaning, so the schema carries the full burden and the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Pause') and resource ('a customer's subscription'), and explains the core behavior: 'stopping future billing while keeping the subscription itself.' It also distinguishes the tool from its siblings by positioning it against cancel_subscription and resume_subscription.

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 explicitly states when to prefer this tool: 'Prefer this over cancel_subscription whenever the customer might come back.' It also names resume_subscription as the reversal path, giving the agent clear guidance on both alternatives.

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

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

Annotations already mark destructiveHint=true, but the description adds concrete behavioral context: 'moves real funds', 'cannot be undone', and 'refuses to run without confirm: true'. This is valuable safety-critical disclosure beyond the structured hints.

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

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

Three sentences with no filler: purpose, consequence, and prerequisites are each addressed in order. The most decision-critical information (irreversibility, confirm requirement) is front-loaded.

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

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

For a destructive, irreversible mutation with no output schema, the description covers purpose, effect, guardrails, prerequisites, and a pre-call verification step. An agent has everything needed to invoke this tool correctly and safely.

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

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

Schema coverage is 100% with solid parameter descriptions. The description adds meaningful semantic guidance by warning that order_id alone does not convey the refund amount, reinforcing why pre-checking is necessary. This enriches the understanding of order_id 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?

States a specific verb and resource: 'Refund a transaction, returning the money to the customer.' It is clearly differentiated from siblings like pause_subscription and cancel_subscription by naming the refund action and its financial effect.

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?

Provides clear context: the operation is irreversible, requires confirm: true, and the agent should check the amount via get_transactions or get_customer before calling. It does not explicitly name excluded alternatives, but this is a singular refund operation among the siblings, so the guidance is sufficient.

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 signal readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description does not need to restate those. It adds useful context: billing restarts and cancelled subscriptions cannot be revived. However, it does not mention potential side effects like proration, payment failures, or whether resuming an already-active subscription is a no-op, though the idempotent hint partially covers that.

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

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

Three short sentences, each earning its place: the action, the relationship to a sibling tool, and an important limitation. The primary purpose is front-loaded and there is no fluff.

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 tool with complete schema coverage and informative annotations, the description sufficiently covers purpose, usage boundaries, and key behavioral constraints. No critical missing context prevents an agent from selecting or invoking this tool 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 input schema already describes both parameters with 100% coverage, including their sources and defaults. The tool description adds no parameter-level meaning, so the baseline score of 3 is appropriate; schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Resume a paused subscription, restarting billing.' It also differentiates itself from siblings by explicitly naming itself as the counterpart to pause_subscription and clarifying it is not for cancelled subscriptions.

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 clearly says when to use the tool (for paused subscriptions) and when not to use it (for cancelled subscriptions, which cannot be revived). It also names the related sibling pause_subscription, providing an explicit alternative and 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral context beyond annotations by disclosing pagination ('one page at a time') and the limited scope of the data ('browsing and counting'), which helps set expectations.

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

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

Three short sentences, front-loaded with the core action and scope, then key usage guidance. Every sentence earns its place and there is no filler or repetition of schema details.

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 optional parameters and a clear alternative for detailed data, this description is complete. The annotations cover the safety profile and the description covers purpose, pagination, and when to prefer get_affiliate.

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

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

Schema description coverage is 100%, so the schema already fully documents page, account, and per_page. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List affiliates on a ThriveCart account, one page at a time.' It clearly distinguishes itself from get_affiliate by noting that get_affiliate provides one affiliate's full stats, while this listing is for browsing and counting.

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 explicitly tells the agent when to use this tool versus an alternative: 'Use get_affiliate for one affiliate's full stats. This listing is for browsing and counting.' This gives clear selection guidance and excludes the primary sibling use case.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds meaningful behavioral context by explaining the tool is a diagnostic identity check bound to the API key, and that it returns owner email plus account details. It stops short of describing exact response structure or error behavior, but that is minor given the simple scope and strong annotations.

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

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

The description is two compact sentences with no filler. The first sentence states the action and returned data; the second gives concrete use cases. All information is front-loaded and 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?

This is a simple read-only identity tool with one optional parameter, thorough schema documentation, and safety hints supplied by annotations. The description explains what it returns and why to call it, so an agent has everything needed 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?

Schema description coverage is 100%, and the single optional 'account' parameter already has a thorough description including default behavior, an example value, and a pointer to list_accounts. The tool description does not add parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb ('Fetch') and resource ('the ThriveCart account this key belongs to'), so an agent immediately knows the tool returns identity/account context for the configured key. It also clearly differentiates from sibling listing tools like list_accounts and list_products by tying the result to the active key and using 'whoami' semantics.

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 explicitly states when to use the tool: confirm a configured account name points at the intended cart before reporting money, and verify a key still works. This gives clear operational context without needing an alternative tool, since whoami is the natural identity-check tool.

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