remover_do_carrinho

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.