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?

The description adds genuinely useful behavior: the tool never self-enrolls, it only records the user's decision, and enrolment requires ml_aceptar_promocion plus explicit user OK. But annotations declare readOnlyHint=true while the description says it 'guarda tu decisión', i.e. it persists state — a read-only claim for a tool with a write action. The contradiction is partial (calendario/fecha are reads, decidir writes) and the description is transparent about it, but it conflicts with the structured hint.

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 what the agenda contains, then the mandatory ask-and-record rule, then the four actions — a sensible order. It is dense and parenthesis-heavy (persona 'Clara', date lists), but nearly every clause carries actionable 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 an 8-parameter, multi-action tool with no output schema, the description covers all four actions, the required user-confirmation flow, and the hand-off to ml_aceptar_promocion. Remaining gaps (return shape of calendario, whether decidir is idempotent or how cuenta-scoped decisions persist) are minor given the action enum is fully documented in the schema.

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 already documents its action (ref, dias, nota, fecha, nombre, participar, cuenta). The description only restates the action names and hints at inputs like 'confirmar una fecha estimada o agregar una propia', adding no formats, defaults or constraints beyond the schema. 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 concretely what the resource is (the commercial agenda: key dates like Hot Sale/CyberMonday/Black Friday and the campaign schedule with sign-up windows, candidates and participation status) and then enumerates its four actions (calendario, decidir, fecha, pagina). An agent can distinguish it from ml_promociones or ml_aceptar_promocion, though the multi-action nature makes it a slightly sprawling purpose rather than a single verb+resource.

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?

Explicit behavioral rule: 'pregunta SIEMPRE si querés participar y guarda tu decisión (no se inscribe sola: inscribir es con ml_aceptar_promocion y tu OK)' — it names the alternative tool and the condition that selects it. It also maps each action to its purpose. It does not, however, say when to prefer this over ml_promociones or ml_tablero for general promo 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?

Annotations only declare readOnlyHint=false, so the description carries the burden and does: it discloses dry-run preview, the backup taken before each overwrite, multi-store propagation with mismo_sku, and the validation rules (no HTML, no contact info/links, measurements with number and unit). This is exactly the mutation context an agent needs.

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 dense paragraph, but front-loaded with the action and every sentence carries new information (structure, scope, sourcing, dry-run/confirm, backup, validation). Slightly overlong and would scan better as a few short lines, but there is 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 10 parameters, no output schema, and a destructive write, the description still covers everything an agent needs: input provenance, preview vs. commit, backup, replication scope, and validation constraints. Nothing essential for a correct call 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 100%, so baseline is 3; the description still adds meaning by linking confirmar to the explicit seller OK, explaining that mismo_sku applies per-listing FAQs from each listing's own questions, and noting faq is auto-computed from the last 90 days. It does not cover cuenta or extra in detail, keeping it just below top marks.

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 a specific verb+resource ('MODIFICA la descripción real de una publicación') and then spells out the exact target structure (resumen, medidas, características, incluye, FAQ). It clearly separates itself from ml_mejorar_publicacion by naming it as the material source and from ml_actualizar_publicacion by describing the structured rewrite.

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 states the two modes: 'Sin confirmar=true solo muestra cómo quedaría; con confirmar=true la escribe (solo con OK explícito del vendedor)'. It also points to the companion tool ml_mejorar_publicacion for source data, so the agent knows the workflow order.

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 safety profile, and the description adds genuinely new behavior: results are ordered worst-first, each item carries a concrete recommended action, and the same audit is run automatically by the Lucía worker. Missing only output shape/pagination detail, which annotations don't cover.

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 statement, then the detected-issue list, then ordering and the ideal use case. The issue enumeration is long but each item is a concrete signal, so it earns its space; only the parenthetical note about the automated worker is mildly tangential.

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?

Three optional parameters, no output schema, read-only annotation: the description sufficiently explains what comes back (ranked publications with severity and action) and what conditions are checked. Minor gaps are the return structure and whether all accounts are audited when cuenta is omitted.

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 cuenta, estado and limite are already documented, and the description adds nothing about them — notably no mention of the limit controlling how many publications get audited. Baseline 3 applies when the schema carries all parameter 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?

Concrete verb + resource: lists the seller's publications with a quality scorecard and per-item improvement action, enumerating the exact problem categories it detects. It is clearly distinct from the raw-listing sibling ml_publicaciones and from ml_mejorar_publicacion, which acts rather than audits.

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?

Names the triggering question ('¿qué publicaciones tengo que mejorar?') and notes the in-house auditor agent runs it automatically every 15 days, which frames when it is appropriate. It does not explicitly say when NOT to use it or point to the alternative tools (ml_mejorar_publicacion, ml_aplicar_mejora) for acting on the findings.

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?

The description states the tool saves data ('guarda lo que el vendedor le enseña') and deletes it ('olvidar'), while annotations declare readOnlyHint=true. This is a direct contradiction between the described write/delete behavior and the declared read-only nature. The otherwise useful disclosure that data stays in a local file on the seller's machine cannot offset the contradiction.

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 front-loaded with the purpose statement and ends with a compact action list, but the middle section is a dense run-on of dashes and capitalized emphasis that mixes guarantees, SKU rules, and privacy notes. Each sentence carries information, yet the formatting makes it slower to parse than needed.

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 9 parameters, no output schema, and a contradictory annotation, the description should carry more weight. It covers storage scope, SKU behavior, and privacy well, but never says what 'ver' returns, what 'olvidar' removes (one SKU, one product, all notes?) or whether deletion is recoverable.

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 100%, so the baseline is 3, but the description adds genuinely new semantics: costs are keyed by SKU and propagate to all listings sharing that SKU, including future ones, and item_id may itself be a SKU (e.g. "TER-1L"). That inheritance rule is not derivable from the schema alone.

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 first sentence defines a specific resource (a local business memory database) with concrete stored fields (costo, % impuestos, envío, medidas, incluye, notas), and the closing 'Acciones: guardar, ver, olvidar' enumerates the operations. It is clearly distinguishable from siblings like ml_rentabilidad, which it explicitly positions as a consumer of this 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?

It tells the agent when to save (costs, taxes, shipping, measurements) and even gives a conditional rule for business-wide data ('para datos del negocio entero... guardar sin item_id'). It stops short of stating when NOT to use the tool or how 'ver'/'olvidar' differ in scope, but the context for use is clear.

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 covers the safety profile, so the description only needs added context, and it does add one useful fact: the fee varies by tipo de publicación. However, it doesn't say whether multiple connected accounts or sites affect the result, nor what the return looks like (a single fee or a breakdown).

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 with the core action front-loaded and no filler. It is appropriately sized, though the mention of listing type without a matching parameter costs it a point.

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 should signal what comes back (fee amount, breakdown by listing type/installments). That return shape is only gestured at, but the core semantics needed to call it are present.

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% (sitio and precio are undocumented), so the description should compensate, but it only echoes 'precio dado' and mentions 'tipo de publicación' — a dimension that has no corresponding parameter in the schema, which can mislead an agent. It adds no meaning for sitio or categoria beyond what the schema already says.

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 action and resource: computing what MercadoLibre charges in fees for a given sale price, broken down by listing type, for margin calculation. Clear enough to distinguish from generic sales tools, though it doesn't explicitly contrast with the closest sibling, ml_rentabilidad, which also deals with margins.

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 use case (cost side of a margin calculation) but gives no explicit when-to-use/when-not guidance and never names alternatives like ml_rentabilidad or ml_precio_catalogo. The agent must infer the routing decision from tool names alone.

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 explicitly says the tool links an account and 'completa la conexión' — a credential/token write — while annotations declare readOnlyHint=true. That is a direct contradiction that could mislead an agent about side effects. Valuable context it does add (env-var prerequisites, browser-based flow) is overshadowed by the inconsistency.

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: the two-mode behavior first, then the environment prerequisite. No filler, and the most decision-relevant information (no-arg vs. code) is front-loaded.

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-optional-parameter, no-output-schema tool it covers the essential flow and the return of the no-arg case (the URL). It leaves out the `sitio` option and what confirms a successful connection, small gaps given the low complexity.

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; baseline 3 applies. The description adds flow-level meaning to `code` (it comes from the authorization page) but never mentions `sitio` at all, so it adds little beyond structured fields.

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 ('Vincula una cuenta de MercadoLibre') and immediately distinguishes its two operating modes (no-arg returns an auth URL; with `code` completes the link). An agent can tell it apart from siblings like ml_desconectar or ml_cuentas without opening the 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?

Clear conditional routing: call without arguments to obtain the browser authorization URL, call with `code` once the user has authorized. It also names the prerequisite (ML_APP_ID / ML_APP_SECRET must be configured). It does not name a sibling alternative to use instead when already connected, which keeps it 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?

With only readOnlyHint=false in annotations, the description carries the behavioral load and does so well: it discloses the COSTO POR SKU gating logic, the fact that the tool refuses to publish and returns a request for cost, and the retry contract ("volver a llamar con costo=…"). That non-obvious failure/retry behavior is exactly what an agent cannot infer from structured fields.

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 essential constraint (real creation, confirmation required) is front-loaded, followed by clone mode and the cost gate. Dense but every clause carries information; the parenthetical asides are slightly heavy but not wasteful.

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 13-parameter mutation tool with no output schema, it covers the critical decision paths (clone vs. build, cost gate, confirmation). It does not say what the call returns on success (e.g., the new item_id) or what `cuenta`/`tipo` defaults are when multiple 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 69% schema coverage the description meaningfully supplements it: it explains that SKU and cost are shared across publications, that `copiar_de` supplies título/categoría/atributos/fotos/descripción, and that título/precio/stock can override the clone. It leaves several params (stock, precio, tipo, condicion, imagenes) without added semantics, so not a 5.

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?

Opens with a specific verb and resource ("CREA una publicación real en la tienda") and immediately distinguishes two modes: creation from scratch vs. cloning via `copiar_de`. This separates it cleanly from siblings like ml_actualizar_publicacion, ml_publicacion, and ml_publicaciones without needing to open 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?

Explicitly states the confirmation requirement ("Usar solo con confirmación explícita del usuario") and the condition selecting clone mode ("ideal para duplicar entre tus propias cuentas"). It also routes between `costo` and `sin_costo`. It stops short of naming a sibling tool as the alternative for the non-create path, so it's not a full 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?

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 description's job is lighter. It usefully discloses the data sources behind each mode ('ranking oficial de más vendidos (highlights) + tendencias') and hedges scope with 'dentro de lo que permite la API', but says nothing about volume of output, latency or what happens if the API lacks coverage for a category.

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, mode information front-loaded, no filler or marketing language. The parenthetical enumeration of market signals is dense but each item earns its place by signalling the analytic depth of the search mode.

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 zero required parameters, the description should say what comes back (a ranked list? candidate products?) and what the default behaviour is when neither categoria nor busqueda is passed. It explains the analysis inputs well but leaves the return shape and the no-argument case undefined.

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% and both 'busqueda' and 'categoria' already carry descriptions with examples (MCO1055), so the schema does most of the work. The description adds the genuinely useful mutual-exclusivity rule ('o'), but leaves 'sitio' completely undocumented and does not clarify behaviour when neither parameter is supplied (0 required params).

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 ('Encuentra'), the resource ('artículos ganadores') and enumerates the two operating modes (CATEGORÍA vs BÚSQUEDA) with the signals each one uses (highlights, competencia, precios, envío gratis, ventas visibles). An agent can tell what the tool produces. It does not, however, distinguish itself from close siblings such as ml_nichos, ml_tendencias or ml_buscar, which overlap with the 'análisis de mercado por keyword' mode.

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?

'Indicar categoria (id tipo MCO1234) o busqueda (keyword)' gives a concrete selection rule between the two modes, which is real guidance beyond the schema. It stops short of stating when to prefer this tool over ml_nichos/ml_tendencias/ml_buscar, and there are no exclusions ('no uses esta herramienta para...').

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 declares this is a safe read, so the bar is lower. The description adds useful domain context — that FULL shipments are handled by MercadoLibre and that it also reports the delay-rate reputation metric — but says nothing about pagination, limits, or empty-result 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?

Everything is packed into one long sentence opened by a persona framing ('La lista de Leo, el coordinador de logística del equipo'), which delays the actual content. The enumeration of shipment states and dimensions is informative but not front-loaded or scannable.

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 does carry some of the return burden by naming the shipment states, types, destinations, and the reputation delay rate. However, it leaves the boundary with ml_envios undefined and gives no sense of result shape or volume for a two-parameter listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both dias and cuenta documented inline (default 7, max 30; user_id per ml_cuentas). The description adds no additional parameter meaning beyond what the schema provides, so 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 names a concrete resource (envíos de ventas recientes) and enumerates the relevant subsets: pendientes de despachar, demorados, no entregados, devueltos, por tipo (FULL/Flex/Colecta) y destino. It is clear what the tool returns, though it never distinguishes itself from the close sibling ml_envios, leaving overlap ambiguity.

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?

Usage is only implied through the framing 'qué tenés que despachar y hasta cuándo', which suggests operational triage. There is no explicit when-to-use vs ml_envios/ml_ordenes, no prerequisites, and no statement of when this is the wrong tool to reach for.

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?

Goes well beyond readOnlyHint=false: it discloses the mutation only happens with aplicar=true and requires explicit confirmation, that the written block is delimited so it can be refreshed biweekly without duplication, and what is deliberately excluded from the block (stock, price, installments, shipping, contact data, anything already in the description). This is exactly the kind of pre-call context a mutation tool needs.

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 core action and packs the filtering rules, idempotent block behavior and dry-run/write switch into a tight run of clauses with no filler. It is a single dense paragraph, though, so the safety-critical confirmation rule sits mid-sentence rather than being visually separated.

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 6-parameter, zero-required mutation tool with no output schema, the description covers selection scope, defaults-driven filtering intent, write safety and re-run behavior. The only residual gap, the exact shape of the proposal returned in preview mode, is minor given that no output schema exists and preview text is self-describing.

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 earns above that by explaining the semantic difference between the aplicar modes and by clarifying that todas targets Lucía's last-audit flagged listings rather than an arbitrary set. It leaves maximo and min_veces' effect on filtering entirely to the schema, and does not say what happens when neither item_id nor todas is supplied despite zero required parameters.

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 a specific verb chain (take buyer questions, group, prioritize, filter, insert as a marked FAQ block into the listing description) plus the distinctive constraint that answers must be the seller's real ones and never invented. An agent can distinguish this from ml_preguntas (reads questions), ml_responder_pregunta (answers them) and ml_actualizar_publicacion (generic description edit) 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?

"Sin aplicar=true solo MUESTRA la propuesta; con aplicar=true modifica la descripción real (pedir confirmación antes)" gives an explicit when-to-use rule for the dry-run vs write path, and todas=true is scoped to Lucía's flagged listings. No sibling tool is named as an alternative, so an agent gets conditions but not a routing decision against ml_mejorar_publicacion or ml_actualizar_publicacion.

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, and the description adds real behavioral context: work runs now, store modifications are flagged for the seller's approval, and sin_correr builds a plan from cached knowledge. The one tension is that setting nombre/emoji persists configuration state inside an allegedly read-only tool, which the description does not reconcile.

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 objective-to-plan behavior, then examples and the naming rules; every sentence carries usable information. It is somewhat long and the naming block is dense, but nothing is 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 correctly carries the return burden, describing the plan's shape (ordered steps, responsible worker, finding, skill) plus the approval marker for store changes. An agent can call this correctly without opening any other artifact.

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 baseline is 3, but the description still adds meaning the schema lacks: nombre is tied to concrete trigger phrases and the empty-string reset, objetivo is illustrated with examples, and the name-only (no objetivo) invocation pattern is spelled out. emoji and sin_correr get no extra prose 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 concretely what the tool does: takes a one-sentence objective, picks which workers (ml_trabajadores) are relevant, runs them immediately, and returns an ordered plan with responsible worker, finding and skill. This distinguishes it clearly from the individual worker/metric siblings in the list, and it is not a restatement of the title.

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 explicit invocation conditions with concrete objective examples ('vender más este mes', '¿por qué gano poco?'), the no-objective fallback (runs with the whole team), the naming flow (name-only call, empty string to reset) and the rule that addressing the boss by name counts as an objective. When-to-use vs. alternatives is 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?

Annotations already declare readOnlyHint=true, and the description is consistent with that ('No modifica nada'). Beyond annotations, it discloses concrete behavior: auto-detection of which store an item_id belongs to, cross-store grouping by SKU, and the shape of the checklist returned. It does not cover failure modes, limits on single-item mode, or latency.

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 core distinction between the two modes is front-loaded in the first sentence, but the text then sprawls into a dense numbered bundle of checklist details with nested parentheticals. Much of that detail is genuinely useful given there is no output schema, yet the phrasing is repetitive and could be tightened considerably.

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 no required parameters, no output schema, and a genuinely complex return, the description does the heavy lifting by enumerating the four checklist sections and the sweep ordering. Remaining gaps are error/edge-case behavior (item not found, empty store) and the exact response structure.

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 schema already documents all four parameters, setting a baseline of 3. The description adds meaningful semantics beyond the schema: item_id presence switches between single-publication review and store-wide sweep, and the cuenta parameter scopes which stores are swept. The maximo and fotos parameters are only implicitly touched.

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 gives a specific verb and resource: it reviews/audits one publication against a conversion recipe and returns a checklist, or sweeps all stores when no item_id is given. It also differentiates itself from ml_aplicar_mejora (the mutating sibling). However, the very close sibling ml_auditar_publicaciones is never mentioned, leaving that boundary to be inferred.

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 two operating modes are stated explicitly and keyed to item_id: with item_id it reviews one publication across any connected store; without item_id it sweeps the stores and ranks them by what is missing. It also names the follow-up alternative: 'No modifica nada: para aplicar, ml_aplicar_mejora con el OK del vendedor.'

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?

readOnlyHint=true is consistent with the framing as an analysis/discovery operation. Beyond the annotation it discloses a real behavioral trait: results are estimates over a sample, ML-reported third-party sales may be approximate, and the tool "nunca inventa datos" – material context for trusting the output. It stops short of covering rate limits or latency for a tool that crawls up to 300 listings per niche.

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 core purpose is front-loaded in the first clause, but the six-item numbered enumeration is dense and partly restates what the tool computes in marketing register ("si los NÚMEROS CIERRAN", "impuestos del cerebro"). It is readable but longer than needed to route an agent correctly.

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 an 8-parameter, no-required-parameter analysis tool with no output schema, the description carries the burden of explaining what is returned and does so via the six analysis dimensions plus the 0-100 ranking score. Missing only edge behavior – what happens when neither busqueda, busquedas nor categoria is supplied, and whether error vs empty results differ from low-demand niches.

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 88% schema description coverage the schema already documents busqueda, busquedas, muestra, categoria, costo and cuenta, so the baseline is 3. The description reinforces the exclusivity of busqueda vs busquedas and the costo-with-one-search constraint, but adds no formats, ranges or defaults not already present 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?

States a specific verb+resource ("descubre y valida NICHOS") and enumerates the six analyses produced, so an agent knows exactly what comes back. It does not name or distinguish itself from plausible siblings such as ml_descubrir_ganadores, ml_buscar or ml_tendencias, which keeps it from 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?

Clearly splits the two usage modes – "Con UNA búsqueda (o una categoría)" for a full niche analysis versus "Con VARIAS búsquedas (hasta 5)" for the opportunity ranking – and ties the cost parameter to the single-search mode. It gives no guidance on when to prefer this over the many sibling discovery tools, so no exclusions or alternatives are 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?

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, and the description adds real behavioral value beyond that: it will flag the result as 'parcial' when costs or taxes are missing, names what is missing, and explicitly promises it never invents data. It also discloses that tax percentages and costs come from 'el cerebro' (ml_cerebro), which matters for interpreting the output.

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 output shape are front-loaded before the parameter note, and every clause about missing costs/taxes earns its place. The 'Carmen, la contadora' framing is a small flavor cost and the single sentence is long, but nothing is truly 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?

With no output schema, the description carries the burden of describing the return: it enumerates the components, the computed net result and margin, the previous-month comparison, and the partial-result flag. An agent knows what it will get back; only the multi-account ('cuenta') case is left to the schema.

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 the schema already documents both parameters. The description restates the 'mes' formats but usefully adds that 'actual' is the default and means 'hasta hoy'; the 'cuenta' parameter is not mentioned in the description at all beyond the schema's pointer to ml_cuentas. That lands at the 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?

The description names a specific resource (monthly accounting summary: billing, sales count, real ML commissions, ads, taxes, COGS, shipping → net result and margin) and states the comparison scope. That is far more than a restatement of the name, and it implicitly sits above the more granular siblings (ml_comisiones, ml_publicidad, ml_envios), though it never explicitly contrasts itself with 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?

It explains the 'mes' argument values including the default, which implies when the tool is relevant, but never states when to call this versus ml_rentabilidad, ml_tablero or ml_panel_ventas. Usage is inferable from the data list, not spelled out.

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 is consistent with a pure detail read, so annotations carry the safety profile. Beyond that, the description discloses the specific data payload returned (price, stock, sales, type, warranty, shipping, link), which is genuinely useful since there is no output schema. It says nothing about error behavior for invalid item IDs or cross-account access.

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 whose field enumeration earns its place. The opening phrase 'Detalle completo de una publicación' partially restates the title, a minor redundancy, but nothing else 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 simple two-parameter read tool with annotations and full schema coverage, the field list compensates reasonably for the absent output schema. It lacks guidance on multi-account disambiguation (when to pass cuenta) and on how it relates to the sibling list/update tools, which keeps it short of a 5.

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% — item_id has a format example (MCO123456789) and cuenta points to ml_cuentas — so the schema does the heavy lifting. The description adds no parameter-level meaning of its own, 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?

States a specific verb and resource ('Detalle completo de una publicación') and enumerates the fields returned (precio, stock, ventas, tipo, garantía, envío, link), which lets an agent tell it apart from the plural list tool ml_publicaciones. It never names a sibling explicitly, so differentiation relies on the singular-vs-plural naming convention.

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?

Usage is only implied: the required item_id plus 'detalle' suggests calling it when you already have a single item ID and need a full record. There is no explicit when-to-use, no exclusion, and no pointer to ml_publicaciones for listing or ml_actualizar_publicacion for changes.

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 already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context: it discloses that it will prompt for missing inputs, that cost and taxes are never fabricated, and that it reports the maximum ACOS a product can bear — useful traits 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?

The formula is front-loaded in one sentence and the behavioral caveat follows, with zero filler. It is dense and heavy on all-caps emphasis, but every clause maps to a distinct part of the calculation or behavior.

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 does explain the return values (net profit, margin, tolerable ACOS). Combined with 100% parameter documentation and a readOnly annotation, an agent has enough to call it correctly; the only gap is the absence of sibling comparisons.

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 every parameter is already documented in the schema, including the 'SIEMPRE preguntarlo' notes for costo and impuestos_pct. The description reinforces that item_id pulls live price and ads spend but adds no syntax or format detail beyond the schema, 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?

States a specific verb+resource: breaks down peso-by-peso profitability of a product, with the exact formula chain (price minus commission, ads, taxes, shipping, cost = net profit and margin). This is clearly distinguishable from siblings like ml_comisiones or ml_precio_catalogo, which cover only a piece of the 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?

Implies usage context (per-unit profitability of a product, with item_id pulling real price/publication type/ads) and warns that missing cost and taxes must be asked, never invented. However, it never states when to prefer this over ml_comisiones, ml_metricas, or ml_panel_ventas, so sibling routing 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?

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?

With only readOnlyHint=false available, the description carries real weight: it discloses the accepted media constraints, the 280 MB cap, and critically that moderation is asynchronous (24-48 hs) and must be re-checked with ml_clips. It does not say whether an existing clip is replaced, what happens on moderation rejection, or auth/account scoping rules.

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, zero filler. The core action is front-loaded and the constraint block plus the follow-up pointer are packed into the second 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 write tool with no output schema, the description covers the media preconditions, the async moderation behavior, and the verification sibling. It leaves the item_id format and any return/confirmation payload implicit, which is a small but real 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 67%; archivo and cuenta are already documented in the schema. The description only implies the meaning of the undocumented item_id ('a una publicación'), without stating it is the publication identifier or the expected format (e.g. MCO123). Baseline 3 given partial schema coverage.

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 (Sube) plus resource (un Clip, video vertical corto) and the target (una publicación), and even names ml_clips as the follow-up verification tool. An agent can distinguish it from ml_borrar_clip and ml_clips 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 'Requisitos de MercadoLibre' block effectively states the preconditions for use (publicación activa, format, duration, resolution, size), and it routes the agent to ml_clips afterwards to check moderation. It stops short of explicitly saying when not to use it or contrasting it with ml_borrar_clip/ml_actualizar_publicacion.

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 meaningful behavior: it is a local page, works without internet, has a guided tutorial, and updates automatically with each team control. It does not specify what is returned when abrir is false or whether a file is written, leaving minor behavioral ambiguity.

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 purpose is front-loaded and nearly all content is relevant, but the first sentence is an extremely long run-on enumeration. It would be more scannable if the dashboard sections were structured or shortened instead of packed into one dense clause chain.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a simple one-parameter tool with no output schema, the description is rich about what the dashboard contains and how it behaves offline. It still does not clarify the return/result when abrir is false, which matters slightly because no output schema exists.

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 schema already explains that 'abrir' opens the page in the browser. The description repeats this ('Con abrir=true la abre en el navegador') but adds no new meaning beyond the schema, so 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?

States a specific verb and resource: 'Arma el tablero visual del día' and then enumerates the dashboard contents. It is clearly a daily visual dashboard, but it does not explicitly distinguish itself from siblings such as ml_panel_ventas, ml_metricas, or ml_numeros.

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?

Usage is implied by the daily overview content and by 'Con abrir=true la abre en el navegador', but there is no explicit when-to-use guidance or comparison with alternative summary/metrics tools. An agent can infer the purpose, but must decide on its own when this is preferable to sibling dashboard tools.

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 annotations declare readOnlyHint=true, but the description plainly describes mutating operations: assigning tasks ('asignar (darle una tarea)'), removing, pausing, activating, connecting Google Drive ('drive (conectar Google Drive)') and taking a database backup. That is a direct contradiction of the read-only declaration, and an agent trusting the annotation would invoke it believing no state changes. Flagged as an annotation contradiction; the description itself is also silent on side effects like writing to equipo.db and pushing files to Drive.

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 text is a single run-on block dense with emoji, nested parentheses and a 19-name roster that precedes any statement of what the tool does. The operational information (actions, naming rules, ml_vigilar fallback) is buried at the end, so the agent must read the whole thing to find the actionable core; the roster is reference material that belongs in a schema or worker enum.

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 18 parameters, 12 actions and no output schema, the description does cover the storage/transport model (local SQLite equipo.db plus Google Drive) and gives one-line glosses for each action. What it omits is what the read actions actually return (equipo state, informe alerts, resultados tables) and the fact that this single tool mixes safe reads with state-changing actions, which matters a lot for a multi-action definition.

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 94%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: it binds specific parameters to specific workers ('a Fede se le asigna ref=TU publicación y fuente=publicación o URL del proveedor', 'a Emma se le asigna ref=la búsqueda del nicho') and explains that workers can be addressed by name or role. That pairing of worker with ref/fuente is genuinely useful routing information beyond the per-field descriptions.

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 opening states a concrete resource (a team of 19 monitoring workers) and the trailing sentence enumerates the management verbs it supports (equipo, asignar, quitar, pausar, activar, frecuencia, correr, informe, resultados, historial, base, drive), so an agent can tell this is the worker-orchestration tool. Sibling differentiation is only partial: ml_vigilar is mentioned once as the fallback source of followed targets, but overlapping siblings such as ml_jefe, ml_auditar_publicaciones and ml_novedades_competencia are never contrasted, and the long roster of personas crowds out the actual purpose statement.

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?

Per-action hints are embedded in the description and schema ('informe (alertas nuevas)', 'correr (que trabajen ya)', 'drive (conectar Google Drive)'), and one selection rule is given (a worker with no own tasks watches your ml_vigilar follows of its type). However there is no explicit 'use this instead of X' guidance against the many overlapping monitoring siblings, and no prerequisites or ordering advice (e.g. assign before correr).

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.