yuantoutao-agent-mall

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 the safety profile ("Read-only") plus the item-count bounds (2-6). It also tells the agent what dimensions are compared, which is effectively output content. It doesn't cover failure modes or what happens with fewer than 2 items, so it isn't 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?

Three short sentences, front-loaded with the core purpose, no filler. The parenthetical list of comparison dimensions is dense but each item earns its place by telling the agent what the matrix contains.

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 and no annotations, so the description must carry everything — and it covers purpose, sequence, item bounds, and compared fields. Remaining minor gap is what the response structure looks like (matrix layout/columns), but nothing critical to 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% and the schema documents the accepted formats ("tbk:ID,pdd:ID" or JSON array). The description adds the meaningful constraint that 2-6 items are expected, which is not encoded in the schema — genuine added semantics beyond the structured field.

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 (side-by-side comparison), resource (shelf items), and scope (2-6 items), plus enumerates the comparison dimensions. This clearly distinguishes it from generic search/detail siblings like cps_item_info or search_goods, which return single items rather than a comparison matrix.

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 after cps_smart_search to justify a recommendation" gives an explicit workflow position and names the preceding sibling, which is strong guidance. It stops short of stating when NOT to use it (e.g., single-item checks should use cps_item_info).

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 but does state 'Read-only' and explains the server-default fallback when activity_id is omitted. However, it omits whether the conversion is idempotent, whether the link expires, and any auth/permission requirements for the yuantoutao console ID.

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?

Compact and front-loaded, leading with the platform and action. Some internal jargon ('LBS business — no product shelf') is terse, but every clause adds routing or default-handling 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 single-parameter, no-output-schema tool, the description covers the purpose, the calling scenario, and the default-ID behavior; the implied return (an affiliate link) is derivable from the stated conversion. Minor gaps around link lifetime/expiry remain.

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% (baseline 3), and the description adds meaning beyond the schema by naming what the server default actually is ('Taobao 领券中心 eleme activity') and reinforcing the omission behavior.

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 (convert) and resource (official ele.me activity: red-packet/landing page) into a defined output (our affiliate link). The sibling converters (cps_jd_convert, cps_pdd_convert) are clearly distinguished by platform.

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: 'LBS business — no product shelf; give the link to users who want food delivery.' This tells the agent the scenario in which this tool applies and, implicitly, that shelf/search tools are inappropriate. It does not explicitly name an alternative or state exclusions, so it stops short of 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 must carry the behavioral burden. It explicitly says 'Read-only', which is helpful, and lists return fields, but omits rate limits, pagination, or what happens with invalid/expired IDs. For a read-only lookup of a finite resource, this is adequate but not rich.

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

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

One dense sentence front-loads the platform and operation, then parameters, then returns, then a safety tag. Zero waste.

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 lookup with no output schema and no annotations, the description covers what it returns (price, coupon, monthly sales, commission, affiliate click_url), the parameter format and limit, and the read-only nature. Missing only error/edge-case behavior and when to prefer alternatives, which are minor for this 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 coverage is 0% and the single parameter is undocumented in the schema. The description adds crucial semantics: it is a string of num_iid(s), comma-separated, up to 40. That covers format, plural batch nature, and a hard limit—compensating well for the missing schema description.

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

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

States a specific verb+resource: retrieving Taobao item details by num_iid, and distinguishes from siblings like cps_jd_goods_search by naming the platform (Taobao) and the exact identifier (num_iid). An agent can tell this apart from other search/detail 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?

Implicitly guides usage by mentioning batch lookup (up to 40 comma-separated IDs) for product cards, but never states when to use this vs cps_smart_search or get_goods_detail, nor any exclusions or prerequisites.

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 the read-only nature and the tracked-commission behavior. It omits other material traits an agent would want: authentication requirements, rate limits, link expiry, and failure behavior for malformed URLs.

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 conversion action, and every sentence adds something (result, workflow, safety). The 'CPS JD:' prefix is mildly redundant with the tool name but costs little.

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 2-parameter tool with no output schema and no annotations, the description covers the intent but not the return shape — it is unclear whether the response is a bare link string or an object with additional fields (e.g., the returned client_ref trace). That is the main missing piece.

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 50%: client_ref is well documented in the schema itself, while material_url has no schema description — the tool description partially fills that gap by naming it as a JD material URL and by clarifying that positionId is server-side rather than a caller parameter. Still no format or validity rules for the URL, so it stays at 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?

The description names a specific verb and resource ('convert a JD materialUrl into an affiliate link') and identifies the platform (JD), which cleanly disambiguates it from cps_pdd_convert, cps_eleme_convert, and the other CPS siblings. It also states the mechanism (our positionId) and the downstream business effect (commission tracked), so an agent can distinguish it 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?

The workflow sentence ('User taps the link, buys in JD app, commission tracked') implies the scenario for using this tool, which is useful. However, it never states when to prefer it over a sibling converter, what preconditions the materialUrl must satisfy, or what happens when the URL is not a valid JD item — usage must be inferred.

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 whole burden and does useful work: discloses the strict daily quota, forbids polling, declares the operation read-only, and names the return payload field (affiliate materialUrl). It stops short of describing pagination behaviour or the shape/limits of the result set.

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 tight sentences with zero filler, and the highest-value facts (what it is, quota warning, next-step tool) are front-loaded. Slightly telegraphic, but every clause 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 4-parameter search tool with no annotations and no output schema, the description covers safety, quota and workflow well but leaves parameter behaviour undocumented. An agent would still have to guess at paging and result-set sizing, so it is adequate but incomplete.

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 25% (just the sort enum values), so the description needs to compensate for page, page_size and query — and it does not. It only implies that query is a keyword, leaving pagination and sorting semantics entirely undocumented outside 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 (search) plus resource (JD union goods) and the keying dimension (keyword). It also carves out what makes this tool's data distinct from the taobao equivalent (commentCount, goodCommentsRate), so an agent can distinguish it from search_goods, cps_pdd_goods_search and cps_smart_search.

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 post-condition workflow — results carry affiliate materialUrl and the next step is cps_jd_convert for a trackable link — and an explicit anti-pattern ("strict daily quota — do not poll"). It does not explicitly say when to prefer this over other platforms' search tools, so it falls short of full alternative routing.

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, yet it only implies a read of order records. It says nothing about pagination behavior despite page/page_size params, nothing about authorization/prerequisite for promoter data, and nothing about the shape of results.

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

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

A single front-loaded sentence with no wasted words; the resource and scope come before the parenthetical context. It is efficient, though the parenthetical is more promotional than operational.

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, no annotations, and 0% schema coverage mean the description is the only source of information, and it omits return shape, pagination semantics, and auth prerequisites. For a four-parameter data-retrieval tool this is materially incomplete.

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%, so the description must compensate. It mentions the time range, which maps loosely to start_time/end_time, but says nothing about expected format or about the page/page_size parameters, leaving two of four parameters entirely unexplained.

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 (retrieve 'order details'), resource ('promoter order'), scope ('in a time range') and a platform qualifier ('JD') that separates it from cps_pdd_orders. It is clear what the tool returns, though it never explicitly contrasts itself with the platform-specific siblings.

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 parenthetical 'source for commission settlement & refund tracking' implies a downstream use case but gives no explicit when-to-use vs. when-not guidance and no conditions for choosing this over cps_pdd_orders or cps_jd_convert. Usage is only hinted at.

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 whole burden. It does disclose the read-only nature, the 2024 goods_id deprecation, server-side goods_id→goods_sign resolution, and the downstream commission flow. It omits auth/pid requirements, rate limits, and error behavior, leaving real gaps for a mutating-in-effect conversion 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?

Purpose is front-loaded in the first sentence and each following clause (preferred input, fallback, commission flow, read-only) adds distinct information. Slightly dense with parentheticals, but no wasted sentences.

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 should cover the likely return value (the promotion url) and the pid requirement, but it does neither explicitly. The flow and deprecation context are present, so it is adequate but incomplete for a no-annotation, no-output-schema 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 coverage is 75% (pid undocumented entirely), yet the description adds genuine decision value the schema lacks: a PREFERRED ordering between goods_sign and goods_id plus the resolution fallback. This goes beyond restating the schema, though pid remains unexplained in both places.

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 ('generate affiliate promotion url') scoped to CPS PDD, which clearly separates it from cps_pdd_goods_search (discovery) and cps_pdd_orders (reporting). An agent can tell what this tool produces 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?

Gives concrete routing guidance for inputs: prefer goods_sign, fall back to numeric goods_id from yuantoutao shelf. It does not explicitly name alternative conversion tools (e.g. cps_tpwd, cps_jd_convert) or state when not to use this one, so it stops short of full when/when-not coverage.

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 well: it declares read-only, describes the returned payload (price, coupon, sales tip, commission), and discloses an external operational trait the schema cannot express — PDD burst rate-limits producing error 40009 plus the cooldown/retry mitigation.

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 in the first clause, then packs returns, safety, and the rate-limit caveat into a tight second sentence. Slightly dense with the parenthetical qualifier and NOTE block, 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?

There is no output schema, so the description compensates by listing the returned fields, and it covers safety and the known failure mode. An agent has what it needs to call the tool correctly and to handle the 40009 error path.

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 25% (pid is documented, page/page_size are bare), and the description adds nothing about pagination, page_size defaults, or pid. It conveys only that a keyword is required, leaving three of four parameters unexplained 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?

States a specific verb and resource ('search Pinduoduo DDK goods by keyword'), names the platform, and adds a targeting qualifier ('price-sensitive users'). This clearly distinguishes it from siblings like cps_jd_goods_search and shelf_search 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 alternative and the condition that selects it: on rate-limit cooldown, wait or use shelf_search (platform=pdd) which has no platform quota. It falls short of 5 because it doesn't cover general selection against other search siblings such as cps_smart_search or cps_jd_goods_search outside the rate-limit case.

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 delivers little: it does not disclose pagination behavior despite page/page_size params, doesn't mention auth or platform account requirements, and doesn't explain what 'incremental' means operationally or what the freshness/latency of the feed is. The read-only nature is only inferable from 'list'.

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

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

A single front-loaded sentence naming platform, resource, and scope with zero filler. Every clause carries information; nothing is redundant or buried.

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 4-parameter tool with 0% schema coverage, no annotations, and no output schema, the description is too thin: an agent cannot determine pagination semantics, time format, return shape, or how results relate to commission/refund workflows beyond the parenthetical hint.

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% across 4 parameters, so the description must compensate and largely doesn't. It conveys only that a time range is required (mapping to start_time/end_time) while page and page_size are left entirely unexplained in both the schema and the prose, including no default values or format hints for the time strings.

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 resource (order list) scoped to a platform (PDD) and mode (incremental) within a time range, which is enough to distinguish it from cps_jd_orders and other siblings. The parenthetical use-case ('commission settlement & refund tracking') further clarifies intent. It falls short of 5 only because 'incremental' is left undefined (cursor vs. timestamp-based).

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 a usage context (commission settlement and refund tracking) but never states when to prefer this tool over cps_jd_orders, cps_pdd_convert, or other sibling order tools. No prerequisites, no exclusions, no alternative routing is given.

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 does disclose safety ('Read-only') and the shape of the useful return fields (shop_url/user_id), but says nothing about pagination behavior, result limits, or rate/authorization constraints for a 20-item-capped query.

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?

Effectively one dense sentence; the core action is front-loaded and the routing caveat follows. The parenthetical mixing Chinese and English is compact but slightly harder to parse quickly.

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 2-parameter, no-output-schema search tool, the description covers purpose, safety, return fields, and the key alternative route. Missing only page_size/pagination guidance, which is minor given the small parameter set.

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%, so the description must compensate. It implicitly defines 'query' as a keyword, but 'page_size' (default 10, max 20) is never addressed, leaving paging semantics to the raw schema only.

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 and resource ('search Taobao shops by keyword') and immediately scopes the result to shop discovery (shop_url/user_id), which separates it from the product-oriented siblings like cps_smart_search and cps_jd_goods_search.

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 purchase/link-following intent to cps_smart_search's buy_url and notes that the legacy shop.get interface no longer returns click_url, so the agent knows what this tool is not for. It stops short of stating broader when-to-use conditions (e.g., when to prefer shop search over item search for discovery).

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 richly: 3-factor ranking, shop-tier ordering, mode semantics, live fan-out to taobao/jd/pdd union APIs with ~1s latency cost, working buy_url on live-only items, and a read-only declaration. It also warns not to invent review text, which is unusually strong 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 purpose and the preferred-over routing before any mechanics. It is dense and parenthesis-heavy, but every clause (ranking, tiers, mode, live, reasons, read-only) earns its place, so waste is minimal.

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

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

For an 8-param tool with no output schema, the description explains the return shape (score + breakdown.reasons), the ranking model, latency trade-offs, and safety. Combined with the dataset-specific routing guidance, an agent has enough 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 50%, but the description adds real meaning for the two non-obvious params: mode (default balanced, with when-to-use for quality/price) and live (parallel fan-out, ~1s cost, coverage gain). It does not add anything for category, page_size, platforms, budget_min/max 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 ('SMART product search for shopping recommendations') and distinguishes itself from named siblings by declaring it PREFERRED over shelf_search/cps_*_search. An agent can route to it 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 trigger ('help me buy X' asks) that selects this tool over alternatives. It further gives selection guidance for mode (pick price when cheap, quality when authenticity) and for live=1, leaving little 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, so the description carries the full burden. It discloses the sharing-context constraint (WeChat blocks links), which is useful behavioral context. However, it doesn't state what the generated password looks like, whether it's an ephemeral token, whether it requires auth, or any side effects. For a generation tool with no annotations, more behavioral detail would be expected.

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

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

Two tight sentences, front-loaded with the purpose and immediately followed by the scoping rule. No wasted words.

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 generator with no annotations and no output schema, the description gives the key usage context but omits parameter meaning (especially 'text') and output expectations. It's minimally viable but leaves an agent guessing about the optional field.

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 0% and there are two parameters. The description only implies what 'url' is; the optional 'text' parameter is entirely unexplained in both schema and description. With low coverage, the description must compensate but does not, leaving a real gap.

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: 'create a taobao password (tao-kou-ling) from a URL'. The parenthetical clarifies the domain concept. Siblings in the cps_* family are mostly convert/search/order tools; this one is distinguishable as a share-link generator, though the description doesn't explicitly name a sibling it might be confused with.

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

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

Explicitly states the condition to use it (out-of-app sharing) and the exclusion (in-app product cards should use click_url directly). This is a clear when/when-not with the alternative mechanism named.

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 largely meets it: it discloses server-side price computation ('never send prices'), the idempotency contract, the payment channel, and the redirect-vs-QR rendering behavior. It omits auth/permission requirements, failure semantics, and rate-limit 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?

Four short sentences, each load-bearing: creation, pricing rule, idempotency, and return/rendering contract. The most decision-relevant constraints (prices computed server-side, idempotency) are front-loaded 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 7-parameter mutation tool with a nested receiver object and no output schema, the description covers the essential workflow: pricing, idempotency, return values, and client rendering. Remaining gaps are auth requirements and error/retry failure behavior.

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 only 43%, so the description must compensate. It valuably explains that idempotency_key may arrive as a header or body field and that prices must never be supplied (clarifying max_price's role indirectly), but qty, merchant_id, product_id, and the nested receiver address fields get no added meaning.

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 ('Create an order') and immediately adds distinguishing scope facts: the server computes amounts, payment is WeChat, and the response carries a pay_url. It never names a sibling tool, so the agent must still infer separation from the many cps_* order/convert 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?

Gives concrete operational context: an Idempotency-Key is required so retries don't double-order, and render_hint tells the host whether to show a QR or redirect. It does not state when NOT to use it or which sibling (e.g. cps_*_orders) is the read-side alternative.

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 add value by declaring 'Read-only' and enumerating what is returned. It says nothing about permissions, rate limits, or whether missing sku_id produces an error, so the safety profile is only partially 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?

A single compact sentence with the resource and key identifier front-loaded, and no filler. It is efficient, though the terse list of return contents reads more like keywords than structured 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 read-only two-parameter tool with no output schema, the description usefully previews the returned fields. The unexplained merchant_id parameter and the absence of any usage context leave a notable gap before an agent could call this confidently.

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%, so the description must compensate. It identifies sku_id as the lookup key but never explains merchant_id, what format sku_id takes, or whether merchant_id is required for scoped results.

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 ('Full detail of one product by sku_id') plus the return contents (spec, images, aftersale rules), which is far more than a restatement of the name. It does not, however, distinguish itself from near-siblings such as cps_item_info or search_goods, so an agent must infer the boundary.

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 no when-to-use guidance and no named alternative. 'Read-only' hints at the operation class but does not tell the agent when to pick this over search_goods or cps_item_info.

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 of behavioral disclosure. It does not state whether the operation is read-only, whether it requires authentication, what happens if the order is not found, or any rate limits. The description is essentially a restatement of the tool name with no 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?

The description is a single, concise sentence with no wasted words. However, it is almost too terse given the lack of other information, but from a pure conciseness standpoint it is efficient.

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 no annotations, no output schema, and 0% parameter description coverage, the description is completely inadequate for a tool that likely returns detailed tracking information. It does not explain what the traces contain, the return format, or how to handle errors. An agent would struggle to use this tool correctly without additional context.

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 there is one required parameter (order_no) with no description in either the schema or the tool description. The description implies that an order number is needed but does not specify its format or source. The baseline for 0 parameters is 4, but here we have a parameter that is completely undocumented, so the score is lower.

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 resource (express tracking traces for a shipped order), which gives a sense of what the tool does. However, the phrasing is slightly awkward and it does not clearly differentiate from the sibling get_order_status, which could also return order-related information. The purpose is vague about whether it returns tracking events, carrier info, or logistics status.

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 no guidance on when to use this tool versus alternatives such as get_order_status. No context about prerequisites or exclusions is provided, leaving the agent to infer usage from the name alone.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose the meaningful behavioral detail that a full status timeline is returned and enumerates the possible states (paid, merchant_accepted, shipped with waybill, delivered, refunded), which is genuinely useful. It says nothing about read-only safety, auth requirements, or the size/shape of the timeline for long-lived orders.

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 line with no filler and the core purpose front-loaded. It is a fragment rather than a sentence, which costs a little readability but wastes nothing.

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 one-parameter read tool with no output schema, the description adequately conveys what comes back. It is incomplete on the parameter's semantics and on routing relative to similar siblings, but nothing catastrophic 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 0% and the single required parameter order_no is undocumented in both schema and description. The description does not clarify the expected order-number format, whose order namespace it belongs to, or what happens if the order is unknown.

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 (order status) and adds scope by naming the event timeline it returns. It does not, however, differentiate itself from the sibling get_logistics or the various cps_*_orders tools, so the agent must infer the boundary.

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 no when-to-use statement, no prerequisites, and no mention of an alternative tool. The description only characterizes the payload, leaving the agent to guess how this differs from get_logistics or cps_jd_orders.

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 does disclose a useful operational fact — free courier pickup with a 3/month per-user cap — which explains the pickup parameter's business meaning. However it never states this is an irreversible mutation, what permissions/auth are needed, or what happens on success.

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 parenthetical sentence with no filler; the primary branch (refund) is front-loaded and the alternative follows. The nested-parenthesis styling is slightly hard to parse but wastes no words.

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?

This is a 6-parameter mutation tool with 0% schema coverage, no annotations, and no output schema, so the description does the bulk of the explanatory work. It covers only the mode choice and leaves parameter meanings, side effects, and outcome unspecified — inadequate for the tool's complexity.

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% across 6 parameters, so the description should compensate. It fully explains the 'type' enum and implicitly explains 'pickup' via the free-pickup note, but says nothing about order_no, user_ref, reason, or reason_class. Two of six parameters receive any semantic treatment.

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 names the two concrete after-sale actions (refund-only vs return+refund) and ties each to a specific type value, so the resource and operation are clear. It does not explicitly say it initiates a new request for an order, but the modes are unambiguous. Siblings are unrelated commerce tools, so no differentiation is needed.

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 tells the agent which branch to pick: 'refund_only' for small amounts or quality issues, 'return_refund' when goods must be sent back. That is explicit selection guidance. It omits prerequisites (e.g., order must be delivered) and when not to use it at all.

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. It usefully declares 'Read-only' and sketches the return shape (compact items, retail_price in CNY cents, available_qty, inventory snapshot time), which is valuable absent an output schema. It omits pagination behavior, result limits, and whether filters combine as AND/OR.

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

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

Two tight sentences, front-loaded with the core action and immediately followed by the return contract. No filler; every clause adds 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 six-parameter tool with no annotations and no output schema, the description covers the return values well but leaves all input parameters undocumented. It is partially complete – strong on outputs, weak on inputs.

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?

All six parameters have 0% schema description coverage, so the description must compensate and does not. It never explains query semantics, the meaning/units of price_min/price_max (contrast the CNY-cents note given only for the return field), category_id, or page/page_size pagination.

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 the product shelf'), so the agent knows this is a read-search over shelf inventory. However, it does not distinguish itself from clearly overlapping siblings such as shelf_search and cps_smart_search, which an agent would need help disambiguating.

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 no statement of when to use this tool versus the many sibling search tools (shelf_search, cps_smart_search, cps_jd_goods_search, cps_pdd_goods_search). No context or exclusion criteria are provided, leaving selection entirely 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 provided, the description carries the full behavioral burden. It does add genuine value by declaring 'Read-only' and naming the returned payload (full attrs, detail page url, buy url), but it omits auth requirements, rate limits, and what happens for an unknown platform+item_id combination.

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 sentence with zero filler; the lookup key and the returned fields are front-loaded, and the read-only note is a short trailing qualifier.

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 usefully sketches the return payload (full attributes, detail page URL, buy URL), and it flags the read-only nature. Missing only edge-case behavior for invalid platform/item_id inputs, which is minor for a simple keyed 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 0% for both parameters. The description names platform and item_id but adds no format, casing, or validity information beyond what the schema already encodes (the platform enum values live only in the schema). It therefore does little to compensate for the coverage gap.

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 one curated shelf item') and the identifying key ('by platform+item_id'), which separates it from the list-oriented shelf_search sibling. It does not, however, explicitly distinguish itself from lookalike siblings such as cps_item_info or get_goods_detail.

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 phrase 'by platform+item_id' implies the precondition for calling this tool (you already have both identifiers), but there is no explicit when-to-use vs shelf_search or cps_item_info, and no stated exclusions or failure cases.

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 well: it discloses 'Read-only', 'No platform quota consumed', and what each item carries (detail_url to show the user, score+breakdown, buy guidance). It omits pagination/limit behavior and result-count semantics, but the safety and cost-profile disclosure is strong.

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 and quota benefit, then returning-item contents, then the sibling-routing decision. Dense but every sentence adds information; only mild loss from packing several facts into parentheticals.

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-param read-only search with no output schema and no annotations, the description covers the safety profile, cost, return-item structure, and tool selection. The remaining gap is per-parameter meaning for the filtering/pagination params that neither the schema nor the description explains.

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 0%, so the description should compensate. It explains the sort parameter thoroughly (default relevance with 3-factor explainable score and shop tiers, plus sales|price|latest), but says nothing about platform, price_min, price_max, page, or page_size, leaving five of seven parameters undocumented.

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 the LOCAL shelf') and immediately scopes it with parenthetical detail about the underlying curated taobao/jd/pdd items. It also distinguishes itself from the platform-search siblings by contrasting LOCAL shelf with quota-consuming platform searches.

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: 'Prefer cps_smart_search for "help me buy X" asks; use this for simple lookups.' This gives both the alternative and the condition that selects it, which is exactly what an agent needs to choose between overlapping search tools.

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