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

readOnlyHint=false already declares a write, and the description adds genuinely useful behavioral context beyond that: the change is buyer-visible ('Visible para compradores') and tied to a specific price, signalling real-world impact. It does not cover reversibility or failure behavior, but the visibility warning is meaningful additional disclosure.

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?

Two tight sentences, front-loaded with the action verb and impact, then the constraint. No filler. Slightly terse – it leaves no room to explain account selection or outcomes – but nothing is wasted.

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?

For a mutation that makes a price-promotion publicly visible, the description covers purpose, price and confirmation but omits failure behavior, reversibility, and how cuenta affects multi-account setups. With no output schema and 60% parameter coverage, a few more specifics would make it complete.

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 60%, so the schema documents tipo, cuenta and precio_final while item_id and promocion_id are bare. The description adds only the 'al precio indicado' reference, loosely mapping to precio_final, and nothing beyond the schema for the undocumented parameters. Baseline 3 is warranted.

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?

Specific verb (ACTIVA) plus resource (una publicación dentro de una promoción) and the price context. An agent can distinguish this action tool from the listing sibling ml_promociones without opening the schema. It stops short of explicitly naming that sibling as the read counterpart, so it is strong but not maximally differentiated.

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?

Provides a real usage condition – 'usar solo con confirmación explícita por ítem' – which effectively gates invocation and functions as a when-to-use guard rail. It does not, however, name alternatives or state when-not beyond the confirmation requirement. Clear context without explicit alternatives.

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

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

Annotations only declare readOnlyHint=false; the description adds that the operation modifies a real publication and requires explicit user confirmation. It does not disclose whether changes are reversible, what side effects occur, or permission requirements, so behavioral detail remains thin.

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?

One concise sentence with the verb front-loaded in caps and the usage condition appended. No filler or redundant restatement.

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?

For a 5-param mutation tool with low schema coverage and no output schema, the description is too sparse: it does not explain item_id, the cuenta parameter, or the return/effect of the change. It covers purpose and confirmation but leaves key invocation details missing.

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 description coverage is only 20%, so the description carries more weight. It names precio, stock, and estado as modifiable fields and clarifies estado via pausar/activar, but omits item_id (required) and cuenta, leaving two parameters without added meaning.

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 (MODIFICA) and resource (publicación real) and enumerates the modifiable fields. It does not name any sibling tool to distinguish from ml_crear_publicacion or ml_publicaciones, so it stops short of full sibling differentiation.

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?

Explicitly says to use only with explicit user confirmation, which is a clear usage condition. It does not mention alternatives or when-not-to-use beyond that confirmation gate.

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

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

readOnlyHint=true already signals a safe read; the description goes further by disclosing ordering ('devuelve las peores primero') and what the audit flags (short/padded title, few photos, no description, critical stock, lost catalog, paused listing). It does not disclose pagination or result limits behavior, but the output-shaping context is real added value.

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 with the core capability, then the flagged conditions, then the routing cue. The condition list is long but each item earns its place by telling the agent what the audit surfaces. Minor redundancy between the semáforo phrase and the condition list.

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?

No output schema exists, so the description must explain returns — and it does (worst-first ordering plus concrete remediation action per listing). With all 3 params documented and safety covered by annotations, only per-field return detail is thin.

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 description coverage is 100% and each parameter (cuenta, estado, limite) is documented with defaults. The description adds no parameter-level syntax or constraints, so the baseline 3 applies since the schema carries the full load.

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?

Specific verb (auditar/listar) plus resource (publicaciones) plus a distinguishing angle: a quality 'semáforo' with remediation per listing. An agent can tell this apart from ml_publicaciones (plain list) and ml_publicacion (single-listing detail) without opening any schema.

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 closing line 'Ideal para "¿qué publicaciones tengo que mejorar?"' gives an explicit triggering context. However, it never names an alternative (ml_publicaciones, ml_actualizar_publicacion) or states when-not to use it, so routing is contextual rather than prescriptive.

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

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

readOnlyHint=false already signals a mutating operation. The description usefully adds that the clip can be deleted regardless of moderation state, but says nothing about permanence/irreversibility, whether the clip is recoverable, or permission requirements — meaningful gaps for a delete tool.

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?

Two short sentences, zero padding, with the action stated first. Efficient and front-loaded, though slightly terse given the destructive nature of the operation.

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?

For a simple delete with a write annotation and no output schema, the description covers scope and use case, but omits consequences of the deletion and the partially-undocumented item_id parameter, leaving an agent with avoidable uncertainty.

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 67%: cuenta and clip_uuid are documented in the schema, but item_id is not. The description adds no parameter-level detail (syntax, ids, relationship between item_id and clip_uuid), so it neither compensates for the gap nor goes 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 (borra) and resource (un clip de una publicación), plus a concrete use case. It is distinguishable from ml_subir_clip and ml_clips by the deletion semantics, though it never names those siblings 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?

Provides a clear when-to-use context ('uno rechazado, para subir la versión corregida') and a scope note ('funciona en cualquier estado de moderación'). No explicit alternatives or exclusion conditions are given, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds that it searches only 'públicas' listings, but says nothing about pagination behavior, how 'limite' bounds results, whether a site must be specified, or rate limits.

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?

A single front-loaded sentence with no waste; the verb and resource come first and the parenthetical earns its place by signaling intent. It is perhaps slightly too terse for a 4-parameter tool, but structurally efficient.

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?

For a tool with 4 parameters (2 undocumented), no output schema, and only a readOnly annotation, the description is too thin. It does not explain the shape of results, whether 'sitio' defaults to a specific country, or how 'limite' interacts with result pages — context an agent needs to call it correctly.

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 only 50%: 'consulta' and 'cuenta' are documented in the schema, while 'sitio' and 'limite' carry no descriptions anywhere. The description adds no parameter meaning at all, so it fails to compensate for the half of the schema that is undocumented.

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 (Busca) and resource (publicaciones públicas en MercadoLibre), plus the intended purpose (competitor and price reconnaissance). However, it does not distinguish itself from similarly competition-oriented siblings such as ml_novedades_competencia, ml_historial_competencia, or ml_descubrir_ganadores, leaving the agent to infer the difference.

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 parenthetical '(para espiar competencia y precios de mercado)' implies a use context, so usage is suggested rather than absent. But there is no explicit when-to-use rule, no exclusions, and no routing to alternatives among the many competitor-tracking siblings.

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

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.

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

With readOnlyHint=true already covering the read-only nature, the description adds substantial behavioral context: moderation states (published, under review for 24-48 hours, rejected with reason and correction guidance) and the store-wide video map behavior when item_id is omitted. This goes well beyond annotations.

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 dense but front-loaded and organized around the item_id condition. It uses one long sentence with parenthetical details and emoji status markers, which is efficient though slightly heavy for a single sentence.

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?

For a read-only tool with two optional parameters and no output schema, the description gives enough detail about what is returned in both modes, including moderation outcomes and store video map prioritization. No critical invocation context appears missing.

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 adds meaning for item_id by explaining that including it returns per-clip moderation status, while omitting it returns a store-wide video map, which supplements the schema's 'una publicación puntual; sin indicarlo, mapa de toda la tienda (hasta 10)'.

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 states a specific verb and resource: 'Consulta los Clips ... de tus publicaciones' and explains the two behavioral modes based on item_id. It is clear what the tool does, though it does not explicitly name sibling tools like ml_subir_clip or ml_borrar_clip to differentiate the read-only consultation role.

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?

It gives clear context for when to pass item_id versus omit it: with item_id it shows each clip and moderation status; without it, it scans active publications and builds a store video map. It does not, however, explicitly state when to choose this tool over alternatives such as ml_publicacion or ml_publicaciones.

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

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

readOnlyHint=true already signals a safe read/compute operation, so the description need not restate safety. It adds that the output is a commission broken down by listing type, which is useful context, but it says nothing about whether all costs (shipping, fees) are included or what the result shape is.

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?

A single, front-loaded sentence with the core purpose stated first and the intended use appended cheaply. No filler, every clause carries meaning.

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?

There is no output schema, so the description should describe the return more fully; it names the returned quantity (commission by listing type) but omits the format and whether other costs are included. For a 4-parameter compute tool this is adequate but leaves the return underspecified.

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?

With 50% schema description coverage, the schema documents 'cuenta' and 'categoria' but leaves 'sitio' and the required 'precio' undocumented. The description hints that precio is the sale price and that a listing-type dimension affects the result, but adds no syntax or format detail 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?

The description states a specific verb+resource: it tells you how much MercadoLibre charges in commission for selling at a given price. It even scopes the result (commission per listing type) and the intent (to compute margins). It's clear, though it doesn't explicitly differentiate itself from near-neighbors like ml_rentabilidad.

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 phrase 'para calcular márgenes' implies the usage context, so the agent can infer this is for margin/profit calculations. However, there is no explicit when-to-use/when-not guidance and no mention of alternatives such as ml_rentabilidad or ml_precio_catalogo.

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

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

Annotations declare readOnlyHint=true, but the description says calling with `code` 'completa la conexión', which persists OAuth credentials and mutates account state. That is a direct contradiction between the declared read-only profile and the described behavior, and no further behavioral context (token lifetime, effect on the existing connection) is offered.

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?

Two compact sentences that front-load the account-linking action and then the branching behavior, with the prerequisite appended last. No filler.

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 the main call paths and configuration prerequisites, but for an auth/credential tool it omits what happens to an existing connection, whether tokens are stored and refreshed, and what the no-argument response contains. The readOnlyHint contradiction also leaves the agent with an inaccurate safety picture.

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% and the `code` property is already documented in-schema; the description only restates where the code comes from. The `sitio` parameter (country/site selection) is never mentioned in the description, so it adds little 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 and resource ('Vincula una cuenta de MercadoLibre') and clearly splits the two operating modes (no args = URL, with `code` = complete). It doesn't explicitly name the counterpart ml_desconectar, so sibling differentiation is left to inference.

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?

Gives a clear two-step flow: call without arguments to get the authorization URL, then call with the `code` shown by the page to finish. It also states the prerequisite configuration (ML_APP_ID, ML_APP_SECRET). No explicit 'don't use when already connected' exclusion is given.

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

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

Annotations only declare readOnlyHint=false; the description adds substantial context beyond that: the operation creates a REAL listing, clone mode copies title/category/attributes/photos/description (with an IP caution about only copying own content), and overriding title/price/stock is permitted. A user-confirmation requirement is stated. It does not describe failure modes or what the response returns, but the mutation semantics are well disclosed.

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?

Three sentences, front-loaded with the verb and the high-stakes nature of the operation, then the clone mechanic, then the safety constraint. No filler; each sentence carries distinct information.

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?

For a 10-parameter mutation with no output schema, the description covers the two operation modes (fresh create vs clone-and-override) and the confirmation requirement. It leaves the required-parameter logic partly to the schema descriptions, but nothing critical to correct invocation is missing.

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 60%, so several params (tipo, cuenta, condicion, descripcion) rely on the schema alone. The description nonetheless adds real meaning: it explains what copiar_de clones and that titulo/precio/stock can override the cloned values, and the schema itself already flags which fields are 'Obligatorio si no hay copiar_de'.

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?

Starts with an emphatic specific verb+resource ('CREA una publicación real en la tienda'), making clear this is a genuine write to the listing store, not a draft. The clone mode is spelled out precisely ('clona una publicación existente... permite pisar título/precio/stock'), so an agent can tell it apart from the sibling ml_actualizar_publicacion.

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?

Gives an explicit usage constraint ('Usar solo con confirmación explícita del usuario') and a positive use case ('ideal para duplicar entre tus propias cuentas'). It does not name an alternative tool for the case where the user wants to modify an existing listing, which would have made routing unambiguous.

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

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

The annotations declare readOnlyHint=true, but the description says 'Con predeterminada fija cuál usar cuando no se indica cuenta' and the parameter is a user_id 'a fijar como predeterminada', implying a persistent write operation. This directly contradicts the read-only annotation.

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?

Two short sentences with no wasted words: the first establishes the listing scope, the second explains the optional parameter. It is front-loaded and appropriately sized.

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?

For a simple one-parameter tool this is mostly adequate, but there is no output schema and the description does not describe what a returned 'cuenta' contains or whether listing is paginated. The dual read/write ambiguity also leaves context incomplete.

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, but the description adds the contextual meaning that predeterminada sets which account to use when no account is specified. This goes beyond the schema's plain 'user_id de la cuenta a fijar como predeterminada'.

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 states a specific verb and resource: 'Lista las cuentas de MercadoLibre conectadas' and adds multi-store context. It does not explicitly compare itself to sibling tools like ml_conectar or ml_desconectar, but the listing purpose is clear.

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?

No guidance is given on when to use this tool instead of alternatives such as ml_conectar or ml_desconectar. The description only explains the effect of the optional parameter, not tool selection or prerequisites.

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

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

readOnlyHint=false already signals a mutating operation, and the description usefully adds what is destroyed (saved tokens) and the scope of the effect (connection on this computer only). It does not say whether reconnection requires re-authentication or whether the change is reversible, but it adds real context beyond the annotation.

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?

A single front-loaded sentence with the action first and the consequence in parentheses; nothing is padded or redundant.

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?

For a one-parameter tool with no output schema, the description gives the essential effect and its scope. Minor gap: it leaves ambiguous whether the token revocation is purely local or also server-side, which matters for an agent reasoning about re-authentication.

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 description coverage is 100% for the single required parameter (cuenta / user_id), so the schema carries the load. The description adds no further meaning about the parameter, which is the expected baseline when coverage is complete.

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: deleting an account's stored tokens, with the observable effect (account is no longer connected on this machine). It is clear enough to distinguish from a generic delete, though it never names the counterpart sibling ml_conectar 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 parenthetical implies the intended scenario (you want the account to stop being connected here), but there is no explicit when-to-use or when-not-to-use statement and no pointer to the complementary ml_conectar tool. Usage is inferred rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower, yet the description still adds substantive behavioral context: it discloses the data sources and the exact dimensions analyzed (competition, prices, free shipping, dominant sellers, visible sales). It omits rate limits, result volume and pagination, so it is not a full 5.

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 with the core action, then two parallel clauses for the two modes, then the input instruction. Dense but every clause carries information; only slight compression loss from packing the keyword-analysis dimensions into one long sentence.

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?

For a read-only analytical tool with no output schema, the description covers both operating modes and what each returns conceptually. It leaves the sitio parameter and the multi-account context (only glancingly referenced via ml_cuentas) implicit, so an agent may not know how to scope the query when several accounts are connected.

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?

At 75% schema coverage the schema already documents cuenta, busqueda and categoria, so a 3 would be defensible. The description earns above baseline by explaining the routing semantics that the schema does not: categoria activates the official ranking+trends path while busqueda activates the keyword market-analysis path, i.e. they are alternative drivers. The undocumented 'sitio' parameter is never mentioned in the description.

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 (encuentra/descubrir) and resource (artículos ganadores) and even splits the behavior into two concrete modes: category mode (official best-seller highlights + trends) and search mode (market analysis of a keyword). This is far more than a restatement of the title. It falls short of a 5 because it does not name or differentiate itself from likely-overlapping siblings such as ml_tendencias, ml_novedades_competencia or ml_buscar.

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 closing line ('Indicar categoria ... o busqueda') tells the agent which input selects which mode, which is genuine usage guidance. However, it never states when to choose this tool over alternatives like ml_tendencias or ml_buscar, nor any prerequisite (e.g. that a connected account is needed). Usage is implied rather than contrasted with siblings.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful disclosure of what the response contains (tracking, status and dates), which matters since there is no output schema, but it says nothing about permissions, the multi-account 'cuenta' context, or failure behavior.

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?

A single front-loaded sentence with no padding. It is efficient, though the extreme brevity leaves useful routing information out rather than being genuinely complete.

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?

For a simple read-only lookup with full schema coverage the bar is modest, and without an output schema the description's mention of the returned fields partially compensates. Still, it omits the relationship to ml_ordenes and the meaning of the optional 'cuenta' parameter, leaving gaps an agent must guess at.

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 description coverage is 100%, so both parameters are already documented in the schema. The description's tracking/estado/fechas list refers to outputs, not inputs, so it adds no parameter meaning beyond the schema. Baseline 3 applies.

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 resource (el envío de una orden) and enumerates what it exposes (tracking, estado y fechas), so an agent knows this reads shipment status. It does not, however, distinguish itself from the sibling ml_ordenes, which could plausibly also touch order data.

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 gives no when-to-use guidance, no indication of when to prefer ml_ordenes over this tool, and no mention that an orden_id is required to call it. Usage must be inferred entirely from the name.

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

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

readOnlyHint=true already establishes the read-only safety profile. Beyond that, the description adds genuinely useful behavioral context: the store is automatically populated by each ml_novedades_competencia check, so the agent knows it is a passively-maintained derived dataset rather than a user-written one, and knows its freshness depends on those checks.

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?

Two sentences that front-load the core identity ('La base de datos de competencia') before the enumeration and the provenance note. No filler, though the three-variant list is slightly dense and the trailing sentence is a bit of an aside.

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?

With no output schema, the description carries the burden of describing what comes back, and it does list the tracked metrics and the time-evolution nature, so the agent can anticipate the payload. It does not specify granularity, date-range handling, or pagination, but for a read-only tool with a rich annotation and full schema coverage it is largely complete.

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 description coverage is 100% and the single 'ref' parameter is fully documented there (including the item_id/nickname/keyword forms). The description repeats the notion of a tracked objective but adds no syntax, format, or matching rules beyond the schema, so the baseline 3 is appropriate.

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 names a specific resource — a competition history database tracking the evolution over time of a watched objective — and enumerates three concrete variants (rival publication price/sales, search leader price, seller publication count/median price). It also names the sibling ml_novedades_competencia as its data source, which helps distinguishing it from that tool. It lacks an explicit action verb ('consultar'/'obtener'), but the noun-phrase scope is nonetheless unambiguous.

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 note that the database 'se alimenta sola con cada control de ml_novedades_competencia' implicitly tells the agent that ml_novedades_competencia drives updates while this tool serves the historical view. However, there is no explicit 'use this when / do not use this when' statement and no comparison against siblings like ml_tendencias or ml_descubrir_ganadores, leaving selection partly to inference.

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

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

Annotations only declare readOnlyHint=true, so the description adds real behavioral value: it discloses that results are compared against the previous period and that cuenta="todas" consolidates all connected stores. Return format/pagination is not addressed, keeping it short of a 5.

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?

Three compact sentences with the returned metrics front-loaded and the usage hint and special parameter value last. No filler, though the quotation-style usage example is slightly informal for a tool definition.

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?

For a read-only, two-optional-parameter tool with no output schema, the description covers what comes back, the comparison baseline, and the multi-store consolidation case. It is adequate; only the absence of sibling differentiation leaves a small 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% (baseline 3), and the description adds meaning beyond the schema by documenting the special value cuenta="todas", which the schema description (a user_id when multiple accounts are connected) does not mention. The dias parameter is left to 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?

Names the specific resources returned (facturación, unidades, ticket promedio) plus the period-over-period comparison, so an agent knows exactly what this produces. It doesn't explicitly contrast with close siblings like ml_panel_ventas or ml_rentabilidad, but the content is far more specific than a name restatement.

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?

"Ideal para ¿cómo vienen las ventas?" gives an implied usage scenario, and the cuenta="todas" note clarifies one consolidation mode. However, with ~29 siblings including ml_panel_ventas and ml_rentabilidad, no alternative is named and no when-not-to-use condition is given.

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

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

Beyond readOnlyHint=true, the description discloses a meaningful behavioral trait: it is a differential report that returns only changes since the prior run. It also enumerates the categories of change (price moves, listings added/removed, estimated sales, search-leader shifts, keyword trend entries/exits), giving the agent real context about what a run produces.

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 delta-only constraint is front-loaded in the first clause, followed by the enumerated report contents and a short usage note. Dense but every clause carries information; no filler.

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?

With no output schema, the description compensates by enumerating what the report contains, which is exactly what the agent needs to judge fit. Combined with readOnlyHint and a single optional param, the definition is complete enough to invoke correctly.

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?

There is only one optional parameter (cuenta) with 100% schema description coverage, so the schema already documents it fully. The description adds no additional meaning about the parameter, making the baseline 3 correct.

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 names a specific verb+resource (recorre la lista de seguimiento y reporta cambios) and defines its scope precisely as a delta report — 'SOLO lo que cambió desde la última corrida'. An agent can distinguish it from a full-history sibling, though it never names ml_historial_competencia or ml_tendencias 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?

It offers a cadence cue — 'Ideal como rutina semanal' — which implies the intended usage pattern. However, it names no alternative tool and states no when-not condition, leaving the agent to infer routing versus ml_historial_competencia or ml_tendencias.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds the descending-chronological ordering, but omits pagination/limit behavior and what the returned records contain or how they are scoped.

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?

Two short sentences, no filler, with the core purpose and sort order front-loaded before the filter note. Every clause carries information.

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?

For a 4-parameter read tool with no output schema, the description is thin: it says nothing about the shape/count of returned orders, the limit behavior, or the account parameter's role, leaving gaps an agent must infer.

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 75%, so most parameters are already documented inline (dias, cuenta, estado). The description only echoes that filtering by date and status exists and adds no format, default, or syntax detail beyond the schema — and 'limite' is undocumented in both.

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 ('Lista') and resource ('ventas (órdenes) del vendedor') with an explicit sort order, so an agent knows it returns a seller's sales list. It does not, however, distinguish itself from the ambiguous sibling ml_panel_ventas, which likely overlaps.

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 phrase 'Filtrable por fecha y estado' implies when the filters apply, but there is no explicit when-to-use guidance, no mention of prerequisites (e.g., needing a connected account), and no routing to a sibling alternative.

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

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

The readOnlyHint annotation already establishes the operation is a safe read; beyond that the description discloses the aggregation scopes it reports (today vs. month, per-shipping-method split, per-province concentration), which is real behavioral context an agent can use. It stops short of stating auth requirements, account-switching behavior, or whether results are cached/real-time.

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?

Two sentences, front-loaded with the substance of the dashboard before the use-case framing, and no filler. Slightly dense but every clause carries distinct content.

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?

With no output schema and only a readOnlyHint, the description carries the burden of describing return content and it does so thoroughly (billing, top products, shipping breakdown, geography). What is missing is differentiation from sibling analytics tools and any note on the optional account-selection flow.

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 single optional 'cuenta' parameter is fully documented in the schema (100% coverage), including a pointer to ml_cuentas for discovering user_ids. The description adds no further meaning to that parameter, so the schema does all the work and the baseline of 3 applies.

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 enumerates the concrete contents of the dashboard (facturación de HOY y del MES, productos más vendidos, reparto por método de envío, concentración por provincia), so an agent knows exactly what this tool surfaces. It is specific about the resource but never contrasts itself with likely-overlapping siblings such as ml_metricas or ml_rentabilidad, so sibling differentiation is left to inference.

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?

It gives clear usage context with the quoted prompts '¿cómo venimos hoy?' and 'el panel del mes', which tells the agent when this tool is appropriate. However, it offers no exclusions and does not point to alternatives (e.g. ml_metricas) for more granular or time-series analysis.

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

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

readOnlyHint=true already tells the agent this is a safe read, lowering the burden. The description usefully adds what the response conceptually contains (buy box status, target price), but says nothing about auth/account selection behavior or that 'cuenta' may be needed when multiple accounts are connected.

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?

A single compact sentence that front-loads the applicable scope ('publicaciones de catálogo') before the returned value. Efficient, though quite terse for a tool whose required parameter is undocumented.

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?

For a 2-parameter read-only query with no output schema, the description adequately conveys the return semantics (buy box status + required price). Missing detail is mostly about the item_id parameter and multi-account context rather than the tool's core purpose.

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 only 50%: 'item_id' has no description at all, and the tool description never explains what a valid catalog item_id looks like. The description does not compensate for the gap, and the 'cuenta' hint lives only in the schema, not the prose.

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 resource (catalog listings / buy box) and precisely what the tool reports: whether you're winning the buy box and the price needed to win it. It is distinguishable from siblings like ml_publicacion or ml_promociones, though it never names them.

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 Spanish phrasing 'Para publicaciones de catálogo' implicitly scopes usage to catalog listings, so an agent can infer when it applies. However, there is no explicit when-to-use/when-not, no prerequisite (e.g. valid item_id must be a catalog item), and no named alternative.

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

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

readOnlyHint=true already establishes that this is a safe, non-mutating read, so the description would need to add context to earn credit. Instead, its only behavioral claim ('por defecto las pendientes de respuesta') merely restates the schema default of estado=UNANSWERED, and it omits pagination/limit behavior and output shape.

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?

It is a single short sentence with the resource front-loaded and no wasted words. Brevity is appropriate in isolation, though it borders on under-specification rather than true conciseness.

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?

For a query tool with no output schema, the description should at least hint at return contents, ordering, or limit semantics. None of that is present, and the relationship to ml_responder_pregunta is unaddressed, leaving real gaps.

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 67%, and the description adds no meaning beyond what the schema documents. Its note about the pending default duplicates the estado description, while 'cuenta' and 'limite' (the latter entirely undocumented in the schema) are not clarified at all.

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 names the resource ('Preguntas de compradores') and a default scope (pending/unanswered), so the agent can infer it retrieves buyer questions. However, it supplies no explicit verb and does not distinguish itself from the closely related sibling ml_responder_pregunta (which answers questions), leaving purpose only implied.

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?

It says nothing about when to use this tool versus alternatives. The most obvious alternative, ml_responder_pregunta, is never mentioned, and no conditions or exclusions are given to help the agent choose between reading questions and answering them.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's added value is its hint about content (eligible listings plus their discount). It does not disclose auth requirements, whether all promotions are returned when called with no args, or any rate/pagination behavior, leaving meaningful behavioral gaps.

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?

A single efficient sentence that front-loads what the tool returns and follows with the operating hint. No padding or redundant restatement of the title.

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?

For a read-only tool with no output schema, the description gives the shape of the return (eligible listings with discount) but omits what happens with zero arguments (all promotions?), the role of cuenta in multi-account setups, and how the result relates to accepting a promotion. Adequate but with clear gaps.

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 67%: tipo and cuenta are documented in the schema, while promocion_id is bare. The description explains that promocion_id and tipo act together to select eligible listings, which adds real semantics for those two, but says nothing about cuenta and does not fill the promocion_id schema gap directly.

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 resource (campañas y promociones que MercadoLibre le ofrece al vendedor) and the read action (lista las publicaciones elegibles con su descuento). An agent can tell this is a read/list tool for promotions, but it never names a sibling to distinguish itself from ml_aceptar_promocion, which operates on the same domain.

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 clause 'con promocion_id y tipo, lista las publicaciones elegibles' implies how and when to call it (to enumerate eligible listings for a given promotion/type), but there is no explicit when-to-use, no exclusions, and no reference to alternatives like ml_aceptar_promocion. Usage is inferable rather than stated.

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

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

readOnlyHint=true already establishes this is a safe read, so the description does not need to restate safety. It does add value by enumerating the returned fields (precio, stock, ventas, garantía, envío, link), which matters because no output schema exists. It omits any note on whether item_id is resolved per marketplace (e.g., MLA prefix) or error behavior for missing items.

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?

A single front-loaded sentence with no filler; the field list is informative rather than padding. Slightly dense with a seven-item enumeration, but every element earns its place given there is no 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?

For a read-only single-item fetch with two fully documented parameters, the definition covers the essentials, and listing the returned fields partially compensates for the absent output schema. The main remaining gap is routing guidance against ml_publicaciones, which is a usage rather than a completeness issue.

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 description coverage is 100%: item_id is documented with the MLA123456789 example and cuenta is documented with a pointer to ml_cuentas. The description adds no parameter-level meaning beyond this, so the baseline 3 applies.

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 pairs a clear resource (una publicación, singular) with the content it returns (precio, stock, ventas, tipo, garantía, envío, link), so an agent can tell this is a single-item detail fetch. It does not explicitly contrast itself with the sibling ml_publicaciones (plural listing), leaving the singular/plural distinction to inference.

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?

No when-to-use statement, no preconditions, and no mention of alternatives such as ml_publicaciones or ml_actualizar_publicacion. Usage is only implied by the singular resource name, which is minimal guidance for a tool sitting in a cluster of listing-related siblings.

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

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

readOnlyHint=true already tells the agent this is a safe read operation, so the description only needs to add context. It clarifies scope ('del vendedor') and the returned fields, but says nothing about pagination via 'limite', multi-account handling via 'cuenta', or result ordering/cap. Useful but thin for a listing tool.

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?

A single front-loaded sentence with the verb and returned data stated immediately; no filler or redundancy. Its brevity is appropriate but contributes to the under-specification noted elsewhere.

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?

For a simple read-only list tool with no output schema and annotations covering safety, a single sentence is close to adequate. Still, it omits how 'limite' bounds results and how 'cuenta' behaves with multiple connected accounts, leaving real gaps an agent would hit at call time.

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 67%, above the 50% threshold, so the schema already documents 'cuenta' and 'estado'. The description mentions 'estado' only as a returned field, not as a filter, and never explains 'limite'. It adds little syntactic meaning beyond the schema, so the baseline 3 holds.

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 (Lista) and resource (publicaciones del vendedor) plus the fields returned (precio, stock, estado), so an agent knows exactly what this produces. However, it gives no differentiation from the singular sibling ml_publicacion, leaving the agent to infer the list-vs-single distinction.

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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives despite many overlapping siblings (ml_publicacion, ml_buscar, ml_auditar_publicaciones). The phrase 'del vendedor' implicitly scopes it to the seller's own listings, but nothing tells the agent when to prefer this over ml_buscar or a single-publication lookup.

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

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

readOnlyHint=true already establishes this is a safe read, so the description only needs to add context. 'Al momento de la consulta' usefully signals the data is live/current rather than cached, which is genuine added value. It does not address rate limits, auth scope, or aggregation latency, so it stays at a solid 3.

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?

Purpose and the two modes are front-loaded in a single dense sentence, followed by a short sentence on the dias parameter. Nothing is padded, though the first sentence is quite long and packs several concepts together.

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?

With no output schema, the description proactively enumerates the returned fields for both modes (inversión, impresiones, clics, CTR, CPC, ACOS, unidades, facturación; estado, presupuesto, resultados), which is exactly what fills the output gap. The only omission is any mention of the cuenta parameter, which the schema already covers.

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 only 67%, and item_id has no schema description at all. The description fills that gap by explaining exactly what item_id does (listing ad detail vs. advertiser campaigns), and restates dias semantics (1 = hoy, default 30). cuenta is left to the schema, but the description compensates well for the undisclosed parameter.

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 (métricas) and resource (Product Ads / publicidad) and clarifies the two operating modes: with item_id returns the ad detail for a listing, without it returns the advertiser's campaigns. This is far beyond a tautology and lets an agent predict behavior. It does not explicitly differentiate itself from nearby metrics siblings like ml_metricas or ml_rentabilidad, keeping it short of a 5.

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 usage by explaining that item_id switches between listing-level ad detail and advertiser-level campaigns, so an agent can infer which mode to request. However it never states when to prefer this tool over general metrics tools (ml_metricas, ml_rentabilidad) or any prerequisites/exclusions. Usage is implied, not explicit.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the behavioral burden and does it well: it specifies that it prompts for missing values and that cost and taxes are NEVER invented (no silent defaults), and that it reports the ACOS the product can withstand. It does not describe output formatting or failure modes, keeping it short of a 5.

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-loads the value (the peso-by-peso breakdown) and is dense but purposeful; the second sentence on missing-input handling and ACOS is useful. Slightly heavy for two sentences but every clause earns its place.

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?

For a read-only calculator with no output schema, the description adequately describes what is produced (net profit, margin, break-even ACOS) and how missing inputs are handled. A brief note on the response shape would complete it.

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 description coverage is 100%, so each of the 7 parameters is already documented. The description reinforces which factors feed the formula and the no-invention rule for costo/impuestos_pct, but adds little syntax or defaulting detail beyond what the schema states, so baseline 3 applies.

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+resource (compute real profitability per unit) and enumerates the exact formula: sale price minus ML commission, ads, taxes, shipping, and cost. An agent can distinguish it from ml_comisiones or ml_publicidad, which only supply a single input to this calculation.

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?

Gives clear context — it pulls real listing fees and live Product Ads spend for a period, and asks the user for missing inputs, implying it is the tool for full-margin analysis. However, it names no sibling alternatives or explicit when-not-to-use conditions.

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

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

La anotación readOnlyHint=true ya comunica que es una operación de solo lectura. La descripción añade valor al enumerar las métricas de reputación que devuelve, pero no describe formato de salida, paginación ni posibles limitaciones, por lo que la transparencia conductual es básica.

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?

Es una frase muy breve y sin relleno, con los elementos principales al inicio. No obstante, su estructura de fragmento nominal, sin verbo, sacrifica algo de claridad y podría ganar precisión sin perder concisión.

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 una herramienta simple de solo lectura con un parámetro opcional y sin esquema de salida, la descripción ofrece las métricas principales que se obtienen. Sin embargo, no cubre cuándo elegirla frente a herramientas hermanas ni detalla el formato de retorno, dejando lagunas contextuales.

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?

El esquema tiene un único parámetro opcional con cobertura de descripción del 100%, por lo que la semántica de cuenta ya está documentada allí. La descripción de la herramienta no añade información adicional sobre ese parámetro, lo que corresponde a la base de 3 cuando el esquema asume el detalle.

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 enumera los datos que devuelve (color de reputación, ventas, tasas de reclamos, demoras y cancelaciones), pero no usa un verbo como 'obtener' ni define explícitamente el recurso. No diferencia esta herramienta de otras similares como ml_metricas o ml_panel_ventas, por lo que el propósito se infiere pero no queda plenamente claro.

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?

No indica cuándo usar esta herramienta frente a alternativas como ml_metricas, ml_panel_ventas o ml_ordenes. Tampoco menciona condiciones previas, como la necesidad de tener una cuenta de Mercado Libre conectada, aunque el esquema sí lo sugiere para el parámetro cuenta.

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

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

Annotations only declare readOnlyHint=false. The description adds two meaningful traits beyond that: the answer is publicly visible ('real y visible') and the action is irreversible, a critical warning for a write tool. This is solid added value, though it omits any auth/account requirements.

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?

Two short sentences with zero waste. The action and scope are front-loaded, followed immediately by the irreversibility warning and the confirmation precondition.

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?

For a simple 3-param write tool with no output schema and only a readOnlyHint annotation, the description covers the essential profile: what it does, that it is public, and that it is irreversible. Minor gaps remain around permissions and account selection.

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 67%; 'texto' and 'cuenta' are documented in the schema while 'pregunta_id' is not. The description only loosely echoes the 'texto confirmado' concept and adds no format or sourcing guidance, so it does not compensate for the gap. Baseline 3 is appropriate.

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 (PUBLICA) and resource (respuesta a una pregunta de comprador) with clear scope ('real y visible'). An agent can distinguish it from the read-side sibling ml_preguntas, 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?

Provides a real usage constraint: 'usar solo con el texto confirmado por el usuario', which implicitly tells the agent to require confirmation before calling. However, it names no alternative or when-not condition and does not point to ml_preguntas for reading/reviewing questions.

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

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

The single annotation (readOnlyHint=false) only confirms this is a write. The description adds genuinely useful behavior beyond that: uploads enter asynchronous moderation taking 24-48 hours, so there is no immediate published result and a later ml_clips check is required. It does not cover auth requirements, error modes, or rate limits.

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?

Two tightly packed sentences: the action first, then the validation rules and the moderation caveat. No filler, and the most important constraint (asynchronous 24-48h moderation) is placed last where it will be read before invocation.

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?

For a 3-parameter write tool with no output schema and only one annotation, the description covers the essential operational facts: acceptance criteria, required active state, and the deferred verification step. What remains thin is the return behavior (clip identifier/status) and failure handling, though the ml_clips pointer partially compensates.

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 67%. The description supplies domain constraints for `archivo` (accepted containers, vertical orientation, duration window, resolution floor, size ceiling) that the schema's bare "Ruta local del video" does not, and the "publicación activa" requirement implicitly qualifies `item_id`. Only the optional `cuenta` parameter gets no mention in the description.

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 opens with a specific verb+resource in the user's domain ("Sube un Clip ... a una publicación") and even defines what a clip is ("video vertical corto"), which removes ambiguity against the many publication-related siblings. It also names ml_clips as the follow-up tool, so the agent can place it precisely in the workflow.

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?

It states the concrete preconditions for successful use (active publicación plus MP4/MOV/MPEG/AVI, vertical, 10-61s, min 360x640, max 280 MB) and tells the agent to verify moderation later with ml_clips. There is no explicit "when not to use" or alternative upload path, but the prerequisites are unusually complete for a tool of this type.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds nothing beyond scope: no data source, timeframe, refresh cadence, or result size. For a trends/analytics read with zero annotation depth beyond read-only, this is a notable gap.

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?

A single well-formed sentence with the resource front-loaded and no filler. It is appropriately sized for a simple read, though the brevity leaves gaps rather than waste.

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?

No output schema and no required parameters keep the bar low, and the description conveys what the tool returns conceptually. Missing timeframe, result limits, and the meaning of the 'cuenta' parameter leave it adequate but not complete.

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 only 33% (only 'cuenta' is documented), so the description carries meaningful weight: 'del sitio o de una categoría' maps directly to sitio and categoria and explains their effect on results. However it says nothing about 'cuenta', the undocumented parameter, so the compensation is partial.

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 resource ('las búsquedas más populares') and its two scopes (site or category), plus the business meaning (what people want to buy). It is clear and distinguishable from most siblings, but never names a sibling it should not be confused with (e.g. ml_buscar, ml_descubrir_ganadores).

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as ml_buscar or ml_novedades_competencia. Usage must be inferred purely from the one-line purpose statement.

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

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

The description discloses state-changing behavior: 'asignar (darle una tarea)', 'quitar', 'pausar', 'activar', 'frecuencia', 'correr (que trabajen ya)' and 'drive (conectar Google Drive)'. Annotations declare readOnlyHint=true, which directly conflicts with these mutating actions, leaving the agent with an unreliable safety profile.

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-loads what the team is and who does what, then compresses all ten actions into one dense clause. The worker roster with emoji is long but each entry carries a distinct domain; little is pure 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?

With 14 parameters, 10 action branches and no output schema, the description covers intent, the workers' domains, action names and a fallback relationship to ml_vigilar. It stops short of mapping which parameters belong to which action and never says what 'informe'/'resultados' actually return, leaving some gaps for a tool this broad.

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 description coverage is 93%, so nearly every parameter is already documented (trabajador aliases, umbral per worker, cuenta, carpeta). The description mostly restates this at a high level ('frecuencia (minutos)', 'drive (conectar Google Drive)') and adds the alias convention already present in the schema, so it contributes little beyond baseline.

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 concrete resource (a 5-agent monitoring team) and names each worker with the domain it watches (Vera=precios, Tomás=ventas, Martina=ranking, Bruno=rivales, Sofía=tendencias). It then enumerates the full action set verb by verb (equipo, asignar, quitar, pausar, activar, frecuencia, correr, informe, resultados, drive), so an agent immediately knows the tool's surface area.

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?

Gives per-action context ('correr = que trabajen ya', 'informe = alertas nuevas') and a routing rule against a sibling: if a worker has no own tasks it watches your ml_vigilar follows of its type. It never states when NOT to use this versus alternatives like ml_vigilar, ml_novedades_competencia or ml_tendencias directly, so a competing-usage decision is left partly implicit.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by stating that it checks for a published update and explains how to update, which goes beyond the annotation. It does not mention authentication or rate limits, but those are minor for a zero-parameter version-check tool.

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 a single, front-loaded sentence that covers the tool's three behaviors without any redundant or filler text. Every clause earns its place.

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?

For a simple zero-parameter, read-only tool with no output schema, the description fully communicates what the tool does and what information it returns (installed version, update availability, update instructions). Nothing essential is missing.

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?

There are no input parameters, so the empty schema is complete and the description does not need to explain parameter semantics. The baseline for zero parameters is 4.

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 states a specific verb and resource: it shows the installed connector version, checks for a published update, and explains how to update. This is clear and distinct from most siblings, though it does not explicitly differentiate itself from update-related sibling tools such as ml_actualizar_publicacion.

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 the tool is useful (when the user needs version or update information), but it does not explicitly state when to use it versus alternatives or provide any exclusions. Usage context is left to inference.

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

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

Annotations declare readOnlyHint=true, yet the description explicitly advertises 'agregar' and 'quitar' actions that mutate a locally stored watchlist ('se guarda local'). The description contradicts the read-only annotation, which is the most serious defect here.

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?

Two dense sentences that front-load the resource, then the types, then the actions, with no filler. The structure is easy to parse even though it packs a lot of enum detail into one paragraph.

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?

For a watchlist manager with no output schema, the description covers the type taxonomy, the action set and the storage locality, which is enough for correct invocation. The missing piece is the read/write safety profile, which it actively misstates rather than omits.

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 already 80%, so the baseline is 3, but the description adds genuine meaning by tying each 'tipo' value to what 'ref' must contain (nickname/id of a seller, item_id, keyword whose top 10 will be watched, site/category). This mapping goes beyond the collapsed schema description of 'ref'.

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 ('Administra la lista de seguimiento de competencia y tendencias') and enumerates both the supported types and actions, so an agent understands exactly what domain this covers. It does not, however, differentiate itself from related siblings such as ml_tendencias, ml_novedades_competencia or ml_historial_competencia.

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 says what the tool manages but gives no when-to-use or when-not guidance, and never mentions the closely related siblings (ml_tendencias, ml_novedades_competencia). The agent must infer that 'vigilar' means persisting a target for later monitoring rather than fetching results now.

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

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

Annotations already declare readOnlyHint=true, confirming a safe read operation. The description adds the temporal window concept and purpose, but it does not disclose rate limits, authentication needs, or return format details beyond what the name implies.

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?

A single sentence that front-loads the resource and purpose with no wasted words. It is appropriately sized for the tool's simplicity.

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?

For a simple read-only metric query, the description covers the basic what and why. But it omits alternative tools (e.g., ml_metricas), does not explain the return shape (no output schema exists), and gives no guidance on the cuenta parameter.

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 description indirectly clarifies that item_id refers to a publication and 'ventana de días' maps to the dias parameter. However, it says nothing about the cuenta parameter, and schema coverage is only 67%, leaving one parameter undocumented in 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?

The description states a specific resource (visits of a publication) and a window of days, making the tool's purpose clear. However, it does not differentiate from similar metric-oriented siblings like ml_metricas or ml_publicacion.

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 phrase 'para medir tráfico y conversión' implies the tool's intended use case, but there is no explicit guidance on when to choose it over alternatives or when not to use it.

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