Joinville Boas Ofertas

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context beyond those annotations: it uses prices from the last calculation (computed_at), is limited to Joinville/SC, and only queries without selling, reserving, or delivering.

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

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

The description is compact and front-loaded, starting with the core purpose before conditional behavior, examples, and coverage. Every sentence adds value without 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?

For a read-only, two-parameter tool with full schema coverage, rich annotations, and an output schema, the description is complete enough. It covers purpose, freshness of prices, geographic limitation, and the fact that no commercial transaction occurs.

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

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

Schema description coverage is 100%, so the schema already documents market and region. The description still adds meaning by explaining that providing market causes item-level detail for that market, which is conditional behavior not captured by the schema alone.

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: calculates the cost of the basic basket per market, and with the market parameter it details that market's items. It is clear, but it does not explicitly distinguish itself from siblings such as find_cheapest or compare_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?

It gives clear usage context through examples like 'cesta básica mais barata' and 'quanto custa a cesta no Bistek', and it explicitly limits coverage to Joinville/SC. It lacks explicit guidance on when to prefer this over sibling tools, but the scope and examples make appropriate use clear.

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

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

The description provides crucial operational behavior regarding data timeliness ('Ofertas vigentes hoje; last_known traz vencidas há até 30 dias'), which is behavioral context beyond the provided annotations. It clearly defines the geographical scope (Joinville/SC) which is a critical behavioral constraint.

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 information is highly dense and logically structured: Function -> Data Scope -> Examples -> Limitations. No sentence is superfluous, making it extremely efficient.

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 definition is complete for its domain. It covers function, data source limits (geography), operational behavior (timeframe), and transaction limits (read-only), giving the agent all necessary boundaries for a correct call.

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 description excels at defining constraints for the parameters. It clarifies that 'product' accepts slug, ID, or text, and hard-limits the 'region' to Joinville/SC, providing semantic depth to the technical schema definitions.

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

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

The description clearly defines the tool's core function as comparing products across markets, specifying the output format (cheapest to most expensive). It also implicitly differentiates itself from simple search tools by focusing on comparative pricing and data quality (current vs. last known).

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 tool provides explicit 'when not to use' guidance by stating it only performs consultation and does not handle sales, reservations, or deliveries. Furthermore, it provides concrete usage examples using natural language phrasing, aiding agent adoption.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds domain-specific transparency by saying it is consultation-only and does not sell, reserve, or deliver products, plus a geographic coverage limit. The phrase about following the ChatGPT connector contract adds little actionable information.

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 important details are front-loaded: full offer text by id from search, examples, coverage limit, and read-only behavior. It is efficient overall, though 'segue o contrato do conector do ChatGPT' is vague and does not clearly earn its place.

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

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

For a one-parameter lookup tool with full schema coverage, full annotations, and an output schema, the description covers purpose, id source, geographic scope, and non-transactional behavior. The main remaining gap is sibling differentiation from get_offer, which keeps it short of a 5.

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 single parameter is already documented as the offer_id returned by search. The description reinforces that the id comes from search but adds no format, validation, or edge-case 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 action and resource: return the full text of an offer by id obtained from search. This is clearer than the generic name 'fetch', but it does not explicitly distinguish itself from the sibling get_offer, which appears to cover similar detail retrieval.

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 clear usage context: use the id returned by search, and examples such as 'detalhe da oferta' and 'endereço do mercado dessa oferta'. It also states a clear exclusion (only Joinville/SC, not other cities), though it does not explicitly say when to use get_offer or search_offers instead.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, and the description adds real context beyond them: only offers valid today are considered, results are grouped by product, and the tool never sells, reserves, or delivers. The geographic coverage limit is a useful operational constraint not present 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?

Purpose is front-loaded in the first sentence, followed by freshness, examples, and scope in a tight four-sentence block. Every sentence carries information; no filler.

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

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

With an output schema present, the description needn't explain return values, and it covers the things structured fields can't: freshness window, geographic coverage, and the non-transactional nature. Nothing critical for correct invocation is missing, though routing guidance among siblings would complete 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?

Schema description coverage is 100%, so limit, region, category, and alternatives are already documented in the schema. The description only reinforces the region restriction implicitly via the coverage statement and adds nothing about limits, alternative counts, or category usage. 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?

States a specific verb and resource ("Encontra o menor preço de um produto ou tipo de produto") plus the grouping behavior and the cross-market alternatives. It does not explicitly distinguish itself from the closest siblings (compare_product, search_offers, top_deals), so differentiation is left to inference.

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 when-to-use examples ("onde comprar carne mais barato hoje", "menor preço do leite") and a hard when-not constraint (only Joinville/SC, other cities not served). It stops short of naming an alternative tool for the cases it excludes.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: only currently valid offers are returned, results are paginated, coverage is limited to one city, and the default sort. It does not explain how the cursor expires or whether pagination totals are exposed, but that is a minor gap given annotations and an output schema.

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

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

Three tight lines, front-loaded with what is returned, then the sort semantics, examples, and scope limits. Minor redundancy between the description's sort list and the schema's identical sort description, but no filler.

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

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

For a 6-parameter read tool with full schema coverage and an output schema, the description supplies the pieces that structured fields cannot: geographic coverage limits, the today-only offer window, and example phrasings. Only the omission of any sibling routing keeps it from being 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%, so the schema already documents market, sort, cursor, category, page_size and region. The description's sort enumeration largely restates the schema's own sort description and adds no format or edge-case guidance for cursor or region; 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?

States a specific verb and resource ("Mostra um mercado") and enumerates what comes back: endereços, destaques, categorias e ofertas paginadas. It is immediately distinguishable from search_offers or find_cheapest by its single-market scope, though it never explicitly names list_markets as the way to discover a slug/id.

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 invocation examples ("ofertas do Angeloni", "o que tem no Cooper") and a hard coverage exclusion — only Joinville/SC, not other cities. It also clarifies the tool is read-only ("não vende, não reserva nem entrega"), which is a form of when-not guidance, but it never routes the agent to a sibling tool for out-of-scope requests.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds valuable context by pinning geographic coverage to Joinville/SC and clarifying it only consults ('não vende, não reserva nem entrega'). It doesn't cover failure modes for an unknown or expired offer_id, but the behavioral picture is solid.

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

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

Three short, front-loaded sentences: purpose, trigger examples, then coverage and read-only constraints. The example phrasings partially restate the first line but earn their place as invocation triggers, so 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?

With an output schema present, the description need not explain return values, and annotations plus full schema coverage handle safety and parameter form. The only real gap is what happens when an offer_id is stale or not from the covered city, which an agent would have to discover at call time.

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 a single required UUID parameter, so the schema already carries the meaning. The description's note that the offer_id comes from another tool largely duplicates the property description rather than extending it with format or error guidance. 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 ('mostra o detalhe completo de uma oferta'), adds scope ('com o encarte de origem') and a precondition ('já devolvida por outra ferramenta'). This distinguishes it from the discovery siblings like search_offers or find_cheapest, though it never names one 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?

Gives concrete trigger phrasings ('mais detalhes dessa oferta', 'qual o encarte dessa oferta') and an explicit when-not: 'só Joinville/SC, Brasil; não serve para outras cidades'. It lacks a named alternative for out-of-coverage requests, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful non-annotated context: counts only include currently active offers ('só ofertas vigentes hoje'), the data is region-scoped, and the tool performs no selling/booking/delivery. Output schema exists, so return shape needs no explanation.

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

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

Four short lines, front-loaded with what is listed and how counts are scoped, then examples, then coverage limits. Every line adds something; the closing 'não vende, não reserva nem entrega' is slightly defensive but still earns its place as a side-effect disclaimer.

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

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

For a one-optional-param, read-only listing tool with an output schema and full annotations, the description supplies everything else an agent needs: what is counted, freshness of the counts, geographic limits, and absence of side effects.

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 single param already carries 'só joinville por enquanto'. The description reinforces this by stating coverage is Joinville-only and explicitly not valid for other cities, clarifying what the region argument effectively means in practice.

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 ('Lista as categorias de produto') plus the enrichment it returns ('com a quantidade de ofertas e de mercados'), which is unique among the siblings (search, list_markets, get_offer). It stops short of naming an alternative tool, but no sibling overlaps with category listing, so an agent can select it confidently.

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 concrete example phrasings ('que tipos de produto existem', 'quais categorias têm ofertas') and an explicit geographic exclusion ('só Joinville/SC, Brasil; não serve para outras cidades'). No sibling alternative is named for out-of-region cases, which keeps it from a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the with_active_only=true default, that query overrides that filter, and that a market without current offers is returned with a warning surfaced in meta.notices.

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 the query/default rule, then coverage limits, then scope exclusions. The two example utterances earn their space as retrieval cues, though the block is dense and a slightly tighter phrasing of the default rule would lose nothing.

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?

Output schema covers return shape and annotations cover safety, so the description only needed to supply the default-filter rule, the override behavior, the geographic limit and the read-only scope — all present. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, but the schema's own query description ('Texto da busca (produto)') is misleading for this tool; the description corrects it to market-name confirmation and explains the query/with_active_only interaction rule that the schema only states tersely. Region is left to the schema's 'só joinville por enquanto'.

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 (list covered markets) plus what the result contains (addresses and offer counts), and frames the query parameter as a name-confirmation path rather than a product search, which separates it from search/search_offers. An agent knows exactly what this returns without opening the schema.

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

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

Gives explicit when-to-use triggers (two example user utterances), documents the default behavior without query vs. with query, and states hard exclusions: only Joinville/SC, not other cities, and it does not sell, reserve or deliver. That is the full when/when-not/alternative picture.

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?

Adds real behavior beyond the annotations: a hard cap of 20 results, a freshness window (only offers valid today), a geographic boundary, and an explicit statement that it does not sell, reserve or deliver. The read-only/idempotent profile is already covered by annotations, so no credit is lost there, but pagination/truncation behavior beyond "up to 20" is left unstated.

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

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

Four short, front-loaded lines that each carry distinct information: return shape, freshness, examples, coverage limits. The telegraphic labels ("Cobertura:") are terse but readable; nothing is redundant.

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?

Output schema exists so return-value explanation is a bonus, not a requirement, and the description still covers return fields, freshness, geography and mutation scope. The one material hole is sibling disambiguation against `search_offers`, which the agent cannot infer from the description.

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 one parameter at 100% schema coverage the baseline is 3; the description earns an extra point by showing sample query strings ("ofertas de café", "cerveja em promoção"), which tells the agent the query is a free-form product phrase rather than a structured filter.

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 ("Busca ofertas vigentes") and even the return shape (up to 20 results with id, título, url). It does not, however, distinguish itself from the sibling `search_offers`, which by name alone appears to do the same thing — an ambiguity the description never resolves.

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 example queries and an explicit exclusion ("Cobertura: só Joinville/SC, Brasil; não serve para outras cidades"), which is a genuine when-not rule. It stops short of routing among siblings — `search_offers`, `find_cheapest`, `top_deals`, `compare_product` are never mentioned, so an agent has no signal for choosing between them.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds real behavioral context on top: only currently valid offers are returned unless include_expired=true, and sort defaults to relevance when a query is present. The scope caveat (Joinville/SC only) and the 'consulta only' statement further set expectations.

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

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

Short, front-loaded lines each carrying a distinct rule (filters, validity default, sort modes, examples, coverage, read-only). No filler; the examples are compact and illustrative.

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 not be explained, and the description covers scope, defaults, pagination and read-only behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: market must go in the market field rather than the query text, the sort default depends on whether text is supplied, and pagination uses the cursor. These are genuine clarifications rather than restatements.

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?

Specific verb+resource ('Busca ofertas') with the exact filter dimensions (produto, categoria, mercado, preço máximo, vencimento hoje) and pagination. It clearly separates itself from siblings like top_deals, find_cheapest and get_offer by being the general filtered search.

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 actionable routing rules: put the market in 'market', not in free text, and points to list_categories for category slugs. It also states the geographic scope limitation and that it is read-only (no selling/reserving/delivery). It stops short of naming explicit alternatives for cases like 'cheapest product' vs find_cheapest, so not a full 5.

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

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

Adds real behavioral context beyond the annotations: it only considers offers valid today, and it explicitly disclaims commerce actions ('não vende, não reserva nem entrega'), reinforcing readOnlyHint. The geographic limitation and the temporal scope are the kind of constraints annotations cannot express. It stops short of describing result ordering/pagination, which is partly covered by the output schema.

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

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

Front-loads the core capability, then scope, then examples, then constraints — a sensible ordering with no filler. The example list is slightly verbose but earns its place by showing intent matching.

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 and full annotation coverage, the description supplies exactly the missing pieces: what 'top' means (savings vs average), the aggregation axes, the temporal filter, and the hard geographic boundary. Nothing needed to call it correctly is 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?

Schema description coverage is 100%, so the schema already documents limit, market, region, category and ending_today. The description adds the conceptual dimensions (overall/category/market) that map to those params, but introduces no format or syntax detail beyond the schema. 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 (lists top deals ranked by savings versus the average) plus the three aggregation scopes (overall, by category, by market). This clearly distinguishes it from siblings like find_cheapest or search_offers, which are filter/lookup tools rather than ranked 'best value' lists.

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 example utterances ('melhores ofertas agora', 'melhores ofertas de bebidas', 'o que o Giassi tem de bom hoje') that map user intent to the tool, and states a hard geographic exclusion (only Joinville/SC, does not serve other cities). It does not explicitly name a sibling as the alternative for out-of-scope requests, so it stops short of a 5.

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