MRC Data — China's Apparel Supply Chain Infrastructure

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds behavioral details: returns empty results if no match, sparse province entries imply niche, rate limit wait, and data source (MRC Data). No contradiction, but no mention of caching or data freshness.

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

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

Well-structured with sections (USE WHEN, WORKFLOW, RETURNS, etc.) and front-loaded with core purpose. However, the Chinese translation at the end is redundant, and the description is somewhat lengthy.

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 2 parameters and no output schema, description is highly complete: covers use cases, errors, workflow, examples, and data source. No major gaps.

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 100% (baseline 3). Description adds meaning via examples (e.g., 'sportswear, denim, underwear'), explains verbose_hints, and outlines return structure (product, total_suppliers, by_province, etc.) despite no output 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?

The description clearly states it provides a market overview and analysis for a product category in China, using specific verbs like 'analyze' and 'overview'. It distinguishes from siblings by explicitly stating it is a bird's-eye view and not for specific suppliers or clusters.

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 lists USE WHEN scenarios, provides workflow (analyze_market → search_suppliers), and includes AVOID section with alternatives (recommend_suppliers, search_clusters). Also gives error correction steps and rate limit handling.

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?

Discloses how the score is computed (fusing up to 5 weighted signals, confidence propagation, red flags as suspected inconsistencies). Annotations already mark it as read-only and idempotent; the description adds behavioral context beyond annotations.

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

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

Description is front-loaded with core purpose, then structured into use cases, prerequisites, return fields, and how it works. It is detailed but efficiently organized; minor redundancy could be trimmed.

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 tool with one parameter, no output schema, and rich annotations, the description fully covers prerequisites, behavior, return structure, and limitations. It is self-contained and sufficient for correct invocation.

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

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

The single parameter supplier_id is described in the input schema with type and example. The main description adds context on where to obtain the ID (from search_suppliers, etc.), adding value over the schema alone.

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?

Description clearly states it assesses supplier credibility by fusing declared-vs-verified signals into a trust score with physical-plausibility checks. This specific verb+resource combination distinguishes it from siblings like check_compliance or detect_discrepancy.

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 'USE WHEN' section lists concrete user queries in both English and Chinese, plus a prerequisite requiring a valid supplier_id from specific tools. This provides clear guidance on when to invoke this tool.

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=true, idempotentHint=true, destructiveHint=false. The description adds crucial behavioral context: it explains the tool is a read-only check, describes the return structure, details error handling and self-correction (e.g., handling 'supplier not found', rate limits, incomplete data interpretation), and notes the data source and market-specific requirements. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear section headings (USE WHEN, PREREQUISITE, WORKFLOW, RETURNS, EXAMPLES, ERRORS, AVOID, NOTE, Chinese translation). It is front-loaded with the core purpose and each section is concise and relevant. Minor redundancy in the Chinese section could be trimmed, but overall 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 the tool's complexity (multiple export markets, data completeness issues, error scenarios) and the lack of an output schema, the description is remarkably complete. It defines the return structure, provides error handling strategies, explains how to interpret missing data, and includes examples for different markets and languages. No gaps are evident.

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 descriptions for all three parameters. The description adds value by explaining the meaning of target_market values (market-specific regulations) and verbose_hints (interpretation annotations), and provides examples showing parameter usage. It goes beyond the schema by linking parameters to use cases, justifying a score above baseline 3.

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

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

The description clearly states the tool's purpose: 'Check if a supplier meets compliance requirements for a target export market.' It uses specific verbs ('check') and resources (supplier, market), and distinguishes from sibling tools like get_supplier_detail and find_alternatives through explicit workflow and usage notes.

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 provides explicit 'USE WHEN' conditions, prerequisites (must have supplier_id), workflow steps, examples, and an 'AVOID' section that tells when not to use the tool and suggests alternatives like search_suppliers with compliance filtering. This thoroughly guides the agent on when and how to use the tool.

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 indicate readOnlyHint, idempotentHint, destructiveHint. Description adds behavior beyond annotations: explains return structure (full records with key metrics), error handling (too many IDs, fewer results, empty data, rate limit 429), constraints (max 10), and data source. No contradictions.

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?

Comprehensive but well-structured with clear section headers (PREREQUISITE, USE WHEN, WORKFLOW, RETURNS, EXAMPLES, ERRORS & SELF-CORRECTION, AVOID, CONSTRAINT). Each section earns its place; slightly verbose but organized for readability.

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 complexity (comparison tool with dependencies, errors, constraints), description is complete: covers workflow, error handling, examples in English and Chinese, constraints, and return structure despite no output schema. Fully equips agent to use tool correctly.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds value beyond schema by providing example valid cluster IDs (humen_women, shishi_casual), emphasizing IDs must come from search_clusters, and explaining that missing IDs are silently skipped.

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?

Clearly states 'Compare multiple Chinese apparel industrial clusters side-by-side on key metrics.' Uses specific verb (compare) and resource (clusters), distinguished from siblings like search_clusters (finds clusters) and get_cluster_suppliers (lists factories).

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 explicit when-to-use examples ('compare Humen vs Shishi vs Jinjiang') and when-not-to-use ('Do not call with guessed cluster_ids', 'Do not use to list factories'). Lists prerequisite (search_clusters first), alternatives (get_cluster_suppliers), and workflow guidance (search_clusters → compare_clusters → optionally get_cluster_suppliers).

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?

Disclosed behavioral traits: returns multiple supplier profiles, silently skips invalid IDs, max 10 IDs, rate limit handling, source (MRC Data), and that it returns full 60+ field profiles. Annotations (readOnlyHint, idempotentHint) are consistent and description adds extra context on errors and constraints.

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?

Description is well-structured with sections: USE WHEN, PREREQUISITE, WORKFLOW, DIFFERENCE, RETURNS, EXAMPLES, ERRORS, AVOID, CONSTRAINT, NOTE, 中文. Each section adds distinct value. Front-loaded with main purpose and usage examples. 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?

Despite no output schema, the description compensates by detailing return structure ({count, data: [profiles]}), error handling, and integration workflow with other tools. Covers prerequisites, constraints, and edge cases (invalid IDs, batching). Highly complete for a read-only comparison tool.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds meaningful context beyond schema: supplier_ids must come from specific tools, examples of valid IDs, and that verbose_hints adds interpretation annotations. This elevates the score.

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 clearly states the tool compares multiple suppliers side by side on all dimensions. It differentiates from siblings like get_supplier_detail (single vs multiple) and search_suppliers (discovery vs comparison). The verb 'compare' is specific and the resource 'suppliers' is clear.

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 explicit use cases (e.g., 'compare these 3 factories', 'benchmark sup_001 vs sup_002'). Also states when not to use (e.g., avoid looping get_supplier_detail) and prerequisite workflow (must have valid supplier_ids from specific tools). Includes Chinese language examples.

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 indicate read-only, idempotent, non-destructive. Description adds important context: max 50 records, requires both values, rate limiting, and data coverage limits. No contradictions.

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

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

Well-structured with clear sections (core feature, use cases, workflow, returns, examples, errors). Front-loaded with core purpose. Every sentence adds value, no redundancy.

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

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

Comprehensive despite no output schema: explains return structure, data limitations, and error states. Covers all necessary context 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 covers 100% of parameters with descriptions. Description adds value by providing Chinese translations, exact-match behavior for composition, and usage examples that clarify threshold 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?

The description explicitly states the core function: surface supplier spec deviations from lab measurements. It lists a wide range of user queries and distinguishes itself from sibling tools by positioning as a standalone audit tool with clear workflow instructions.

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 explicit 'USE WHEN' list, workflow guidance, error handling, self-correction tips, and an 'AVOID' section. Fully informs when and how to use vs. alternatives.

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 description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It discloses that the tool provides estimates based on database averages, not binding quotes, and must be clarified to the user. It also includes error self-correction (rate limit 429 → wait 60s) and constraints on output usage. No contradiction with annotations.

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

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

The description is long but well-structured into labeled sections (USE WHEN, WORKFLOW, RETURNS, EXAMPLES, ERRORS, AVOID, CONSTRAINT, NOTE, 中文). It front-loads the core purpose. While every section seems necessary, the large list of example queries could be slightly trimmed without losing information. Overall, it earns its length.

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

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

Given the tool's complexity (5 parameters, no output schema), the description provides thorough coverage: usage scenarios, workflow integration with sibling tools, error handling, constraints, and a note on accuracy. The EXAMPLES and ERROR sections concretely illustrate boundary conditions. The description is complete enough for an agent to use this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing example mappings (e.g., fabric_category: 'knit' from 'cotton t-shirts') and a RETURNS section that clarifies output shape, helping agents understand how parameters affect results. However, parameter descriptions in the schema are already fairly descriptive, so the added value is moderate, not exceptional.

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 clearly states the tool's purpose: 'Estimate sourcing cost for a product based on fabric price, supplier pricing, and order quantity.' It uses a specific verb ('estimate') and a clear resource ('sourcing cost'), distinguishing it from sibling tools like search_fabrics or recommend_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 description includes a comprehensive 'USE WHEN' section with many concrete example queries, an 'AVOID' section listing when not to use it (e.g., for detailed BOM costing), and a workflow hint (estimate_cost → optionally search_fabrics → recommend_suppliers). This provides explicit when-to-use and when-not-to-use 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 readOnlyHint=true and destructiveHint=false, so the description's disclosure of constraints (max 10 alternatives, product type matching) and error handling (supplier not found, empty alternatives, rate limits) adds valuable behavioral context beyond the annotations.

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

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

The description is well-structured with clear headings and sections (USE WHEN, PREREQUISITE, DIFFERENCE, etc.). While lengthy, every part earns its place by providing essential guidance. Could be slightly more concise, but the structure aids readability.

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

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

Given the tool's complexity (5 parameters, multiple use cases, error conditions), the description covers all necessary aspects: examples, error recovery, constraints, and return format. No output schema exists, but the description explains what the tool returns sufficiently.

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%, but the description adds meaning beyond the schema (e.g., sorting logic for reasons, requirement that supplier_id comes from a valid source, optional province filtering). This helps the agent use parameters correctly.

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?

Clearly states 'Find alternative suppliers similar to a given supplier.' The verb and resource are specific, and the description explicitly differentiates from sibling tools 'recommend_suppliers' and 'search_suppliers' by explaining their distinct starting points.

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 explicit 'USE WHEN' and 'AVOID' sections, prerequisites, workflow examples, and clear differences from sibling tools. This gives the agent comprehensive guidance on when to invoke this tool versus alternatives.

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?

Discloses sorting by quality_score DESC, pagination behavior, rate limit handling (429 with 60s wait), and source (MRC Data). Annotations already indicate read-only, idempotent, non-destructive; description adds valuable behavioral context without contradiction.

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

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

Well-structured with clear sections (USE WHEN, PREREQUISITE, WORKFLOW, RETURNS, EXAMPLES, ERRORS, AVOID, NOTE). Front-loaded with main purpose. Some redundancy in examples and inclusion of Chinese translation, but overall efficient for the level of detail needed.

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?

Despite no output schema, the description defines the return object structure ({cluster_id, has_more, data}) and explains pagination (limit 1-50). Covers error scenarios and recovery steps, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds examples showing how limit and offset are used in practice (e.g., pagination example). This provides additional context beyond the schema, justifying a score above the baseline of 3.

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

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

The description clearly states 'List all suppliers in a specific industrial cluster' and provides numerous specific user query examples. It distinguishes from sibling tools like search_suppliers (global search) and compare_clusters (cluster comparison).

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 prerequisites (must have cluster_id from search_clusters), workflow steps, when to use (specific queries), and what to avoid (don't guess cluster_ids, don't iterate clusters). Includes error handling and self-correction 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 provide readOnlyHint and idempotentHint. Description adds substantial behavioral details: error handling (fabric not found, null fields, rate limit), return structure (30+ fields), and method references. No contradiction.

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

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

Well-structured with clear sections (prerequisite, use when, workflow, examples, errors). Though verbose, every section serves a purpose and the front-loaded summary quickly conveys the tool's function.

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?

Despite no output schema, description lists 30+ fields categorically and includes error handling, workflow, and method details. Could be more precise about field names but is sufficient for complex lab data 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% but description adds value by clarifying fabric_id must come from search_fabrics, providing examples, and explaining verbose_hints behavior. The contextual constraint 'Do not guess IDs' goes beyond 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?

Clearly states it gets the complete lab-tested record of a single fabric by ID. Distinguishes from siblings like search_fabrics (prerequisite) and get_fabric_suppliers. Provides specific user queries for context.

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 prerequisite: must call search_fabrics first. Lists when to use with bulleted user query examples. Describes workflow and provides clear avoid statements (no looping, no browsing).

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 indicate read-only, idempotent, non-destructive. The description adds: sorting by quality_score DESC, specific error behaviors (count=0, rate limit 429 with wait), data source (MRC Data), and implicit read-only nature. No contradiction with annotations.

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

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

Well-structured with sections (purpose, usage, workflow, examples, errors). The Chinese translation adds length but aids multilingual users. Could be slightly tighter, but all content 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?

Given no output schema, the description fully documents the return format. Covers prerequisites, error handling, and workflow integration with siblings. Provides concrete examples. All critical context for an AI agent is present.

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 has 100% coverage with descriptions. Description reinforces fabric_id meaning with examples and prerequisite, and verbose_hints is explained. Adds context about output structure but does not go beyond schema into parameter formats.

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 clear verb+resource statement: 'List all suppliers offering a specific fabric, sorted by quality score, with price comparison.' It distinguishes itself from siblings like search_suppliers (general browse) and get_supplier_fabrics (full range for a supplier) in the AVOID section.

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 a comprehensive 'USE WHEN' list with multiple query patterns, explicit workflow (search_fabrics → this tool → get_supplier_detail or compare_suppliers), and clear exclusions in the AVOID section. The prerequisite and error-handling sections further guide appropriate invocation.

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 indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable context: results are ranked by supplier count, data source is MRC Data, and it returns a specific structure. It also includes error handling (empty data, invalid province, rate limit) that goes beyond the annotations.

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

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

The description is well-structured with clear sections (purpose, when to use, workflow, returns, examples, errors, avoid). While lengthy, every section adds value and the front-loaded purpose sentence ensures immediate clarity. A slight reduction from 5 due to verbosity, but still 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?

For a tool with 2 optional parameters and no output schema, the description is comprehensive: it specifies the return structure, provides error self-correction, workflow integration with sibling tools, and examples in multiple languages. No gaps remain for an agent to safely and effectively use the 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%, but the description adds meaningful examples for the 'province' parameter (showing both English and Chinese inputs), mentions that 'normalizeProvince handles both', and explains the 'verbose_hints' parameter. This adds value beyond the schema's basic descriptions.

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 clearly states 'List all product categories available in the database with supplier counts.' This is a specific verb and resource, and it distinguishes itself from sibling tools by explicitly listing use cases and comparisons (e.g., 'DO NOT use for geographic insight — use get_province_distribution').

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 provides a detailed 'USE THIS FIRST when:' section with concrete user queries, and an 'AVOID' section clarifying when not to use it. It also compares to sibling tools like search_suppliers and get_province_distribution, giving explicit guidance on alternatives.

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, and destructiveHint, covering the safety profile. The description adds detailed behavioral context: it describes the return format, provides error handling guidance (empty data, sparse results, rate limit 429), explains data source, and includes self-correction steps. No contradiction with annotations.

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

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

The description is well-structured with clear sections (USE WHEN, WORKFLOW, RETURNS, EXAMPLES, ERRORS, AVOID, NOTE). The first sentence states the core purpose. However, it is somewhat lengthy and could be tightened without losing key information. It earns a 4 for structured comprehensiveness.

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

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

Given the tool has 2 non-required parameters and no output schema, the description fully covers usage context, workflow integration, return format, error scenarios, and edge cases. It explains what to do with empty data, sparse results, and rate limits. The Chinese translation adds accessibility.

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 provides examples and usage context (e.g., when to use product_type) but does not add significant semantics beyond what the schema already conveys. The parameter descriptions in the schema are clear, and the examples illustrate typical values.

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 starts with 'Show supplier distribution across Chinese provinces' which clearly states the verb (show) and resource (supplier distribution by province). It distinguishes from siblings by specifying that cluster-level queries should use search_clusters and deeper market analysis uses analyze_market.

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 'USE WHEN' section provides explicit example queries covering English and Chinese, and includes follow-up scenarios. The 'AVOID' section clearly states when not to use this tool (e.g., for cluster-level granularity) and directs to alternatives (search_clusters). It also advises when to include product_type.

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 readOnly, idempotent, destructive, openWorld. Description adds: dynamic vs static nature, return structure, exclusion of unverified records, error handling (retry on zero counts, wait on 429), and source attribution. No contradictions.

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

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

Well-structured with clear sections (USE WHEN, WORKFLOW, DIFFERENCE, RETURNS, EXAMPLES, ERRORS, AVOID, NOTE) and front-loaded core purpose. Some redundancy with Chinese translations, but overall 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?

For a simple stats tool with 1 optional param and clear annotations, description provides comprehensive context: usage examples, error handling, return structure, data scope (verified only). Meets full needs.

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 has 1 optional boolean parameter with full description (100% coverage). Description does not add new meaning beyond schema; baseline 3 is appropriate.

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

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

Description explicitly states 'Get overall database statistics: total counts of suppliers, fabrics, clusters, and links.' It clearly identifies the resource and action, and distinguishes from sibling tools like get_product_categories and database-overview resource.

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 extensive usage guidance: lists specific user queries (including Chinese), defines workflow as standalone discovery tool, explicitly states when NOT to use (e.g., before every tool, for per-category counts, for geographic metadata), and differentiates from similar tools.

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 description discloses behavioral traits beyond what annotations provide. Annotations show readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds: numeric fields show both declared and lab-verified values, null fields mean unverified, coverage_pct guidance, error handling for 'Supplier not found' and 'not available for public access', and rate limit behavior. This fully informs the agent about side effects and data quality.

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 structured with headings (PREREQUISITE, USE WHEN, RETURNS, EXAMPLES, ERRORS, AVOID, NOTE) making it easy to scan. It front-loads the core purpose. While lengthy, the complexity of the tool justifies the length. Could be slightly more concise, but overall well-organized.

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 tool has no output schema, so the description must cover return values. It does: 'Returns 60+ fields...' with a sample JSON structure and lists key fields. It also explains error cases and self-correction. Given the tool's richness and lack of output schema, the description is very complete, leaving no major gaps.

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 descriptions for both parameters. The description adds example values for supplier_id but does not add significant new meaning for verbose_hints beyond the schema. Baseline is 3 when schema already covers parameters well. The description does not compensate further, so a 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Get the complete profile of a single Chinese apparel supplier by ID.' It provides specific verb+resource and lists many concrete use cases (user asks for details, certifications, etc.). It distinguishes from siblings by mentioning workflow with search_suppliers and compare_suppliers, and explicitly says not to call in a loop but use compare_suppliers instead.

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 provides explicit usage guidelines: a PREREQUISITE section requiring a prior call to search_suppliers, a USE WHEN list of user queries, and an AVOID section warning against looping or browsing. It also includes error self-correction instructions (e.g., rate limit handling, field nulls). These guidelines help the agent decide when and how to use the tool compared to alternatives.

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, destructiveHint. Description adds return format, error cases (count=0, invalid ID, rate limit), data source note, and self-correction steps. No contradictions.

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

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

Well-structured with clear sections (USE WHEN, PREREQUISITE, WORKFLOW, RETURNS, EXAMPLES, ERRORS, AVOID, NOTE). Front-loaded with purpose. Every sentence serves a need, no redundancy.

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

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

Despite no output schema, description explains return fields and error behaviors. Covers all edge cases, prerequisites, and workflow integration. Complete for a 2-parameter 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 already provides 100% coverage. Description adds concrete examples of supplier_id values and explains the effect of verbose_hints parameter, adding value beyond 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?

The description clearly states 'List all fabrics a specific supplier can provide, with quoted prices' and distinguishes from siblings like search_fabrics, get_fabric_suppliers, and get_fabric_detail with explicit avoid guidance.

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 exhaustive when-to-use examples (USE WHEN), prerequisites (MUST have supplier_id), workflow steps, and explicit avoid instructions. Leaves no ambiguity about when to call this vs alternatives.

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?

Discloses ranking logic (own_factory > quality_score > capacity), source (MRC Data), and includes an extensive error and self-correction section. Annotations already indicate safe read-only behavior; description adds significant behavioral context beyond that.

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

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

Well-structured with clear sections and front-loaded purpose. Slightly verbose but each section provides necessary guidance. Could be tightened, but overall 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?

Comprehensive: covers input, differences from siblings, return format, error handling, and self-correction. Despite no output schema, the description provides sufficient context for correct use.

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%, but the description adds value by showing how to map user requests to parameter values via examples and explaining limit behavior (request max once then slice).

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 clearly states the tool's purpose: recommending suppliers based on sourcing requirements. It distinguishes from sibling tools like search_suppliers and find_alternatives by explaining differences in approach and input.

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 lists when to use (e.g., 'User describes what they need', specific example queries) and when not to use (exact filtering, repeated calls for different limits). Provides workflow and chaining options.

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=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: pagination, rate limit handling (wait 60s on 429), self-correction strategy for empty results, and return format. No contradictions.

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 lengthy but well-organized into sections (usage, examples, errors, workflow). It is front-loaded with purpose. Some repetition (e.g., Chinese translation) could be trimmed, but overall structure supports clarity.

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

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

Given the 7 parameters, no required fields, and no output schema, the description thoroughly covers use cases, workflow, error handling, data source, and return fields. It provides all necessary context for correct tool invocation.

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

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

Schema coverage is 100%, baseline 3. The description adds usage examples for each parameter, synonyms for specialization, and guidance on broadening filters. This provides practical context 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?

The description clearly states the tool searches for Chinese apparel industrial clusters and textile markets. It provides specific example queries and distinguishes from sibling tools like compare_clusters and 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 description explicitly lists when to use (e.g., user asks about cluster locations or comparisons) and when not to (e.g., not for specific factory search). It also outlines the workflow and warns against redundant calls.

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 beyond annotations by detailing error self-correction steps, rate limit handling (wait 60 seconds), return structure (summaries only), and constraints. This provides full 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?

Well-organized into labeled sections (USE WHEN, WORKFLOW, EXAMPLES, etc.) with the first sentence capturing purpose. Slightly verbose due to duplicate Chinese translation at end, but earns its length with actionable guidance.

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

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

No output schema, but description details return fields and structure via JSON example. Covers error handling, self-correction, rate limiting, and constraints. Complete for a tool with 9 parameters and many siblings.

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?

Input schema has 100% description coverage, so baseline is 3. The description adds value through concrete usage examples but does not provide additional per-parameter semantic 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?

The description clearly states 'Search the Chinese fabric and textile database' and provides extensive usage examples. It distinguishes itself from sibling tools like get_fabric_detail and get_fabric_suppliers in the AVOID section and workflow.

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?

Includes a 'USE WHEN' list of example user queries, a 'WORKFLOW' section positioning it as the primary entry point, and an 'AVOID' section explicitly listing when not to use it, directing to alternatives.

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?

Adds significant behavioral context beyond annotations: return structure (has_more, available_dimensions), rate limit handling, empty data self-correction, typo normalization. Annotations already indicate read-only and idempotent; description is consistent.

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

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

Well-structured with clear sections (USE WHEN, WORKFLOW, RETURNS, EXAMPLES, ERRORS). Perhaps slightly long, but every section is relevant and front-loaded. Slightly above average.

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?

Complete coverage given complexity: 12 parameters, returns field structure described, workflow with siblings, error handling, Chinese language queries, and even typo map. No output schema but description compensates.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter meaning through detailed examples and error handling (e.g., how to adjust when empty), adding value beyond the schema descriptions.

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 clearly identifies the tool as searching verified Chinese apparel suppliers with specific verb and resource. It lists numerous user queries and explicitly distinguishes from siblings like recommend_suppliers and compare_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?

Provides extensive guidance including when to use, workflow sequence, explicit 'AVOID' instructions (e.g., not to loop, use get_province_distribution first), and alternatives (recommend_suppliers for ranked). Includes error handling and self-correction steps.

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