GotCashback MCP

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 that: it returns at most 5 matches, orders them by cashback rate then gift card discount, returns empty when nothing matches, notes data is refreshed several times a day, and instructs the agent to always display the store links. This is substantial operational context.

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 well-structured and front-loaded: purpose first, then when-to-use, then alternatives, then return behavior and display instructions. Every sentence adds operational value, and there is no repetition of schema content or annotation 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 an output schema present, the description does not need to enumerate return fields. It covers query disambiguation, ranking logic, result limits, empty-result behavior, data freshness, and required user-facing links. An agent has everything needed to select and invoke 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%, with detailed explanations for both brand_name and country_code, including examples and the 'gb' vs 'uk' nuance. The description adds no new parameter-level meaning, but given full schema coverage the baseline of 3 is appropriate; it does connect brand_name to the matching behavior in the return statement.

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 goes on to state exactly what is returned and how results are ranked. It also distinguishes itself from sibling tools by identifying brand-based queries as its target, so an agent can tell it apart from store- or category-based tools.

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

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

Usage guidance is explicit: 'Use it when the user names a product brand rather than a specific retailer,' with concrete example queries. It also names the alternatives for the excluded cases: get_cashback_rates_by_store_name for named retailers and get_best_deals_by_category for product types, leaving no ambiguity about when to choose this tool.

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, and the description adds valuable behavior beyond that: it returns up to 5 categories, best match first, empty when nothing matches, and notes data freshness. It also instructs the agent to always surface specific URLs to the user, which is a meaningful behavioral detail not captured in structured fields.

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 detailed but every sentence earns its place: it front-loads the core behavior, then gives usage guidance, then output limits, then presentation requirements. It is structured so an agent can quickly extract the most important selection and invocation facts.

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

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

Given the tool's moderate complexity, the presence of an output schema, and rich annotations, the description is complete. It covers ranking logic, result limits, empty results, data freshness, and user-facing link requirements, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the schema. The description adds examples that align with the parameters but does not add significant new meaning beyond what the input schema already provides.

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

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

The description states a specific verb and resource: it finds where to buy products from a shopping category with the most savings, returning matching categories and ranked stores. It clearly distinguishes itself from siblings by explicitly naming get_cashback_rates_by_store_name and get_best_deals_by_brand as the alternatives for retailers and brands.

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

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

It gives explicit when-to-use guidance with concrete user query examples ('where can I buy dog food with the biggest discount?', 'best cashback for electronics'). It also names the sibling tools to use for retailer or brand queries, so an agent knows exactly when not to use this tool.

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 meaningful behavioral context: it returns an error for a nonexistent id, rates are refreshed several times a day, and cashback is only credited when the user clicks the url link. This goes beyond the structured hints and is not contradictory.

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 appropriately sized and front-loaded: the core behavior appears first, followed by routing guidance, error/freshness information, and presentation instructions. Each sentence carries distinct, useful information with no filler or redundancy.

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

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

Given the tool has a single well-described parameter, a read-only/idempotent annotation set, an output schema, and clear sibling alternatives, the description fully covers what the agent needs: when to call it, when not to, what to expect, and how to present results. 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?

Schema description coverage is 100%, so the parameter is already fully documented in the input schema. The tool description reaffirms that store_id is numeric and should come from an earlier result, but does not significantly extend what the schema already states; hence 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 ('Returns') and resource ('current online and in-store cashback rates from every cashback portal for one store identified by its numeric store_id'), making the tool's purpose immediately clear. It also differentiates from the sibling by explaining the store_id vs store_name lookup split.

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 usage guidance: use only when a store_id is already known, and when only a store name is available, call get_cashback_rates_by_store_name directly without looking up the id first. This clearly routes the agent between two similar siblings and prevents unnecessary lookup steps.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the bar is lower, and the description adds substantive behavior beyond them: data freshness ('refreshed several times a day'), matching semantics ('best match first, one entry per country'), no-match edge behavior ('an empty list means no match'), and the critical click-through rule ('cashback is only credited when the user clicks through it'). No contradiction with annotations — the description is fully consistent with a read-only, idempotent lookup.

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 core purpose, then ordered logically: trigger examples, routing rules, return semantics, and presentation requirements. It is a long description, and the six example queries are somewhat redundant (all illustrate the same trigger pattern), while the final presentation paragraph edges into UX policy rather than invocation guidance. Still, every sentence carries decision-relevant information, so it earns a 4 rather than a 3.

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 substring-matching, multi-portal aggregation tool with an output schema present, nothing an agent needs is missing: when to call it, sibling routing, matching and edge-case behavior, data freshness, and how results must be presented (show every portal's rate in a table with a clickable url, not just the best). The output schema relieves the description of explaining return-value fields, and the 100% param coverage relieves it of param semantics.

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

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

Schema coverage is 100% and the schema already documents store_name (case-insensitive substring, plain name only) and country_code (lowercase ISO alpha-2, 'gb' not 'uk', default null). The description adds value above that: operational retry guidance tied to each parameter ('retry with a shorter name or without country_code') and result-level semantics for country_code ('one entry per country'), plus query examples that map to parameter usage ('Dell cashback in Germany').

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+resource+scope: 'Finds a store by name and returns its current cashback rates from every cashback portal that lists it,' including coverage details (online/in-store, percentage/fixed, 'up to' flags). It immediately differentiates from siblings by declaring itself 'the preferred first call for any cashback question that names a store' and explicitly naming calls NOT to make first (get_stores_by_name, get_stores_by_country, get_countries).

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 with six concrete example queries ('best cashback for Walmart', 'Dell cashback in Germany'), explicit when-not-to ('do not call get_stores_by_name...'), and explicit alternative selection conditions: get_cashback_rates_by_store_id only when store_id is known, get_gift_cards_by_store_name for gift card discounts, get_best_deals_by_brand for brand-level purchase questions. Failure recovery is also specified: empty list means no match — retry with a shorter name or without country_code.

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 non-destructive behavior. The description adds useful behavioral context about the output format (lowercase code, 'gb' example) and clarifies that this tool is a reference lookup, not a prerequisite for other calls.

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

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

The description is a single dense sentence that front-loads the core purpose, then explains the code format, gives a concrete example, and provides explicit usage guidance. Every clause earns its place without redundancy.

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

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

With zero parameters, a rich output schema, and comprehensive annotations, the description fully covers what an agent needs: what the tool returns, how to interpret it, when to call it, and when to skip it.

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

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

The tool has zero parameters and schema description coverage is 100%, so the schema has nothing to document. The description compensates by explaining the purpose of the returned country_code and how it connects to other tools.

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 the countries GotCashback covers, with a specific output detail (lowercase ISO 3166-1 alpha-2 code). It is distinct from sibling tools like get_stores_by_country or get_cashback_rates_by_store_id, which serve different purposes.

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 says when to use this tool: only to confirm country support or determine the correct country_code. It also states when not to use it—before store, cashback, or gift card lookups—because those tools accept country_code directly and search all countries when omitted.

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 cover read-only, idempotent, and non-destructive traits. The description adds valuable behavioral details: it returns an empty list when no discounted cards exist, errors on an invalid id, lists multiple sellers for comparison, and emphasizes the 'url' is the tracked purchase link. This goes well beyond what annotations alone communicate.

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 slightly long but every sentence earns its place: it covers the return value, the exact condition for use, the alternative tool, edge-case behavior, and user-presentation requirements. It is front-loaded with the core purpose and flows logically without 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 tool is simple (one required parameter), has a rich input schema, annotations, and an output schema, so the description does not need to restate return types. It still covers empty results, error behavior, the compare-across-sellers point, and even how the agent should present the results with clickable tracked links. 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?

The input schema already documents store_id as GotCashback's numeric ID taken from earlier results and tells the agent to use the by-name tool when only a name is available. The description reinforces this but adds little new meaning beyond the schema. With 100% schema coverage, 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 ('Returns'), a specific resource ('discounted gift cards... for one store identified by its numeric store_id'), and a distinguishing detail ('from multiple sellers, so the discounts can be compared'). It also contrasts directly with the sibling get_gift_cards_by_store_name, so an agent can select this tool without ambiguity.

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

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

The description gives explicit when-to-use guidance ('Use it only when a store_id is already known from an earlier result') and explicit when-not-to-use guidance with the named alternative ('When the user gives a store name instead, call get_gift_cards_by_store_name directly — do not look the id up first'). This leaves no room for the agent to misuse the by-id tool.

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), so the bar is lower, but the description still adds substantial behavior: return shape ('each with its 'gift_cards' list and a 'gift_cards_url' page'), ordering ('best match first, one entry per country'), empty-result semantics ('an empty 'gift_cards' list means no discounted cards right now'), and presentation requirements including the tracked purchase link. This goes well beyond what annotations provide.

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 (~140 words) but every sentence earns its place and the core purpose is front-loaded before routing and presentation details. It packs purpose, when-to-use, examples, return shape, exclusions, and output handling into one dense block. A minor trimming of the presentation guidance could tighten it, but it remains highly structured and information-dense.

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 lookup tool with an output schema, a 100%-covered 2-parameter schema, and full annotations, the description is complete: it explains result ordering, empty-list meaning, country behavior, seller-list structure, and how to present results. An agent has everything needed to select and invoke the tool correctly without opening the schema or output schema.

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

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

Schema coverage is 100% with strong per-parameter descriptions, so baseline is 3. The description adds value on top: it shows natural-language query forms ('best gift card discount for Gap') reinforcing how users phrase store_name, and repeats the plain-name-only guidance. It doesn't add syntax details for country_code beyond the schema, but the marginal enrichment of store_name justifies a 4.

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 and returns the discounted gift cards currently on sale for it') with a precise resource and scope, and clearly differentiates from siblings by naming get_gift_cards_by_store_id and get_cashback_rates_by_store_name. The title and first sentence alone tell an agent exactly what this tool does.

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?

Explicit when-to-use guidance: 'This is the preferred first call for any gift card question that names a store' with four real query examples, plus 'No prior lookup is needed'. It also states exclusions and alternatives explicitly: use get_ift_cards_by_store_id only when store_id is known, and get_cashback_rates_by_store_name for cashback questions. 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?

Beyond the annotations, the description discloses the OAuth requirement, the required 'alerts' scope, and that anonymous callers are prompted to authorize. It also states the specific alert fields returned, providing behavioral context over and above the readOnlyHint and idempotentHint annotations. 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 tight sentences: the first states what the tool returns, and the second states when to use it and the authentication requirement. Every sentence earns its place, and the core purpose is front-loaded.

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

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

For a simple parameterless, read-only, idempotent tool with rich annotations, the description covers the function, exact result fields, usage context, and auth behavior. The absence of an output schema is compensated by naming the precise fields returned. Nothing critical 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 takes zero parameters, so there is nothing to document in the input schema. The description appropriately focuses on the return data and usage context rather than inputs, matching the baseline of 4 for parameterless tools.

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') and resource ('the signed-in user's cashback and gift card alerts'), and enumerates the fields returned (store, type, threshold percent, last notification). This clearly distinguishes it from sibling tools such as get_my_profile or get_my_favorite_stores by the alert-specific resource and the enumerated return data.

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

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

The description explicitly names two use cases: answering 'what alerts do I have?' and being used before changing an alert. This implies it is the read/precondition tool for the mutation siblings set_store_alert and remove_store_alert, but it does not name those alternatives or explicitly state when not to use it. The context is still clear enough for an agent to route correctly.

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 builds on that by adding the OAuth requirement and the anonymous-caller authorization prompt. This is meaningful behavioral context beyond the structured annotations, though it does not cover potential failure modes or empty results, which are minor for this simple read-only tool.

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

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

The description is compact and front-loads the main purpose before usage guidance and auth details. A few phrases, such as 'Scope: favorites' and the general note about comparison tools, add useful context but are slightly redundant or tangential. Overall it is efficient without being bloated.

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

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

Given the tool has no parameters, no output schema, and rich annotations, the description covers all necessary operational context: what it returns, when to use it, how to pair results with another tool, and the auth requirement. Nothing critical is missing for correct selection and 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?

There are zero parameters and schema description coverage is 100%, so the schema carries no parameter burden. The description adds useful output context by stating the returned store_id, which supports the recommended pairing with get_cashback_rates_by_store_id. This meets the baseline for a no-parameter tool.

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

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

The description uses a specific verb and resource: 'Returns the signed-in user's favorite stores (with their store_id).' It clearly distinguishes this from sibling tools like get_my_alerts and get_my_profile by focusing on favorite stores, and it also notes the store_id output that enables downstream use. This is unambiguous and easy for an agent to act on.

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 names trigger phrases ('my favorites' or 'my saved stores') and gives a direct next-step pairing with get_cashback_rates_by_store_id. It also clarifies the auth boundary by stating that comparison tools work without signing in, helping the agent choose appropriately among siblings.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds important behavioral context beyond those annotations: it requires OAuth sign-in with a GotCashback account, anonymous callers are prompted to authorize, and the required scope is 'profile'. This gives the agent a clear picture of what will happen at invocation.

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 well-structured and front-loaded with the core purpose and return fields. The use-case and auth guidance are useful, but the sentence about all comparison tools working without signing in is somewhat tangential to this specific tool, making it slightly less crisp than it could be.

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 profile retrieval tool, the description is complete: it names the resource, the returned fields, the trigger conditions for use, the authentication requirement, and the OAuth scope. No output schema is needed because the description already states what data the user will receive.

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 is 4. The description does not need to explain parameter semantics, and it correctly implies that no arguments are required to retrieve the signed-in user's profile.

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 ('Returns') and names the exact resource: the signed-in user's GotCashback profile, including the fields (name, email, avatar). It also states clear use cases ('asks who they are signed in as or wants their account details'), which distinguishes it 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?

The description explicitly says when to use this tool: when the user asks who they are signed in as or wants their account details. It also states the auth prerequisite and the fact that anonymous callers are prompted to authorize. However, it does not explicitly name a sibling alternative or provide a when-not-to-use condition, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: it explains error behavior for nonexistent ids and the meaning of null/0 values in payout fields. This is useful context for interpreting 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 longer than minimal but is front-loaded with the core purpose and use condition, then progressively adds payout term details and examples. Each sentence contributes useful usage or interpretation information, though some payout-field explanation may overlap with the output schema.

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

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

For a single-parameter read-only tool with an output schema, the description covers the parameter source, when to use versus alternatives, error behavior, and the semantics of the returned payout fields. This is sufficient for an agent to select and invoke the tool correctly without missing key 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 that portal_id is the numeric id from an earlier get_portals or get_portals_by_name result. The description largely repeats this rather than adding new meaning, so it meets the baseline but does not exceed it.

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'), a specific resource ('one cashback portal by its numeric id'), and the included payout terms. It also explicitly names the sibling tools get_portals and get_portals_by_name, making it clear how this tool differs from them.

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

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

The description gives explicit guidance: use it only when the id is already known, and call get_portals_by_name instead when the user names a portal. It also notes that an error is returned when the id does not exist, which helps the agent decide when 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: results are optionally country-filtered, each portal includes payout terms, sign-up bonus is only credited via its URL and should be shown as a clickable link, and null/0 semantics for minimum payout are explained. This exceeds the baseline for annotation-covered tools.

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 longer than strictly minimal, but every section earns its place: distinguishing siblings, usage examples, payout-term semantics, and the sign-up-bonus URL rule. The main sentence is dense and front-loaded with the core behavior before diving into payout details. Slight redundancy in the payout-term explanations could be tightened, but it is well organized.

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 list tool with one optional parameter, 100% schema coverage, an output schema, and read-only/idempotent annotations, the description fully covers what an agent needs: what data comes back, how to interpret null vs 0 values, how to present sign-up bonus links, and how to route to siblings. No significant gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by explaining how to pass the country code ('gb', not 'uk'), gives concrete examples ('us', 'ca', 'de'), and tells when to omit it ('omit it to search all supported countries'). It also links the country_code parameter to the natural-language usage examples.

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 ('Returns') and resource ('cashback portals GotCashback compares'), and immediately specifies the optional country scope and that each portal includes its payout terms. It clearly names sibling tools (get_cashback_rates_by_store_name, get_portals_by_name) to distinguish what it is not, so an agent can select it correctly.

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 with example natural-language queries ('which cashback portals are there in Canada?', 'compare portals side by side'), and explicitly says when not to use it: for store rates call get_cashback_rates_by_store_name, for one named portal call get_portals_by_name. This is strong when-to-use vs 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 mark the tool as read-only, idempotent, and non-destructive, and the description enriches that with meaningful behavior: results are country-specific entries, sign_up_bonus can be null, minimum_payout distinguishes null from 0, and payment_frequency/method examples clarify the domain. 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?

The description is front-loaded with purpose and usage, then provides a clear alternative, then gives field-level output detail. It is longer than strictly necessary, especially given an output schema exists, but every section serves a purpose and the structure is logical and scannable.

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 search tool with two fully documented parameters and an output schema, the description is complete. It covers what the tool does, when to use it, when not to use it, what alternative to call, and the meaning of key output fields. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the input schema already fully documents portal_name and country_code. The description reinforces the portal-name use case and country-per-entry output, but it does not add new parameter-specific semantics beyond what the schema already provides. 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: 'Searches cashback portals by name' and says it returns payout terms, one entry per country. It also clearly distinguishes itself from the sibling get_cashback_rates_by_store_name by explicitly calling out what this tool is not for. An agent can easily tell when to choose this tool over the sibling.

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

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

It gives explicit when-to-use guidance: '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 an explicit alternative: 'For a store's cashback rate at that portal, call get_cashback_rates_by_store_name.' This is model-friendly routing behavior.

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 read-only, idempotent, non-destructive behavior, and the description adds meaningful context: results are limited to stores with current cashback offers, the list can run to hundreds of stores, rates are excluded, and response fields such as has_gift_cards and gift_cards_url are disclosed. It also adds presentation guidance about rendering URLs as clickable links.

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?

Core behavior is front-loaded in the first sentence; use cases, exclusions, and alternatives follow logically; and the presentation instruction is the only trailing detail. Every sentence adds a distinct operational fact without repetition or filler.

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

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

For a single-parameter readonly list tool with an output schema, te description covers scope, intended usage, exclusions, sibling alternatives, supported-code lookup, list size expectations, and result presentation behavior. Nothing needed to invoke or present the tool 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 fully documents country_code with format, examples, the 'gb not uk' caveat, and a pointer to get_countries, so the schema carries the parameter-semantics load. The description reinforces that the parameter represents the country to browse but adds no new parameter-level detail.

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

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

States a specific verb and resource: 'Lists every store ... in one country' and defines the exact scope: stores with current cashback offers, identity, store page url, gift-card presence, and no rates. This clearly distinguishes it from sibling store-name 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?

Gives explicit when-to-use guidance ('when the user wants to browse or count what is available in a country') with example queries, and explicit do-not-use guidance for finding a particular store or its rates, naming get_cashback_rates_by_store_name and get_gift_cards_by_store_name as alternatives. It also directs callers to get_countries for supported codes.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: matching is best-first, empty results are returned when nothing matches, and results contain only identity fields—going beyond the 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 dense but well organized: purpose, use cases, alternatives, result behavior, and presentation guidance each occupy distinct clauses with no filler. Every sentence contributes to correct selection or invocation.

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 a rich input schema, output schema, and read-only annotations, the remaining contextual burden is small, and the description meets it fully: it defines the result shape, ordering, empty behavior, and presentation requirements. Nothing needed to use this tool 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 already 100% with detailed descriptions for both parameters. The tool description adds value on top by instructing the agent to pass the plain brand name only, avoid terms like 'cashback' or 'gift card', and by clarifying when to include or omit country_code based on user phrasing.

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

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

The description opens with a specific verb and resource—'Searches stores by name'—and immediately scopes the result set to identity fields only, explicitly excluding cashback rates and gift cards. It also signals differentiation from the cashback/gift-card siblings by naming them, so an agent can tell this tool apart without reading 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?

It gives explicit when-to-use conditions: coverage checks, country availability, and obtaining a store_id for account tools. It also gives explicit when-not-to-use instructions, directing cashback and gift-card questions to get_cashback_rates_by_store_name and get_gift_cards_by_store_name and noting this tool is not a required prerequisite.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds meaningful context beyond annotations: it requires OAuth sign-in with a specific scope, and mentions that anonymous callers are prompted to authorize. It doesn't contradict annotations and gives the agent useful expectations about side effects and failure modes.

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

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

Three sentences, each earning its place: the first states the operation, the second gives a concrete usage example, and the third covers auth requirements and the sibling tool. Information is front-loaded and no filler exists.

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

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

For a two-parameter tool with fully covered schema and annotations, the description covers the essential behavioral and contextual needs: what it removes, how to find inputs, auth requirements, and the natural-language trigger. The lack of an output schema is acceptable since the operation is defined by its side effect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that store_id comes from an earlier result and that alert_type has specific firing semantics ('fires on the store's best cashback rate'). This is helpful clarification 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 states a specific verb ('Removes'), a precise resource ('signed-in user's alert for a store and alert type'), and cites an exact user utterance ('stop alerting me about Nike cashback'). It clearly distinguishes this tool from siblings 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 provides explicit when-to-use guidance via a natural-language example, tells the agent to use get_my_alerts to find the required identifiers, and names the alternative tool ('by-name tool') for cases where only a store name is known. This is strong, actionable routing.

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

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

The description adds substantial behavioral information beyond the annotations: the alert sends email, re-saving updates and re-arms the alert, there is a hard limit of 10 active alerts, and OAuth with the 'alerts' scope is required. This gives an agent important side-effect and precondition knowledge that annotations do not convey, and it does not contradict 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 five concise sentences with the core behavior first, followed by memorable examples, lifecycle semantics, limits, and prerequisites. Every sentence carries distinct information and there is no filler or restatement of the schema.

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

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

For a mutation tool with no output schema, it covers all prerequisites needed to call it correctly: store_id resolution, auth scope, the maximum number of alerts, and what re-saving does. An agent has enough to decide when to use it and how to construct a valid invocation.

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

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

The input schema already documents all three parameters in detail with 100% coverage, so the baseline is 3. The description adds useful operational framing—store_id provenance, re-saving semantics, and alert limits—but does not materially extend the parameter-level definitions already present in the schema.

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

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

The description opens with a clear verb-plus-resource: 'Creates or updates an alert' and specifies exactly what triggers it (cashback rate or gift card discount reaching a threshold. The examples like 'alert me when Nike cashback hits 10%' remove ambiguity, and the create/update operation is clearly distinct from sibling get/remove alert tools.

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

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

It provides explicit use cases and a direct pointer to get_stores_by_name for resolving a store_id, and notes the required OAuth scope. It stops short of explicitly contrasting this tool with get_my_alerts or remove_store_alert, but the usage context is clear enough for an agent to select 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 description adds useful behavioral context beyond annotations: the tool mutates the user's favorite stores, requires OAuth, and may prompt anonymous callers to authorize. Since idempotentHint/destructiveHint/readOnlyHint are already covered by annotations, the description only needs to add the auth and scoping context, which it does.

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 well-structured and front-loaded with the core action and examples. It is a bit repetitive with the schema's store_id explanation, but every sentence carries useful operational or auth context, so it remains reasonably 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?

For a simple two-parameter mutation tool, the description covers purpose, examples, input sourcing, auth requirements, scope, and the relevant alternative. No critical information is missing for an agent 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?

Schema description coverage is 100%, so the parameted semantics are already fully documented. The description reates the store_id sourcing guidance and favorite true/false meaning, which adds some practical context but does not expand significantly beyond the schema.

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

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

The description clearly states the tool adds or removes a store from the signed-in user's favorites, with concrete natural-language examples. It also distinguishes this from the read-only get_my_favorite_stores and from store alert tools.

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

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

It explicitly provides when to use the tool, includes example phrases, explains how to obtain store_id from an earlier result or get_stores_by_name, and notes the OAuth requirement. The contrast that comparison tools work without signing in helps the agent route to the correct tool.

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