GotCashback

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

Annotations already mark the tool readOnly, idempotent, and non-destructive, and the description adds substantial behavior beyond that: result cap ('Returns up to 5 matching brands'), ordering ('best match first'), empty-result behavior, data freshness ('refreshed several times a day'), and a UI requirement ('Always show each store's links to the user'). This is rich, non-redundant context that meaningfully shapes how the agent presents 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 description is front-loaded with the core function and ranking logic, and every sentence earns its place — usage routing, return limits, freshness, and link display are all load-bearing. It is a long single paragraph, so a small deduction for scannability; breaking the usage-vs-alternative guidance into bullets would improve structure without adding words.

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 output schema exists, annotations carry the safety profile, and both parameters are fully documented in the schema, the description covers everything else an agent needs: sibling routing for retailer/category cases, ranking order, match cap, empty results, data recency, and required user-facing output. There are no missing behavioral or routing details.

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 schema already documents brand_name matching semantics and country_code format, defaults, and examples thoroughly. The description adds query examples ('Adidas', 'Apple') and implies brand_name is the central parameter, but does not need to compensate since the schema fully documents both parameters. 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 opens with a specific verb and resource: 'Finds where to buy a brand's products with the most savings' and even specifies the ranking logic (cashback rate, then gift card discount). It explicitly names sibling tools it is not ('call get_cashback_rates_by_store_name instead; ... use get_best_deals_by_category'), so an agent can disambiguate 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 trigger condition ('Use it when the user names a product brand rather than a specific retailer'), concrete query examples ('where is the best cashback for Adidas products?'), and explicit when-not-to-use routing with named alternatives for both the retailer case and the product-type case. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety traits. Beyond the annotations, the description adds rich behavioral context: it discloses the return cap (up to 5 categories), the ordering rule (best match first), the empty result behavior, data freshness ('refreshed several times a day'), and a mandatory display instruction for the store links, all of which materially inform an agent's 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?

The description is long but information-dense, and every sentence contributes a distinct fact (purpose, usage examples, sibling differentiation, return limit, empty behavior, freshness, display requirement). There is minor redundancy — 'best current cashback rate' appears twice and the sibling differentiation is stated both in the purpose clause and again in the usage guidance — but this does not meaningfully harm clarity.

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 2 parameters, 100% schema coverage, an output schema, and safety annotations, the description covers everything an agent needs: purpose, when to use vs. alternatives, return structure, ordering, limit, empty case, data freshness, and display obligations. No critical information is missing for correct invocation.

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

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

Schema coverage is 100% (both parameters have descriptions), and each description adds meaning far beyond the type. category_name explains matching behavior, case-insensitivity, word-boundary matching, and multi-word fallback; country_code explains the ISO 3166-1 alpha-2 format with examples, the 'gb not uk' caveat, when to pass it (user names a country) versus omit it (search all supported countries). The descriptions genuinely help an agent construct correct calls.

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 where to buy products') and identifies the exact resource (shopping category) and return format (matching categories with ranked stores). It also explicitly distinguishes the tool from its siblings by naming get_cashback_rates_by_store_name and get_best_deals_by_brand as alternatives, so an agent can disambiguate without opening other 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 explicit 'when to use' guidance with concrete example queries ('where can I buy dog food with the biggest discount?', 'best cashback for electronics', 'travel booking sites with cashback'). It also provides an explicit 'when not to use' rule by naming the sibling tools to use for a specific retailer or brand, covering 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 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?

The description aligns with the annotations (readOnly, idempotent, non-destructive) and adds useful behavioral context. It explains data freshness ('refreshed several times a day') and instructs how to present results to ensure users click through links for cashback credit. No contradictions with the annotation metadata.

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 comprehensive yet well-organized. It front-loads the core purpose and then proceeds logically through examples, exclusions, usage guidance, and presentation rules. Each sentence adds valuable information without unnecessary repetition. The structure makes it easy for an agent to extract all necessary instructions.

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 parameters and 100% schema coverage, the description provides complete context. It explains the output format (matching stores with cashback rates), how to handle empty results, and the presentation requirement. It also covers edge cases like partial matches and country-specific usage. All necessary operational details are included.

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?

Both parameters are fully described with detailed semantics beyond the schema. The store_name description covers matching logic, case-insensitivity, word boundaries, and partial-word fallback, with examples. The country_code description explains the format, valid examples, and when to pass it vs. omit it. This goes well beyond the basic schema definitions.

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's purpose: finding a store by name and returning cashback rates from all portals. It explicitly differentiates from sibling tools like get_cashback_rates_by_store_id and get_best_deals_by_brand, and provides concrete example queries. The primary use case (any cashback question that names a store) 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 gives explicit when-to-use and when-not-to-use guidance. It states 'No prior lookup is needed' and names the tools to avoid calling first. It also specifies alternative tools for different scenarios (store_id, gift cards, brand product queries) and provides presentation requirements (show all rates, clickable links). This is thorough and actionable.

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?

The annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral details: the store-name matching algorithm (case-insensitive, word boundaries, best-match-first), the structure of results (gift_cards list, gift_cards_url), and that an empty list means no discounted cards. This exceeds what annotations provide and discloses the tool's behavior transparently, with no contradictions.

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?

Though the description is long, every sentence serves a purpose: it covers functionality, usage alternatives, matching rules, output details, presentation instructions, and edge cases. There is no redundancy or filler; the structure is dense but well-organized, making it appropriately sized for the complexity of the tool.

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

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

The description is complete for the tool's context. It explains the output format and how to use it (clickable link, mention gift_cards_url), handles empty results, and clarifies the distinction from related tools. Even with an output schema present, the description provides necessary context that the schema alone does not convey.

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?

Both parameters have detailed descriptions in the schema. store_name includes matching rules and example values, and country_code specifies format, allowed values, and when to use it. The schema description coverage is 100% and the tool description reinforces parameter handling, making parameter semantics fully explicit.

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's function: finding a store by name and returning discounted gift cards from multiple sellers. It also distinguishes it from sibling tools like get_cashback_rates_by_store_name and get_gift_cards_by_store_id, 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 explicitly states when to use this tool ('preferred first call for any gift card question that names a store'), when not to (use get_gift_cards_by_store_id when store_id is known), and that no prior lookup is needed. It also provides guidance on presenting results, fulfilling the usage guideline requirement thoroughly.

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 readOnly/idempotent/destructive safety, and the description adds meaningful context beyond them: OAuth sign-in requirements, the 'alerts' scope, anonymous-caller authorization behavior, and the exact payload shape. This gives the agent a clear picture of side effects and prerequisites.

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 sentences and every sentence earns its place: first the core function, then when to use it, then output fields and auth requirements. It is dense but not bloated, and the most decision-relevant 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 zero-parameter, read-only, idempotent tool with annotations and an output schema already present, the description covers everything an agent needs: purpose, usage context, return fields, downstream interoperability, and authorization prerequisites. Nothing material is missing.

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

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

The tool has zero parameters and an empty schema, so schema coverage is trivially 100%. The 0-parameter baseline of 4 applies, and the description's output-field details compensate for any need to understand what the no-input call returns.

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 cashback and gift card alerts.' This clearly distinguishes it from sibling tools like get_my_favorite_stores and get_my_profile, and it even names the alert_type values that scope the resource.

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 use cases: 'what alerts do I have?' and 'before changing an alert.' It also names downstream sibling tools (set_store_alert, remove_store_alert) whose parameters can be filled directly from the returned values. It doesn't state exclusions, but no competing read-alerts sibling exists.

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. The description adds useful context beyond annotations: the tool requires OAuth sign-in and anonymous callers are prompted to authorize, plus the scope is restricted to 'favorites' rather than all stores. However, it doesn't describe what happens when there are no favorites, or the exact shape of the response beyond store_id, and the 'Requires OAuth sign-in' behavior is a useful addition that partially compensates.

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 well-structured: a clear opening sentence, a direct when-to-use clause, a downstream pairing instruction, and an auth note. Every sentence earns its place. It loses one point because the final annotation-style line 'Scope: favorites.' is slightly redundant with the opening sentence, and the sign-in mention could be more prominent.

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 rich annotations and an output schema, the description is largely complete. It tells the agent the resource, the access requirement, the sibling to pair with, and the boundary between signed-in and comparison tools. It could be more complete by clarifying the response when there are no favorites, but given the output schema exists and the annotation set is strong, 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?

There are zero parameters, and schema description coverage is 100%, so the input side is fully documented. With no parameters, the baseline is 4. The description adds no parameter-level specifics because none are needed; it does convey that the primary meaningful output is store_id, which aids downstream tool selection.

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 ('Returns'), the specific resource ('the signed-in user's favorite stores'), and the key field returned ('store_id'). It distinguishes itself from siblings by explicitly framing its scope as 'my favorites' / 'my saved stores' and by noting that comparison tools work without sign-in, which separates it from the broader store and deal retrieval 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?

Provides explicit when-to-use guidance: 'Use it when the user asks about my favorites or my saved stores.' It also gives routing direction by telling the agent to pair the resulting store_ids with get_cashback_rates_by_store_id, and notes that comparison tools work without signing in, implicitly warning against using this tool when the user's request does not require the signed-in 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?

Beyond the readOnlyHint, destructiveHint, and idempotentHint annotations, the description discloses the OAuth requirement and the behavior for anonymous callers ('anonymous callers are prompted to authorize'). It also mentions the 'profile' scope, adding meaningful behavioral context not present in the structured 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?

Four short sentences, each earning its place: the result, the use case, the auth behavior, and a contrast with comparison tools. Information is front-loaded and there is no 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?

Given the output schema exists and the annotations cover safety/idempotency, the description fills all remaining gaps: auth requirement, scope, and when to invoke. Nothing an agent needs to call this 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 tool has zero parameters and the schema is empty, so the baseline is 4. The description adds no parameter-level detail, but none is needed; the mention of OAuth scope and auth requirement is the only extra context, which is not parameter-related.

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 (name, email, avatar).' It also names the exact triggering user requests, making the tool's purpose unmistakable and distinct from sibling tools like get_my_alerts or get_my_favorite_stores.

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 states when to use the tool: 'Use it when the user asks who they are signed in as or wants their account details.' It also provides a relevant exclusion by noting 'All comparison tools work without signing in,' which guides agents toward alternatives in anonymous contexts.

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 declare readOnly, idempotent, and non-destructive behavior, and the description adds genuinely new context: one result per country of operation, null-vs-0 semantics for minimum_payout, the bonus being credited only via its specific URL, and the requirement to render that URL as a clickable link. No contradiction with annotations; it goes well beyond 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 core purpose is front-loaded and nearly every sentence earns its place, including field semantics and the presentation constraint. However, the sentence 'Use these to answer questions about a portal's sign-up bonus, payout threshold, payment schedule and payment options' largely restates the earlier when-to-use sentence, a minor redundancy in an otherwise tight description.

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

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

For a 2-parameter search tool with 100% schema coverage, full annotations (readOnly, idempotent, non-destructive), and an output schema, the description covers result multiplicity, field-level semantics, and how to present bonuses. Nothing an agent needs to call it correctly or interpret its results 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 already carry rich descriptions (case-insensitive word-boundary matching, best-match ordering, country-code format, 'gb' not 'uk', when to pass or omit country_code). The description adds portal examples and result-field semantics but no parameter meaning beyond the schema, so the high-coverage 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 opens with a specific verb-resource pair: 'Searches cashback portals by name' with concrete examples (Rakuten, TopCashback, Honey), and states the exact output shape: 'returns each match with its payout terms, one entry per country.' It differentiates from siblings by scope (by name vs. by id vs. list-all) and explicitly contrasts with get_cashback_rates_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?

Gives explicit when-to-use conditions ('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') and an explicit when-not-to-use with the named alternative ('For a store's cashback rate at that portal, call get_cashback_rates_by_store_name and read the "portal" field'). This fully routes the agent with no inference 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, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds meaningful behavior beyond those: match ordering (best first), case-insensitive word-boundary matching, empty-result behavior, and a presentation requirement (include 'url' as clickable link). These are not inferable from annotations alone.

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 information-dense with no filler. Each sentence earns its place: return scope, use cases, sibling routing, ordering, empty behavior, and link presentation. Critical routing information is front-loaded, and parameter details are left to the schema. Excellent structure.

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

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

For a read-only, idempotent search tool with a fully documented schema and an output schema present, the description covers everything needed for correct selection and invocation. It addresses scope, alternatives, result ordering, empty results, and presentation. Nothing an agent needs 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%, so the schema fully documents store_name and country_code. The description reinforces the key semantic point that store_name should be a plain retailer name without qualifiers like 'cashback' or 'gift card', and it ties country_code usage to user mentions of a country. This adds slight value beyond the schema but not enough for a 5.

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 starts with a specific verb and resource ('Searches stores by name') and immediately narrows the scope to 'identity only' fields, explicitly excluding cashback rates and gift cards. It also names the sibling tools (get_cashback_rates_by_store_name, get_gift_cards_by_store_name) that handle those excluded areas, making differentiation 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 states clear when-to-use conditions: checking store coverage, countries, or obtaining a store_id for account tools. It also provides explicit when-not-to-use guidance by directing cashback and gift card questions to dedicated sibling tools and clarifying that this tool is not a required first step. This is strong 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, openWorldHint=false. The description adds valuable behavioral context: it requires OAuth sign-in with a GotCashback account and the 'alerts' scope, and notes that anonymous callers are prompted to authorize. This is additional information beyond the annotations, clarifying authentication prerequisites and user 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?

Two sentences, no fluff. The first sentence states the action and the exact store/alert types; the second provides the usage example, parameter sourcing guidance, and authentication requirements. Information is front-loaded and every clause earns its place.

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

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

For a mutation tool with only two parameters and no output schema, this description is complete. It covers the primary use case, parameter provenance, authentication, and alert type specificity (including edge cases like 'up to' rates and ignored portals). The destructive nature is implied by the verb 'removes' and covered by annotations, 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%, and both parameters are thoroughly documented in the schema, including details about alert_type semantics and store_id sourcing. The description adds only the instruction to pass both values unchanged from get_my_alerts, which is a minor reinforcement. Since schema carries the heavy lifting, 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 begins with a precise verb and resource: 'Removes the signed-in user's alert for a store and alert type'. It clearly identifies the target object (store alert) and scopes it to the signed-in user, distinguishing it from alert creation (set_store_alert) and alert listing (get_my_alerts). The purpose 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 provides a concrete use case ('stop alerting me about Nike cashback') and explicitly instructs the agent to use get_my_alerts to retrieve the store_id and alert_type, passing them unchanged. It does not explicitly name set_store_alert as the alternative for adding alerts, but this is strongly implied by the sibling context and the removal verb. Slight gap in naming the alternative explicitly.

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

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

The description adds substantial behavior beyond annotations: re-saving updates the existing alert's threshold and re-arms it, there is a 10-active-alert cap, it emails the signed-in user, and requires OAuth with the 'alerts' scope. It also clarifies that anonymous callers are prompted to authorize. This is consistent with idempotentHint=true and destructiveHint=false.

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 purpose, then examples, then behavioral constraints and prerequisites. Every sentence adds distinct information: purpose, use cases, update semantics, limit, store_id sourcing, and auth requirements. There is 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 mutation tool with no output schema, the description covers all essential calling context: what it does, how to identify the store, how re-saving behaves, the active-alert limit, and authentication requirements. An agent has enough information to decide when to invoke it and how to populate the required parameters 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 schema already fully describes all three parameter fields, so the baseline is 3. The description adds value by giving real-world threshold examples, explaining that re-saving updates the threshold, and providing practical store_id sourcing workflow. It does not merely repeat the schema.

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

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

The description states a specific verb and resource: '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 also gives concrete example intents, and its semantics are clearly distinct from sibling tools like get_my_alerts and remove_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?

It gives explicit usage examples, indicates where to source store_id ('take it from an earlier result, or find it with get_stores_by_name'), and states auth prerequisites. The guidance to use the by-name tool when only a name is available is a clear when-to-use/when-not-to-use distinction.

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.