El cerebro del conector (memoria del negocio)

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

Las anotaciones declaran readOnlyHint=true mientras la descripción describe explícitamente operaciones de escritura y borrado ('guarda lo que el vendedor le enseña', acción 'olvidar') que persisten en un archivo local. Es una contradicción directa entre descripción y anotación. El resto del texto (todo queda en la máquina del vendedor, nunca sale de ahí) sí aporta contexto valioso, pero la contradicción domina la dimensión.

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?

Está front-loaded: primero qué es la base, luego el beneficio (las otras herramientas la usan), luego la privacidad local y al final las acciones. Algo de relleno conversacional ('deja de preguntar lo que ya sabe'), pero cada bloque aporta información distinta.

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?

Para 8 parámetros sin output schema, cubre qué se guarda, dónde vive el dato y qué acciones existen. Faltan detalles que un agente necesita: qué devuelve 'ver' (formato/estructura), si 'olvidar' borra todo el item o solo campos, y si guardar es idempotente; la anotación errónea tampoco ayuda a saber si hay efectos.

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?

Con cobertura de esquema del 100% la línea base es 3, y la descripción añade valor real: explica la semántica de item_id ('sin item_id, el dato es del negocio entero') y enumera los campos almacenables, mapeándolos a costo, impuestos_pct, costo_envio, medidas, incluye y nota. No aclara si guardar sobrescribe o mezcla datos existentes del mismo item.

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?

Es un verbo y recurso específicos: una base de datos de memoria local del negocio que guarda costo, impuestos, envío, medidas, incluye y notas. Además se diferencia de sus hermanas al explicar que otras herramientas (la calculadora de rentabilidad) la consumen solas, algo que ningún otro nombre de la lista sugiere.

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?

Enumera los tres modos (guardar, ver, olvidar) y da una regla de enrutamiento concreta: para datos del negocio entero, guardar sin item_id. No dice cuándo NO usarla ni cómo se relaciona con ml_rentabilidad más allá de la mención pasiva, pero el contexto de uso queda claro.

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