Reevol Source: supplier search

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read-only, no key required' reinforces the safety profile. It adds useful return-behavior context by stating that shared signals (common HS codes, certifications, country) are returned, though it does not cover error behavior or response structure details.

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 scope, then adds return semantics and read-only context. It is dense but each sentence carries useful information; it could be slightly tightened but wastes 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?

There is no output schema, so the description reasonably compensates by listing compared dimensions and shared signals. It is sufficient for an agent to call the tool correctly, though it could say a bit more about response shape or failure modes.

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 the slugs array (2-4 suppliers) and the lang parameter. The description only repeats the 2-4 slug constraint and adds no additional meaning about parameter formatting or the lang 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?

The description gives a specific verb and resource ('side-by-side comparison of 2-4 suppliers by slug') and enumerates the compared fields (identity, location, certifications, trade-fair count, employee range, year founded, HS code overlap, visibility). This clearly distinguishes it from single-supplier siblings like get_supplier and from search-oriented siblings like search_suppliers.

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 intended use case is implied by 'so you can summarize the trade-offs for a buyer,' but the description does not explicitly state when to use this tool versus alternatives such as get_supplier or get_similar_suppliers, nor does it give exclusions. This is workable context rather than explicit routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this usefully with 'Returns the draft text only; nothing is sent'. It further adds a real behavioral trait (bilingual EN+zh output for Chinese-region suppliers) and an auth constraint (partner/enterprise key) that annotations do not convey. Only gaps are failure modes and any length/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?

Three short sentences, front-loaded with what is produced, then output/safety, then constraints. Every sentence carries information an agent would otherwise have to guess.

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, non-destructive tool with no output schema, the description covers what comes back ('draft text only'), that nothing is sent, localization behavior, and the key tier required. What is missing is resolution of the 'slug' parameter and behavior on invalid/unknown suppliers.

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%: 'brief' is documented in the schema and 'quantity' explains itself, but 'slug' and 'buyerCompany' are undocumented in both places. The description only indirectly ties 'slug' to the supplier ('grounded in the supplier's facts'), leaving it unclear whether slug is a supplier identifier or a listing handle.

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 artifact: 'Generate a professional RFQ ... email body' grounded in supplier facts and the buyer's brief. That is clearly distinct from the supplier-search/compare siblings, though it never names an alternative explicitly. An agent can tell what this 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?

It offers context ('Requires a partner or enterprise key', bilingual output for Chinese-region suppliers) but never says when to choose this over e.g. match_suppliers_by_brief or request_introduction, nor any when-not condition. Usage is implied by the purpose rather than stated.

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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: discloses the partner-or-enterprise key requirement, that the response is complete and non-streaming, and that identical brief+filters are cached for 24h with stable citations. Those are exactly the operational facts an agent needs before invoking an expensive composite call.

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 what the tool does, then the pipeline stages, then the streaming caveat, caching, and auth in descending priority. Roughly five dense sentences with little waste; the 'Returns the complete result (non-streaming)' clause is slightly redundant with the SSE sentence but still 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?

The pipeline stages effectively communicate what comes back despite no output schema, and auth/caching are covered. But for a 13-parameter tool at 8% schema coverage, the description leaves the entire filter surface unexplained, which is a material gap 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 8% across 13 parameters — only 'brief' is documented. The description adds no meaning for the filter parameters (countries, hsCodes, employeeRange, certifications, foundedAfter/Before, businessType) beyond a passing reference to 'brief + filters,' so an agent must guess at their semantics, formats, and interactions.

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 and resource: 'One-shot deep research' that runs a named pipeline (shortlist, dossier with due-diligence signals, AI comparison, recommended next step). The phrase 'full pipeline in a single call' distinguishes it from the granular siblings like match_suppliers_by_brief, get_red_flags, and compare_suppliers 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?

Explicit routing condition: use it 'when your agent cannot consume the /mcp/deep SSE stream,' which names the alternative and the condition selecting this tool. It also notes caching makes repeated calls cheap. It does not, however, say when to prefer this over the sibling pipeline pieces (e.g. match_suppliers_by_brief or compare_suppliers) for cheaper partial work.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds one genuinely useful behavior beyond that: results are 'ordered by visibility score', which tells the agent the default ranking. It says nothing about result caps, paging, or empty-result 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?

A single sentence with the resource, the required key, the optional filters, and the ordering behavior — front-loaded and with no filler. Nothing here is redundant or padded.

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 read-only lookup with full schema documentation and clear annotations, the description covers what it must: scope, filters, and sort order. The remaining gaps (limit/lang behavior, result shape) are handled by the schema or are non-critical, and no output schema exists to lean on for returns.

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 with examples and enums. The description only names the optional filter categories, which the schema does better (e.g. any-of semantics for certifications, employee band examples). 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 suppliers headquartered in a given country') plus the optional filter axes, so the agent knows exactly what set is returned. It does not differentiate itself from siblings like search_suppliers or find_suppliers_by_hs_code, which is the only thing keeping it from a 5.

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

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

Usage is implied by the country-keyed framing: use it when the geography is known. However, there is no explicit guidance on when to prefer this over search_suppliers, find_suppliers_by_hs_code, or match_suppliers_by_brief, and no stated prerequisites or 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only that filters are optional, saying nothing about result shape, truncation at the 25-result cap, or whether partial HS codes broaden results — modest added value against an already-rich annotation 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?

Two short sentences, front-loaded with the core capability and followed by example queries that earn their place as intent-matching cues. Slight redundancy with the schema's own "8473.30" example, but nothing is padded.

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 7 parameters, no output schema, and rich annotations, the description is adequate but leaves gaps an agent would want: no indication of what a returned supplier record contains, no note that results are capped at 25, and no guidance on how partial HS codes affect match breadth. Not broken, but not fully sufficient for correct invocation expectations.

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 every one of the 7 parameters documented in the schema (format examples, bounds, enum, any-of semantics). The description contributes no parameter-level meaning beyond what the schema already states, 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 ("List") and resource ("suppliers") plus the exact scoping criterion — goods classified under a given HS code — which inherently separates it from find_suppliers_by_country and search_suppliers. 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?

The description supplies concrete trigger phrasing ("find me a supplier for HS code 8473.30" / "who makes [HS-described product]"), which is strong routing guidance for an agent matching natural-language intent. It stops short of naming alternatives or exclusions (e.g., when to prefer match_suppliers_by_brief or find_suppliers_by_country instead), so it is clear context without routing rules.

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?

The annotations already declare readOnly/idempotent/non-destructive, and the description adds what annotations cannot convey: that the output is structural signals, never an accusation or credit judgment, which tells the agent how to frame the results. It also adds the auth requirement (partner or enterprise key). It does not cover rate limits or result volume, which is why it scores 4, not 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 description is three tight sentences: the scan scope comes first, then the interpretation guardrail, then the access requirement. Nothing is repeated and there is 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?

With no output schema and minimal annotations, the description adequately tells what is scanned, how to interpret the output, and what access is needed. The only gap is the undocumented lang parameter, which an agent cannot use confidently from either the schema or the description.

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, and it does not. It implies a single supplier identifies the record but never names the slug parameter or its constraints, and the lang parameter is never mentioned at all.

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, then lists the exact signal categories (missing data, certification freshness, trade-fair recency, completeness, enrichment staleness), so the tool's purpose is unmistakable. It never names get_supplier or verify_supplier_listing as the alternatives it should be compared with, leaving that sibling boundary to inference.

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

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

Usage is implied by 'for one supplier' and by naming the prerequisite (a partner or enterprise key), but there is no explicit statement of when to pick this tool rather than get_supplier or verify_supplier_listing, and no exclusion for when not to use 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety burden is lifted. The description adds useful scoping (same industry and country) and a result cap, but states 'up to 10' while the schema allows limit up to 25 — a minor tension the agent must resolve — and says nothing about ranking or ordering of the similar 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?

Two sentences, zero waste, with the core behavior and constraints front-loaded ahead of the usage examples. Nothing needs trimming.

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 simple read-only lookup with full schema coverage and no output schema, the definition is essentially complete: input, scoping, result size, and use case are all present. The only small gap is the 'up to 10' vs. limit-max-25 discrepancy and no note on how similarity/ranking is determined.

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 slug, lang, and limit are all documented in the schema and the baseline is 3. The description only reinforces that slug is a single reference supplier; it adds no semantics for limit or lang beyond what is already structured.

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 ('Given one supplier slug, return ... similar suppliers') plus the scoping constraints (same industry and country) and result cap. An agent can tell this apart from search_suppliers or find_suppliers_by_country 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?

Provides concrete usage contexts via example questions ('what are alternatives to X?', 'who else makes similar products in [country]?'), which clearly frames when to reach for it. It stops short of naming sibling alternatives such as search_suppliers or find_suppliers_by_country that could also answer 'alternatives' queries.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the conditional `catalog` block that only appears for Reevol Catalog publishers and notes that contact happens via request_introduction with no key needed. It doesn't say what happens for an unknown slug or how large the payload can get.

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 and return contents, then usage sequencing, then the conditional catalog behavior. Dense and largely waste-free, though the final sentence packs the catalog block, the catalog MCP endpoint, and the introduction path into one run-on that could be tightened.

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

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

With no output schema, the description does the work of describing the return payload and flags the conditionally-present catalog block, which is exactly the kind of variability an agent needs to anticipate. It omits error/not-found behavior and any indication of response size, but is otherwise sufficient for a two-parameter 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 coverage is 100%, with both slug and lang fully documented including the locale enum values, so the schema carries the parameter burden. The description only implicitly touches parameters ("by slug", and the localized "buyer-facing summary + FAQ" implying lang's effect), adding marginal meaning. 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 opens with a specific verb and resource ("Fetch a full supplier profile by slug") and then enumerates the returned content (identity, location, HS codes, certifications, trade fairs, export markets, summary + FAQ). It explicitly positions itself relative to search_suppliers, so an agent can tell it apart from the other lookup siblings 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?

It gives clear sequencing ("Use after search_suppliers to dig into a specific match") and routes the contact use case to request_introduction rather than this tool. What's missing is any explicit when-not guidance (e.g., don't call it for bulk discovery or listing verification), so it stops short of full alternative 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?

Annotations already cover read-only/idempotent/closed-world safety, so the description earns credit for disclosing the internals that matter: semantic search over specific supplier fields combined with hard structured filters, plus a ranked result set with per-result matchExplanation. It doesn't clarify how conflicts between freeform brief and structured filters resolve (hard exclude vs. boost) or note behavior when no matches exist.

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 plus a compact example, front-loaded with the selection condition before mechanism, output, and illustration. Every sentence carries distinct information: when to use, how it works, what comes back, and a concrete input.

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 14-parameter tool with no output schema, the description covers the essential contract: what goes in, how ranking happens, and that supplier cards carry a matchExplanation. The remaining gap is edge-case behavior (empty result sets, precedence between brief-derived and explicit filters), which is minor but non-zero.

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 93%, so the baseline is 3; the description adds real value by enumerating the filter families and, more importantly, by showing a realistic `brief` value that mixes certifications, country, staff band, and export markets into freeform text. That example teaches an agent what belongs in `brief` versus the dedicated parameters, which the schema alone 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+resource (match suppliers to a buyer brief) and immediately scopes it to freeform natural-language requests, which separates it from the structured-lookup siblings like find_suppliers_by_country and find_suppliers_by_hs_code. The mention of the ranking output and matchExplanation makes the outcome concrete.

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?

"Best tool when a buyer describes what they need in their own words" gives a clear selection condition, and the contrast with structured filters implies when the pure-filter siblings are better. It stops short of explicitly naming alternatives or stating when not to use it, so it lands at 4 rather than 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?

Beyond the annotations (openWorldHint=true, destructiveHint=false, non-idempotent), the description discloses what actually happens: the request lands in the supplier's own Reevol inbox and they reply by email, or Reevol routes a lead with different handling for verified vs. unclaimed suppliers. It does not address duplicate submissions or the response shape, which is the remaining gap.

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

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

Front-loads the core action in one sentence, then branches into the two paths in a logical order with no filler. It is dense but every clause carries operational information; only the parenthetical field list borders on list-dumping.

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 5-parameter mutation with no output schema, the description covers both execution paths, the key requirements, and the downstream consequence for the buyer. It omits what the caller gets back and how to handle repeat submissions, which an agent would want for a non-idempotent write.

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 40%, so the description carries real weight and does: it explains that buyerName and buyerEmail should be the buyer's real details and that briefSnippet must be a specific brief naming products, quantities, and destination. `slug` and `buyerCompany` are left implicit, which keeps it short of a 5.

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: submit a buyer's interest in a specific supplier, and immediately distinguishes the two resulting behaviors (supplier inbox vs. Reevol-routed lead). This is clearly separable from siblings like get_supplier, request_supplier_listing, and draft_rfq.

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 decision rule: if get_supplier returned a `catalog` block use the direct inbound path, otherwise a routed lead is created. It also states plan/key prerequisites per path (no key needed vs. partner or enterprise key), so the agent knows when it can and cannot use this.

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

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

Annotations only declare the generic profile (not read-only, open-world, non-idempotent, non-destructive); the description adds the substantive mechanics: a 6-digit emailed verification code, a post-verification review consisting of an automated website/product check plus a human when needed, and a 'you are live' notification with the link. It also discloses binding input policy not captured elsewhere at workflow level (own-domain website required, free webmail rejected).

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 audience and action, then workflow, then policy, then outcome — a logical order with no filler. It is dense and long for a single tool, but each sentence carries either a routing rule or a constraint; only the closing Reevi profile-management detail is marginally beyond what an agent needs 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?

For a 9-parameter, non-idempotent, open-world submission tool with no output schema, the description covers the full lifecycle: pre-check, submission, code delivery and reading, verification call, human review, and final notification. An agent can execute the whole flow 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 coverage is 100%, so the schema already documents all nine fields and the baseline is 3. The description still adds meaning beyond it: the requirement that the website be the company's own and the explicit rejection of free webmail domains (gmail, qq.com, 163.com, outlook) is a substantive constraint on the `email` parameter that the schema only implies.

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 (submits a request to be added to Reevol Source) and immediately scopes the audience (suppliers not yet listed). It is clearly distinguishable from search_suppliers (check first) and verify_supplier_listing (the next step) which it names 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?

Gives explicit preconditions and alternatives: 'search_suppliers first to make sure the company is not already listed', then after the request the agent must read the 6-digit code from the inbox and call verify_supplier_listing. The routing between this tool and its two siblings 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?

Annotations already flag openWorldHint=true, idempotentHint=false and destructiveHint=false; the description adds genuinely new behavioral facts: a real email is sent, the code is 6 digits, and sending is rate-limited per request. It does not say what happens when the limit is hit or whether previously issued codes are invalidated.

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 short sentences, front-loaded with the action and followed by the constraint. Nothing is redundant with the title 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 one-parameter side-effecting action with no output schema, the description covers the action, the precondition, and the rate limit. The remaining gaps (limit-exceeded behavior, code invalidation, delivery failures) are minor but real.

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 requestId parameter is already documented as coming from request_supplier_listing, so the schema does the work. The description adds no further meaning about the parameter (no format, no behavior on invalid or expired ids).

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: it emails a fresh 6-digit code for a pending verification request. The phrase 'still waiting for verification' scopes it apart from the initial request_supplier_listing and from verify_supplier_listing, though it never names 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?

'For a request that is still waiting for verification' gives a clear precondition for when this tool is the right call, implicitly excluding already-verified or not-yet-created requests. It stops short of naming the alternative tools to use in those other 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?

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds that results come back as ranked supplier cards — useful since there is no output schema. No disclosure of ranking basis, auth, or paging beyond the limit parameter.

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 capability, then return shape, then usage trigger. 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 simple read tool with full schema coverage and rich annotations, this is close to sufficient; the only gap is what 'ranked' means and when to escalate to get_supplier for full detail.

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 documents query, limit, and lang thoroughly; the description's main addition is confirming bilingual (English/Chinese) name support and alias matching. It says nothing about lang or limit behavior, so it sits at the baseline for a fully-documented 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 plus the search keys (company name in English or Chinese, brand, alias), which cleanly separates it from siblings like find_suppliers_by_hs_code and find_suppliers_by_country that search on other axes.

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 trigger: a buyer naming a supplier or asking 'who is X?'. It does not name the follow-on alternatives (e.g., get_supplier for detail, find_suppliers_by_country when only a country is known), so routing is clear but exclusions are absent.

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?

Goes well beyond the annotations by disclosing code lifetime (15 minutes), lockout behavior after 5 wrong attempts, and the post-success state change (enters the Reevol review queue). These are non-obvious operational facts an agent cannot derive 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?

Three tight sentences, front-loaded with the sequencing and inputs, then constraints, then outcome. 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?

Covers prerequisites, input origins, failure/retry path, and the resulting state change; with no output schema, that outcome sentence is exactly what is needed to interpret success.

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; the description adds value by stating the provenance of requestId and that the code is 6-digit from email. Minor tension: it calls the code "6-digit" while the schema permits 6–12 characters, but this does not impede calling.

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 the specific operation and its position in a workflow ("Second step of request_supplier_listing"), stating exactly what inputs are required. It clearly distinguishes itself from resend_supplier_listing_code and request_supplier_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 says when to call it (after request_supplier_listing, using its requestId plus the emailed code) and names the alternative for the failure case ("call resend_supplier_listing_code for a new one"). No inference required.

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