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

Beyond the annotations (non-readOnly, non-idempotent), it discloses the real consequence: reserved units reduce availability for other customers until checkout or removal. The re-add accumulation rule crisply explains why the call is not idempotent, and the error list names the insufficient-stock failure with the number of available units returned.

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 first sentence front-loads the action and its side effect; the Args/Returns/Erros blocks are scannable and each line carries information. Slightly long for a four-parameter tool, and the Returns block is partly redundant 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?

Covers what the call does, its side effect on shared stock, the accumulation rule, and every documented failure mode with what the error message contains. With an output schema present, the brief Returns line is sufficient rather than a 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 baseline is 3; the description earns one more by tying parameters to behavior — quantidade must be > 0, tamanho restricted to P/M/G/GG, and the same produto_id+tamanho pair merges into an existing line rather than creating a new one, which changes how an agent should call it repeatedly.

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 ('Adiciona um item ao carrinho') plus the side effect ('RESERVA as unidades no estoque'), and the sibling set makes the add-vs-remove distinction obvious. An agent can tell immediately this is the cart-write path, not a read like ver_carrinho or verificar_estoque.

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?

Explains the operational consequence of reserving stock and that the same product+size accumulates quantity, and implies reversal via 'até o pedido ser finalizado ou o item ser removido'. It does not explicitly point at verificar_estoque as a pre-check or name remover_do_carrinho as the undo path, so a small inference remains.

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 as read-only, idempotent, non-destructive and closed-world, so the description only needs to add behavior beyond that. It contributes real value by documenting the error path ('Produto não encontrado. A mensagem lista os IDs existentes') and by explaining that `disponivel_por_tamanho` is physical stock minus reservations, a non-obvious business rule.

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 one-line purpose followed by short Args/Returns/Erros blocks — easy to scan and no wasted prose. The Args section is near-redundant with the schema, which slightly dilutes it, but the structure remains 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?

For a single-parameter lookup with full annotations and an output schema, the description covers the essentials: what is returned, where the ID comes from, and how failure behaves. The only gap is guidance on preferring verificar_estoque when only stock is needed.

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 fully described in the schema, so the baseline is 3. The description's 'ID do produto, obtido em listar_produtos' restates the schema text verbatim rather than adding format or constraint 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 ('Retorna todos os detalhes de um produto') and enumerates what details are included (descrição, cores, tamanhos, preço, disponibilidade por tamanho). This clearly separates it from listar_produtos, which only lists. It does not explicitly address the overlap with verificar_estoque, which also reports availability.

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

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

The description gives concrete usage context by telling the agent where the required ID comes from ('obtido em listar_produtos'), which chains it correctly after the listing tool. It lacks an explicit exclusion rule against verificar_estoque for stock-only lookups, so it is clear context but not 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?

Goes well beyond the annotations by disclosing concrete side effects: the cart is converted, stock is decremented, and the cart is cleared, plus a list of error conditions. What is missing is an explicit statement that the operation is not idempotent and cannot be undone/replayed, which matters for a checkout finalizer with idempotentHint=false and destructiveHint=false.

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

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

Front-loaded summary sentence, then prerequisite, then Args/Returns/Erros sections — easy to scan. The Args block is somewhat redundant given full schema coverage, which keeps it from a 5.

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 mutating checkout tool it covers the essential ground: side effects, prerequisite confirmation step, return payload contents, and failure modes. The gaps are non-idempotency/duplicate-order behavior and what state the cart is left in on partial failure, so it stops short of 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%, so both parameters are already documented in the input schema, including the 'use o mesmo valor em toda a compra' note for session_id and the address component breakdown. The Args section in the description largely restates that, adding no format or validation 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 and resource ('Finaliza a compra: converte o carrinho em pedido') plus the side effects (baixa estoque, limpa carrinho), which distinguishes it from siblings like ver_carrinho or adicionar_ao_carrinho. An agent can identify this as the terminal checkout action without reading 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?

Explicitly routes the agent to the sibling 'ver_carrinho' and states the precondition of confirming the cart with the customer before calling. It also enumerates the blocking conditions (carrinho vazio, endereço vazio/incompleto), which doubles as a when-not-to-call signal.

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, closed-world behavior, so the bar is lower, and the description adds real context: the exact fields returned, summation across sizes, and the error case where an invalid category lists valid ones. It doesn't mention pagination or result-size limits, which would matter for a catalog listing.

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 purpose sentence followed by usage, then structured Args/Returns/Erros sections. There is mild overlap with the schema on the category list, but the extra semantics justify the length.

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, yet the description still summarizes the returned fields and the total count, and it documents the error path. Combined with full parameter coverage and annotations, an agent has everything needed to call 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 coverage is 100%, so baseline is 3, but the description adds behavior the schema lacks: the filter is case- and accent-insensitive ('calcas' also works). That is genuinely useful matching semantics an agent could not infer from the anyOf string type.

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 os produtos do catálogo'), names the store, and implies its role versus the id-based and stock siblings. An agent can distinguish this from buscar_produto_por_id or verificar_estoque without opening any 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?

Explicitly says when to use it: 'descobrir o que existe à venda antes de recomendar ou adicionar itens', which ties it to the recommendation and cart flows. It stops short of naming an alternative tool or stating 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?

Annotations already declare the mutation profile (readOnly false, idempotent false, destructive false), and the description adds real value on top: the reservation is returned to stock, a confirmation plus updated cart comes back, and the specific error conditions are enumerated. Consistent with destructiveHint=false since stock is restored.

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 one-sentence purpose followed by Args/Returns/Erros sections that are each short and skimmable. Minor redundancy with the schema's parameter descriptions, but nothing is padded.

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 the Returns block is a bonus rather than a requirement, and the error taxonomy covers the realistic failure modes. For a 4-parameter mutation tool the definition leaves no significant ambiguity about inputs or outcomes.

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 all four parameters are already documented, and the Args block largely restates them. It does add the conditional behavior for 'quantidade' (omitted = remove the whole line) and the upper bound against the cart quantity, but that is only marginal 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 (remove) and resource (item from cart) plus the scope qualifier 'inteiro ou em parte', and discloses the stock-restoration side effect. It is clearly the inverse of adicionar_ao_carrinho, though the description never names that 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?

The omission rule for 'quantidade' implies when to do a full-line vs partial removal, and the Erros section bounds valid input. There is no explicit guidance on when to use this versus correcting the cart another way (e.g. ver_carrinho first, or reducing quantity vs deleting the line).

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 behavior. The description adds useful behavioral detail that an empty session returns an empty cart with total R$ 0,00 and that totals are calculated, without contradicting 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?

Purpose is front-loaded and the Args/Returns structure is easy to scan. The Args section largely repeats a fully documented schema field, though the Returns section earns its place by adding empty-cart behavior.

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?

This is a simple single-parameter read tool with rich annotations and an output schema. The description covers purpose, return shape, and the empty-cart edge case, so 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?

Schema coverage is 100%, and the schema already documents session_id with an example and reuse instruction. The description only restates that it identifies the customer's cart, adding no new parameter semantics.

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, 'Exibe', and resource, 'conteúdo atual do carrinho', plus the total calculation. It is unmistakably the read-only cart-viewing sibling, distinct from add/remove/finalize tools, even without naming 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?

Implies use for inspecting a customer's current cart, but does not explicitly say when to choose it over siblings or state prerequisites. No exclusions or workflow guidance 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 readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description goes further by explaining what the numbers mean (physical stock, reserved in carts, addable units) and by listing the error cases (product not found, size outside the grid). Return-value detail overlaps the existing output schema, which keeps this 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 summary followed by Args/Returns/Erros sections is easy to scan and appropriately sized. The Returns block duplicates the output schema, so a sentence or two does not 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 two-parameter read-only lookup this covers purpose, pre-cart usage, accepted size inputs, and failure modes, while the output schema carries the return shape. An agent has everything needed to call 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 coverage is 100%, so both parameters are already documented, and the Args block largely restates them. The one genuine addition is "aceita minúsculas" for tamanho, a case-insensitivity rule the schema does not mention, which prevents a real invocation error.

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

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

The first sentence names a specific verb (consulta) and resource (estoque disponível) scoped to a product and size, which is clearly distinct from sibling tools like listar_produtos and buscar_produto_por_id. It stops short of explicitly naming those siblings or stating what it is not, so it lands at clear-but-not-differentiated.

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?

"Consulte antes de adicionar ao carrinho" gives an explicit workflow trigger that ties it to the adicionar_ao_carrinho sibling. It states when to use it clearly but gives no when-not conditions or alternatives for other stock-related questions.

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