Hadacart KR/US product search and purchase links

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so the description usefully adds beyond them: it discloses the bounded result semantics, that example data does not verify price/inventory/orders/commission, that answer prose is not positive evidence, and that on failure the agent should inspect isError and structuredContent.recovery. These are substantive behavioral constraints not encoded in annotations.

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

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

The prose is dense and repetitive, with the 'questions may ask about unsupported claims / answers are not positive feature evidence' caveat appearing in both the description and the query param. Defensive disclaimers dominate and bury the actionable core; sentences are long and front-loading is weak.

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 7-parameter, no-output-schema, no-annotation-gaps tool, the description covers safety, evidence semantics, and failure recovery adequately. What it lacks is any sense of what the response contains or how paginated/bounded results are shaped, which an agent needs given there is no output schema.

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

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

With 71% schema coverage the schema already carries much of the load, and the description echoes the key filters (literal keywords, guide example country, native currency, merchant, unit) without adding format detail. limit/offset are never mentioned and the added param prose largely restates the schema's own descriptions, so it adds only marginal value over structured fields.

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?

It does identify a verb and resource (find/discover KR/US buying questions and guide documentation by literal keywords), and implicitly contrasts with find_purchase_candidates by insisting it is not 'exact candidate membership.' But the opening sentence crams 'dated comparison evidence and exact product routes' in, which muddies whether the tool returns questions, evidence, or products. An agent knows roughly what it does but the purpose is diluted by defensive caveats.

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 implied when-nots ('not general translation,' 'examples do not replace actual buyer selections,' 'not exact candidate membership, current stock or compatibility'), which helps exclude misuse. However, it never names a sibling as the alternative to use instead when the agent wants actual products, leaving routing 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?

Annotations already declare read-only, idempotent, closed-world and non-destructive, yet the description adds substantial extra context: no link activation or substitute occurs, returned links are not clicks or orders, results are not live inventory, zero-result originalIssuedRouteCheck semantics, and failure handling via isError/structuredContent.recovery. It is genuinely informative beyond the annotations, though the density and repetition blunt the impact.

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

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

The description is a wall of run-on, jargon-dense sentences that repeat the brief/full and read-only/no-execution points several times. The key action is front-loaded, but the remaining bulk is unstructured, so an agent must parse hard to extract usable rules.

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 25-parameter, nested-object tool with no output schema, the description does cover the important behavioral envelope: what is returned, what is never executed, zero-match guidance, recovery on error, and budget/unit-price distinctions. Gaps remain around the un-documented filter parameters, which keeps it out of the top band.

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

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

At 52% schema coverage across 25 parameters, the schema already documents the high-traffic fields (query, budget, quantity, productId, optionQuery, maxOptionPrice, unitPriceCeiling, purchasePreferences, includeVerificationPlans). The description adds real semantics, notably that maxOptionPrice maps to unitPriceCeiling and never both, and how budget applies per alternative. However, many parameters (maxPrice, maxUnitPrice, unit, limit, category, sellerId, destinationRegion, referenceQuantity, minPackageQuantity, maxSnapshotAgeHours) remain undocumented in either place.

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 opening sentence does state a concrete action (find products with original issued affiliate purchase links scoped by buyer country, currency, quantity and options), and 'Read-only bounded product shortlist' restates it plainly. But the jargon ('original issued affiliate purchase links', 'recordedOptionIdentity') obscures the intent, and nothing distinguishes this from the siblings find_buying_guides, get_product or search_products.

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?

There is embedded conditional guidance: 'Prefer responseMode brief for compact initial discovery', 'Add includeVerificationPlans true when source verification is the next step', and 'use optionQuery for recorded exact options'. These are parameter-level hints rather than tool-level routing, and the description never says when to pick this tool over the listed siblings.

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?

Beyond the read-only and idempotent annotations, the description discloses extensive behavioral limits: dated benefit restrictions, return-policy unknowns, storage/cooking null semantics, non-live package verification, no inferred temperature/lifetime or quantity scaling, and bounded SKU ambiguity. These are exactly the non-obvious 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?

The description is a dense, multi-sentence wall of caveats. It starts with the purpose, but then buries key usage context among many repetitive 'dated' warnings and recovery notes, making it hard to scan.

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

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

There is no output schema, so the description carries the burden of explaining returned semantics. It covers the main data areas and limitations well, including recorded fields and null meanings, though it remains less structured than ideal for a complex read 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 0%, and the single productId parameter is not described in the schema. The description only says 'exact product' and refers to 'exact product-ID sources' in a failure context, which gives marginal meaning but does not explain the identifier's source, format, or relationship to SKU/variant data.

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

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

The description states a specific verb and resource: 'Read one exact product' with dated options, native prices, source evidence and merchant route. This clearly distinguishes a single-product read from sibling search/find tools, though it does not name those siblings explicitly.

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

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

The description implies use when an exact product ID is available, but it never says when to use this tool versus search_products, find_purchase_candidates or find_buying_guides. It includes failure recovery guidance, but that is not the same as selection guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail: it searches public merchant snapshots, exact IDs do not fall back to title search, affiliate approval can be pending, optionQuery excludes incompatible ranking, and failures expose structuredContent.recovery. It also repeatedly clarifies that the tool never places orders and never selects options, which is valuable context beyond the annotations.

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

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

The purpose is front-loaded in the first sentence, but the remaining description is a dense run-on paragraph with many semicolon-linked constraints and some repetition around option selection. Given the tool's complexity, much of the content is useful, but the structure makes it harder to scan than necessary.

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 25-parameter search tool with no output schema, the description provides useful return-related detail such as matchedIdentifierEvidence, matchedQueryTerms, dated price/stock scopes, and recovery fields. Still, it leaves many parameter behaviors and result-shape details under-specified, so an agent would need to infer too much from the schema alone.

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

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

Schema description coverage is only 32% across 25 parameters, so the description must compensate heavily. It explains several complex parameters such as optionQuery, maxOptionPrice, productCondition, and affiliateLinkedOnly, but many core search, pagination, price, market, category, and availability parameters remain semantically unspecified or only inferable from names and enums.

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

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

The description states a specific verb and resource: searching multiple KR/US merchant catalogs by product keywords or exact identifiers. It clearly defines the search scope and exact-identifier behavior, though it does not explicitly differentiate itself from sibling tools such as get_product or find_purchase_candidates.

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 some explicit usage guidance, such as using affiliateLinkedOnly true to find recorded issued purchase routes, and explains optionQuery/maxOptionPrice constraints. However, it does not state when to use search_products versus the sibling tools, nor does it name alternatives or exclusions for catalog search versus direct product lookup.

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