Actualización masiva

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

Las anotaciones ya indican que es destructiva, y la descripción añade comportamiento útil: es transaccional, los IDs inexistentes se reportan en 'errors' y no abortan el resto de la operación. También explica la semántica de mode='set' y mode='add'.

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?

La descripción es breve, está bien estructurada y cada frase aporta: funcionalidad principal, formato de items, modos, casos de uso y manejo de errores. No hay contenido redundante ni relleno.

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?

Dado que no hay esquema de salida, la descripción explica cómo se reportan los errores, lo cual es valioso. Cubre los parámetros clave y el efecto de la operación, aunque no detalla el formato completo de la respuesta exitosa; aun así, es suficiente para invocar la herramienta correctamente.

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?

La cobertura del esquema es del 50%: items está documentado, mode no. La descripción compensa explicando qué hace cada modo y que cada item debe tener {card_id, quantity}, añadiendo significado más allá del enum y del arreglo.

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?

La descripción usa un verbo específico y un recurso claro: actualizar cantidades de múltiples cartas en una llamada transaccional. Se distingue de su hermano set_card_quantity al enfatizar el carácter masivo, y explica los dos modos de operación.

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?

Indica cuándo es ideal usar esta herramienta: al procesar capturas de pantalla de la colección o dictados del usuario. No menciona explícitamente alternativas para actualizaciones individuales, pero el contexto y la palabra 'masiva' hacen clara la diferencia.

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