Descubrir artículos ganadores

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

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

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

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

Front-loaded with the core action, then two parallel clauses for the two modes, then the input instruction. Dense but every clause carries information; only slight compression loss from packing the keyword-analysis dimensions into one long sentence.

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

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

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

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

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

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

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

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

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

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

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

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

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