busca-produtos

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

With no annotations, the description carries the full burden and does disclose a non-obvious behavioral contract the schema cannot express: the caller must NOT construct the search term, and the tool derives and ranks it against context. It also notes the standardized return with link. It stops short of permission, rate-limit or failure behavior, 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 the scenario and the action, then the routing rule for who builds the search term, then the return shape. Sentences are dense and earn their place, though the context description is partly repeated from 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?

There is no output schema, so the description usefully states what comes back ('produtos padronizados com link'). Combined with 100% parameter coverage and the latency/tradeoff notes in the schema, an agent has enough to invoke it correctly; only error/auth behavior 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 baseline is 3. The description restates that 'context' should include what/for whom/color/size/price/rejected brands, which mirrors the schema field text rather than adding new syntax or format details.

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 ('encontra produtos reais à venda') and a precise input trigger ('Dado o RESUMO de uma conversa com um cliente'), plus the concrete outcome (products with a ready purchase link). It also names the multi-store scope, making it instantly distinguishable from listar_lojas, live_leads and negociar_local.

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 activation condition: 'Use assim que o cliente demonstrar intenção de comprar.' This is clear when-to-use guidance. It does not name an alternative tool or state when NOT to use it, but the sibling tools are functionally unrelated, so the omission is minor.

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?

No annotations are present, so the description carries the full behavioral burden. It discloses the key trait that would otherwise mislead an agent: this is a CURATED highlights list, not an exhaustive inventory, and it is not authoritative for product/brand availability. It omits anything about result size limits or refresh cadence, but for a static reference list this is largely sufficient.

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

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

Three sentences, front-loaded with what the tool returns before the usage guidance and the routing caveat. The parenthetical segment list is long but genuinely informative about result contents, so it earns its space.

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

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

With no output schema and no annotations, the description still explains what comes back (stores grouped by segment plus a total count) and its curated limitation, which is what an agent needs to call and interpret it. It does not state the response format or whether the list is paginated, a minor gap for a zero-argument static 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?

The tool takes no parameters, so the baseline is 4. The description correctly adds no parameter detail, and schema description coverage is 100% anyway.

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 precise verb+resource (list stores covered by BuscaZap) and specifies the shape of the result: grouped by segment, plus a total of +180 stores. It explicitly distinguishes itself from 'buscar_produtos_por_contexto', so an agent can pick between them 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?

Gives concrete trigger phrasings ('quais lojas vocês têm?') and a clear intent (check coverage before searching), plus an explicit exclusion rule: to confirm a specific product/brand, use 'buscar_produtos_por_contexto' instead. When-to-use and when-not-to-use are both covered.

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?

With no annotations, the description must carry the full behavioral burden. It usefully discloses an Enterprise plan requirement, a setup step (generate a key at a URL), real-time delivery, and the data nature (georeferenced purchase intent). It does not cover side effects, rate limits, return format, or whether the operation is read-only.

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 lock/plan requirement and the core purpose. The setup instruction is brief and directly actionable. No filler or 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 tool with one undocumented parameter, no annotations, and no output schema, the description leaves key gaps. It does not explain what 'segment' does, what a returned lead looks like, how results are delivered (streaming vs polling), or any rate limits, making it insufficient for reliable 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 schema has one parameter ('segment') with 0% description coverage, and the description never mentions it. No meaning, format, allowed values, or effect of 'segment' is provided, so the description does nothing to compensate for the schema gap.

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: 'Entrega leads quentes em tempo real' (delivers hot leads in real time). It also specifies the lead type (georeferenced purchase intent) and target audience (partner merchants), clearly distinguishing it from siblings like product search, store listing, and local negotiation.

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 a clear precondition ('Requer plano Enterprise') and target audience ('para lojistas parceiros'), which implies when the tool is appropriate. However, it does not compare against or route to alternatives like buscar_produtos_por_contexto, listar_lojas, or negociar_local, nor does it state when not to use it.

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

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

With no annotations, the description carries the full behavioral burden, yet it only discloses the plan requirement. It does not say whether this contacts real stores autonomously, whether commitments/charges are irreversible, expected latency, or rate limits — critical for a tool that performs real-world outreach.

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 plus a link, front-loaded with the capability and the plan constraint. The key-generation URL is somewhat tangential but compactly stated.

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 an action tool with a required undocumented parameter, no annotations, and no output schema, the description is too thin: it omits the parameter meaning, the expected behavior/return, and the real-world consequences of triggering negotiation agents.

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 single required 'context' parameter has 0% schema description coverage, so the description must compensate — and it never mentions the parameter at all. An agent is left guessing what 'context' should contain (product, target store, negotiation goal?).

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

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

The description names a specific action and resource: it triggers agents that negotiate price/conditions directly with the local physical store on the customer's behalf. That is distinct from the read-only siblings (search products, list stores, live leads), though the differentiation is left implicit rather than stated.

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 discloses a gating prerequisite (Enterprise plan required), which is useful usage context. However, it never states when to prefer this over the sibling tools or in what scenarios negotiation is appropriate, 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.