Pechincha.ai

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is free to add value elsewhere: it discloses the negative outcome ('or says there is none'), the currency/locale of the data, and the cross-store lowest-price comparison. It does not mention rate limits, auth, or pagination, but for a read-only lookup those are minor.

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

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

Two sentences, front-loaded with the core action and outcome, and each remaining clause earns its place by naming the returned fields and the 'none' case. No filler or restatement of the title.

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

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

With an output schema present, the description needn't enumerate return values, and it correctly limits itself to the outcome semantics and the Portuguese-language caveat. The only omission is any relationship to the sibling lookup tools, which would help an agent route between them.

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 there is only one parameter, so the schema already documents 'url' as a product page URL at the store. The description adds only the loose constraint that it is an online-store product page; it contributes no format, normalization, or accepted-domain guidance beyond the schema.

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

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

States a specific verb (check) plus resource (Pechinha.ai active deal for a product page URL) and enumerates the payload shape (price in BRL, discount, store, coupon, link, lowest price across stores). This is clearly distinct from siblings like get_deal, get_product, or search_deals, which operate on IDs or queries rather than an external store URL.

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 implies the trigger condition (the agent has a product page URL from an online store) but never states when to prefer this over get_product or get_deal, nor what to do when the caller lacks a URL. Usage is inferable from the input shape rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the response is Markdown rendered in Brazilian Portuguese, which affects how the agent should present and localize 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?

One front-loaded sentence enumerating the payload, with a short trailing clause for format and language. Every clause carries information; the only minor cost is that the long enumeration reads as a list rather than a structured one.

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?

An output schema exists, so return structure need not be explained, and the description still summarizes the content plus its language/format. For a read-only, single-required-param tool the definition is nearly sufficient; only the sibling-routing gap keeps it from being fully complete.

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

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

Schema description coverage is 100% and the single 'id' parameter is fully documented in the schema with its UUID format and URL source. The description adds nothing about the id, but the baseline of 3 is appropriate when the schema does the work.

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 ('Full details of a deal') and enumerates the payload precisely: photo, price/discount in BRL, store, coupon, purchase link, 30-day history, pros/cons, specs, FAQ. That is enough to distinguish it from most siblings, but it never names or contrasts get_product, get_price_history, or get_similar_deals, whose content overlaps with what is listed here.

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

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

There is no when-to-use guidance and no routing away from the overlapping siblings, even though get_price_history and get_product cover a subset of this tool's output. The only implicit cue is that a single deal id is required, which an agent can already read from the schema.

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 the safety profile (readOnly, non-destructive), so the description earns credit for adding behavior beyond them: pagination defaults (10 per page, limit cap of 25), the fact that content is public/unauthenticated, and that content is in Brazilian Portuguese. It does not discuss pagination edge cases or error behavior, keeping it short of a 5.

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

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

A single front-loaded sentence identifies the resource and its return contents before the parenthetical operational detail. It is slightly dense with the URL pattern and pagination notes packed into one line, but nothing is wasted.

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?

An output schema exists, so return values need not be spelled out, and the annotations cover safety. For a simple one-required-param read tool, the description supplies the missing context (public access, language, pagination). Only the undocumented `page` parameter keeps it from being fully complete.

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

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

Schema coverage is 67%, with slug and limit already described in the schema; the description largely restates the 10-per-page default and 25 cap that the schema already encodes. It adds no semantics for the `page` parameter, which remains undocumented in both places, so the baseline 3 fits.

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+resource (fetch a public Pechincha.ai list) and enumerates the returned content: name, description, price range and active deals. It is clearly distinguishable from siblings like get_deal or search_deals, though it never names an alternative to sharpen the boundary.

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 'such as a gift list someone shared' example implies the intended context (shared public lists), and the URL pattern shows how to obtain the slug. However, there is no explicit when-to-use vs when-not guidance and no mention of alternatives such as search_deals.

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 the safety profile (readOnly, not destructive, closed-world), and the description adds real behavioral context on top: the shape of the returned summary, an update-frequency-independent "insufficient history" signal under 3 distinct days, and the fact that all text is Brazilian Portuguese. It does not mention rate limits or latency, but this is well beyond the annotation baseline.

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

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

Three compact sentences, front-loading the resource and purpose before listing outputs and edge-case behavior. Slight awkwardness in "Says so when..." (the agent as subject is unstated), but no sentence is wasted.

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 needn't enumerate return values, yet it summarizes them helpfully for selection; annotations cover safety and the schema covers the required param. The only real gap is that period's semantics (what each window means) are left to the enum alone.

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 50%: product_id is fully documented in the schema (including how to extract it from the URL), while period is undocumented beyond its enum and default. The enum values 30d/90d/1y are largely self-explanatory, but the description adds no meaning for the window or its default, so 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?

States a specific verb+resource ("Price history of a product") and the analytical intent ("to judge whether a discount is real"), which is unambiguous and distinct from reading a single current price. It stops short of naming how it differs from siblings like get_product or get_deal, so 4 rather than 5.

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?

"to judge whether a discount is real" implies the scenario the tool serves, and the caveat about needing 3+ distinct days effectively signals a limitation. However there is no explicit when-to-use-vs-alternative routing against get_product or get_deal, leaving usage 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the response is Markdown rendered in Brazilian Portuguese and prices are denominated in BRL, both of which materially affect how an agent consumes the result.

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

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

Two sentences, no filler, and the payload inventory is front-loaded so the agent learns the scope immediately. The output-format caveat is correctly placed last as a secondary detail.

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 one fully documented parameter, an output schema present, and annotations covering the safety profile, the description only needs to add scope and format, which it does. The main residual gap is routing guidance against the many sibling lookup tools.

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 is a single parameter and schema description coverage is 100% — the schema already explains that 'id' is the UUID from the pechincha.ai product URL. The description adds nothing about the identifier, so the baseline of 3 applies; the schema is doing all the work.

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 enumerates exactly what the resource is (a product aggregated across stores) and what comes back: photo, offers with BRL prices, lowest price, 30-day stats, reviews, pros/cons, specs, FAQ. It is a noun phrase rather than a verb+resource, but the content is specific enough to separate it from siblings like get_price_history or get_similar_deals. It stops short of naming any sibling explicitly.

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

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

Usage is only implied: the breadth of the payload (offers, stats, reviews, specs) suggests this is the comprehensive single-product lookup. There is no statement of when to prefer it over get_price_history, get_similar_deals, or get_deal, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so safety is covered. The description adds genuine behavioral context beyond them: results are limited to 'active' deals, the similarity scope is spelled out, and the payload is in Brazilian Portuguese — a non-obvious trait an agent must know before using the 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?

A single sentence that front-loads the core purpose and packs scope, similarity semantics, intent, and locale without filler. Slightly dense but every clause carries 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, return values need no explanation, and both parameters are documented in the schema. The description supplies the non-obvious traits (active-only, similarity definition, language), leaving only minor gaps such as pagination behavior for the 'limit' parameter.

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 'id' (UUID from the pechincha.ai URL) and 'limit' (up to 25) are fully documented in the schema. The description adds only indirect meaning via the 'similar deal' framing, so the baseline of 3 applies.

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

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

States a specific verb ('get') and resource ('similar deals') and, crucially, defines the otherwise-ambiguous notion of 'similar' as 'same kind of product, other brands, models and stores'. This lets an agent distinguish it from get_deal (single deal) and search_deals (query-driven) without opening either schema.

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

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

It gives an intent ('to compare alternatives or find a cheaper one'), which implies when the tool is useful, but it never names alternatives like search_deals or get_deal or states a condition under which this tool should be preferred. Usage is implied rather than directed.

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

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

Annotations already declare this a safe, read-only, closed-world operation, so the safety profile needs no restating. The description adds that names are in Brazilian Portuguese, a genuinely useful locale detail, but says nothing about ordering, size, or caching behavior.

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

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

A single tightly-written sentence with no filler, and the key point (what a category looks like) is front-loaded. It is slightly elliptical in phrasing ('as name ... and slug'), which costs it the top mark.

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?

An output schema exists, so return values need not be re-explained, and the description covers the resource, its fields, and its downstream use with search_deals. For a zero-parameter lookup tool this is close to sufficient, with only ordering/deduplication details absent.

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

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

The tool takes no parameters, so there is no parameter documentation burden to carry. That meets the baseline for a zero-parameter tool, and the description correctly spends its words on the return shape 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 names the resource (Pechincha.ai categories) and the exact fields returned (name in Brazilian Portuguese and slug), which is specific. It stops short of a clean verb+scope statement, but the connection to the search_deals category filter distinguishes it from siblings like list_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 phrase 'for the category filter of search_deals' implies this is a lookup helper to call before filtering deals, which is useful routing. However, it never explicitly says when to call it or what to do with the result, leaving the workflow 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that the listing is restricted to stores with active coupons, with no detail on result size, pagination, or ordering.

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

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

Two short sentences, front-loaded with what the tool returns and followed by the natural next step. 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?

With an output schema present, return-value details need not be repeated, and the description names the key fields anyway. For a zero-parameter read tool, this is nearly complete; only a pointer on result volume or pagination 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 the baseline is 4. Schema coverage is 100% and there is nothing parameter-related the description could meaningfully add.

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

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

States a specific resource and scope: 'Stores with active coupon codes on Pechincha.ai', plus the returned fields (name and slug). This distinguishes it from the sibling list_store_coupons, which serves codes rather than stores, though the distinction from list_stores is only implied by the 'active coupon codes' qualifier.

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

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

The second sentence routes the agent to list_store_coupons for the actual codes, implying a two-step flow, but it never states when this tool should be chosen over list_stores or when it should be skipped. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: the content is in Brazilian Portuguese, coupon titles encode the rule, and valid_until is the store-reported end date rather than a guaranteed expiry.

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 tightly packed sentences, front-loaded with what is returned and then how to interpret it. No filler, though the language note could sit more naturally at the end.

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, return values need no explanation, and the description covers the semantic gotchas an agent needs: locale, title-encoded rules, and store-reported validity. Missing only an explicit pointer to the sibling tools for the non-deal case.

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 is only one parameter and schema description coverage is 100%, with the schema already explaining the deal UUID. The description adds no additional parameter meaning, 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 description states a specific resource (active coupon codes) scoped to the store selling a given deal, and gives the reason for retrieval (to check applicability). It is distinguishable from siblings like list_store_coupons by the deal-scoped input, though it never names an alternative explicitly.

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 tells the agent what to do with the results ('compare them with the deal's title and price before suggesting a code'), which implies the use case, but it never states when to prefer this over list_store_coupons or list_coupon_stores, nor any exclusion conditions.

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 this as a safe, read-only operation. The description adds two useful behavioral details: only active coupons are returned, and the content is in Brazilian Portuguese. It does not discuss pagination, rate limits, or authentication.

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

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

Two short sentences, both information-dense and front-loaded. There is no filler, and the second sentence adds a non-obvious output-language constraint.

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

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

For a simple read tool with full schema coverage, clear annotations, and an output schema, the description provides enough to call it correctly. The main gap is routing guidance among similar coupon-related siblings, but that is a minor omission.

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 store parameter is fully documented in the schema, including the slug source and example. The description adds no parameter-specific details beyond the schema, making the baseline score of 3 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 identifies the resource: active coupon codes for a specific store on Pechincha.ai. It does not explicitly differentiate itself from nearby siblings like list_deal_coupons or list_coupon_stores, though the phrase 'of a store' helps distinguish the scope.

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

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

Usage is implied by the resource description and the prerequisite note that the store slug comes from list_stores. However, there is no explicit guidance on when to use this tool versus list_deal_coupons or list_coupon_stores, nor are exclusions stated.

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

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

Annotations already establish a safe read-only, non-destructive operation, and the description adds real behavioral context beyond them: the default result set is scoped to stores with deals in the last 7 days and the store population exceeds 1000. It does not mention pagination or result limits, which matters at that scale.

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

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

Two tight sentences with no filler, front-loading what the tool returns before the conditional behavior. Every clause carries actionable 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?

An output schema exists so return shape need not be explained, and the description covers default scoping, query semantics, and catalog size. The one remaining gap is how to page or retrieve beyond the default/limited result set given 1000+ stores.

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?

With 100% schema coverage the baseline is 3, and the description goes further by explaining that `query` is a partial name match and that its presence/absence changes the result set entirely. That meaning exceeds the schema's 'Part of the store name' text.

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+resource (list stores) and adds what the result contains (name and slug) plus the downstream tools it feeds (search_deals, list_store_coupons). It does not contrast with the similarly named sibling list_coupon_stores, so an agent must infer that difference.

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 an explicit use rule: omit `query` for stores with deals in the last 7 days, pass `query` to locate any of the 1000+ stores by name. It lacks any exclusion or comparison against sibling listers such as list_coupon_stores, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful domain context by characterizing the taxonomy (seasonal events, gift ideas, product niches) but says nothing about result size, ordering, or empty-result behavior.

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

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

A single sentence that front-loads the resource and return shape, then the usage purpose, then the parameter hint. No filler and no repetition.

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 needn't explain return values, and it covers purpose, usage context, and the filter parameter adequately. Only minor gaps remain (ordering, result volume), which are low-risk for a read-only lookup list.

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

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

Schema description coverage is 100% and the single `query` parameter is fully documented in the schema with a concrete example. The description's 'Pass `query` to filter' merely restates the schema, so 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?

States the specific resource (Pechincha.ai themes), the exact shape returned (name and slug), and its downstream purpose (the theme filter of search_deals). This distinguishes it from sibling list tools such as list_categories and list_stores without opening a 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?

It clearly says when to use it — feeding the theme filter of search_deals — and notes that `query` filters the list. It gives no explicit when-not guidance or alternatives, but the context is unambiguous for a small lookup 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=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered; the description adds real behavioral context beyond that — Portuguese-language content, whole-word plus stem plus semantic matching, possible keyword loss at 3+ words, and accessories matching the term. The enumerated result fields partly duplicate the output schema, which keeps it from a 5.

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

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

Front-loaded with purpose and pagination defaults, then moves to matching semantics and filters in a logical order. Sentences are long and clause-heavy, so a few items (result-field inventory, multiple examples) could be trimmed, but nothing is filler.

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

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

With an output schema present, the description need not explain return values, and it still covers language, matching behavior, ordering rules, pagination, and all filter families. An agent has everything required to call this correctly on the first try.

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 high (89%), yet the description still meaningfully extends it: `limit` default of 10 with a 25 cap, `sort` behavior (relevance vs newest unless overridden), `query` matching semantics with worked examples, and the mapping of budget/floor/range phrasing to `max_price`/`min_price`. This is value the schema alone would not convey.

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: "Search active (not expired) deals on Pechincha.ai," which immediately separates it from get_deal (single deal), get_similar_deals, and search_guides (guides). The scoping word "active (not expired)" tells the agent exactly which population is returned.

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

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

Gives concrete operating conditions: relevance ordering with `query`, newest ordering without it, and when to add `theme` (seasonal events, gifts, niches) or price bounds (budget, floor, range), pointing to list_themes as the slug source. It does not explicitly state when to prefer a sibling such as check_product_url or get_deal over this tool, so it stops short of full alternative 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?

Annotations already declare a safe read-only, non-destructive, closed-world operation. The description adds value beyond them by disclosing the return fields, the no-query default (newest posts), and the required content language (Brazilian Portuguese).

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 dense sentences with no filler; the resource, return fields, search syntax, and default behavior are all front-loaded and immediately actionable.

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

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

An output schema exists so return structure need not be re-explained, and the description still covers language, search syntax, and default behavior. It omits any note on result count or pagination, which is a minor gap.

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

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

Schema coverage is 100%, so the `query` parameter is already documented, but the description adds real semantics: search terms should be short and in Portuguese, and omitting the optional parameter returns the newest posts rather than failing.

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 (search) and resource (buying guides and blog articles), names the source (Pechinha.ai blog), and enumerates returned fields. It is clearly separable from siblings like search_deals and get_product.

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

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

Gives concrete usage direction - search in Portuguese with short terms - and specifies the default behavior when `query` is omitted (newest posts). It does not, however, state when to prefer this over sibling tools such as search_deals.

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