adicionar_ao_carrinho

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.