China Trade & Market Data

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: return fields, pagination and limits, snapshot semantics ('not a historical-version selector'), empty-array behavior on no match, and argument-error on invalid input. This goes well beyond the structured annotations and is not contradicted.

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 moderately long but well-structured, front-loading the core purpose and then covering inputs, returns, limitations, required fields, and errors in logical order. Each sentence adds information; there is little redundancy, though it could be tightened by merging the required-fields sentence into the input sentence.

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 no annotations for return structure, the description does a good job of covering return fields, pagination, snapshot behavior, edge cases, and required inputs. It lacks explicit guidance on when to use sibling tools, which is a minor gap given the complexity, but the tool's scope is clearly bounded.

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 repeats required fields and briefly mentions aliases, but it does not add significant parameter-level meaning beyond what the schema already documents (e.g., commodity matching behavior is described in the schema as 'Recorded major-commodity name or a selected exact Chinese alias'). The limitation on fuzzy translation is more behavioral than parameter-semantic.

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 ('Query') and resource ('China import or export observations'), scoped by 'recorded major-commodity label.' It clearly distinguishes itself from translation/HS-code tools and implicitly differentiates from siblings focused on country trade, investment, or MOFCOM stats.

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 states when to use the tool (for exact commodity labels with optional metric) and explicitly what it does NOT do ('not general translation or HS-code classification', 'No category merging or conversion'). However, it does not name any sibling tools or provide explicit conditions for choosing between them, relying on implicit differentiation from the resource 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 mark it read-only/idempotent, and the description adds useful behavioral detail beyond that: the returned fields (units, scope, source_class, provenance, snapshot, pagination, limits), empty data array on no match, and argument errors on invalid input. This gives an agent a clear model of what happens when the tool is called.

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 dense but every sentence earns its place: purpose, input orientation, semantics, return contents, exclusions, edge cases, and error behavior. The main action and scope are front-loaded before the parameter details.

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 six parameters, annotations, and no output schema, the description covers the essential operational contract: required inputs, optional flow, return fields, no-match behavior, invalid-input behavior, and limitations. Combined with the schema's detailed parameter documentation, nothing critical is missing 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the flow enum in plain terms (IMPORT/EXPORT/BOTH), clarifying that TOTAL means all partners, and noting that units are currently 1000USD. This is modest but real added value.

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: 'Query China merchandise trade by partner country/region', and immediately clarifies the special 'TOTAL' aggregate. It also draws a clear boundary from the commodity-level sibling by saying 'No commodity filter', so an agent can tell this tool apart from get_customs_commodity_trade.

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 gives clear context for use (period + country + optional flow), names the required inputs, and states exclusions ('No commodity filter or currency conversion'). However, it does not explicitly name an alternative tool for commodity-level queries or otherwise say 'use X instead', so it stops just short of full when/when-not/alternative 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?

Beyond the read-only and idempotent annotations, the description discloses several behavioral traits: no inference or aggregation, snapshot-limited coverage, empty data array on no match, and argument errors on missing/invalid input. These are substantive and not present in 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 compact and front-loaded with purpose, then inputs, return format, and behavioral notes. Each sentence is informative, though the final sentences covering required input and errors could be merged for slightly better economy.

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?

Since there is no output schema, the description compensates by naming return record fields (source_class, provenance, snapshot, pagination, limits) and the empty-array behavior. Combined with the detailed schema, an agent has enough to invoke the tool correctly, though the meaning of each return field is only summarized.

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 a high-level mention of year, country, and metric and notes that year is required, but it omits limit, offset, and snapshot from its summary. The schema already fully documents each parameter, so the description contributes little beyond the baseline.

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

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

The description uses a specific verb ('Find') and a clear resource ('foreign-investment observations') plus filter dimensions (statistical year, country, measure). It states the core action unambiguously, but it does not explicitly differentiate this tool from sibling tools by name.

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

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

The description implies usage context by stating 'Recorded facts only; this query performs no new inference or aggregation' and 'Coverage is limited to the available snapshot', which suggests when raw recorded facts are needed. However, it never names an alternative tool or gives explicit when-to-use / 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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful context by stating that the tool takes no arguments and returns only the standard document, not records or facts, but it does not describe the document's structure or any pagination/format 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?

Two sentences with no wasted words. The core purpose is front-loaded, and the clarifying exclusions ('not business records or an assessment of facts') are valuable for agent decision-making.

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 zero-parameter, read-only, idempotent tool, the description is complete enough. It tells an agent what the tool returns, what it does not return, and that no arguments are needed. The lack of an output schema is offset by the clear high-level description of the document.

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?

There are zero parameters, and the description explicitly confirms 'Takes no arguments,' so there is no ambiguity about invocation. Baseline for zero-parameter tools is 4, and the description removes any doubt about whether arguments are needed.

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

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

States a specific verb ('Retrieve') and a clear resource ('definitions of information formation classes, provenance fields and snapshot/version metadata'), and further clarifies that it returns the information-standard document rather than business records or factual assessments. It is clear on its own, though it does not explicitly differentiate itself from likely-related siblings such as get_standard_metadata.

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

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

The description implies its use case: call this tool when you need the standard definitions/metadata document, and it explicitly says it does not return business records or factual assessments. However, it does not name alternatives or explain when to prefer this over sibling tools like get_standard_metadata or search_standard_metadata.

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 goes beyond the annotations by detailing the return payload (units, scope, source_class, provenance, snapshot, pagination, limits), stating that no conversion/aggregation/cross-period calculation occurs, and describing behavior on no match (empty array) and errors. This adds significant behavioral context beyond the readOnly and idempotent hints.

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 concise and front-loaded with the primary purpose, followed by inputs, exclusions, return behavior, and error handling. Each sentence serves a clear function, and there is no redundancy or filler. It is appropriately sized for a query tool with several parameters.

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 there is no output schema, the description compensates by specifying return fields and pagination limits, and clarifies error and no-match behavior. It also explains the required period and the distinction between periods and snapshots. The description is largely complete for an agent to use the tool correctly, though it could benefit from a brief mention of how it differs from the sibling trade tools.

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 all parameters are already described in the schema. The description only mentions 'period and optional country, flow and metric' without adding new semantic detail; it does note that periods are not interchangeable, which is also present in the schema. The description adds little beyond the schema for parameter understanding.

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 queries trade observations from two distinct collections (country-workbook and China–Portuguese-speaking-country bilateral), and explicitly notes it is not China national all-partner monthly totals. It names the verb 'Query' and the resource 'trade observations', but does not explicitly differentiate from sibling tools like get_customs_country_trade, which also handle trade data.

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 context on what data is included (country-workbook and bilateral observations) and excludes China national monthly totals, but it does not offer explicit guidance on when to use this tool versus the sibling tools. The exclusion hints at scope but no alternatives are named or conditions given for switching.

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