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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond these: pagination behavior, return structure, data source (MRC Data), rate limiting (429 wait 60s), and specific error recovery strategies. This is substantive addition, though the core safety profile is already covered by 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 lengthy but well-organized using clear section headers (USE WHEN, WORKFLOW, EXAMPLES, ERRORS, AVOID, NOTE). Every sentence adds value; there is no fluff. While not concise in length, the structure makes it easy to scan. A slightly shorter version could achieve perfection, but the current structure is appropriate for the tool's complexity.

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

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

Given 12 parameters, no output schema, and a large sibling set, the description is remarkably complete. It covers entry conditions, detailed error handling with recovery steps, pagination, parameter interactions, and integration with other tools. The 'RETURNS' block also describes the response structure despite no formal output schema, filling that gap effectively.

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

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

With 100% schema coverage, the baseline is 3. The description adds value over the schema by providing examples of parameter combinations, clarifying product_type normalization via TYPO_MAP, giving province examples in both languages, and explaining the meaning of data_confidence and compliance_status. The examples demonstrate practical parameter usage, raising the score above baseline.

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

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

The description clearly states the tool's purpose: searching verified Chinese apparel suppliers. It provides a large set of example user queries that cover various use cases, and explicitly contrasts with sibling tools like recommend_suppliers. The verb 'search' combined with specific resource 'suppliers' and context 'verified Chinese apparel' leaves no ambiguity.

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 an extensive 'USE WHEN' section with concrete user utterances, a 'WORKFLOW' section showing the primary entry point role, and an 'AVOID' section that explicitly calls out when NOT to use this tool (e.g., do not loop across provinces, use recommend_suppliers for ranked recommendations). Error handling and self-correction steps further guide appropriate usage.

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