Server Quality Checklist

Tool Scores

• answer_questionC
  2.8/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It names the action but does not disclose effects such as marking the question answered, notifying the buyer, or whether the action is reversible. No authentication or rate-limit context is provided.

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

  Conciseness4/5

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

  The description is short, front-loaded, and the usage example is useful and concrete. It is efficient, though slightly informal in structure.

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

  Completeness3/5

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

  The output schema existsheb, and the schema documents parameters and defaults. However, the description lacks usage context, exclusions, and behavioral effect details. It is minimally viable but with clear gaps.

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

  Parameters2/5

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

  The description's example illustrates question_id and answer_text, but it adds little beyond the schema's own parameter descriptions. Given the low schema-description-coverage signal, the description should have compensated more fully, including for account and site_id.

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

  Purpose4/5

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

  The description clearly states the tool's action and resource: 'Answer a pending question about an item.' It is distinguishable from sibling tools like list_questions, though it does not explicitly contrast with any sibling.

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

  Usage Guidelines2/5

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

  No guidance is given about when to use this tool versus list_questions or other alternatives. The usage example shows syntax but does not explain prerequisites, such as verifying the question is actually pending or whether the answer will be publicly posted.

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

• get_orderC
  2.8/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys read-only intent by the word 'Get', but does not state side effects, authorization needs, error behavior, or that it does not mutate the order.

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

  Conciseness4/5

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

  The definition is short and front-loaded with its core purpose. The usage example is compact and useful, though the parenthetical 'or wherever the order lives' is vague and could be more explicit.

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

  Completeness3/5

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

  Given that an output schema exists and the operation is nominally a simple getter, the definition is minimally adequate. However, it lacks usage-context information, especially whether to use search_orders when the order ID is unknown, and it does not specify how the site_id should be resolved.

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

  Parameters2/5

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

  The description only gives a loose example mapping an order ID to site_id="MLA", and does not explain required order_id semantics or the optional account parameter. With schema description coverage listed at 0%, the description does very little to help an agent understand the parameters.

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

  Purpose4/5

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

  The description states a specific operation: it gets detailed information about a single order. It is clearly different from listing or searching, but it does not explicitly differentiate itself from sibling tools like search_orders, so it lacks the explicit sibling contrast that would earn a 5.

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

  Usage Guidelines2/5

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

  The description provides a usage example but no guidance about when to choose get_order over search_orders or other order-related tools. There is no when-to-use, when-not-to-use, prerequisites, or fallback guidance.

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

• list_questionsC
  2.9/5.0
  Behavior2/5

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

  With no annotations, the description must carry the full burden of behavioral disclosure. It only says 'list' and 'optionally filtered' but does not mention pagination/limit behavior, account/site resolution, or what the response contains. Important operational traits are left undocumented.

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

  Conciseness4/5

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

  The description is short and front-loaded, with usable examples that add practical value without excessive verbosity. The phrasing is efficient, though the confusing 'unanswered' example keeps it from being excellent.

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

  Completeness2/5

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

  For a tool with no annotations and one nested input object, the description is incomplete: it does not explain limit/pagination behavior, output shape, how to combine filters, or account/site selection beyond the schema's own field descriptions. An agent would still have to infer several important details before calling it reliably.

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

  Parameters2/5

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

  The top-level `input` parameter has no description, and the description does not compensate for that gap. It mentions item and status but omits `limit`, `account`, defaults, and status value constraints; the 'unanswered questions' example maps to `site_id`, which is misleading instead of demonstrating the `status` filter.

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

  Purpose4/5

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

  The opening sentence, 'List questions asked about items, optionally filtered by item or status,' clearly states the action, resource, and key options. It is easy to distinguish from item CRUD siblings, though it never explicitly names a sibling alternative, 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.

  Usage Guidelines3/5

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

  The usage examples provide situational context ('Show me unanswered questions for my items', 'List questions about item MLU...'), which implies when the tool is appropriate. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives like answer_question.

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

• get_shipmentB
  3.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. 'Get' strongly implies a read-only operation, which is useful. However, it does not explicitly state non-mutation, authentication assumptions, or how the optional account/site_id selection behaves at runtime.

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

  Conciseness4/5

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

  The description is short, front-loaded, and free of filler. The usage example is slightly redundant with the first sentence but still compact and harmless.

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

  Completeness3/5

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

  For a simple lookup tool with an output schema and documented parameters, this is close to sufficient. The main gaps are the lack of usage guidance around alternatives and the minimal behavioral detail beyond 'get', which matters because no annotations are present.

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

  Parameters3/5

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

  The description itself adds little parameter meaning beyond the example mapping 'shipment 987654321' to shipment_id. The input schema is actually descriptive for account, site_id, and shipment_id, so the agent still has the necessary semantics even though the tool description does not enrich them.

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

  Purpose4/5

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

  The description clearly states a specific action and resource: 'Get tracking information for a shipment.' This is not a tautology and distinguishes the tool from obviously different siblings like get_item or get_user. However, it does not explicitly differentiate it from closely related order or shipping-method tools.

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

  Usage Guidelines2/5

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

  The description includes a usage example ('Track shipment 987654321') but provides no guidance about when to prefer this tool over alternatives, when not to use it, or what context makes it appropriate. No sibling alternatives or exclusions are mentioned.

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

• relist_itemB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full behavioral burden. It only says it creates a new listing from a closed item, but it does not disclose side effects (e.g., what happens to the original item), permission requirements, error states, or that it is a mutation operation. This is a significant gap for a write tool.

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

  Conciseness4/5

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

  The description is short and front-loaded with the purpose sentence, followed by clearly structured usage examples. Each example earns its place by showing parameter mappings. No unnecessary prose.

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

  Completeness2/5

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

  The tool has an output schema, so return details are not needed. However, for a mutation tool without annotations, it should explain prerequisites, side effects, or how account/site selection interact with the relisting process. The description only mentions 'previously closed item' but not what the new listing means for the old item ID, whether the old listing is deleted, or the need for valid country authorization, making it incomplete for a tool with nested object complexity.

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

  Parameters2/5

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

  Schema description coverage is 0% at the parameter level, so the description must compensate. The examples illuminate how site_id may be derived (M,L,A vs M,L,U) and mention '10 units available' as a clue for quantity, but they do not cover the required item_id clearly (it's only implied by the prefix) nor the account param. The nested schema has descriptions for all fields, but the top-level 'input' object lacks a description, and the description itself adds only partial guidance.

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

  Purpose5/5

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

  The description states a clear verb ('relist') and resource ('a previously closed item') and explains it is now a new listing. This distinguishes it from create_item, update_item, and delete_item without tautology.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool by referencing 'previously closed item', but does not explicitly compare with sibling tools or state when not to use them. The usage examples show how to map user expressions to parameters, but not when to select this tool over alternatives.

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

• get_categoryA
  3.5/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It states that the tool returns detailed category information including children and attributes, which implies a read-only lookup. It does not describe edge cases, site/account defaulting behavior, or failure modes, though the schema partially covers account and site selection.

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

  Conciseness4/5

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

  The description is compact and front-loaded: the main purpose appears in the first sentence, followed by two concrete usage examples. There is 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.

  Completeness4/5

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

  For a simple lookup tool, the description plus the rich input schema and output schema gives an agent enough to invoke it correctly. It states what information is returned and how a category is referenced. The only notable omission is explicit routing guidance toward sibling tools for category browsing or prediction.

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

  Parameters3/5

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

  The visible nested schema already documents account, site_id, and category_id with examples and defaults, so the description does not need to repeat them. The description's usage examples add practical context by showing real category IDs like MLA1051 and MLU1000. While the stated coverage signal is 0%, the actual schema text provides the needed parameter guidance.

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

  Purpose4/5

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

  The description clearly identifies the tool as retrieving detailed information about a single category, including children and attributes. The phrase 'specific category' helps distinguish it from sibling tools like list_categories, though it does not explicitly name alternatives.

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

  Usage Guidelines3/5

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

  The usage examples ('Tell me about category MLA1051') show the intended interaction pattern and imply the main use case: querying by a known category ID. However, the description does not explicitly say when not to use this tool or direct the agent to list_categories or predict_category for browsing or inference.

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

• list_my_itemsA
  3.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It usefully discloses that results are limited to the authenticated user's items and selected country profile, but it does not describe pagination behavior, auth side effects, or any limitation beyond the schema. For a read-only list tool, 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.

  Conciseness4/5

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

  The core purpose is front-loaded in a single sentence, and the usage examples are relevant and compact. It could be slightly tightened since the title already conveys 'List My Items', but there is no meaningful filler.

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

  Completeness4/5

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

  Given the rich nested input schema and the presence of an output schema, the description sufficiently explains the tool's scope. It does not explicitly cover when-not-to-use or sibling tool distinctions, but those are more of a usage-guideline gap than an invocation-completeness gap.

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

  Parameters3/5

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

  The nested schema already documents limit, offset, status, account, and site_id with descriptionsyb. The description adds illustrative natural-language-to-parameter mappings, especially for site_id and status, which is helpful. However, the context signal reports 0% top-level schema description coverage, and the description does not compensate for all parameters, keeping this at baseline.

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

  Purpose4/5

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

  The description states a specific verb ('List'), a resource ('items'), and clear scoping ('owned by the authenticated user', 'given country profile'), so an agent can distinguish it from broader search tools. It does not explicitly name sibling tools to rule out alternatives, so it falls 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.

  Usage Guidelines3/5

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

  The ownership scope and usage examples imply when the tool is appropriate, but there is no explicit guidance such as 'use search_items for global search' or 'use get_item for a single item'. The examples clarify site_id and status mapping but do not contrast with alternatives.

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

• get_item_visitsA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses that the tool returns visit statistics and that last_week=true changes the time window to 7 days instead of 24h. However, it doesn't disclose the return format, whether the tool is read-only, or any rate-limit/auth behavior. The time-window behavior is useful but the description is thin on other behavioral traits.

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

  Conciseness4/5

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

  The description is short and front-loaded with the core purpose, followed by two illustrative examples. Every sentence earns its place. The examples are slightly redundant with the schema's last_week description, but they add practical usage context without bloat.

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

  Completeness3/5

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

  The tool has a nested input object, an output schema, and no annotations. The description explains the main use case and the last_week toggle, but it doesn't mention the account/site_id selection behavior or any prerequisites (e.g., authenticated accounts). Given the output schema exists, return values don't need explanation, but the description could be more complete about which account/site context applies.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The description's examples clarify the item_id parameter ('MLA1234567890') and the last_week parameter ('last week's visits' → last_week=true). However, it doesn't explain account or site_id semantics beyond what the schema already provides, and the schema descriptions are actually quite detailed. The description adds marginal value for the two main parameters but doesn't fully compensate for the 0% coverage signal.

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

  Purpose4/5

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

  The description states a specific verb and resource: 'Get visit statistics for a MercadoLibre listing.' This clearly identifies what the tool does. It doesn't explicitly distinguish it from siblings, but the sibling list contains no other visit-statistics tool, so the purpose is unambiguous enough.

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

  Usage Guidelines4/5

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

  The description provides two concrete usage examples that illustrate when to use the tool ('How many views does MLA1234567890 have?') and how to select the last_week option. It doesn't explicitly state when not to use it or name alternatives, but the examples give clear context for typical use cases.

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

• list_ads_campaignsA
  3.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden and does disclose important prerequisites: OAuth2 is required and Mercado Ads must be enabled for the account. It also clarifies the data is limited to the authenticated seller's campaigns. It doesn't discuss pagination/limits or empty-result behavior, but the output schema covers return shape.

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

  Conciseness5/5

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

  The description is compact and front-loaded: purpose, prerequisites, then concrete examples. Every line contributes to correct selection/invocation, and the examples are scannable.

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

  Completeness4/5

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

  The prerequisites, country/site context, and natural-language examples make the tool callable for common cases, and an output schema exists so return values don't need to be restated. The main gap is that account and limit are not covered in the description, but the examples cover the most frequent invocation patterns.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate, but it only demonstrates site_id and status through examples. There is no explanation of limit or account in the description, so an agent relying solely on this description would not fully understand those parameters.

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

  Purpose4/5

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

  The description opens with a clear verb and resource: 'List Mercado Ads campaigns for the authenticated seller in a given country.' This distinguishes it from sibling item/order/search tools by naming 'Mercado Ads campaigns' and country scoping. It doesn't explicitly name a sibling alternative, 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.

  Usage Guidelines3/5

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

  The usage examples imply when to use the tool ('Show my active advertising campaigns', 'List my Mercado Ads campaigns in Uruguay') and map to site_id/status. There is no explicit guidance on when not to use it or which sibling to prefer, so usage guidance is contextual but not fully explicit.

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

• list_categoriesA
  3.6/5.0
  Behavior3/5

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

  With no annotations provided, the description must disclose behavioral traits. It indicates the tool fetches categories for a site, implying a read-only operation, but does not explicitly state that it is safe or non-destructive. It does not disclose potential rate limits, authentication requirements, or what happens if the site_id is invalid. It also does not describe the structure of the response beyond the mention of 'top-level categories'. Given zero annotations, the description carries a moderate burden but does not meet it fully, hence a 3.

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

  Conciseness4/5

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

  The description is concise, with a single sentence stating the purpose, followed by two bullet-point usage examples. It is front-loaded with the core function and then provides concrete mappings. The structure is efficient, but the usage examples could be considered redundant with the schema's parameter descriptions. Overall, it is well-sized and structured, earning a 4.

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

  Completeness3/5

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

  The tool is relatively simple (listing categories) with an output schema available, so the description need not detail return values. However, it lacks guidance on error scenarios (e.g., unauthenticated sites, invalid site_id) and does not mention that the account parameter is optional or how authentication factors in. Given the context signals (only 1 param, output schema exists), the description is adequate but not complete for an agent to handle edge cases, so a 3 is fair.

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

  Parameters3/5

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

  The input schema has 0% description coverage, meaning parameter descriptions in the schema are present but only the descriptions in the JSON schema are used; however, the schema does include detailed descriptions for 'account' and 'site_id', which explains their purpose and defaults. The tool description's usage examples add meaning by linking site_id to specific countries (e.g., MLA=Argentina), which is not in the schema. This compensates slightly, but the description itself does not elaborate on parameters beyond the examples. Since the schema provides decent parameter documentation via its own descriptions, a baseline 3 is appropriate.

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

  Purpose4/5

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

  The description states the tool's purpose clearly: 'Get all top-level categories available on a MercadoLibre site'. It identifies a specific verb ('Get'), resource ('top-level categories'), and scope ('available on a MercadoLibre site'). It distinguishes from siblings like get_category (which fetches a single category) and predict_category (which predicts a category), though it does not explicitly name these alternative sibling tools. The usage examples provide concrete mappings from natural language to the site_id parameter, which aids selection.

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

  Usage Guidelines4/5

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

  The description implies usage context: it is for listing top-level categories, not for searching items or predicting categories. The examples ('What categories are available in Argentina?' → site_id=MLA) show when to use it, but there are no explicit exclusions or guidance on when not to use it versus alternatives. It relies on the context signals and sibling tool names to infer the boundary, which is reasonable but not fully explicit.

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

• search_ordersA
  3.6/5.0
  Behavior2/5

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

  Annotations are absent, so the description carries the full burden. It discloses the OAuth2 read scope requirement, which is useful, but it does not mention that this is a read-only operation, pagination behavior, response structure, error handling, or any side effects. For a search tool, these omissions leave behavioral expectations underspecified.

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

  Conciseness5/5

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

  The description is minimal and well-organized: a single-sentence purpose, an authentication note, and three concise usage examples. It front-loads the core action and avoids redundant prose. Every element earns its place.

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

  Completeness4/5

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

  The tool has an output schema, so return values need no explanation. The description covers the core purpose and gives practical examples for site_id and status. While it lacks explicit guidance on account selection and pagination, the schema descriptions for those parameters fill the gaps. Overall, sufficient for a search tool given the structured schema.

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

  Parameters3/5

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

  Schema description coverage is 0% per the signal, so the description must compensate. It adds value by showing how natural language maps to site_id (e.g., 'Argentina' → 'MLA') and status (via 'paid orders', 'pending shipment'), but it does not explain limit, offset, or account beyond what the schema already describes. The examples are partial compensation, resulting in a modest score.

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

  Purpose5/5

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

  The description clearly states the action ('Search orders') and the target resource ('orders for the authenticated seller in a given country'). This distinguishes it from siblings like search_items (items) and get_order (single order), and the usage examples reinforce the scope by mapping natural language queries to site IDs.

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

  Usage Guidelines3/5

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

  The examples imply when to use the tool (e.g., 'Show me my recent orders' suggests searching by criteria), but there is no explicit guidance on when to prefer this over get_order (specific order ID) or how to combine with account filtering. The OAuth scope requirement is a prerequisite, not usage routing. No exclusion conditions are given.

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

• get_shipping_methodsA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden, and 'Get available' does convey a non-mutating lookup. It does not mention account/site selection behavior, possible errors, or any additional constraints, but for a simple read-only tool this is not a serious omission.

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

  Conciseness5/5

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

  One functional sentence plus a single illustrative example; there is no filler, redundancy, or repeated schema information. The main purpose is front-loaded.

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

  Completeness3/5

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

  The description is adequate for a straightforward getter, and the output schema exists to define the return shape. It lacks explicit alternative routing (get_shipment vs get_shipping_methods) and account/site profile hints, leaving some context to be inferred.

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

  Parameters3/5

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

  The two required parameters are semantically covered by 'item' and 'destination zip code', and the example maps them to realistic values (MLA123, 11000). The optional account and site_id fields are documented in the nested schema, so the description does not need to repeat them, though it adds no extra selection guidance for those profiles.

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

  Purpose5/5

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

  The description states a specific action ('Get'), a concrete resource ('available shipping methods'), and a clear scope ('for an item to a destination zip code'). This distinguishes it from siblings like get_shipment or get_item without needing to inspect their schemas.

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

  Usage Guidelines3/5

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

  The usage example signals the intended query pattern ('What shipping options are available...?'), so an agent can infer when to use it. However, it gives no explicit when-not-to-use guidance or contrast with siblings such as get_shipment for tracking an existing shipment.

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

• predict_categoryA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses the core behavior (predicting a category from a title) and shows site_id selection in examples. However, it doesn't disclose what the output looks like, whether it returns a confidence score, or any rate limits or auth requirements beyond what the schema implies.

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

  Conciseness4/5

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

  The description is compact and front-loaded with the core purpose, followed by two illustrative examples. Every sentence earns its place. The markdown formatting with bold 'Usage examples' is clear. Slightly more detail on output could be added, but the structure is efficient.

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

  Completeness3/5

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

  The tool has a nested input object, an output schema, and no annotations. The description explains the primary use case and gives examples, but doesn't describe the output format or any caveats (e.g., what happens if no category matches). Given the output schema exists, the return value is partially covered, but the description could still mention confidence or fallback behavior.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The description explains the 'input' object's purpose via the title examples and shows how site_id is used in examples. However, it doesn't explain the 'account' parameter or the defaulting behavior of site_id/account, which the schema does document. The description adds some value through examples but doesn't fully compensate for the 0% coverage.

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

  Purpose5/5

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

  The description states a specific verb ('Predict') and resource ('best matching MercadoLibre category for a given product title'). It clearly distinguishes this from sibling tools like list_categories or get_category, which retrieve category data rather than predict a category from a title. The usage examples reinforce the purpose with concrete queries.

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

  Usage Guidelines4/5

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

  The description provides clear usage examples showing how to phrase queries and which site_id to use. It implies this tool is for category prediction from a title, which distinguishes it from list_categories/get_category. However, it doesn't explicitly state when not to use it or name alternative tools for category lookup.

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

• create_itemA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden, and it discloses the key external side effect: the authenticated account matching site_id will own the new listing and OAuth2 write scope is required. The examples use 'publish,' implying a live marketplace action. It doesn't discuss reversibility, fees, or review processes, but the core write behavior and auth requirement are transparent.

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

  Conciseness5/5

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

  The description is compact and front-loaded: a one-sentence action, a bolded auth caveat, a bolded prerequisite, and two concrete examples. Every line earns its place and there is no filler.

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

  Completeness4/5

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

  The description covers the essential invocation context: authentication scope, account ownership, category prerequisite, and site selection via examples. An output schema exists, so return-value documentation is not required. It could mention that the listing becomes publicly visible or the defaults for site_id/account, but those are either implied or available in the schema.

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

  Parameters3/5

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

  The prose adds useful semantic guidance: category_id should come from predict_category/list_categories, and site_id is mapped to countries in the examples. However, it doesn't enumerate the required fields (title, category_id, price, available_quantity) or the 'input' wrapper, so parameter understanding depends heavily on the nested schema. Given the stated 0% schema coverage, this is only partial compensation.

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

  Purpose4/5

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

  The description opens with a clear verb-resource pair: 'Create a new product listing on MercadoLibre.' It adds platform context and the word 'new' helps separate it from update/relist siblings, though it doesn't explicitly name an alternative for modifying existing listings.

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

  Usage Guidelines4/5

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

  It provides concrete usage conditions: OAuth2 write scope is required, and category IDs should be obtained from predict_category/list_categories first. The natural-language examples clarify when to use the tool with specific site_id, price, and category values. It doesn't explicitly state exclusions like 'use update_item for existing listings,' so it stops short of full routing guidance.

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

• get_userA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It implies a read-only operation by saying 'get' and mentions 'authenticated user' and 'public profile', suggesting authentication requirements. Yet it does not explicitly state that it makes no modifications, what happens on missing authentication, or any rate limits. The description conveys the core behavior but leaves out some transparency that a robust agent would benefit from.

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

  Conciseness5/5

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

  The description is two short paragraphs: one states the core purpose and the empty-user_id behavior, the other gives two on-target examples. Every sentence earns its place, no fluff, and the most important detail (the empty-user_id behavior) is front-loaded. This is exemplary conciseness.

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

  Completeness4/5

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

  The output schema already documents the return structure, so the description does not need to duplicate that. The description covers the two primary modes (own profile vs. specific user) and provides clear examples. It could mention that 'account' is optional, but the schema already does, and the context is sufficiently complete for a get-unified read tool. Minor extra context like error handling would be nice, but not necessary given the schema and examples.

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

  Parameters4/5

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

  The description significantly adds meaning to the user_id parameter by explaining that leaving it empty returns the authenticated user's profile, which is not obvious from the schema alone. The examples also clarify the site_id argument (e.g., 'MLA' for Argentina). The account parameter is not described, but the schema handles it. Given that the schema descriptions are already present, the description's added semantic value is meaningful.

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

  Purpose5/5

  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: 'Get public profile and seller reputation for a MercadoLibre user.' It unambiguously states what the tool does and is clearly distinct from the sibling tools, which all deal with items, orders, or similar domains. This fully clarifies purpose with no ambiguity.

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

  Usage Guidelines4/5

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

  The description provides two concrete usage examples that illustrate when to call the tool (e.g., fetching one's own profile vs. another user's reputation). It also explains the behavior of leaving user_id empty, which is a critical usage rule. However, it doesn't explicitly contrast with alternative tools, but the resource distinction is strong enough that an agent can infer when this tool applies.

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

• update_itemA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden and it discloses key behavior: only supplied fields are changed, and site_id must match the owning country profile or the write is rejected with 403. It does not cover every side effect, but the critical failure mode and patch semantics are explicitly stated.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the operation, and uses a bolded warning plus two minimal examples. Every sentence contributes operational value without redundancy.

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

  Completeness4/5

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

  For a write operation with no annotations and a nested input object, the description addresses the most likely failure (site_id ownership) and partial-update behavior. Since an output schema exists, the lack of return-value detail is acceptable, though the description could mention item-not-found behavior.

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

  Parameters3/5

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

  The description adds concrete usage meaning for site_id, price, and stock through examples and the ownership rule, but context indicates 0% schema description coverage. It does not compensate for all nested fields, leaving most field semantics to the schema's property descriptions.

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

  Purpose5/5

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

  The description states a specific action ('Update an existing MercadoLibre listing') and immediately clarifies partial-update semantics ('Only provided fields are changed'). This differentiates it from create_item, delete_item, and relist_item even without naming them.

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

  Usage Guidelines4/5

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

  Using the word 'existing' establishes when the tool applies, and the two usage examples show concrete invocation patterns for price and stock updates. It does not explicitly list alternative tools or when-not-to conditions, but the context is clear enough for selection among the update/create/delete siblings.

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

• list_authenticated_sitesA
  4.3/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full disclosure burden and meets it excellently: it explicitly states the tool does NOT create a client or make an API call, and that it only inspects locally cached OAuth profiles under a specific path (~/.mercadolibre_mcp/profiles/). This removes any ambiguity about side effects or network activity without any help from annotations.

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

  Conciseness4/5

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

  The first sentence states the core purpose immediately, the second adds the key no-side-effect qualifier, and the final usage examples earn their place by showing the agent when to invoke it. It is slightly longer than strictly necessary, but the quoted invocation triggers add practical value for an AI caller.

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

  Completeness4/5

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

  Since an output schema exists, the description is not required to explain return values, and it covers what, where, and side-effect profile completely. Everything an agent needs to decide to call this tool correctly is present; only minor clarity on the required empty input envelope is absent.

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

  Parameters3/5

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

  The schema has a single required 'input' parameter that is an empty object with no properties, so there is essentially no semantic meaning to add; the description's omission of parameter details is not harmful because there is nothing to document. The description does not explicitly tell the caller to pass an empty input object, but the schema makes that self-evident.

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

  Purpose5/5

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

  The description names a specific resource (MercadoLibre authenticated country profiles) and a precise scope: it reports which of the 18 supported sites ARE authenticated and which are NOT. This is a concrete verb+resource statement that clearly distinguishes it from all item/order/category siblings, which are all domain CRUD operations.

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

  Usage Guidelines4/5

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

  The description gives three concrete usage example queries that define the tool's triggers ('Which countries am I authenticated in?', 'Am I set up for Uruguay yet?'). It does not name excluded alternatives, but none of the 19 siblings concern authentication, so there is no real competing tool to route away from; the examples carry the guidance.

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

• delete_itemA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It reveals that the operation is a write that sets status to 'closed', that items can be relisted later, and that a mismatched site_id causes a 403 rejection. This gives the agent a solid safety and reversibility picture, though it does not enumerate every possible side effect.

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

  Conciseness5/5

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

  The description is compact and front-loaded: purpose, status effect, reversibility, critical caveat, and examples. Every sentence earns its place, and the important site_id warning is bolded for prominence.

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

  Completeness4/5

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

  The description is sufficient for an agent to invoke the tool correctly: it explains the operation, the state change, reversibility, the ownership requirement, and provides usage examples. Since an output schema exists, return-value details are not needed. Minor omissions like behavior for already-closed items do not significantly hurt completeness.

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

  Parameters4/5

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

  The top-level schema description coverage is 0%, but the child schema already documents item_id, site_id, and account. The description adds significant value by explaining the critical ownership constraint for site_id and by giving real examples that map item ID prefixes to the correct site_id values.

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

  Purpose5/5

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

  The description clearly states the action with a specific verb and resource: 'Close/finish a MercadoLibre listing.' It further clarifies the misleading tool name by noting the item is set to 'closed' and can be relisted later, distinguishing it from permanent deletion and from the sibling relist_item.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use the tool: to close or finish a listing. It also provides critical operational guidance about site_id matching the owning authenticated profile, with concrete examples mapping item ID prefixes to site IDs. However, it does not explicitly name alternative tools or state when not to use this tool.

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

• get_itemA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It clarifies that the operation is a read (public catalog data) and that it uses the authenticated profile, which is useful for understanding side effects. However, it does not mention rate limits, error behavior, or whether the item might be inactive/deleted, which are minor gaps given the read-only nature 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.

  Conciseness5/5

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

  The description is concise and front-loaded: the first sentence states the core purpose. It adds useful context about site_id and includes two usage examples, all in a compact format. No wasted words, every sentence contributes value.

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

  Completeness4/5

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

  Given the tool's simplicity (single required parameter) and the presence of an output schema (which likely describes return format), the description provides sufficient context for an agent to call it correctly. It does not explain the output structure, but that is in the output schema, not the description's job. It covers essential usage nuances (site_id behavior) and examples, making it complete enough.

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

  Parameters4/5

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

  The schema has 0% description coverage, meaning the description must compensate for explaining parameters. It explicitly explains the significance of site_id (selects profile, public data) and provides item_id format examples. The account parameter is not described in the description, but the schema has a detailed description for it, so the description's added value is mainly on site_id, which it handles well.

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

  Purpose5/5

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

  The description clearly states the tool retrieves full details of a MercadoLibre listing by item ID, using a specific verb and resource. It distinguishes itself from siblings like search_items (which finds items) and update_item (which modifies), making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description explains that any authenticated site profile can read any item, clarifying when site_id is relevant. It also provides usage examples that illustrate natural-language queries. However, it does not explicitly state when NOT to use this tool versus alternatives like search_items, though the purpose clarity helps fill that gap.

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

• search_itemsA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full behavioral burden, and it meets it well by disclosing that this is a read-only operation on public data accessible to any authenticated profile across countries. It does not mention pagination behavior or rate limits, but the presence of an output schema covers return structure. This is solid disclosure given zero annotation support.

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

  Conciseness5/5

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

  One compact purpose sentence followed by three scannable examples. No filler, no repetition of schema content, and the most important semantic (scope + public data) is front-loaded. Each of the three examples earns its place by demonstrating a distinct filter scenario (basic, price-filtered, different site).

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

  Completeness3/5

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

  Purpose and common usage patterns are well covered, and the output schema covers return shape. However, the description never flags that all parameters must be wrapped in a nested 'input' object — the examples show flat parameter names, which could lead an agent to pass them at top level. No guidance on combining filters or on the offset/limit pagination workflow is given beyond what the schema states.

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

  Parameters5/5

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

  Schema description coverage is 0% for the counted top-level parameter, so the description must compensate — and it does, with three worked examples that show precisely how to populate query, site_id, and price_max from colloquial user requests. This adds practical meaning far beyond the schema's bare type definitions, teaching the agent to transform intent into parameter values.

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

  Purpose5/5

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

  States a specific verb and resource ('Search for products on MercadoLibre across a site') and immediately clarifies scope ('public data... regardless of which country'). This clearly distinguishes it from siblings like list_my_items (own items), get_item (single item), and create_item (write operation). The three usage examples reinforce the exact purpose.

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

  Usage Guidelines4/5

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

  The usage examples map natural-language user intents to concrete parameter values (query, site_id, price_max), which teaches an agent when and how to invoke this tool. However, it never explicitly excludes alternatives (e.g., no 'use get_item when you need a single product' or 'use list_my_items for seller's own items'), leaving sibling differentiation to inference from the purpose statement.

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