olist_pedido_estornar_estoque

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Esta operação altera dados e exige confirmar=true', alerting the agent that this is a mutating operation requiring confirmation. It also provides a documentation link. However, it does not detail side effects or specific data affected beyond the general statement.

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 three concise sentences, front-loaded with the purpose and including the endpoint and documentation. Every sentence provides useful information without redundancy or padding.

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?

Given the tool's simplicity (2 simple params, no output schema) and the lack of annotations, the description covers the essential context: what the operation does, the API endpoint, documentation, and the mutating nature requiring confirmation. It does not describe return values or error behavior, but that is not critical for this mutation-focused tool.

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 already describes both parameters (id and confirmar) with 100% coverage. The description adds no additional parameter semantics beyond reiterating that confirmar must be true, which is already encoded in the schema as a const.

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 states the operation: 'Estornar Estoque do Pedido' (reverse order stock) with a specific verb and resource. It also provides the exact API endpoint (pedido.estornar.estoque) and notes it's API 2.0, distinguishing it from sibling tools like olist_pedido_lancar_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?

The description implies when to use the tool (to reverse order stock) but does not explicitly state alternatives or exclusions. It mentions the confirmation requirement and gives a documentation link, but lacks clear guidance such as 'use this instead of X' or 'do not use if...'.

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