GotCashback

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: returns up to 5 matching brands, best match first, empty when nothing matched, rates refreshed several times a day, and specific URL fields that should always be surfaced to the user. There is no contradiction with the annotations.

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

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

The description is organized and front-loaded: the core purpose comes first, followed by usage examples, sibling alternatives, return behavior, data freshness, and display requirements. Every sentence earns its place, and 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?

The description covers matching behavior, result cap and ordering, empty-result handling, data freshness, and required link presentation. With an output schema present and annotations conveying the read-only safety profile, nothing essential is missing for an agent to call 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?

Schema description coverage is 100%, and the schema already provides detailed semantics for both parameters, including case-insensitive substring matching and ISO country code rules such as 'gb' not 'uk'. The tool description itself mostly reinforces usage context rather than adding meaning 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 opens with a precise statement of what the tool does: it finds where to buy a brand's products with the most savings, returning matching brands and stores ranked by cashback rate and gift card discount. It also explicitly contrasts itself with related tools, so an agent can distinguish it from get_cashback_rates_by_store_name and get_best_deals_by_category.

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 concrete when-to-use guidance: use when the user names a product brand rather than a retailer, and provides example queries. It explicitly names the sibling tools to call instead for retailer or product-category intents, and explains when to pass country_code versus omit 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context: ranking by cashback rate then gift card discount, up to 5 matching categories, empty results behavior, data freshness, and a required instruction to surface store links. 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?

The description is front-loaded with the core purpose and ranking behavior, then moves through usage guidance, alternatives, output limits, data freshness, and required user-facing links. Every sentence adds value and 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?

Given the two-parameter schema, output schema, and read-only annotations, the description is complete: it explains matching, ordering, result limits, empty results, data freshness, and how links should be presented. An agent has everything needed to select and invoke 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?

The input schema already covers both parameters thoroughly, with 100% description coverage. The description adds useful semantic context by giving example category values like 'dog food' and 'electronics' and by clarifying that this tool is for category-style queries rather than store or brand queries.

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: 'Finds where to buy products from a shopping category with the most savings' and explains the ranking logic. It clearly distinguishes this tool from siblings by naming get_cashback_rates_by_store_name and get_best_deals_by_brand as the 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?

It explicitly says to use this tool when the user names a product type or category rather than a store or brand, with concrete example queries. It also gives explicit when-not-to-use guidance: use get_cashback_rates_by_store_name for a specific retailer and get_best_deals_by_brand for a brand.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond annotations: it returns an error for nonexistent ids, rates are refreshed several times a day, and every portal's rate must be presented with clickable url links because cashback only credits on click-through. 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?

The description is front-loaded with the core purpose, and every subsequent sentence adds necessary operational or selection detail. Although longer than minimal descriptions, the extra length is justified by the crucial display/click-through requirement and sibling routing guidance.

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?

The tool is simple (one parameter) and has both output schema and annotations, so the description does not need to restate return structures. It covers selection context, error behavior, data freshness, and required presentation behavior, making it complete for correct agent 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 coverage is 100%, so the schema already fully documents store_id. The description adds practical meaning by reinforcing that the id must be numeric, must come from an earlier result, and that a store-name input should route to the by-name sibling instead.

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 ('Returns'), resource ('cashback rates from every cashback portal for one store'), and scope ('one store identified by its numeric store_id'). It also explicitly distinguishes this tool from get_cashback_rates_by_store_name, making the 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?

The description gives clear when-to-use guidance: only when a store_id is already known from an earlier result. It also states the exclusion condition and alternative directly: when the user gives a store name, call get_cashback_rates_by_store_name and do not look the id up first.

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

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

Annotations already mark read-only/idempotent/non-destructive, so the description adds non-safety behavior: best-match ordering, one entry per country, empty-list meaning and retry guidance, data refresh cadence, and the click-through requirement for cashback credit. This materially changes how an agent should present and follow up on results.

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 opening sentence carries the core contract and every later paragraph addresses a distinct concern (when to call, sibling routing, result interpretation, presentation). It is long, but the example query list and presentation rules earn their place; slight trimming of redundant sibling routing would tighten it.

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?

Combined with a rich output schema and annotations, the description covers matching, scoping, empty results, retry behavior, refresh timing, and output presentation expectations. There are no obvious gaps for an agent to invoke this tool and interpret its response 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?

Input schema already has 100% description coverage for store_name and country_code, so the description only lightly reinforces matching semantics and retry advice; it adds no syntax or 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?

Opens with a distinct verb+object ('Finds a store by name and returns its current cashback rates') and precisely delimits coverage (every portal, online/in-store, percentage/fixed, up-to flags), which separates it from store lookup, gift card, and best-deal 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?

Explicitly declares itself the preferred first call and gives positive examples, then lists exclusions: don't call get_stores_by_name/get_stores_by_country/get_countries first; use get_cashback_rates_by_store_id only with known store_id; use gift-card and brand-deal siblings for other intents.

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, destructiveHint=false and openWorldHint=false, covering the safety profile, so the bar is lower. The description adds genuine context beyond that: the exact output format, the UK exception example, and the cross-tool contract that the returned 'code' feeds into other tools' country_code parameter. It doesn't disclose minor details like sort order or list exhaustiveness, but for a 0-param reference list these are low-stakes.

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 waste: the first front-loads the core purpose and key format detail with an example; the second delivers usage exclusions with rationale. 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?

With 0 params, a present output schema, and safety covered by annotations, the description covers everything an agent needs to call this tool correctly: what it returns, in what format, when to use it, and why it is not a required prerequisite for sibling lookups. Nothing material is missing for a simple read-only reference 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?

The tool has 0 parameters, so the baseline is 4 per the rubric. The description adds adjacent value by explaining that the return value's 'code' field is precisely what must be passed as country_code to sibling tools, effectively documenting the parameter contract of the entire tool family.

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 — 'Returns the countries GotCashback covers' — and goes further by specifying the output format (lowercase ISO 3166-1 alpha-2) with a concrete example ('gb' for the United Kingdom). It differentiates from its 17 siblings by positioning itself as a reference lookup for country_code rather than a deals/cashback/stores tool.

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

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

Explicitly states when to use it ('only to confirm whether a country is supported or which code to use') and when not to ('not needed before store, cashback or gift card lookups'), with the reason that those tools accept country_code directly and search all countries when omitted. This is a model of when/when-not guidance, with the alternative behavior clearly described.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral details beyond annotations: empty list behavior when no discounted cards exist, error behavior for a nonexistent id, multiple-seller comparison purpose, and the requirement to always show the tracked url as a clickable link. These are precisely the non-obvious behaviors an agent needs to invoke and present 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?

The description is front-loaded with the core result, then covers usage conditions, edge cases, and output presentation in a compact set of sentences. Every sentence carries distinct information: result type, comparison purpose, when to use, when not to use, empty/error behavior, and required presentational format. No filler or redundancy weakens it.

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?

The tool is simple with one parameter, strong annotations, and a rich output schema, so the description does not need to restate return types. It covers the selection condition, the alternative tool, edge-case behavior, and user-facing presentation requirements. This is fully sufficient for correct invocation and result handling.

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 parameter description in the schema already explains that store_id is GotCashback's numeric id from an earlier result and directs name-only cases to the by-name tool. The tool description adds little parameter meaning beyond echoing 'numeric store_id' and the known-id condition, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns discounted gift cards for one store by numeric store_id and emphasizes comparison across multiple sellers. It distinguishes itself from the sibling get_gift_cards_by_store_name by explicitly naming the ID-based vs name-based route, so an agent can disambiguate 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 description gives explicit when-to-use guidance: only when a store_id is already known from an earlier result. It also explicitly directs the agent to call get_gift_cards_by_store_name when only a store name is available and tells it not to look up the id first, which prevents a costly mistake. Additional presentation instructions add further practical 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 mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: multiple matching stores are returned best-match-first with one entry per country, an empty gift_cards list means no current discounts, and the returned url is a tracked purchase link. This gives the agent important runtime behavior without contradicting 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 front-loaded with the core purpose, then flows naturally into usage examples, output behavior, alternative tools, and user-presentation instructions. Every sentence carries actionable information with no redundant filler or restatement of the title.

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

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

For a tool with two parameters, one required, the description is complete: it explains what triggers this tool, how results are ordered and structured, what an empty list means, which sibling to use instead, and exactly how the agent should present results to the user. The presence of an output schema means the return-shape details are already covered elsewhere.

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 store_name and country_code including matching semantics, examples, and ISO format notes. The main description adds no substantial parameter-level meaning beyond reinforcing that the lookup is by store name, 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 verb ('Finds a store by name'), the resource ('discounted gift cards'), and the exact output fields (face value, price, discount percent, digital or physical). It explicitly differentiates from the sibling get_gift_cards_by_store_id and get_cashback_rates_by_store_name, so an agent can identify this tool immediately.

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 when-to-use guidance: 'preferred first call for any gift card question that names a store', includes concrete example queries, and states 'No prior lookup is needed.' It also names the precise alternatives: use get_gift_cards_by_store_id when a store_id is already known, and get_cashback_rates_by_store_name for cashback questions.

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 readOnly, idempotent, and non-destructive; the description adds valuable context by requiring OAuth sign-in with GotCashback and the 'alerts' scope, and warns that anonymous callers are prompted to authorize. It also discloses the returned fields, which is useful since there is no output schema.

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

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

Two sentences: the first states the function and returned data, the second gives usage contexts and auth requirements. Information is front-loaded and every sentence carries essential information.

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

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

For a zero-parameter, read-only tool, the description covers what data comes back, when to use it, and the auth requirement. With no output schema and no params, nothing an agent needs to invoke it correctly is missing.

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

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

The input schema has zero parameters and 100% description coverage, so there is nothing to explain. The description correctly focuses on the semantics of the resource being fetched rather than 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 the tool returns "signed-in user's cashback and gift card alerts" with specific fields (store, type, threshold percent, last notification). The verb 'Returns' and the focus on alerts clearly differentiate it from sibling tools like get_my_favorite_stores or set_store_alert.

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 explicit usage scenarios — 'what alerts do I have?' and 'before changing an alert' — which implies viewing current state prior to set/remove operations. It also notes the OAuth prerequisite for authorization. However, it does not name alternative tools directly or state 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 cover read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: it requires OAuth sign-in and specifies that anonymous callers are prompted to authorize. This is a behavioral trait not conveyed by the 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?

The description is generally tight and front-loaded with purpose, then usage, then auth. The final 'Scope: "favorites"' line is somewhat redundant with the first sentence, and the auth/alternative sentences could be tightened, but overall every sentence contributes meaningful routing or selection information.

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

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

With no output schema, the description correctly states what is returned (favorite stores with store_id), covers auth requirements, and explains when to use it. It could be slightly more complete by describing the exact response shape or error cases, but for a parameterless, read-only favorites list the essential context 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?

The tool has zero parameters, so the baseline for this dimension is 4. The description does not need to explain parameters, and it avoids any redundant parameter talk. It does reveal that store_id is part of the return value, which indirectly supports downstream parameter usage.

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-resource pair: 'Returns the signed-in user's favorite stores (with their store_id)', and scopes it to 'favorites'. It distinguishes this from sibling tools like get_my_alerts and get_my_profile by making the resource (favorite stores) and user 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?

Provides an explicit trigger condition: 'Use it when the user asks about "my favorites" or "my saved stores"'. It also contrasts against comparison tools by stating they work without signing in, giving an implicit when-not-to-use and pointing to the appropriate 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 mark the operation read-only and idempotent, and the description adds genuinely useful behavioral context: OAuth sign-in is required, anonymous callers face an authorization prompt, and the OAuth scope is 'profile'. It does not cover error responses, but for a simple zero-parameter read call this is sufficient.

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?

Thtree sentenses delivver eveery sentense earns its place: what it returns, when to use it, and what auth is needed. The description is front-loaded with the core behavior and avoids redundancy with the annotations.

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 tool with no output schema, the description is complete: it states the return fields, the exact use case, the auth requirement, the anonymous-caller behavior, and the scope. An agent has everything needed to select and 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?

There are no parameters, so the baseline is 4. The description adds no parameter-specific meaning because there are no parameters to document, and the input schema is already complete.

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: 'Returns the signed-in user's GotCashback profile' and lists the returned fields (name, email, avatar). This clearly distinguishes it from sibling get_my_alerts and get_my_favorite_stores, while the OAuth and scope details reinforce what the tool is for.

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: when the user asks who they are signed in as or wants account details. It also gives useful context that anonymous callers are prompted to authorize and that comparison tools do not require sign-in, though it does not name specific alternative sibling 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/idempotentHint/destructiveHint, so the bar is lower, but the description adds substantial behavioral context beyond them: it returns an error for non-existent ids, documents null semantics ('null when none', 'null when not published', '0 means no minimum'), and exposes the critical caveat that the sign-up bonus is only credited when the user signs up through the provided url. This is exactly the kind of non-obvious behavior an agent needs to know.

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 long but dense with value: selection rule, error behavior, field semantics, and a usage caveat each earn their place, with the core purpose front-loaded. It loses a point for minor redundancy — 'with its payout terms for that country' appears twice — but is otherwise well-structured for its richness.

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

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

For a single-parameter lookup tool with an output schema, this is complete: the description covers when to use it, how to source the id, error behavior, field-by-field semantics for the result, and the special display rule for sign-up bonus urls. Nothing an agent needs to call it correctly and use its results is left unstated.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already explains portal_id as 'GotCashback's numeric portal id, taken from the 'id' field of an earlier get_portals or get_portals_by_name result.' The description repeats this same sourcing guidance, adding no incremental meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Returns one cashback portal by its numeric id... with its payout terms for that country.' It adds the key distinguishing constraint (lookup by id) and explicitly differentiates from the sibling get_portals_by_name, so an agent can tell them apart without opening schemas.

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 an explicit when and when-not: 'Use it only when the id is already known; when the user names a portal, call get_portals_by_name instead.' It also discloses the error case for non-existent ids and tells the agent how to use the returned fields to answer user questions, which is clear selection and invocation 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds substantial context beyond it: country-scoped payout terms, the null vs 0 semantics of minimum_payout (null = not published, 0 = no minimum), and the attribution rule that sign_up_bonus.url must be rendered as a clickable link because the bonus only credits through it. No contradiction with annotations — 'Returns' is consistent with readOnlyHint=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?

The definition is long (~200 words) but front-loaded: purpose in sentence one, usage and exclusions in sentences two and three, then field semantics and presentation rules. Every section earns its place, though there is minor redundancy between the two usage sentences ('Use it to...' and 'Use these to answer...'), which keeps it from a perfect score.

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

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

For a tool with one optional parameter, a fully documented input schema, an output schema, and safety annotations, the description covers everything else an agent needs: sibling routing, per-field semantics including edge cases, and the clickable-link presentation requirement. Nothing required to select and invoke it correctly is missing.

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

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

Schema coverage is 100%: country_code is fully documented with format, examples, passthrough guidance, and omission semantics. The description adds only marginal context (results are country-scoped, payout terms are per-country), which does not materially improve parameter understanding, so the baseline 3 applies.

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

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

The first sentence names a specific verb ('Returns') and resource ('the cashback portals GotCashback compares') with an explicit optional country scope. It also differentiates from siblings inline: 'It does not return store rates' routes to get_cashback_rates_by_store_name, and 'for one named portal use get_portals_by_name', so an agent can distinguish it without opening other definitions.

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 concrete query triggers ('which cashback portals are there in Canada?') and comparison use cases (payout speed, minimum payout, PayPal, sign-up bonus). It states explicit exclusions with named alternatives for store-rate lookups and single-portal lookups, so when-to-use and when-not-to-use are both fully specified.

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 the tool read-only, idempotent, and nondestructive. The description adds useful behavioral context beyond that: one entry per country, whether sign-up bonus exists (null), minimum_payout semantics, and the crucial fact that the bonus URL must be shown as a clickable link because the bonus is only credited through it.

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 main action, use cases, and the key alternative in the first three sentences. It becomes repetitive later ('Use these to answer...' restates the same fields) and spends several sentences re-explaining values that an output schema would already define, so it is not maximally concise.

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 read-only annotations, complete input schema, and output schema, the description supplies the missing context an agent needs: when to call it, which sibling to call instead, per-country result behavior, and output-presentation instructions like linking the sign-up bonus URL.

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 both parameters already have rich descriptions (case-insensitive substring matching, country code formatting, 'gb' not 'uk'). The tool description reinforces use cases but does not add substantive parameter semantics 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?

Opens with a specific verb and resource: 'Searches cashback portals by name... returns each match with its payout terms, one entry per country.' It also contrasts with get_cashback_rates_by_store_name, so an agent can separate portal-level terms from store-level cashback rates.

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 states when to use: 'Use it when the user asks about a named portal: its sign-up bonus, minimum payout, how often it pays, or which payout methods it offers.' It also gives the exclusion: for a store's cashback rate, call get_cashback_rates_by_store_name instead.

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, so no contradiction exists. The description adds useful behavioral context beyond annotations: the result can include hundreds of stores, only current cashback-offer stores are included, and gift-card presence is indicated via specific fields with no rates returned. This goes beyond what annotations alone convey.

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 front-loaded with the core purpose and then provides usage guidance, exclusions, and presentation instructions. It is longer than minimal but each sentence carries information; the final formatting instruction is useful even if slightly beyond selection/invocation 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?

Given the rich input schema, an output schema, and annotations, the description covers scope, limitations, alternatives, country-code handling, and output presentation. There are no significant gaps that would prevent an agent from 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 fully documents country_code with format, examples, and a pointer to get_countries, so high schema coverage gives a baseline of 3. The description reinforces that a single country is used but does not add substantially new parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Lists') and resource ('every store that currently has cashback offers in one country'), and immediately clarifies what is excluded ('but no rates'). It also distinguishes itself from rate- and gift-card-focused siblings by naming them as alternatives. An agent can tell exactly what this tool does and does not return.

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 scenarios with example queries and explicitly warns against using it to find a particular store or its rates, naming the correct sibling tools instead. It also routes the agent to get_countries for supported codes. This is complete usage guidance with both positive and negative selection criteria.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description goes beyond that by disclosing that results are identity-only, sorted best match first, and empty when nothing matches. It also adds presentation guidance for the returned URLs. No contradiction with annotations 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?

Although long, the description is dense and well-ordered: scope, trigger conditions, exclusions, ordering, empty behavior, and presentation guidance each get exactly one sentence. Every sentence earns its place and the core output boundary 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?

With an output schema present, complete parameter descriptions, and safety annotations, the description still covers use cases, alternatives, result ordering, empty behavior, and presentation instructions, so an agent has enough to select and invoke it correctly. The only minor wrinkle is mentioning 'gift_cards_url' after saying gift cards are excluded, which is slightly ambiguous even though it likely refers to a store page URL.

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 documents both parameters thoroughly at 100% coverage, including examples, lowercase country-code format, and the 'gb, not uk' guidance. The top-level description does not need to add parameter mechanics, so the baseline of 3 applies.

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

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

The description names a concrete verb and resource ('Searches stores by name') and then sharply bounds the result set to identity fields only, explicitly excluding cashback rates and gift cards. This makes it immediately distinguishable from siblings such as get_cashback_rates_by_store_name and get_gift_cards_by_store_name.

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

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

It lists concrete trigger conditions: checking store coverage, seeing which countries a store is listed in, or obtaining a store_id for account tools. It also tells the agent when not to use it by routing cashback and gift-card questions directly to the sibling tools and clarifies this tool is not a required first step.

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 reveals important behavioral context beyond the annotations: the operation is scoped to the signed-in user's alert, requires OAuth with the 'alerts' scope, and prompts anonymous callers to authorize. The annotations already cover destructiveness and idempotence, so the description adds complementary value without contradiction.

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?

Every sentence earns its place: the core action, a concrete example, a lookup alternative, and the auth requirement. It is front-loaded with the primary purpose and contains 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 two-parameter removal operation with idempotent and destructive annotations, the description covers the action, alert types, parameter sourcing, alternatives, and authentication. A minor gap is that it does not describe the response behavior, but this is acceptable without an output schema and with idempotence already annotated.

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 both parameters thoroughly. The description reinforces that store_id comes from an earlier result and gives the alert_type meaning, but does not need to add much beyond the schema. Baseline 3 is appropriate.

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

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

The description states a precise verb ('Removes') and a specific resource ('the signed-in user's alert for a store and alert type'), and clarifies the two possible alert types. This clearly distinguishes it from sibling tools like set_store_alert and get_my_alerts.

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 natural-language use case ('stop alerting me about Nike cashback'), tells the agent to use get_my_alerts to find the required store_id and type, and in the schema notes the by-name alternative when only a store name is available. This is direct when-to-use and alternative 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail beyond those annotations: re-saving updates and re-arms the alert, the alert emails the user, there is a 10-alert cap, and anonymous callers are prompted to authorize. No contradiction with the annotations.

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

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

The description is four dense sentences with no filler. It front-loads the core behavior, then efficiently covers update semantics, quota, store_id sourcing, and auth requirements. 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 mutating tool with no output schema, the description is self-contained: it explains create-vs-update behavior, trigger conditions, the alert limit, authorization, and how to obtain store_id. An agent has enough information to select and invoke the tool correctly without additional context.

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

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

Schema description coverage is 100%, and the schema already explains store_id provenance, alert_type values, and threshold_percent semantics. The main description mostly restates or illustrates these meanings with examples rather than adding new parameter-level information, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Creates or updates an alert that emails the signed-in user when a store's cashback rate or gift card discount reaches the threshold percent or higher.' It is clearly distinct from read-only siblings like get_my_alerts and remove_store_alert, and includes concrete use-case examples.

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 when-to-use examples, explains the store_id sourcing path including the get_stores_by_name fallback, and states the OAuth scope requirement. It also discloses the 10-active-alert limit, giving an agent enough context to decide whether this tool is appropriate.

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

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

Beyond the annotations, the description discloses that this mutates user-specific state, requires OAuth sign-in, prompts anonymous callers to authorize, and scopes the operation to 'favorites'. This meaningfully supplements the idempotentHint and destructiveHint annotations 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 moderately long but every sentence carries useful information: purpose, examples, parameter sourcing, auth requirements, and scope. It is front-loaded with the core semantics and avoids fluff, though a couple of phrases could be tightened.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, parameter provenance, authentication, scope, and alternatives. An agent has everything needed to select and invoke the tool correctly in common scenarios.

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 documents both parameters with 100% coverage, so the baseline is 3. The description adds value by explaining where store_id can come from, suggesting get_stores_by_name as a lookup path, and mentioning the optional country_code for that lookup.

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 precise operation—adding or removing a store from the signed-in user's favorite stores—with concrete example utterances for both directions. It clearly differentiates this mutation tool from read-only siblings like get_my_favorite_stores and from store-lookup 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 tells the agent when to use the tool via natural language examples, and it routes store_id lookup to get_stores_by_name when only a store name is available. It also notes that comparison tools work without signing in, giving helpful context about when this tool is not needed.

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