NAO

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

The description says the tool adds, subtracts and removes items from a cart — a state mutation — while annotations declare readOnlyHint=true and idempotentHint=true (repeated calls with the same cantidad accumulate, so they are not idempotent either). The helpful details about the token and return value are overshadowed by this direct conflict.

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?

Four short sentences, each carrying operational information (mutation semantics, token chaining, return payload, closing step), with the core purpose front-loaded and no filler.

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

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

Even without an output schema, the description tells the agent what comes back (el carrito con total y envío) and how to continue the flow with crear_pedido. The one gap is that it never warns that the cart token is session-scoped or how it relates to ver_carrito, though that is minor.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by adding behavior the schema does not state: cantidad=0 removes the item entirely, and the carrito token must come from the previous call. It still does not explain producto_id sourcing in the prose, but the schema covers it.

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

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

States a specific verb and resource (agrega un producto al carrito de esta compra) plus the negative/zero quantity semantics. It does not explicitly distinguish itself from the sibling ver_carrito, which an agent might reasonably confuse with inspecting the cart, so it falls short of full sibling differentiation.

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

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

Gives explicit sequencing rules: omit 'carrito' on the first call, always pass the returned token afterwards, and use crear_pedido with that token to close. It lacks an explicit 'do not use this to view the cart, use ver_carrito' exclusion, but the when-to-use context is clear.

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

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

Annotations already declare this a safe, read-only, idempotent, closed-world read. Beyond that, the description adds real behavioral context: local businesses deliver same-day within 2 km via a neighborhood courier, and supplying colonia or CP prunes results to only what actually delivers there. That filtering side effect is the kind of non-obvious behavior an agent needs and cannot get from the schema. It stops short of describing result shape or what happens with an unrecognized colonia.

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

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

Three sentences, front-loaded with the verb and scope, then the delivery-filter behavior, then the currency note. The parenthetical business-type list and trailing ellipsis are slightly chatty, but every clause carries usable information; nothing is padding.

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

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

Six optional parameters and no output schema, yet the description covers domain, geography, delivery semantics, and currency — enough to call it correctly. The remaining gap is what a result actually contains (fields per product, seller vs. local-business distinction), which the description only gestures at.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents each parameter including the categoria enum and price bound. The description earns above baseline by explaining the semantic consequence of colonia/codigo_postal — results are hard-filtered to deliverable inventory rather than merely ranked — which the schema's one-line descriptions do not convey.

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

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

States a specific verb and resource ('Busca productos en NAO') and immediately scopes the resource domain: NAO sellers plus local colonia businesses (ferreterías, tlapalerías, farmacias...). That is far more than a restatement of the name/title. It does not, however, differentiate itself from the nearest sibling, buscar_tienditas_cerca, which an agent could plausibly confuse it with.

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

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

The description implies usage (search a product with optional colonia/CP to get only deliverable results) but never says when this tool should be chosen over buscar_tienditas_cerca, ver_producto, or ver_tiendita. No exclusions or prerequisites are given, so the agent must infer routing from the parameter set alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: results are sorted by distance, delivery is same-day, the radius is 2 km, and shipping costs 25 MXN. It stops short of describing behavior when no location is supplied or what an empty result means.

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: the first front-loads the core capability and geography, the second supplies the delivery mechanics. The category parenthetical earns its place by defining the inventory scope, and nothing is redundant.

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

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

For a read-only discovery tool with full schema coverage and no output schema, the description supplies enough to call it correctly and understand the commercial model behind the results. The remaining gap is what happens when no location filter is provided, given zero required parameters.

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

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

Schema coverage is 100% and every parameter already carries a description with an example, so the schema does the heavy lifting. The description reinforces the Guadalajara scope of colonia/codigo_postal and explains that ordering derives from location, but adds no format or precedence rules (e.g., which param wins if both are given).

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") plus resource ("negocios locales") and scopes it geographically to Guadalajara delivery zones, with concrete business categories that make the result type unmistakable. It implicitly separates itself from siblings like buscar_productos (products) and ver_tiendita (single shop) by naming the resource, but never explicitly contrasts with them.

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

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

Usage is implied by the delivery framing: an agent can infer this is the discovery step before ver_tiendita or agregar_al_carrito. However, it gives no explicit when-to-use/when-not guidance, no mention of alternatives such as buscar_productos for item-level search, and no indication that at least one of colonia/codigo_postal is needed even though all three params are marked optional.

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

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

Annotations only declare it is a mutation (readOnlyHint=false, destructiveHint=true); the description adds the crucial context that no money moves and nothing ships, that a demo address fallback is used instead of prompting the user, and that the returned token must be saved because estado_pedido requires it. It also explains the conditional idempotency behavior (same clave + same data returns the same order), which refines rather than contradicts idempotentHint=false.

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 dense paragraph that front-loads the purpose and the demo caveat before mechanics. Every sentence carries information, but the block is long and the return-value enumeration could be tightened or split for scanability.

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

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

For an 11-parameter mutation with no output schema, the description covers the missing pieces: it lists return values (order id, token, MXN total, tracking link, business panel link) and closes the loop with the downstream estado_pedido call. An agent has everything needed to invoke and follow up 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?

With 91% schema coverage the schema already does most of the work, but the description adds real semantics: productos and carrito are mutually exclusive alternatives, colonia/codigo_postal trigger the demo-delivery fallback, and comprador groups a person's orders in their panel. It leaves 'notas' and 'agente' unexplained, and doesn't spell out that a delivery location is effectively required.

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

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

Opens with a specific verb+resource ('Cierra la compra: crea un pedido de PRUEBA en NAO') and immediately scopes it as demo-only (pago al recibir, no se cobra nada, nadie entrega). This distinguishes it from the browsing/cart siblings without needing their schemas.

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

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

Explicitly routes the agent between alternatives: send 'productos' (ids from buscar_productos) OR 'carrito' (token from agregar_al_carrito), naming both siblings and the token source. It also states follow-up actions (share 'seguimiento' and 'vista_del_negocio' links) and exclusions (do not ask for name/phone; do not ask for an address if 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the explicit state progression (recibido → preparando → en camino → entregado) tells the agent what values to expect, and the token requirement signals an authorization constraint. It does not describe error behavior for invalid/expired tokens, which keeps it at 4.

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 core action and the state sequence, then the input prerequisite. 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?

With no output schema, the description usefully indicates the return contains both the status and the order's products. It could say more about what product details come back or what happens on an invalid token, but for a two-parameter read tool this is nearly 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%, so both parameters are already documented with format hints (NAO-7K2Q9X) and provenance from crear_pedido. The description merely restates that provenance, adding no new syntax or constraints, so the baseline 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?

States a specific verb (Consulta) and resource (estado de un pedido de NAO), plus the secondary payload (sus productos). It is clearly distinguishable from sibling tools like crear_pedido or ver_carrito, which create or inspect a different resource.

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

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

The description establishes the prerequisite context — you need the id and token returned by crear_pedido, so it is clearly positioned as a follow-up to order creation. It does not state exclusions (e.g., what to do if the token was lost, or that it cannot look up other users' orders), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally; the description reinforces the read-only nature ("No compra nada") and, more usefully, enumerates the payload contents (productos, envío, total, entrega de demo). It doesn't cover failure modes such as an invalid or expired token, which is the main remaining gap.

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

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

Two tight sentences with no filler; the purpose and the returned contents come first, followed by the anti-pattern warning. Nothing here could be cut without losing 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?

With no output schema, the description does the necessary work of listing what the call returns, which is exactly what an agent needs. It falls slightly short by not saying what happens when 'carrito' is omitted (the schema marks 0 required parameters) or when the token is invalid.

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

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

Schema coverage is 100% and the single parameter 'carrito' is documented as a token (c1.…), so the baseline is met. The description adds mild value by tying the token to both this call and the follow-up crear_pedido call, reinforcing the token's continuity across 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?

Specific verb + resource ("Muestra el carrito") plus an explicit inventory of what is returned: productos, envío, total y la entrega de demo. It also distinguishes itself from crear_pedido in the same sentence, so an agent can separate viewing from ordering without opening a schema.

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

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

States the negative case outright ("No compra nada") and routes the agent to the correct alternative ("para pedir usa crear_pedido"), including the handoff detail that the same 'carrito' token is reused. This is the explicit when/when-not/alternative pattern.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds which fields the detail includes, useful context, but omits behavior on missing/invalid IDs and any return format discipline.

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

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

A single compact sentence with the resource front-loaded and no filler. Efficient, though its terse listing style leaves little structure beyond the field enumeration.

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 effectively compensates by listing the fields the detail returns. With one well-documented parameter and complete read-only annotations, an agent has enough to invoke it correctly; only error-case behavior is unaddressed.

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 there is only one parameter whose format ('p-...' or slug) is fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

Names a specific verb-resource pairing ('Detalle de un producto de NAO') and enumerates the fields returned (precio, stock, vendedor, imagen, condiciones de entrega). An agent can tell it retrieves a single product's detail, though it doesn't explicitly contrast with buscar_productos or ver_tiendita.

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

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

Usage is implied by the resource: fetch the detail of one product. But the description gives no explicit condition for choosing this over buscar_productos (search/list) or other siblings, and no prerequisite or when-not 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 readOnly, idempotent, closed-world and non-destructive behavior, so the safety profile is covered. The description adds valuable content context by listing the returned data (hours, neighborhood, delivery radius, delivery staff, full catalog), but says nothing about behavior for missing/invalid ids or response shape.

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

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

A single front-loaded sentence identifying the resource and its contents, with no filler or redundant restatement 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?

With no output schema, the description usefully enumerates the profile fields an agent will receive. For a simple one-parameter read-only lookup this is nearly complete, though routing guidance relative to search/catalog siblings is absent.

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

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

Schema coverage is 100% and the schema already explains that tiendita_id accepts an id (t-...) or slug. The description mentions neither the parameter nor its formats, so it adds no meaning beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb+resource: returns the profile ('Ficha') of a local business or seller, and enumerates what the profile contains. It is distinguishable from search-oriented siblings like buscar_tienditas_cerca, though it never names an alternative explicitly.

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

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

No when-to-use or when-not-to-use guidance. The agent must infer that this is a direct lookup by id/slug rather than a search, and no sibling tool is mentioned as an alternative for discovery scenarios.

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