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

With no annotations, the description carries the burden well: it discloses that this is a REAL write operation, that Meli approval is required, and that approval causes the item to sell at the promotional price for the campaign duration. It stops short of covering permissions/auth scopes, rate limits, or whether a submission can be withdrawn.

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?

Well front-loaded — the write-operation warning appears in the first clause, then the flow, then the return info. Dense but each sentence carries distinct information; the tool's resource name is partly restated in the opening.

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?

Without annotations or an output schema, the description supplies the side-effect model, the sequencing with get_promotions, and a brief note on the return value (item id and status). It could say more about rejection/error handling, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by stating that deal_price must fall within the campaign's allowed range. It does not explain the optional top_deal_price, which the schema already documents.

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 ('Submit one of your items to a promotion campaign') and clarifies it is a real write operation rather than a lookup. An agent can distinguish it from get_promotions and get_promotion_items without opening either schema.

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

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

Explicitly prescribes the workflow and prerequisites: call get_promotions to find a 'candidate' campaign first, then pass a deal_price within the campaign's allowed range, and confirm the price with the user before calling. Nothing about when to use it is left to inference.

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

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

With no annotations, the description carries the full burden and delivers: it discloses that the answer is public and irreversible ('CANNOT be edited or deleted afterwards') and instructs confirmation of exact text. It also describes the return payload, so the agent knows what to expect in the response.

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 tight sentences, front-loaded with the action and its irreversible nature before the sourcing hint and return description. No filler, though the return-value sentence could be trimmed given it is not strictly needed for invocation.

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

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

For a two-parameter mutation tool with no output schema and no annotations, the description covers the side effects (public, permanent), the prerequisite (question_id source) and the response shape. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the irreversibility of 'text'. The description reinforces their meaning but adds no format or syntax detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a precise verb+resource+audience ('Post a public answer to a buyer's pre-sale question'), which cleanly distinguishes it from the read-only sibling get_questions. An agent immediately knows this is a write operation on a listing question.

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 tells the agent where the required question_id comes from ('Get the question_id from get_questions, typically with status=UNANSWERED'), routing it to the correct sibling and condition. It also prescribes a confirmation step before sending, which is actionable 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?

No annotations are provided, so the description carries the full burden. 'Get' and 'current' imply a read-only lookup, and the description usefully discloses the return shape (ratio plus both currency codes), but it says nothing about rate source, freshness/update frequency, or whether it covers only a single pair. Adequate but thin for an annotation-free tool.

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

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

Three short sentences, front-loaded with the core action, then usage context, then return value. Every sentence carries information with no redundancy.

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

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

With no output schema, the description compensates by naming what is returned (conversion ratio and both currency codes), and both required params are schema-documented. Only minor gaps remain, such as rate provenance and freshness guarantees.

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 both parameters ('from'/'to' ISO codes) are fully documented in the schema. The description adds the directional example (USD → BRL) and confirms both currency codes come back, but contributes no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Get the current Mercado Livre exchange rate between two currencies') with a concrete example (USD → BRL). No sibling tool performs currency conversion, so an agent can route to it unambiguously.

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

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

Gives clear context for use ('cross-border pricing or comparing prices across Meli sites'), which tells the agent when this tool is relevant. It stops short of explicit when-not conditions or named alternatives, but no sibling offers overlapping functionality.

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

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

With no annotations, the description carries the full burden and does well: it declares 'this is a real write operation' and spells out side effects (display and sales conditions change, free-shipping and price rules may differ). It also states return values. It omits whether the link can be reversed/unlinked, which is the main gap for a mutation of this kind.

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

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

Front-loads the operation and its consequence in the first sentence, then compresses prerequisites and flow into tight follow-ups. Slightly dense with three separate concerns, but every sentence adds information an agent needs.

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, it enumerates the return payload (linked item id, status, permalink) and covers prerequisites, side effects, and the recommended flow. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100% and the schema already provides formats and examples, so the baseline is 3. The description adds business semantics beyond the schema: item_id must belong to the authenticated seller, and catalog_product_id must match the item's catalog product.

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: linking an EXISTING listing to a catalog product to opt it into catalog competition. It distinguishes itself from siblings like create_item (new listing) and search_catalog/get_catalog_product (read-only catalog lookups) by emphasizing 'EXISTING'.

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 an explicit call flow (search_catalog → get_catalog_product → create_catalog_listing), prerequisites (item must belong to the authenticated seller and match the catalog product), and a human-in-the-loop requirement ('Confirm with the user before calling'). Nothing about when to use it is left to inference.

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

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

With no annotations, the description carries full behavioral burden and does so: it discloses that the item becomes public, that selling fees apply, that user confirmation is required, how errors surface (full error body returned), and common remediation (missing required attributes). It also states return values (item id, status, permalink).

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

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

Front-loads the critical fact (real write/public/fees) before the workflow, and the numbered steps are scannable. It is dense and slightly long, but nearly every clause carries actionable information.

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

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

For a 13-parameter mutation tool with nested objects, no annotations, and no output schema, the description supplies prerequisites, execution workflow, error semantics, and return values — everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters, including the 60-char title limit, attributes requirements, and listing_type_id origin. The description reinforces the workflow origins for category_id/attributes but adds little syntax beyond what the schema already states.

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 (create and publish) on a specific resource (a listing on Mercado Livre), and immediately sets scope with 'this is a real write operation'. It is clearly distinguishable from siblings like update_item, update_item_status, and create_catalog_listing.

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

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

Provides an explicit numbered recommended flow naming alternatives (predict_category, get_category_attributes, get_listing_types/get_listing_prices) with the conditions that select each. Also states the confirm-with-user prerequisite and a retry procedure on validation failure.

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

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

With no annotations the description carries the full burden and does well: it discloses the 30-day default window, that some metrics (ACOS) may be absent ('when present'), and that scope errors surface clearly, which prepares the agent for auth failures. It omits pagination, rate limits, and whether it is strictly read-only, but the behavioral coverage is strong for a metrics getter.

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

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

Front-loads the core purpose and metric list, with prerequisites layered after. The ACOS explanation sentence is useful sense-making but slightly expandable; overall it is dense and earns its length.

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, so the description compensates by naming the returned metrics (impressions, clicks, CTR, cost, attributed sales, ACOS). Combined with the default range and scope note, an agent has enough to invoke and interpret results, with only residual gaps around formatting and pagination.

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

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

Schema description coverage is 100%, so the schema already documents campaign_id, date_from, date_to with their defaults. The description repeats the date format and 30-day default rather than adding new parameter semantics, making this the baseline 3.

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

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

Specific verb+resource ('Get performance metrics of a Mercado Ads campaign') with the exact metric list enumerated, which distinguishes it cleanly from the sibling get_ads_campaigns that only supplies ids. An agent can tell what it returns without opening the schema.

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

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

Explicitly frames the intent ('evaluate ad spend efficiency') and routes to get_ads_campaigns as the source for campaign ids, plus flags the required advertising scope. It stops short of stating when not to use it or naming a competing metrics tool, so it is a clear context without exclusions.

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

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

With no annotations provided, the description carries the full behavioral burden and does so: it discloses the required advertising scope and active ads account, and explains that a scope/permission error is surfaced to signal the feature is unavailable. It also states the shape of the return value ('compact list with campaign id, name, status, budget and strategy'), which is essential given there is no output schema.

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

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

Front-loads purpose, then usage, then the prerequisite gotcha, then the sibling hand-off, then return contents – a sensible priority order. Every sentence adds distinct information with no restatement of the name or schema.

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

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

For a read-only listing tool with three fully documented parameters and no output schema, the description supplies everything essential: what it returns, the auth prerequisites, the failure mode, and the next tool to call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so limit, offset and status are already fully documented in the schema. The description only gestures at 'which campaigns exist, their status', adding no format, default, or range detail beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

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 ('List the seller's Mercado Ads (Product Ads) campaigns') and immediately scopes the content it covers (status, daily budget, bidding strategy). It is clearly distinguishable from the sibling get_ads_campaign_metrics, which is explicitly named as the performance tool rather than the listing tool.

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 an explicit use case ('Use this for advertising questions: which campaigns exist...'), states the follow-up workflow ('Get campaign ids here, then check performance with get_ads_campaign_metrics'), and flags the exclusion condition (advertising scope or ads account missing). An agent can route to this tool versus its sibling without inference.

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

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

No annotations are provided, so the description carries the full behavioral burden; it discloses the returned fields (name, attributes, pictures, main features, buy box winner), a 'when present' caveat, and the business semantics of buy_box_winner as the price reference. It stops short of permissions, rate limits, or error behavior, which is the only gap keeping it from a 5.

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

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

Three sentences, front-loaded with the purpose, then usage, then return contents. Every sentence earns its place, though the buy-box explanation is slightly verbose for a single-parameter read tool.

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, so the description correctly compensates by enumerating return fields, and it explains when the tool is used in the workflow. Given no annotations, it could disclose a bit more about permissions/failure modes, but it is complete enough to invoke correctly.

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

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

Schema coverage is 100% and the schema itself documents product_id with an example ID format. The description adds no syntax or format detail beyond what the schema already provides, so 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 ('Get full details of a catalog product') and immediately distinguishes itself by calling out the buy box winner payload, which no sibling provides. An agent can differentiate it from search_catalog (search) and create_catalog_listing (link) 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?

Explicit sequencing: 'Use this after search_catalog' and 'before linking your listing with create_catalog_listing.' It names the alternatives and the condition that routes to each, leaving nothing to inference.

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

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

With no annotations, the description carries the burden and does well: it discloses the shape of the response (name, path, children, listing settings), the leaf/non-leaf semantic, and its place in the create_item workflow. It stops short of noting auth requirements, errors, or rate limits, but covers the behaviorally important parts.

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 passage, front-loaded with what is returned and then the actionable workflow note. Every clause carries information, though it is slightly long and could be split into a return-value sentence and a usage sentence.

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

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

There is no output schema and no annotations, so the description must explain returns and next steps; it does both (fields returned, leaf semantics, follow-up with get_category_attributes). Only minor gaps remain around pagination/limits or error cases, which are unlikely to matter for this lookup.

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

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

Schema description coverage is 100% and the single category_id param is documented with an example format and its source tools (get_site_categories, predict_category). The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (category) and enumerates what details are returned: name, full path, child categories, and listing settings. It also clearly separates itself from siblings like get_site_categories (which lists) and get_category_attributes (which handles mandatory attributes).

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: a childless category is a leaf and can be used as category_id in create_item, then get_category_attributes should be called for mandatory attributes. It also flags that constraints must be read BEFORE create_item, giving concrete when-to-use and sequencing.

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

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

With no annotations, the description carries the full burden and does well: it discloses the returned fields (id, name, value_type, required flag, allowed values for closed lists) and the concrete validation behavior that required attributes must be supplied to create_item. It does not mention permissions, rate limits, or read-only safety, but the workflow and return-shape disclosures are substantial.

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 purpose and workflow position, followed by the consequence of omission and the return shape. Every sentence adds actionable information with 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?

There is no output schema, and the description compensates by enumerating the key return fields and explaining how they feed into create_item. The single-parameter input is fully covered by the schema, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% and category_id is already documented as the id returned by predict_category. The description adds no syntax, format, or constraint beyond what the schema provides, so 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 and resource: get the attributes defined for a Mercado Livre category. It distinguishes the tool from siblings like predict_category and get_category by scoping it to attribute definitions and allowed values, so an agent can route correctly without opening the schema.

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

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

Explicitly prescribes workflow order: call AFTER predict_category and BEFORE create_item. It also explains why — to discover mandatory attributes and allowed values — and names the alternative consequence (publication rejected if required attributes are omitted).

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?

No annotations are provided, so the description carries the full burden. It discloses a genuine behavioral trait — graceful degradation where messages are omitted if that endpoint is unavailable — which is real context beyond structured fields. It stops short of stating permissions, rate limits, or how many messages count as 'recent', keeping it from a 5.

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

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

Purpose and returned fields are front-loaded in the first sentence, usage guidance second, and the degradation caveat last. It is somewhat dense, but every sentence carries actionable information.

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

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

With no output schema and no annotations, the description compensates by enumerating the returned fields (type, status, stage, reason, order id, parties, resolution, messages) and clarifying buyer/seller party roles. Nothing needed to invoke or interpret the result is missing.

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

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

Schema coverage is 100% and the single claim_id parameter is already documented as 'Numeric claim id from get_claims'. The description references get_claims but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Get the full details of a single claim') and enumerates the returned facets, making it clearly distinct from the sibling get_claims (list) and send_claim_message (write). An agent can route without opening the schema.

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

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

Explicitly names the workflow position: 'Use this after get_claims to understand a specific claim before replying with send_claim_message.' It names both the prerequisite tool and the follow-up tool, leaving no inference required.

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 are absent, so the description carries the burden. It adds useful context that claims have response deadlines and that results are paginated, but it does not disclose whether this requires specific auth scopes beyond 'authenticated seller', nor what the compact list omits relative to get_claim_detail.

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

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

Front-loads what a claim is and why it matters, then covers filters, pagination, and return shape. It is a bit dense but every sentence earns its place; the parenthetical Portuguese gloss is a minor redundancy.

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

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

Covers purpose, urgency, filters, pagination, and the compact return fields, and points to the sibling for full detail. With no output schema, it adequately enumerates the returned fields, though it could state auth requirements and whether status values are constrained to an enum.

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 descriptions already document all five parameters with defaults, ranges, and formats. The description reinforces the optional status filter and ISO 8601 date range but adds no format or syntax detail 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 (Search) and resource (authenticated seller's claims), then parenthetically defines claims as buyer complaints opened against sales. It clearly distinguishes itself from the sibling get_claim_detail, which it explicitly routes to.

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 a clear reason to use it ('Open claims hurt seller reputation and have response deadlines, so use this to find claims needing attention') and points to get_claim_detail for full details. It does not mention when NOT to use it or other alternatives like get_returns, keeping it from a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the read nature, a significant precondition (Full enrollment), and the error behavior when unenrolled ('Meli answers with an error, which is surfaced clearly'). It omits pagination/rate-limit behavior and any permission/auth detail, keeping it from a 5.

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

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

Three sentences, front-loaded with purpose, then routing, then a clearly flagged 'Gotcha' precondition. Every sentence earns its place with 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?

For a read-only list tool with no output schema and one optional param, the description supplies purpose, sibling routing, return content (available and non-sellable quantities), and the enrollment precondition with error behavior. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single 'limit' parameter is fully documented in the schema (range 1-100, default 50). The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (List) plus resource (seller's stock at Mercado Livre fulfillment centers) and scope (available and non-sellable quantities). It also explicitly names the sibling tools (get_my_items/get_item) it should not be confused with, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ('inventory questions about Full'), explicit when-not/alternative ('for regular seller-shipped stock use get_my_items/get_item'), and a precondition ('only works for accounts enrolled in Full'). Nothing is left to inference.

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

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

No annotations are provided, so the description carries the full burden, and it does meaningful work: it discloses the ID-format constraint ('bare numbers do not work') and enumerates the returned fields. It still omits auth/permission requirements and error behavior for unknown or inaccessible ids, which is a gap for an unannotated tool.

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

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

Three sentences, front-loaded with purpose and the id constraint before routing and return details. The return-field list is long but earns its place because there is no output schema.

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, enumerating the returned fields (title, price, quantity, status, pictures, attributes) is exactly the right compensation, and sibling routing is covered. Only permission/error context is missing, which keeps it short of a 5.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3; the description goes slightly beyond by warning that bare numeric ids fail, which the schema only implies via the example. That extra constraint is genuinely actionable.

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 ('Get full details of a single Mercado Livre listing by its item id') and explicitly contrasts itself with the sibling get_my_items. An agent can distinguish it from bulk/seller-scoped siblings without opening any schema.

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

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

Gives an explicit when ('inspect a specific listing (yours or a competitor's) in depth') and names the alternative with the condition that selects it ('For bulk listing of the seller's own items use get_my_items instead'). Both the positive and negative routing cases are covered.

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

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

With no annotations, the description carries the full burden and does well: it discloses the default date window (last 30 days), the 50-item cap, and the return shape (one entry per item id with total visits). It stops short of stating read-only safety or auth requirements, but fully covers the behavioral traits an agent needs.

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

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

Front-loaded with the core action, then defaults, then the analytic use case. The 'powerful combo' sentence is longer than strictly necessary but earns its place by routing the agent to a real workflow.

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 compensates by explaining the return format (one entry per item id with total visits). For a read-only, 3-parameter tool with full schema coverage, nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the 30-day default and the 50-id limit, which the schema already documents, without adding format or edge-case semantics beyond that.

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 ('Get the number of page visits per listing') plus scope (date range). An agent can distinguish it cleanly from siblings like get_listing_prices or get_my_items without opening any schema.

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

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

Explicitly names the use case ('measure listing traffic') and a concrete combination workflow (get_my_items + get_item_visits to spot high-traffic, low-sales listings). This is direct when-to-use guidance, not inference.

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

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

With no annotations and no output schema, the description carries the full burden and does so well: it discloses the return shape (one entry per listing type with sale fee percentage, fee amount and flags) and that omitted listing_type_id yields all types. It omits any note on permissions, idempotency, or currency/price-error behavior, which keeps it from a 5.

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

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

Three sentences, front-loaded with the core action, then timing guidance, then return shape — nothing redundant except a mild restatement between "BEFORE create_item" and "before committing." Well sized for the tool's complexity.

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, three-parameter estimate with no output schema or annotations, the description covers what the tool does, when to call it, and what comes back. It is nearly complete; only permission/error context (e.g. invalid price or category handling) is absent, which is minor for a low-risk estimation call.

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

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

Schema description coverage is 100%, so the schema already explains price, category_id and listing_type_id, including the omit-to-get-all-types behavior. The description restates the same semantics ("optionally for a specific category and listing type") without adding syntax, valid values, or edge cases beyond the schema, so the baseline 3 applies.

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

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

The description states a precise action and object ("Estimate the selling fees for publishing an item at a given price") and even corrects the misleading tool name, which sounds like it returns listing prices rather than a fee estimate. It clearly separates itself from siblings like create_item and get_listing_types by naming the fee-estimation scope.

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

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

It gives explicit sequencing guidance: "Use this BEFORE create_item," so the seller knows the commission cost per exposure plan before committing. It does not state when not to use it or name a direct alternative with comparable output, so it falls just short of the top score.

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

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

With no annotations, the description must carry the behavioral burden. It discloses the return shape ('Returns ids and names') and explains the domain tradeoff (fees vs. exposure, higher tiers cost more but boost visibility). It does not mention authentication or rate limits, but for a simple read-only lookup this is minor.

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 core purpose and examples, followed by useful domain context and then usage/return info. No wasted words; every sentence adds value for an agent deciding whether and how to call it.

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

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

Given the zero-parameter schema, no annotations, and no output schema, the description is nearly complete: it explains what the tool does, why the output matters, when to call it, and what it returns. It could add a note on authentication or caching, but such details are not essential for this simple lookup.

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

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

The tool takes zero parameters, so per the scoring rules the baseline is 4. The description correctly does not attempt to document nonexistent inputs.

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

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

The description states a specific verb ('List'), a clear resource ('listing types (exposure plans)'), and scope ('available on the configured site'). It gives concrete examples and distinguishes itself by referencing the downstream tools get_listing_prices and create_item.

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

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

It explicitly says to call this before create_item to choose the listing_type_id and names get_listing_prices as an optional companion. However, it does not state when not to use this tool or any exclusions, so it falls short of a full 5.

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

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

With no annotations, the description carries the full behavioral burden and does disclose a real trait: the account may lack a shop and the call returns a graceful 'no shop' response rather than an error. It also reveals the shape of the payload. It does not mention auth requirements or rate limits, but the optional-feature behavior is the salient one.

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 tight sentences: identity/return shape first, the optional-feature caveat second, the usage trigger last. Every sentence earns its place with no repetition of the 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?

There is no output schema, and the description compensates by naming the returned fields and the empty-state behavior, which is the main thing an agent needs. Remaining omissions (response format, pagination) are immaterial for a zero-argument lookup.

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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not invent parameter details.

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 (get) and resource (Mercado Shop info) and enumerates exactly what is returned (id, name, URL, status). No sibling tool in the list overlaps with a storefront-info read, so the agent can identify it unambiguously.

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

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

Explicitly says to use it 'when the user asks about their store page or wants the shop URL', which gives a clear triggering condition. It doesn't name an alternative tool or a when-not-to-use case, but no plausible sibling alternative exists here.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the authentication requirement, that results are paginated via limit/offset, and what fields hydrate each entry, but says nothing about permissions beyond auth, rate limits, or error/edge behavior. Solid context, though a few gaps remain for a no-annotation tool.

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

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

Front-loads purpose, then routing, then filter semantics, then pagination/return shape in a compact block with no filler. Slightly dense in the middle clause, but every sentence earns its place.

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

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

With no annotations and no output schema, the description fills both gaps: it covers auth, pagination controls, and the return shape (id, title, status, price, currency, permalink). An agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description exceeds it by explaining the semantics of each status value ('active' published and visible, 'paused' temporarily hidden, 'closed' finished; items with sales usually end here)—meaning the enum labels alone don't convey. It also confirms limit/offset drive pagination, adding a small amount beyond the schema.

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

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

States a specific verb and resource ('List the authenticated seller's own listings') with scope ('own listings') that immediately separates it from marketplace-wide siblings. It also names search_products as the contrasting tool, so the agent can pick correctly without opening either schema.

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

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

Explicitly says when to use it ('whenever the user asks about my listings/ads/products') and when not to ('for marketplace-wide search use search_products instead'). The alternative is named along with the condition that selects it, leaving nothing to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (sender/recipient with ids and roles, ISO 8601 date, read status) and the domain quirk that the messaging 'pack id' equals the order id. It omits pagination behavior (the limit cap) and any auth/permission notes, so it stops short of a 5.

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

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

Front-loaded with the purpose, followed by usage, return format, and the alternative action, with zero filler. Every sentence earns its place.

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

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

There is no output schema, so the description's explicit enumeration of returned fields and its id-mapping note make the tool fully callable and interpretable. Purpose, usage, return values, and the sibling alternative are all covered.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the messaging-API pack-id-to-order-id equivalence and reinforces the reply flow using the same id, which the schema's terse 'Numeric order id from get_orders' does 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 (Read) and resource (the post-sale message conversation with the buyer of a specific order), scoping it to one order. This clearly separates it from send_message and from get_questions, which handle other communication channels.

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

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

Explicitly says when to use it ('to see what the buyer asked after the purchase') with concrete examples, and names the alternative for the opposite action ('To reply, use send_message with the same order id'). Nothing is left to inference.

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

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

With no annotations the description carries the full burden, and it delivers: it discloses the 'Requires authentication' prerequisite, the default sort order, pagination via limit/offset, and the shape of each returned order. It does not mention rate limits or explicitly characterise the operation as read-only (only implied by 'List'), so it falls short of exhaustive.

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

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

Front-loaded with the core action and scope, then usage, then parameter detail, then return shape and auth. Every sentence carries information the schema does not, and there is no filler or repetition.

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

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

There is no output schema and no annotations, yet the description covers return fields (id, date, status, total, currency, buyer, line items), pagination, sort order and auth. An agent has everything needed to call and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by enumerating two status values absent from the schema ('payment_required', 'payment_in_process') and by restating pagination semantics. The role of status as an optional filter is also made explicit.

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 ('List the authenticated seller's orders (sales)'), plus the ordering (newest first). The '(sales)' gloss and the authenticated-seller scope separate it cleanly from siblings like get_shipment, get_order_messages and get_returns without needing to open 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?

'Use this for questions about recent sales, revenue, or what a specific buyer purchased' gives concrete invocation contexts. It does not name an alternative tool or state when NOT to use it, so it stops short of the top band, but the positive guidance is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses the real gotcha that not every listing has a suggestion due to insufficient data, that partial data is returned as-is, and it enumerates the returned fields. It omits auth/permission requirements and any rate-limit behavior, keeping it out of 5 territory.

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 purpose, followed by usage and a clearly labeled 'Gotcha'. Every sentence carries information the agent needs; 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?

For a single-parameter read tool with no output schema, the description is complete: it covers purpose, triggering scenarios, the failure mode (partial/absent suggestion), and the shape of the return. Nothing an agent needs in order to call it correctly is missing.

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

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

Only one parameter with 100% schema coverage, so the schema already documents item_id and its site-prefix format. The description adds no format or syntax detail beyond that, matching the baseline-3 rule.

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 ('Get Mercado Livre's competitive price suggestion') and pins the scope to 'one of your listings' with the basis (comparable sales). An agent can distinguish this from get_listing_prices, the raw-price sibling, because the description frames it as a recommendation rather than a price read.

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

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

Explicitly states the triggering user intents — 'whether a listing is priced right' or 'wants to undercut the competition' — which is clear usage context. It does not name an alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses pagination behavior and the shape of returned values, and the verb 'List' implies a read-only operation, but it never explicitly states that this is non-mutating nor mentions permission or rate-limit considerations. Adequate but with a real gap for a zero-annotation tool.

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

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

Front-loaded with the core action and outcome, followed by usage and prerequisite hints. Slightly redundant in that pagination via limit/offset and the price fields are each mentioned in both the description and the schema, but the text stays short and earns most of its space.

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

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

With no output schema and no annotations, the description correctly compensates by describing what comes back (promotional price, original price, status) and how results are paged. Auth/permission expectations are the only notable omission for a 3-parameter, single-required tool.

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

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

Schema description coverage is 100%, with limit, offset, and promotion_id all documented inline including ranges and defaults. The description only restates pagination and the provenance of promotion_id, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb+resource ('List the items already participating in a specific promotion campaign') and enumerates the returned fields (promotional price, original price, status). It is clearly distinguishable from add_item_to_promotion (which enrolls items) and get_promotions (which returns campaigns).

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 use cases ('check which of your items are in a campaign after adding them with add_item_to_promotion, or to audit active discounts') and names the prerequisite source for the required id ('Get the promotion_id from get_promotions'). The agent knows both when to call it and where its input comes from.

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?

No annotations are provided, so the description carries the full burden, and it does well: it frames the scope as the authenticated seller, warns that an empty list is legitimate (a common false-negative trap), and describes the return shape and pagination. It does not mention rate limits, permission nuances, or whether the listing is cached, so it falls short of fully rich behavioral disclosure.

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

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

Front-loaded with the verb and resource, then routing, then behavioral caveat, then return shape — a logical order with no filler. It runs slightly long by restating return fields the caller could not otherwise know, but every sentence carries information.

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

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

For a zero-required-parameter read tool with no annotations and no output schema, the description covers purpose, routing, empty-result caveat, and the return shape well enough to call it correctly. Remaining gaps (permissions, rate limits) are minor for a listing endpoint; it stops just short of fully 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 the schema already documents limit, offset, status, and promotion_type in detail. The description restates the candidate/started semantics and the limit/offset pagination but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource (promotions/campaigns offered to the authenticated seller) and scopes it to what the seller can join vs. what is running. It distinguishes itself from the sibling tools by naming get_promotion_items and add_item_to_promotion as the follow-up actions, so an agent can tell the three apart without opening any schema.

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

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

Explicitly says when to use it ('Use this to discover discount opportunities') and routes to the correct alternatives with their distinct purposes: inspect participants via get_promotion_items, join via add_item_to_promotion. The when/when-not distinction is unambiguous.

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

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

No annotations are provided, so the description carries the full burden: it discloses the auth requirement, the default sort order (newest first), the enumerated status values, and the shape of each returned record. It does not discuss pagination or rate limits, but covers the core behavioral facts a caller needs.

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

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

Front-loads purpose, then the primary-use-case tip, then status values, then the item_id filter, and finishes with the return shape and auth note. The return-field enumeration is somewhat long but earns its place given there is no output schema.

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 list tool with no annotations and no output schema, the description supplies the missing pieces: auth requirement, ordering, return fields, and status semantics. Nothing an agent needs to invoke it correctly 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%, so baseline is 3, but the description adds real meaning: it explains why UNANSWERED is the recommended status and frames item_id as a narrowing filter. This goes beyond the schema's terse field docs.

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 (List) and resource (pre-sale questions), plus scope (authenticated seller's listings, newest first). An agent can immediately distinguish this from the sibling answer_question, which the description explicitly links as the consumer of the returned ids.

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 names the primary use case (status='UNANSWERED' to find pending questions) and explains why it matters for conversion, and notes item_id restricts to one listing. It stops short of naming when not to use it or explicit alternatives beyond the implicit answer_question link.

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?

No annotations, so the description carries the full burden and does disclose real behavior: the authenticated-seller scope, the linked-claim relationship, and notably that accounts without returns may raise an API error that is surfaced gracefully. It stops short of covering auth/permission requirements or rate limits, so not a 5.

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

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

Front-loaded with purpose, then usage, return contents, and edge cases in tight succession. Every sentence carries distinct information 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?

With no output schema, the description compensates by listing the returned fields (return id, claim id, order id, status, creation date), documents pagination, and flags an error edge case. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and already documents limit, offset, and status in detail. The description's mention of 'paginated with limit/offset' largely restates the schema and adds no syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the authenticated seller's product returns'), including the Portuguese term devoluções and the claim linkage, which separates it from sibling tools like get_claims and get_orders.

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

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

Gives clear when-to-use guidance ('Use this to track return requests and their statuses') and routes to the complementary get_claim_detail for full context. No explicit when-not-to-use condition, but the sibling routing is strong.

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

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

With no annotations, the description carries the full burden and does disclose behavior beyond the schema: it explains that omitting user_id yields the authenticated account, that other sellers return public data, and that metrics cover 'the last period'. It does not mention auth requirements, rate limits, or error behavior for invalid user_ids, so it falls short of a 5.

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

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

The purpose and default/override behavior are front-loaded, and the following sentences earn their place by decoding fields the schema cannot (level_id color scale, power_seller_status tiers, metric list). It is dense but not padded; only the level_id explanation is slightly more verbose than strictly needed to invoke the tool correctly.

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

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

There is no output schema, and the description compensates by enumerating the returned payload (nickname, registration date, transaction totals, metric rates/values) and interpreting the enum-like fields (1_red through 5_green, silver/gold/platinum). An agent has everything needed to call it and interpret the result.

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's schema text already says 'omit to check the authenticated account', so the description largely restates it. It adds only the 'public data' nuance. Per the rubric, the baseline is 3 when the schema does the heavy lifting.

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

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

The description gives a specific verb+resource ('Get a seller's reputation profile on Mercado Livre') and immediately disambiguates the two operating modes: the authenticated account by default vs. any seller via user_id. No sibling tool in the list covers seller reputation, so the agent can place it unambiguously.

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

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

It states the purpose ('Use this to check the seller's reputation thermometer and service metrics') and the condition that selects the parameterized mode (user_id for public data on any seller). It does not name a when-not case or a sibling alternative, but no sibling overlaps this capability, so the gap is minor.

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

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

With no annotations, the description carries the full burden; it discloses the returned data shape (status, substatus, tracking, dates, address, items, logistic type) and the enumerated status values, which is strong for a read tool. It does not state read-only semantics explicitly or any auth/permission requirements, but 'Get' and the read-oriented field list make the behavior clear.

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

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

Front-loads the returned fields, then id provenance, status values, and the sibling pointer. Every clause carries information, though the status enumeration and provenance note make it slightly long relative to a single-parameter getter.

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, so the description appropriately enumerates return fields and status values to compensate. It stops short of describing error or not-found behavior, but is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents that shipment_id is a numeric id from order.shipping.id. The description's statement about id provenance largely duplicates that schema text, adding little beyond the baseline.

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

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

States a specific verb+resource ('Get the shipping details of a sale') and enumerates the returned fields, so the agent knows exactly what it produces. It distinguishes itself from siblings by routing to get_orders for id discovery and get_shipment_label for labels.

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

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

Explicitly states the prerequisite for obtaining shipment_id ('call get_orders first to find the shipment id') and names the alternative tool for a different task ('Use get_shipment_label to download the printable label'). When-to-use and alternative routing are both covered.

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

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

With no annotations, the description carries the full burden and does so: it discloses the local-file write side effect, the returned path/size, both output formats, the state precondition, the failure modes for unsupported logistic types, and that Meli errors are surfaced as-is.

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

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

Front-loads the action and return value, then packs preconditions and gotchas into a compact trailing block. Every sentence earns its place with 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?

No output schema exists, so the description must explain the return, and it does (absolute file path plus size in bytes). Combined with format options and failure behavior, an agent has everything needed to call and interpret the result.

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 documents both parameters, including the order.shipping.id origin and the pdf/zpl2 enum. The description largely restates that, adding no syntax or format detail beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb (download/save) and resource (Mercado Envios shipping label) plus the concrete side effect (saved to a local file), which clearly separates it from the sibling get_shipment.

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 real preconditions and routing advice: label only exists after 'ready_to_ship', flex/self-service logistics have no printable label, and 'call get_orders first if you only have an order id.' It does not explicitly contrast with get_shipment, but the when-to-use context is strong.

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?

No annotations are provided, so the description carries the burden. It discloses that the site is configurable with MLB as the default, that the result is a tree entry point, and that it returns a list of {id, name}. Missing are auth/rate-limit or empty-result notes, but for a 0-param read listing this is solid behavioral context.

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

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

Front-loaded with the core purpose, followed by drill-down guidance, the alternative, and the return shape. Every sentence adds information and none 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?

There is no output schema, so the description correctly compensates by stating the return shape ('a list of {id, name}'), and it covers the default-site behavior and workflow. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to document beyond the schema's empty object and the baseline default of 4 applies.

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

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

States a specific verb and resource ('List the top-level categories of the configured site') and immediately distinguishes itself from siblings by naming get_category for drilling down and predict_category for title-driven shortcuts. An agent can tell exactly what this returns and how it differs from the other category tools.

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

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

Explicitly frames itself as the entry point to the category tree, gives the workflow (pick here, then drill down with get_category to reach a leaf usable in create_item), and names predict_category as a faster alternative for a title-driven case. When-to-use and alternatives are both spelled out.

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

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

With no annotations, the description carries the full burden, and it does disclose return content ('keyword + URL for each trend') and trimming behavior ('trimmed to the requested limit'). However, it says nothing about freshness/latency of 'right now', rate limits, or auth requirements for what is implicitly a read operation.

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 tight paragraph, front-loaded with the core purpose before the use case and the category_id mechanics. Every clause earns its place and nothing is repeated.

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

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

For a two-parameter read tool with no output schema and no annotations, the description covers purpose, use case, dependency routing, and return shape. Minor gaps remain around data recency and failure modes, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, including the category_id example and the omit-for-site-wide behavior. The description reframes category_id as 'niche trends within a specific category' but adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get the trending search terms on the marketplace') and immediately clarifies what that means in domain terms ('top searches buyers are making right now'). This is clearly distinguishable from siblings like get_item_visits or search_products, which measure different things.

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 an explicit use case ('Great for product research and demand discovery') and routes the agent for the category_id dependency by naming get_site_categories and predict_category. It doesn't state when NOT to use it or how it differs from related analytics siblings, so it falls just short of the top band.

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?

No annotations, so the description carries the full behavioral burden. It usefully discloses the edge case for accounts with no warehouses ('empty list or a clear API error') and implies a read-only listing via 'List', but says nothing about authentication/scope requirements or pagination. The hedge 'or a clear API error' is also imprecise about actual failure behavior.

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

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

Three sentences, front-loaded with the core purpose, and each adds something (returned fields, use case, edge case). Mildly padded by the alternative-synonym parenthetical and the vague 'or a clear API error' clause.

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 no-parameter read-only listing with no output schema, the description adequately covers what is returned and the empty-state behavior. A brief note on auth scope or result ordering would close the remaining gap.

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

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

Zero parameters, so there is no parameter semantics to describe; baseline is 4. The schema is empty and consistent with the description's claim that the tool takes no input.

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 ('List') and resource ('seller's registered warehouses') and enumerates the returned fields (ids, descriptions, addresses). The parenthetical gloss 'multi-origin stock locations / depósitos' disambiguates a domain term, so no sibling (none of which handle warehouses) could be confused with it.

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 concrete when-to-use context: accounts shipping from multiple addresses, and setting up per-origin shipping options. It offers no exclusions or named alternatives, but with no overlapping sibling tool there is little routing ambiguity to resolve.

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

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

With no annotations, the description carries the full burden and delivers: it discloses that blocking only suppresses new questions, that the user can still buy, and that block/unblock is a real account change requiring user confirmation. These are non-obvious side effects an agent could not infer from the schema.

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

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

Front-loads the purpose, then action semantics, then cautions, then input sourcing. Every sentence conveys a distinct, actionable constraint with 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?

For a two-parameter action tool with no output schema and no annotations, the description covers purpose, mode semantics, side effects, confirmation needs, and input sourcing. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100% and the enum is documented, so the baseline is 3. The description adds value beyond the schema by giving the provenance of user_id (from get_questions or orders) and clarifying the list/block/unblock mapping to each parameter.

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

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

States a specific verb+resource ('Manage the seller's questions blacklist') and then enumerates the three action modes, so an agent knows exactly what the tool does. It is clearly distinguishable from read-only siblings like get_questions.

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

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

Explicitly says when to use 'block' ('only for abusive users'), what it does not do, and where to obtain the required user_id ('buyers' questions (get_questions) or orders'). It also names the confirmation prerequisite before mutating.

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

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

With no annotations, the description carries the disclosure burden and does well: it explains the return shape (list of categories with id, name, full path) and the consequence of misfiling. It omits auth/rate-limit behavior, but for a lightweight read-style prediction tool the operational context is largely covered.

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

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

Front-loaded with the core action, then a workflow directive, then a follow-up tool, then the return format. Every sentence earns its place and none 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?

No output schema exists, but the description explains the return values, and it embeds the tool in the publish workflow (before create_item, then get_category_attributes). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'title' param is already documented with an example in the schema, so the description adds only marginal meaning ('pass the title you intend to publish') plus guidance on picking the top prediction. 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 (predict) and resource (Mercado Livre category) with the exact input (product title). It clearly distinguishes itself from siblings by positioning the tool as the pre-step to create_item, an agent can tell what it does without opening the schema.

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

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

Explicitly says to ALWAYS call this before create_item and gives the reason (create_item needs category_id, wrong category hurts visibility/is rejected). It also names the follow-up tool get_category_attributes, providing a clear end-to-end workflow.

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?

No annotations are provided, so the description carries the burden; it conveys that this is a read-only search that returns a compact paginated list with named fields. It omits explicit read-only confirmation, auth requirements, and rate-limit behavior, but the operational profile is otherwise clear.

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

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

Front-loads purpose, then workflow, then return shape. The catalog/marketing context earns its place by motivating use, though the buy-box/traffic aside is slightly verbose for a tool definition.

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

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

With no output schema, the description steps up by describing the return ('product id, name, thumbnail and main attributes, paginated'), and it names the two follow-on tools an agent needs. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents query, limit, and offset. The description's 'paginated with limit/offset' merely restates the schema and adds no format or constraint detail beyond it; baseline 3 applies.

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

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

States a specific verb and resource ('Search Mercado Livre's product catalog') and immediately clarifies what a catalog product is. It distinguishes this catalog-specific search from generic product search and names the downstream tools (get_catalog_product, create_catalog_listing).

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

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

Explicitly states the purpose of use ('find the catalog_product_id for a product you sell') and the sequencing ('then inspect it with get_catalog_product and link your listing with create_catalog_listing'). The agent knows exactly when to reach for this and what follows.

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

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

With no annotations, the description carries the full burden and delivers: it discloses pagination semantics (limit max 50, offset paging), the return shape (total count plus a compact list with named fields), and the site-scoping behavior. It lacks only non-essential operational details like rate limits or auth requirements.

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

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

Dense but zero waste: purpose, use cases, the sibling exclusion, pagination mechanics, and the return shape in three front-loaded sentences. Nothing is buried or redundant.

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

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

For a read-only search tool with six fully documented params and no output schema, the description supplies the missing pieces — return fields and pagination behavior — so an agent can call it and interpret results correctly without further reference.

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 all six parameters are already documented in the schema (limit range, query example, offset, category id source, price bounds). The description largely restates the limit/offset mechanics rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search public listings on Mercado Livre') with scope (configured site, default MLB). It explicitly distinguishes itself from the sibling get_my_items by clarifying it searches the whole marketplace, not the seller's own listings.

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

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

Names concrete use cases (competitor research, market prices, finding item/category ids) and gives an explicit exclusion with the alternative ('NOT the seller's own listings — use get_my_items for that'). Both when-to-use and when-not are covered.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses that the message is REAL and visible to both buyer and Mercado Livre mediation, that it becomes part of the claim record, that text must be user-confirmed, and that the moderation rules (no contacts, links, phone, e-mail) carry sanction risk. It even states the return shape (message id and date).

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

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

Front-loaded with the core action, then prerequisites and risk in descending priority. Slightly redundant — the moderation constraint is repeated in both prose and the 'text' schema description — but every sentence otherwise carries operational weight.

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?

Covers the prerequisite tool, the visibility/irreversibility risk, the compliance constraint, and the return payload, with no output schema needed. An agent has everything required to invoke this correctly and safely.

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

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

Schema coverage is 100%, so both parameters (text, claim_id) are already documented, including the moderation constraint and the claim_id source. The description adds no syntax, format, or length semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource+actor: 'Send a message inside a claim (reclamação) thread as the seller.' This is clearly distinct in kind from the generic send_message sibling, though the description never explicitly names that sibling to contrast with it.

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

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

Explicit prerequisite and ordering: 'Use get_claim_detail first to read the thread context.' It also gives the when-to-be-careful condition (confirm exact text before sending). It stops short of naming send_message as the non-claim alternative, which would make routing fully unambiguous.

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

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

No annotations are provided, so the description carries the full behavioral burden and does so thoroughly. It discloses that this is a REAL buyer-facing message, requires user confirmation, is subject to Mercado Livre moderation with account suspension risk, forbids contact information, is limited to 350 characters, and returns message id, moderation status, and date.

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

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

The description is front-loaded with the core action and then layers in critical warnings, prerequisites, and return information. It is somewhat long and repeats the schema's character limit and moderation warning, but every major sentence contributes useful guidance.

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

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

For a mutation tool with no annotations and no output schema, the description is complete: it covers side effects, moderation rules, user confirmation, prerequisite context lookup, and return values. An agent has enough information to call it safely and correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the text limit and moderation constraint already in the schema, and adds little new syntax or meaning for order_id beyond what is already documented.

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: send a post-sale message to the buyer of a specific order. It distinguishes itself from sibling read tools like get_order_messages by being the send action, and from claim messaging by restricting to post-sale communication tied to an order.

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

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

Gives clear usage context: only for post-sale communication tied to an order, confirm exact text with the user before sending, and use get_order_messages first for context. It does not explicitly name send_claim_message as the alternative for claim-related messages, but the scoping exclusion is strong.

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

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

With no annotations, the description carries the full burden, and it delivers real behavioral context: partial-update semantics ('Only the provided fields are sent') and a non-obvious business rule (title updates rejected once units are sold). It stops short of stating auth/permission requirements or failure/reversibility behavior, so it is strong but not exhaustive.

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

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

Front-loads the core purpose, then the sibling routing rule, then the gotcha, then the return shape, in four dense sentences with no filler. Every sentence earns its place.

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

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

No output schema exists, and the description compensates by naming the returned fields (id, price, available_quantity, status). It covers partial-update semantics and the key business constraint; only permission/error-handling context is absent, which is a minor gap for a mutation tool.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the title's no-sales constraint and the site-prefixed item_id format. The description adds little beyond restating field names, so the baseline 3 applies.

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

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

States a specific verb (update) and resource (an existing listing owned by the authenticated seller) and enumerates the mutable fields: price, stock, title, video. It explicitly distinguishes itself from the sibling update_item_status, so an agent can route correctly without opening either schema.

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

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

Explicitly names when to use it ('price changes and stock adjustments') and when to use the alternative instead ('to change visibility (pause/activate/close) use update_item_status'). This is the when/when-not/alternative pattern at full strength.

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

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

With no annotations, the description carries the full burden and does so: it discloses irreversibility for items with sales, the confirm=true prerequisite, the reversibility of pause, and that a closed item requires a new listing. It even states the return payload (item id + new status), which is uncommon and useful.

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

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

The warning and confirm requirement are front-loaded and the sentences are dense with useful information, but the reversible/pause-and-reactivate point is stated twice (once in the action list, once in the follow-up sentence), a minor redundancy.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers the destructive path, the confirmation prerequisite, reversibility per action, and the return value. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents each enum value and the confirm flag. The description still adds value by framing confirm as an explicit refusal gate and by tying each action to its reversibility consequence, though much of the enum wording is duplicated rather than extended.

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 ('change the visibility status of a listing') and enumerates the three discrete actions with their effects, which no sibling tool (e.g. update_item, create_item) claims. An agent can immediately tell this is the state-transition tool rather than an edit tool.

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

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

It gives per-action selection guidance ('pause' hides, 'activate' re-publishes, 'close' finishes) plus an explicit gating rule ('close' is refused unless confirm=true) and a workflow instruction to confirm with the user first. There is no ambiguity about which action to pick for which intent.

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

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

With no annotations, the description carries the full burden and does well: it discloses that url is downloaded by Meli, that file_path is sent as multipart, and what the response contains (picture id, source URL, size variations). It does not mention auth/permission requirements, file size limits, or rate limits, which are relevant for an upload endpoint.

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 purpose, then the input constraint, then the create_item integration, then the return shape. Every sentence carries new information with 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?

No output schema exists, but the description explains the return value, and with only two fully documented parameters and no annotations there is nothing an agent needs to invoke this tool correctly that is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule ('exactly ONE of') that the schema does not encode via required/oneOf, plus clarifying that url is public and downloaded by Meli and file_path is a local multipart upload.

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 ('Upload a picture to the seller's Mercado Livre account') plus the concrete outcome ('get back a picture id'). It is clearly distinguishable from the sibling upload_video and from create_item, which it explicitly references.

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 routing: use the returned id in create_item's pictures for local files, but for already-hosted public URLs you can pass the URL straight to create_item. It also states the input constraint ('exactly ONE of url or file_path'), so an agent knows both when to call it and when to skip it.

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

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

With no annotations, the description carries the behavioral burden and does it well: it discloses that only local files are supported, lists accepted formats, warns that Meli enforces size/duration limits, and explains that API errors are surfaced as-is so the caller can adjust and retry. It stops short of stating auth/permission requirements or rate limits.

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

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

Four front-loaded sentences that lead with the action and the returned handle, then constraints. Slightly redundant in restating the accepted extensions already present in the schema, but otherwise every sentence earns its place.

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

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

For a single-parameter upload tool with no output schema and no annotations, the description covers purpose, downstream workflow, format constraints, failure behavior, and return contents (video_id plus id/size/quality info). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% for the single file_path parameter, so the schema already documents the absolute-path requirement and allowed extensions. The description's format list largely repeats the schema's own detail, adding little new meaning beyond the baseline.

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

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

States a specific verb (upload) plus resource (product video) and target account (seller's Mercado Livre account), and names the concrete artifact produced (video_id). It also distinguishes itself from siblings like upload_picture by specifying video from a local file, so an agent can select it without opening the schema.

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

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

Explicitly describes the workflow: upload here, then pass the returned video_id to create_item or update_item to attach it to a listing. It does not state an explicit when-not-to-use or point to an image alternative, so it stops short of full routing guidance, but the usage context is clear.

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