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

The annotations already mark the tool as destructive and non-read-only; the description adds the important real-world consequence that the change is visible to buyers and requires confirmation. This complements the annotations and does not contradict them.

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 compact sentence with no filler. The core action is front-loaded, and the warning about user confirmation follows naturally without adding unnecessary detail.

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?

It covers the essential risk warning for a side-effecting tool and names the affected fields. However, with low parameter schema coverage and no output schema, it leaves some parameter semantics and the full allowed estado values for the agent to 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 description coverage is only 40%, so the description needs to compensate. It identifies which fields can be edited and mentions active/paused states, but it omits the 'closed' enum value present in the schema and does not explain constraints or per-field behavior for precio, título, or estado.

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 uses the specific verb 'Modifica' and names the resource 'publicación EN MERCADOLIBRE' plus the affected fields (precio, stock, título, estado). It clearly distinguishes this tool from the sibling listing/report tools by describing a direct update operation.

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 one useful guideline: confirm with the user before executing because the write is real and visible to buyers. However, it does not state when to prefer this tool over siblings or when not to use it, so the usage context is only partially covered.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful content context about the types of alerts but does not disclose return format, pagination, or any filtering behavior, which would have added more value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no filler. The first sentence front-loads what alerts are available, and the second adds a practical workflow hint. Every word 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 read-only tool with one optional, well-described parameter and strong annotations, the description provides enough to understand what the tool does and when to use it. It could be more explicit about the output shape or that it returns a list, but the alert categories make the expected result reasonably clear.

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 input schema covers 100% of the single parameter (cuenta) with its own description, so the schema already carries the parameter meaning. The description adds no additional parameter guidance, which is acceptable given the high 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?

The description clearly identifies the resource (system-generated alerts) and enumerates specific categories: stock-outs, competitor price drops, new claims, and paused listings. However, it lacks an explicit verb like 'list' or 'show,' so the action is implied rather than stated, and it doesn't explicitly distinguish itself from related siblings beyond the workflow hint.

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 explicitly positions the tool as a good second step after ml_panel, giving the agent useful sequencing guidance. It does not mention alternatives or when not to use it, but the context is clear for a simple read-only alerts tool.

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 alreadly declare it as read-only and non-destructive, and the description goes beyond them by explaining what each mode means: dia includes released and about-to-enter money, rango covers last 14 days, and proyeccion describes uncredited income day by day. This adds useful behavioral context without contradicting 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?

Two dense sentences carry all key information: the first defines the three modes and the second gives when-to-use guidance. There is no filler, and the intended usage is front-loaded enough; it could be slightly clearer with an explicit action verb.

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

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

Given the low complexity, full schema coverage, and read-only annotations, the description supplies enough calling context: mode meanings, optional date behavior, and common user intents. The return format/amount structure is not described, but there is no output schema and the agent's selection/invocation task is well supported.

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 three parameters. The description adds real semantic value beyond the schema by expanding 'modo' with user-facing meanings (available money, when paid, weekly inflow) that help the agent choose between dia/rango/proyeccion. It contributes little for fecha/cuenta, but those are adequately described 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 clearly identifies the tool as a MercadoLibre money/caja lookup with three explicit modes (dia, rango, proyeccion) and concrete use cases. It lacks a direct verb like 'consulta' or 'muestra' and does not name a sibling, but the mode breakdown and title 'Caja y acreditaciones' make its purpose distinct from metrics/order/publication siblings.

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 last sentence gives explicit triggers: 'Usar cuando preguntan por plata disponible, cuándo cobran o cuánto entra esta semana.' This tells an agent when to select the tool, though it does not state when not to use it or name alternative tools for other money/order 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about scope (own and monitored competitor price movements), though it does not clarify the recency window, data freshness, or response format.

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 filler. The first sentence states the tool's scope, and the second explains when it is useful. Information is front-loaded and every sentence 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 read-only tool with two optional parameters, the description plus annotations is mostly sufficient. It communicates the data scope and intended use cases, though it omits response details and a defined time window, which would be more critical if no output schema existed.

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

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

The schema describes 'cuenta', but 'limite' has no description. The tool description adds no parameter meaning beyond the schema, so it does not compensate for the partial schema coverage. The agent must infer 'limite' from its name and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource: recent price movements for the user's own listings and monitored competitors. It lacks an explicit verb like 'list' or 'get', and it does not explicitly differentiate from sibling tools like ml_competidores or ml_simular_precios, but the intended function 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?

The description gives concrete use cases: reacting to a competitor price drop or auditing one's own price changes. It does not name alternatives or state when not to use the tool, but the context provided is enough to guide selection.

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 destructiveHint=false. The description adds what the tool returns—competitor list, prices, and winner—which is valuable since there is no output schema. It doesn't disclose limitations or edge cases, but does not contradict the 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?

Two short sentences with no filler: the first states the core function, the second gives the use case. Information density is high and 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-parameter read-only tool, the description covers the main use case and output contents, and the schema covers parameter semantics. It lacks an example and doesn't explain 'caja de compra', but these are minor given the sibling context and annotations.

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 'buscar' and 'cuenta' are already documented. The description adds no further parameter-level meaning beyond restating that it searches for a catalog product, which is already 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 action (search for a catalog product) and a specific outcome (show who competes for the buy box, at what price, and who is winning). The phrase 'Usar cuando preguntan por qué no ganan el catálogo' anchors it to a concrete user intent, distinguishing it from generic competitor tools like ml_competidores.

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 provides an explicit trigger condition: use when asked why they don't win the catalog. However, it doesn't name alternative tools or state when not to use it, so it stops at clear context without exclusions.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some context by noting that the sellers are being monitored and that sales are 'estimadas', but it does not disclose data freshness, update cadence, or any operational caveats beyond that.

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 two short sentences with no filler. The core subject and returned metrics come first, followed by a clear usage cue, so the most decision-relevant information 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 simple read-only tool with one optional parameter and annotations covering safety, the description conveys what the tool returns and when to use it. The main gap is that it does not explain what happens when 'cuenta' is omitted, even though the schema marks it as optional.

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 single parameter 'cuenta' is already described as the MercadoLibre account ID. The description adds no further meaning about how to choose or omit this optional parameter, which leaves the baseline at 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource (monitored competitor sellers) and the data returned (reputation, listings, estimated sales, average price). It lacks an explicit action verb like 'list' or 'get', and does not name sibling tools to distinguish itself, but the content is specific enough to separate it from broad market tools.

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 provides an explicit usage trigger: 'Usar cuando preguntan cómo están contra la competencia.' It gives clear context for when the tool applies, but it does not mention exclusions or explicitly compare against sibling tools such as ml_competitividad or ml_mercado.

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 carry the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), so the description only needs to add context. It discloses what is evaluated and the three outcome states, including the buy-box concept. However, it does not explain how 'market' pricing is sourced, data freshness, or edge cases such as listings without market data.

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 with zero waste. The function and output categories are front-loaded, followed by the usage trigger. Every sentence 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 2-param read-only tool with no output schema, the description conveys the conceptual return value (comparison status vs. market) and the trigger scenarios for use. It does not describe the exact response format or define the 'caja de compra' domain term, but the three outcome categories largely cover return semantics.

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 50%: cuenta is documented in the schema, while limite is left to its name and constraints (default 30, min 1, max 100) for meaning. The description adds no parameter-level detail and does not clarify how limite interacts with the 'cada publicación propia' scope, though the constraints make limite reasonably inferable.

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 (compara) and resource (el precio de cada publicación propia contra el mercado), and concretely defines the output as three categories: por encima, por debajo, o perdió la caja de compra. It does not explicitly name siblings, but the precise scope makes it readily distinguishable from close relatives like ml_simular_precios (simulation) and ml_cambios_precio (price-change history).

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 second sentence gives explicit trigger scenarios: 'Usar cuando preguntan si están caros o por qué cayeron las ventas.' This tells an agent exactly when to select this tool. It stops short of a 5 because it does not state when not to use it or name a specific alternative tool.

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 convey readOnlyHint, openWorldHint, and non-destructive behavior. The description adds meaningful context by stating it 'Devuelve un link que el usuario abre en el navegador' and explicitly declaring 'no autoriza nada por su cuenta,' which clarifies the side-effect boundary beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences with the core function first, then explicit usage triggers, then a clarifying behavioral note. Every sentence earns its place and the most decision-relevant information 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 tool with one optional boolean parameter and no output schema, the description covers what the tool does, when to use it, what it returns, and what it does not do. An agent has enough information to select and invoke 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 description coverage is 100%, and the single optional boolean parameter 'diagnostico' is already documented in the schema. The tool description itself adds no further parameter-level meaning, so the baseline score of 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 opens with a specific verb and resource: 'Genera el link de autorizacion para vincular una cuenta de MercadoLibre nueva' and also mentions showing the status of already connected accounts. This clearly separates the tool from siblings like ml_cuentas or ml_sincronizar by focusing on the authorization-link connection flow.

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 explicit trigger conditions with exact user phrases: 'quiero conectar mi tienda', 'agregar otra cuenta', 'vincular MercadoLibre', plus the fallback scenario 'cuando alguna herramienta falla porque no hay cuentas.' However, it does not name alternative sibling tools or specify when not to use it, so it falls just 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 and destructiveHint=false, so no contradiction exists. The description adds useful behavioral context by specifying that data is grouped by category and represents the commission and shipping cost per publication. It does not detail data freshness or whether values are percentages, but given the annotation coverage, this is acceptable.

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 concise sentences: the first states what the tool returns, and the second states its purpose. No filler or repetition. The description is efficiently front-loaded with the core resource and grouping 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 simple read-only tool with one optional parameter and no output schema, the description adequately communicates the output shape ('agrupado por categoría') and the practical use case. Minor omissions like currency or whether the fee is a percentage are not severe for selecting and invoking the tool.

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

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

The schema has 100% coverage: the only parameter, 'cuenta', is fully described as 'ID de la cuenta de MercadoLibre. Omitir para la cuenta por defecto.' The description itself does not add any information about the parameter, so the baseline score 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 clearly identifies the resource: commissions and shipping costs charged by MercadoLibre per publication, grouped by category. It also gives the intended use case ('saber cuánto se lleva ML de cada venta antes de fijar precio'). However, it lacks an explicit verb like 'obtener' or 'consultar', so it is a noun-phrase description rather than a full imperative statement, and it does not explicitly distinguish itself from sibling tools.

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 a clear context for when to use the tool: before setting a price, to know how much MercadoLibre takes from each sale. It does not mention alternatives or explicitly state when not to use it, but the use case is specific enough to guide an agent.

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 indicate readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral detail about the output: linked accounts, app configuration state, active accounts, and webhook status. It does not contradict the annotations and does not imply any hidden side effects.

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 purpose and output items, followed by a practical usage note. Every part of the description earns its place; there is no filler or repetition.

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 parameterless read-only listing tool with no output schema, the description is complete: it names the output categories, the connection-state fields, and the canonical use case. An agent has enough information to select and invoke the tool 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?

The tool has zero parameters, so there is little semantic burden on the description. The description even supports parameter selection indirectly by explaining that the tool reveals which account ID to pass in the 'cuenta' parameter of other tools.

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 specifies a concrete action ('Lista') and resource ('cuentas de MercadoLibre vinculadas'), and it clarifies what aspects of the connection state are included (app configurada, cuentas activas, webhook). This clearly distinguishes the tool from the many sibling tools that operate on orders, publications, metrics, or messaging.

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 an explicit usage directive: use it at the beginning when there is more than one account, and explains the purpose is to know which ID to pass in the 'cuenta' parameter of other tools. This is direct, actionable guidance that tells the agent when to invoke the tool.

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 destructiveHint=false, covering the safety profile. The description adds that the tool reports per-publication visit/question/sale counts, but it does not disclose aggregation windows, data freshness, or response shape; with annotations present, this is adequate but not rich.

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 front-loaded sentence states metrics and purpose with no filler. The title and description are slightly redundant but the description itself is efficiently structured.

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 one optional parameter and read-only annotations, the description gives sufficient semantic context to invoke it. The only notable gap is the lack of any mention of time period or how the per-publication rows are returned, which would matter in richer contexts.

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% (cuenta is fully described as an optional MercadoLibre account ID), so the schema carries the parameter meaning. The description adds no parameter-level detail, meeting the baseline for high 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?

The description names the resource (each publicación) and the metrics (visitas, preguntas, ventas), tying them to a conversion-funnel objective. It is clear enough to distinguish from visit-only or question-only siblings, though it never names an alternative and lacks an explicit imperative verb.

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 detectar dónde se cae la conversión' gives a clear context for when to request this report. However, it does not state when not to use it or point to alternatives among the many metric tools (e.g., ml_visitas, ml_preguntas_estadisticas).

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 destructiveHint=false, covering the safety profile. The description adds the time-window scope and reconciliation purpose, but doesn't disclose return format, pagination, or data-source behavior. No contradiction with 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?

A single sentence with no filler. It front-loads the core output (billing/commissions evolution and totals) and then states the purpose, making the tool easy to scan.

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 report with two optional parameters and no output schema, the description conveys the output subject and purpose well. It doesn't enumerate exact response metrics, but the low complexity and rich annotations make it sufficient for correct selection and invocation.

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 (dias window with default and range; cuenta ID and omission behavior). The description only reinforces 'últimos N días' and adds no deeper parameter meaning, 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 clearly identifies the tool's subject: evolution of billing and commissions over a rolling N-day window, with totals for reconciliation. It lacks an explicit imperative verb and doesn't name sibling tools, but the AFIP/month-end-closing detail distinguishes it from generic metrics tools.

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 'con los totales necesarios para conciliar contra AFIP o para un cierre de mes' gives an explicit use-case context. However, it doesn't mention when to prefer an alternative tool or when not to use this one, so exclusionary guidance is missing.

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 destructiveHint=false, so the safety profile is covered. The description adds useful context about the data being post-purchase and order-scoped, but it does not disclose return format, pagination behavior, or how the optional 'limite' parameter affects results.

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 concise and front-loaded, with two purposeful sentences and no filler. It earns a deduction because it reads as a noun-phrase definition rather than an action-oriented tool description, but it remains well-structured and easily 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?

For a simple read-only tool with only two optional parameters, the description adequately conveys the subject matter and use case, and the annotations cover the safety profile. However, with no output schema, the description does not explain what the response contains or how 'limite' affects the returned messages, leaving a minor completeness 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?

The description adds no parameter-level meaning. One of the two parameters ('limite') lacks a semantic description in the schema, and the description does not compensate for that gap. With schema description coverage at only 50%, the description should have clarified parameter intent but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource: post-purchase messages between buyers and sellers, associated with each order. It also states its analytical purpose (detecting incipient claims or change requests), which partially distinguishes it from siblings like ml_reclamos and ml_preguntas. However, it lacks an explicit action verb such as 'list' or 'retrieve', so it stops 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 when to use the tool via 'Sirve para detectar reclamos incipientes o pedidos de cambio', giving a clear use case. But it does not explicitly state when to prefer it over alternatives like ml_reclamos or ml_preguntas, nor does it provide exclusion criteria or routing guidance.

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 `destructiveHint: false`, so the read-only nature is covered. The description adds behavioral context by specifying what each mode returns (e.g., 'búsquedas que están creciendo', 'categorías más relevantes', 'más vendidos y rango de precios') and the requirement for `categoria_id`. This is useful but does not go deeper into output formats or pagination, fitting a mid-range score.

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, well-structured sentence that front-loads the core purpose and uses semicolons to efficiently list the three modes. Every clause adds value—no redundancy or filler. The formatting with quotes and bold would likely be clear in display.

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 explains the modes and their inputs but does not specify the exact shape of the response (e.g., whether results are lists, objects, with price ranges, etc.). An agent could infer these from the mode names, but the definition is not fully self-contained for a smooth invocation. The lack of return-format details is a notable 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%, with the `modo` enum and `categoria_id` described in the schema, but the description goes beyond by explaining what each enum value does and providing an example ID ('MLA1234'). This adds meaningful semantic clarity for the `modo` parameter and clarifies the conditional requirement of `categoria_id`, compensating for the uncovered portion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides MercadoLibre market intelligence and enumerates three distinct modes ('tendencias', 'categorias', 'categoria') with a one-line explanation of each. This differentiates it from sibling tools that handle accounts, orders, sales, etc., and gives an agent a precise idea of what it does.

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 explains the three modes and notes that 'categoria' requires a `categoria_id`, which is useful internal guidance. However, it does not explicitly say when to use this tool versus siblings like `ml_competidores` or `ml_competitividad`, and offers no exclusions or alternative routing. The context implies use for market trends and category insights, but it lacks explicit comparison.

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 cover read-only and non-destructive behavior, so the description adds value by detailing the aggregation semantics: it sums all stores, can be narrowed to one account, and lists the output contents including shipping breakdown and product ranking. It does not contradict the annotations and no hidden destructive behavior is implied.

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 direct sentences with no filler: scope is front-loaded, every metric in the run-on list contributes value, and the account-filter behavior is stated at the end. The all-caps 'SUMANDO TODAS' is emphatic but reinforces the key aggregation semantics.

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 must explain what the tool returns, and it does: it enumerates sales counts, revenue, net after commissions, average ticket, per-store contribution, shipping-type split, and top products. The only optional parameter's effect is also described, making the definition complete enough for correct invocation.

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

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

The schema already documents 'cuenta' fully, so the baseline is 3. The description adds explicit behavioral meaning: 'si le pasas una cuenta, muestra solo esa' and clarifies that omitting it means all stores, resolving the schema's slightly ambiguous 'por defecto / todas'.

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 has a specific verb ('Resumen') and resource ('ventas de los últimos 30 días') and spells out the exact metrics delivered: ventas, facturado, neto, ticket promedio, aporte por tienda, envíos por tipo, and top 12 productos. It clearly distinguishes itself from generic dashboards and narrower sales tools by stating the all-stores aggregation scope.

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 the tool is for a 30-day sales overview across all stores and that passing a 'cuenta' filters to one store, but it never explicitly says when to prefer this tool over sibling tools like ml_ventas_geo, ml_caja, or ml_rentabilidad. No alternatives or exclusions are named.

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

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

Las anotaciones ya declaran readOnlyHint=true y destructiveHint=false; la descripción añade contexto útil: devuelve campos específicos, limita a 100 órdenes y ordena de más reciente a más vieja. No contradice las anotaciones y aporta más detalle del que estas ofrecen.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

La descripción es breve, directa y va al grano: primero enumera los datos devueltos y luego especifica el límite y el orden. No hay frases redundantes ni información que duplique innecesariamente el esquema.

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 de solo lectura con dos parámetros opcionales bien documentados en el esquema, la descripción entrega los campos de salida, el límite máximo y el orden de resultados. Aunque no hay esquema de salida, la descripción es suficiente para que un agente sepa qué esperar y cómo invocarla correctamente.

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

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

El esquema cubre el 100% de los parámetros con descripciones claras: cuenta opcional con comportamiento 'por defecto / todas' y límite con mínimo, máximo y valor por defecto. La descripción solo repite indirectamente el tope de 100 órdenes y no agrega significado adicional a los parámetros.

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 indica claramente que la herramienta devuelve ventas/órdenes recientes con comprador, total, comisión, neto, estado de pago y fecha de acreditación. El recurso y el alcance quedan claros, aunque no se diferencia explícitamente de herramientas hermanas como ml_ventas_geo o ml_metricas.

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?

Se puede inferir que la herramienta se usa para consultar las últimas órdenes/ventas, con límite de 100 y orden de más reciente a más vieja. Sin embargo, no se indican condiciones de uso explícitas ni alternativas para casos en que se necesiten otros tipos de reportes de ventas.

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 destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: it sums data from all connected stores, includes a comparison against yesterday, and adjusts scope based on the 'cuenta' parameter. This goes beyond the annotations without contradicting them.

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 concise for the information it conveys: a first sentence summarizes the output, a second provides usage guidance, and a third clarifies parameter behavior. The key purpose is front-loaded, and every sentence is purposeful. It is slightly verbose 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?

Given the tool's simplicity (1 optional parameter, no output schema), the description covers the essential aspects: what data is returned, how scope is controlled, and when to use it. It does not specify details like pagination or data freshness, but these are not critical for a summary dashboard tool. Overall, it is sufficient for an agent 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 100% since the single parameter 'cuenta' has a clear description ('ID de una tienda puntual. Omitir para el consolidado de todas.'). The description's note 'Si le pasas una cuenta, muestra solo esa' essentially restates the schema, adding minimal extra value. This matches the baseline of 3 for high 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?

The description clearly states the tool's purpose: a consolidated daily summary across all connected stores, including sales, billing, units, comparison vs. yesterday, per-store breakdown, and recent sales. It uses specific verbs and a clear resource, and it is easily distinguished from sibling tools like ml_metricas or ml_ventas_geo by its aggregate 'photo of the day' scope.

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 explicitly identifies this as the starting tool for queries like 'how is the day going' or 'how are the stores', providing strong usage context. It also clarifies the effect of the 'cuenta' parameter (filtering to a single store). However, it does not explicitly name alternatives or state when *not* to use this tool, 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 mark it read-only and non-destructive, so the bar is lower. The description adds the default pending state, the urgency rationale, and the fact that the response includes the internal ID needed for ml_responder_pregunta — useful behavioral and output context beyond the 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?

Two sentences with no filler: resource/filters first, default behavior second, and output linkage last. Every sentence contributes a distinct fact.

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?

The core information for calling the tool correctly is present: filters, default estado, and the output linkage to ml_responder_pregunta. It could be more complete by explicitly noting that it returns a list of questions and pointing to ml_preguntas_estadisticas for aggregate statistics, but the current definition is adequate for a simple filtered-list 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?

With 83% schema coverage, the schema already documents most parameters, but the description adds meaning by grouping filters (estado, publicación, mes, texto) and labeling pending items as urgent, which helps an agent decide on defaults. It does not add detail for cuenta or limite, but the schema covers those.

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 (buyer questions on listings) with named filters and explicitly ties its output to ml_responder_pregunta, which distinguishes it from related siblings like ml_preguntas_estadisticas. The verb is implicit but the scope is unambiguous and not a mere restatement of the tool's name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: by default it returns pending questions because they are urgent, and it supplies the ID required for the follow-up tool ml_responder_pregunta. It does not explicitly enumerate exclusions or alternatives like ml_preguntas_estadisticas, so it stops 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?

Las anotaciones ya cubren readOnlyHint=true y destructiveHint=false, y la descripción agrega contexto útil sobre las métricas devueltas. Sin embargo, no revela detalles de comportamiento como autenticación, formato de salida o efectos de los filtros. No hay contradicción con las anotaciones.

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?

Dos frases compactas que primero enumeran los resultados y después el caso de uso; sin relleno ni repetición del título.

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 de solo lectura con dos parámetros y sin output schema, la descripción lista las métricas clave y su finalidad; el agente sabe qué esperar y cúándo usarla. Sin embargo, no explica cómo 'dias' afecta el cálculo ni qué cuenta se usa, aunque el schema da pistas parciales.

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

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

La cobertura del schema es solo del 50%: cuenta está descrita, pero 'dias' no. La descripción no menciona ningún parámetro ni aclara que 'dias' define la ventana de tiempo del análisis, por lo que no compensa el hueco del esquema.

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 métricas concretas (tasa de respuesta, tiempo promedio en minutos, ventas, publicaciones top, distribución horaria) y el propósito ('dimensionar la atención'), dejando claro que es un reporte estadístico de preguntas. Aunque no usa un verbo imperativo explícito, el recurso y las métricas la distinguen de herramientas hermanas como ml_preguntas o ml_responder_pregunta.

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?

La frase final 'Sirve para dimensionar la atención y decidir horarios de cobertura' establece un contexto de uso claro y cuándo tiene sentido invocar la herramienta. No menciona exclusiones ni alternativas explícitas, como usar ml_preguntas para preguntas individuales, por lo que no llega 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context that results are account-specific and that eligibility is potential ('podrían entrar'), but it does not describe pagination, data freshness, or the return format. This is consistent with the annotations and adds moderate value beyond them.

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 two short sentences with no wasted words. The first sentence defines what the tool returns, and the second gives the practical trigger for using it. This is well-structured and 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 read-only listing tool with three optional, fully schema-documented parameters and no output schema, this definition is largely sufficient for an agent to select and call it. Minor gaps include not stating what happens when no filters are provided and not naming closest sibling alternatives, but these are not blocking.

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 has a clear description in the input schema. The tool description does not add parameter-level detail, but the schema carries that burden, so the baseline score of 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 clearly states that the tool surfaces MercadoLibre promotions/campaigns offered to the account and which listings might qualify. It also ties the tool to a concrete user question ('si conviene entrar a una promo o al Hot Sale'), which helps distinguish it from the many other ml_* tools. It lacks an explicit verb like 'list' or 'returns', so it stops short of a perfect 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 gives an explicit trigger: use it when someone asks whether it is worth joining a promotion or the Hot Sale. It does not mention when not to use it or name alternative siblings, but the use case is clear enough for an agent to route correctly.

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 mark readOnlyHint=true and destructiveHint=false, and the description adds that the data are 'sincronizadas' and enumerates the returned fields. This is useful context beyond the annotations, though nothing further about auth, pagination, or rate limits is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, each carrying substantive value: one defines the resource and content, the other describes the filtering option. No filler or redundancy.

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, the description covers the result fields, the sync scope, and the search capability; the schema covers the optional parameters and limits. Minor omissions such as default ordering are acceptable given the annotations.

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's only parameter guidance ('buscar por título o MLA') largely repeats the schema's existing property description for 'buscar'. It adds no meaning for 'cuenta' or 'limite', and at 67% schema coverage the description does not compensate for the gap.

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 title 'Listar publicaciones' and description 'Publicaciones sincronizadas con título, precio, stock, vendidos, estado y link' clearly identify a list operation over publication records with specific output fields. This distinguishes it from sibling mutation tools like ml_actualizar_publicacion and from metrics/panel tools.

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 indicates the tool lists synchronized publications and accepts a text filter, which implies when to use it, but it does not explicitly state conditions or exclusions relative to the many sibling tools. No alternatives are named, so an agent must infer the decision.

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

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

Las anotaciones ya declaran readOnlyHint=true y destructiveHint=false, así que la barra es más baja. La descripción agrega qué campos reporta, pero no aclara el nivel de agregación, el comportamiento del período de días ni prerequisitos de conexión. Es una transparencia básica y útil, sin contradicción con las anotaciones.

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?

Dos oraciones sin relleno: la primera presenta el recurso y las métricas clave, la segunda da la instrucción de uso. No repite información del esquema ni incluye contenido sobrante.

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 read-only con dos parámetros simples y sin output schema, la descripción es casi suficiente: indica las métricas devueltas y el tipo de pregunta que resuelve. Podría mencionar prerequisitos de conexión o cómo filtran los parámetros, pero esos son detalles menores dado el esquema simple.

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 ya documenta 'cuenta' como ID de MercadoLibre y 'dias' tiene tipo, rango y default. La descripción no explica explícitamente que 'dias' controla el período analizado ni que los resultados dependen de 'cuenta', pero el nombre y el esquema cubren la mayor parte. Es adecuado con un vacío menor.

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?

Identifica un recurso específico (campañas de publicidad de MercadoLibre) y las métricas que devuelve: inversión, impresiones, clics, ACOS y ventas atribuidas. No usa un verbo explícito, pero la frase de uso deja claro que el propósito es responder sobre pauta publicitaria. Se distingue de hermanos como ml_metricas o ml_publicaciones por el foco en 'publicidad', aunque no nombre una alternativa.

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?

Da un disparador claro y accionable: usar cuando pregunten si conviene la pauta o cuánto están gastando en ads. Es contexto suficiente para elegir la herramienta sin abrir el esquema. No menciona exclusiones ni alternativas específicas, por lo que no llega 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 and destructiveHint=false, and the description does not contradict them. It adds meaningful behavioral context beyond annotations by describing the output contents: open claims, ongoing returns, reputation-affecting items, expired deadlines, and amount in play. This helps the agent set expectations for what the tool exposes.

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 concise sentences with no filler; the first front-loads the concrete data categories, and the second gives the use case. Every sentence earns its place and the description 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?

Given the simple two-parameter schema, read-only annotations, and no output schema, the description provides enough context about what the tool returns and when to use it. It could be slightly stronger by clarifying how optional parameters like 'cuenta' behave when omitted, but that is a minor gap relative to the overall clarity.

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 50%, with 'cuenta' documented but 'limite' only given constraints (default 30, max 100, min 1) and no semantic explanation. The tool description does not compensate for this gap, as it does not mention either parameter or clarify how 'limite' affects results. The schema leaves the meaning of 'limite' mostly to inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource ('reclamos abiertos, devoluciones en curso') and the specific information provided: reputation impact, expired action deadlines, and amounts at stake. It also distinguishes this tool from siblings like ml_reputacion by framing it as the first stop when reputation drops.

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 an explicit trigger condition: 'Es lo primero a mirar cuando la reputación baja.' This tells an agent when to use the tool, though it does not explicitly name alternatives or state when not to use it. The context is clear enough for selection among the many sibling 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 and destructiveHint=false, so the safety profile is covered. The description adds the 30-day time window and diagnostic intent, but gives no further behavioral detail such as how results are aggregated or returned.

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 focused sentences with no filler. The first defines the computation, the second states actionable value, making it easy to scan.

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

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

No output schema exists and the description does not describe the return shape or how 'limite' affects results. It is adequate for a simple read-only analytics tool, but leaves invocation details partly to inference.

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 50%; 'cuenta' is documented, but 'limite' has no schema description and the tool description does not explain it. The description's 'últimos 30 días' refers to the analysis window, not the 'limite' parameter, so it adds no parameter-level 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?

The description states a specific analytic action: crossing visits against sales for the last 30 days and calculating conversion rate per publication. This clearly distinguishes it from sibling tools like ml_visitas or ml_metricas by including sales and conversion, not just traffic.

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 use case is implied by 'Detecta las que reciben tráfico pero no venden' — an agent can infer when to use it. However, no explicit when-to-use/when-not-to-use guidance or named alternatives is provided.

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, openWorldHint, and non-destructive, so the safety profile is covered. The description adds behavioral context by enumerating exactly which costs feed the margin and by clarifying the two output modalities. This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short, front-loaded sentences. The first defines the calculation, the second gives mode semantics, and the third gives the usage trigger. There is no filler or redundant restating of the tool name.

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 required parameters and no output schema, the description covers purpose, calculation components, mode behavior, and when to invoke it. An example of the expected output shape would have made it slightly more complete, but nothing critical is missing for selecting and calling the 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 83%, so the schema already documents most parameters. The description adds value by explaining the choice between 'periodo' and 'mensual' in terms of 'rango puntual' vs. 'serie mes a mes', which is not fully captured in the schema. It does not need to repeat parameter names or types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool computes: real margin after ML commission, shipping cost, product cost, and taxes. It also gives concrete query triggers ('si ganan plata, cuánto margen dejan o qué producto no conviene'), which effectively separates it from generic reporting tools. It lacks an explicit verb and does not name a sibling tool, so it falls just short of the top score.

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 explicit usage conditions: use this tool when the user asks about profitability, margin, or unprofitable products. It also explains when to use each mode ('periodo' for a specific range, 'mensual' for a month-by-month series). It does not name alternative tools or state negative selection criteria, so it is not a perfect 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?

Las anotaciones ya declaran readOnlyHint=true, openWorldHint=true y destructiveHint=false, y la descripción no las contradice. La descripción añade que la herramienta entrega métricas concretas, pero no detalla comportamiento adicional como autenticación, vigencia de los datos o alcance por cuenta. Con la barra baja que otorgan las anotaciones, un 3 es adecuado.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

La descripción es de dos frases sin relleno: la primera enumera el contenido devuelto y la segunda establece el caso de uso. Cada oración aporta información necesaria y está bien priorizada.

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 y sin esquema de salida, la definición es suficiente: el esquema documenta el parámetro, las anotaciones cubren la seguridad y la descripción lista los campos principales devueltos. Podría añadir una nota sobre el comportamiento sin cuenta o su relación con ml_metricas, pero no es crítico.

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 cubre el 100% del único parámetro 'cuenta' con su descripción ('ID de la cuenta de MercadoLibre'). La descripción de la herramienta no aporta semántica adicional sobre el parámetro. Por tanto, se aplica el baseline de 3 para esquemas con alta cobertura.

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?

El título y la descripción identifican el recurso (reputación del vendedor) y enumeran los datos devueltos: color, nivel MercadoLíder, porcentaje de reclamos, cancelaciones y demoras. No hay un verbo explícito tipo 'obtiene' o 'consulta', pero el contenido deja claro qué hace la herramienta. Se distingue razonablemente de hermanas como ml_reclamos o ml_metricas por su foco en el termómetro de reputación.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

La descripción indica explícitamente cuándo usar la herramienta: 'cuando preguntan por el termómetro o por qué bajó la reputación'. Esto proporciona una condición de uso clara. No menciona alternativas ni exclusiones, pero para un caso de consulta de reputación es suficiente en la mayoría de los escenarios.

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 goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing that the write is irreversible ('escritura real e irreversible'), that the answer becomes publicly visible, and that the agent must obtain explicit user confirmation before executing. This is exactly the behavioral guidance an agent needs for a destructive external-state-changing tool, and it is consistent with the 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?

Three compact sentences, each carrying necessary weight: the action, the safety warning, and the ID provenance. The public-visibility and irreversibility warnings are front-loaded immediately after the main verb, which is the right placement for a destructive tool. No wasted words.

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 two-parameter destructive write with full schema coverage, the description covers everything essential to invoking it correctly: what it does, the public/irreversible consequence, the required confirmation step, and where the ID comes from. The only omission is the return value or post-execution behavior, but no output schema exists, and for this tool an agent has enough to act safely.

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 fully documents both id and texto, including the ID column source and the fact that texto is exactly what buyers will read. The description reinforces the ID origin ('El id es el que devuelve ml_preguntas'), which is mildly useful, but it does not add meaning beyond what the parameter descriptions already provide. 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 states a specific verb and resource: 'Publica la respuesta a una pregunta EN MERCADOLIBRE, visible para todos'. It clarifies the action is a public write to MercadoLibre, which clearly distinguishes it from read-only siblings like ml_preguntas and private-message tools like ml_mensajes. The irreversible-write warning further pins down its identity.

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 explicit operational context: show the answer text to the user and await confirmation before executing ('mostrale el texto al usuario y esperá su confirmación'), and states the ID comes from ml_preguntas. This effectively tells the agent when and how to invoke it. However, it does not explicitly name alternatives or state when not to use it (e.g., private replies should go through ml_mensajes).

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 cover read-only and non-destructive behavior. The description adds useful context about the output content (quality score and improvement tasks) but does not disclose return format, scoring scale, or any limitations. This is adequate but not rich.

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 concise sentences: the first states what the tool returns, the second states when to use it. No wasted words and the important output purpose 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 read-only diagnostics tool with optional parameters, the description covers the core purpose and usage context. Gaps remain around the exact return shape and the meaning/effect of 'limite', but these are minor for an agent deciding to call it.

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

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

The schema documents 'cuenta' well, but 'limite' has no semantic description. The tool description adds nothing about either parameter. With only 50% schema description coverage, the description should compensate for the undocumented 'limite' parameter and does not, leaving its meaning ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's purpose: providing a MercadoLibre quality score per publication and concrete tasks to improve it. It names specific quality factors (photos, technical sheet, description, warranty), which distinguishes it from siblings like ml_rendimiento_publicaciones or ml_metricas.

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 an explicit trigger: use when users ask how to improve positioning or why a listing isn't selling. It does not mention when not to use it or name alternatives, but the stated context is clear enough for selection.

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 destructiveHint=false, so the non-mutating behavior is partially covered there. The description adds useful behavioral detail by stating that configured rules (percentage or fixed amount) are applied and that non-persistent results are returned, without contradicting the 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?

A single, compact sentence packs the action, the rule types, the output, and the crucial non-mutating guarantee. There is no filler, and the most important differentiator—simulation, no changes to MercadoLibre—is clearly emphasized.

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 output schema, the description does a decent job explaining the return values (new price and delta) and the non-mutating nature. However, it omits any explanation of how 'limite' behaves and does not describe the output structure beyond a brief phrase, leaving some gaps for correct invocation and result interpretation.

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 50%: 'cuenta' has a description but 'limite' does not. The description adds no parameter-level meaning and does not mention that 'limite' constrains the simulation size or that 'cuenta' selects the target account. It fails to compensate for the schema's missing parameter documentation.

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 action—apply configured price rules—and a specific resource, the catalog, then states exactly what it returns: new price and delta per publication. The emphatic 'SIN tocar nada en MercadoLibre. Es una simulación.' clearly distinguishes this from real price-change operations among siblings.

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 makes the usage context explicit: use this when you want to preview price changes without affecting MercadoLibre. It clearly signals a simulation use case, though it does not explicitly name an alternative like ml_cambios_precio or state when that alternative should be used instead.

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 behavioral context beyond the annotations: it warns that the operation 'Puede tardar' and clarifies that it forcibly syncs against an external API. It does not contradict the annotations, and readOnlyHint=false already signals mutation. A small gap is that it doesn't describe what happens to existing data if sync fails or partially completes.

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 compact and well-structured: the core action comes first, followed by a relevant latency warning, then a clear usage condition. Every sentence earns its place without redundancy.

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 zero-parameter manual sync action, the description is complete: it specifies the data domains synced, warns about duration, and provides a concrete invocation criterion. No output schema exists, but the agent has enough information to decide when and how to call the 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?

There are zero parameters and schema description coverage is 100%, so the schema carries no parameter burden. Per the baseline for 0-param tools, this is a 4; the description doesn't need to explain parameter meanings.

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 ('Fuerza una sincronización') and a clear resource scope ('órdenes, publicaciones y preguntas contra la API de MercadoLibre'). It also distinguishes this tool from the many query/update siblings by emphasizing it forces a sync rather than reading or editing specific 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?

Explicit usage guidance is provided: 'Usar solo si el usuario dice que faltan datos recientes; el sistema ya sincroniza solo.' This tells the agent exactly when to invoke the tool and implies the alternative (automatic synchronization) that should be preferred in normal circumstances.

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 destructiveHint=false, and the description aligns with them by describing a reporting tool. It adds useful behavior context: the difference between the low-stock mode and the full Fulfillment panorama with coverage days and breakage risk. It does not discuss pagination or data freshness, but this is acceptable for a read-only stock report.

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 short sentences carry substantial information: mode definitions, the Fulfillment detail, and a clear usage trigger. There is no filler or repetition.

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 query with zero required parameters, the description plus schema covers the invocation essentials: modes, threshold, account ID, and when to use it. No output schema exists, but the description states what each mode returns, so the remaining gap is only a lack of example output formatting.

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%, with cuenta and maximo described but not modo. The description fills the main gap by explaining what 'bajo' and 'full' modes mean. It also reinforces the threshold concept behind maximo, though somewhat redundantly with 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 defines two modes ('bajo' for low-stock listings, 'full' for Fulfillment stock coverage with days of inventory and breakage risk) and clearly identifies the resource as stock-related. It does not explicitly name a sibling to disambiguate from tools like ml_salud_publicaciones, but the stock/stockout focus makes the purpose recognizable.

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 an explicit trigger: 'Usar cuando preguntan qué se va a quedar sin stock o qué reponer.' This tells an agent when to invoke the tool, though it does not mention when not to use it or name alternative sibling 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 and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns an aggregated provincial distribution rather than raw sales data, but does not describe response format, time windows, or account-scoping 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?

The description is two short sentences with no filler. The core meaning ('Distribución de las ventas por provincia') is front-loaded, and the second sentence provides useful business context without redundancy.

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 tool with one optional parameter, the description covers purpose and usage well. Since there is no output schema, a bit more detail about the exact response format could have been helpful, but the tool is simple enough that the description 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 only parameter 'cuenta' has a clear description in the schema. The tool description adds no extra parameter meaning, but given full schema coverage, the baseline score of 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 clearly identifies the tool's output: sales distribution by province ('Distribución de las ventas por provincia'). This is a specific, province-level resource that is distinct from the broader sibling tools, though it does not explicitly name a differentiating sibling or use an action verb.

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 'Sirve para decidir depósitos, costos de envío o dónde pautar' gives concrete business contexts in which the tool is useful. It provides clear usage context without explicitly stating when not to use it or naming alternative 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?

Las anotaciones ya declaran readOnlyHint=true, openWorldHint=true y destructiveHint=false, cubriendo el perfil de seguridad de la operación. La descripción añade contexto útil al especificar que se trata de una serie temporal por publicación, pero no detalla aspectos como el rango de fechas, la granularidad, la paginación o el formato de la respuesta.

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 sola frase sin relleno, con la idea principal al inicio y la finalidad al final. Resulta eficiente, aunque al ser tan escueta no estructura otros elementos útiles como formato de salida o criterios de filtrado, lo que impide la máxima puntuació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 de lectura simple con un único parámetro opcional bien documentado en el schema, la descripción es adecuada. No obstante, al no existir output schema, deja sin aclarar la forma exacta de la serie devuelta y el período cubierto, y tampoco orienta sobre cuándo preferirla frente a otras herramientas analíticas hermanas.

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 schema cubre el 100% del único parámetro (cuenta, opcional, con descripción), por lo que la descripción no necesita compensar vacíos. La descripción no aporta información adicional sobre cómo usar 'cuenta', así que el baseline de 3 es adecuado.

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 identifica un recurso concreto (visitas por publicación) y una finalidad específica (detectar si el tráfico sube o baja), lo que la distingue de herramientas hermanas como ml_mensajes o ml_preguntas. Sin embargo, carece de un verbo explícito de acción como 'muestra' o 'devuelve', por lo que no alcanza la máxima claridad.

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?

El propósito comunicado, 'para ver si el tráfico sube o baja', sugiere implícitamente cuándo usar la herramienta: al analizar la evolución temporal de visitas de publicaciones. No se ofrecen condiciones explícitas de uso ni se excluyen alternativas como ml_rendimiento_publicaciones o ml_publicaciones, por lo que la orientación queda a cargo de la inferencia del agente.

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