年の範囲・流れ・品目で、相手の国を数量か金額の大きい順に並べる。1 つあたりの平均の値段（円）も付ける。
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | quantity＝数量の順・value＝金額の順（省くと quantity） | |
| hs | Yes | 品目の番号。例：8903（船の合計）・890332（モーターボート 7.5〜24m）・890322（セールボート 7.5〜24m）・840721（船外機）・8902（漁船）。一覧は list_codes | |
| flow | Yes | import＝日本の輸入・export＝日本の輸出 | |
| limit | No | 何か国まで（省くと 10） | |
| year_to | No | 年（2011〜2025） | |
| year_from | No | 年（2011〜2025） |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It does usefully disclose a derived output (per-unit average price in yen) and the descending sort, which are not in the schema. But it omits the default count (10, per schema) and max (50), and says nothing about whether results are single-year or aggregated across the year range.
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 compact sentences with the scope stated first and the extra output (average unit price) appended. No filler, though it is arguably terse enough to leave gaps rather than dense.
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 six parameters, no annotations and no output schema, the description should explain what comes back. It mentions country ranking plus average unit price but leaves unclear whether year_from/year_to produce a single aggregated ranking or per-year rows, and does not cover the limit parameter.
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 every parameter has an enum or example-rich description, so the baseline is 3. The description restates the same scope dimensions (year range, flow, HS) without adding syntax, defaults or format detail 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 states a specific operation: rank partner countries in descending order of quantity or value, scoped by year range, flow and HS code. That is more precise than the bare name, but it never names the sibling it differs from (get_trade, yearly_series), so an agent must infer the distinction.
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 only implied by the stated scope: an agent can guess this is for 'top N partners' style questions. There is no explicit when-to-use, no exclusion against get_trade or yearly_series, and no mention of when to prefer quantity ranking over value ranking beyond the schema's enum.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.