Japan Trade Statistics (customs data)

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

Annotations already establish that this is a safe, read-only, idempotent, closed-world tool. The description adds useful operational context beyond annotations: it is a bootstrap/catalog call, reveals keyless limits, and discloses known source-data gaps.

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 key 'call first' instruction and then lists return contents efficiently. The bilingual duplication is useful for a multilingual tool but does roughly double the surface length without adding new information per language.

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 properly describes what the catalog returns: periods, latest months, levels, routing, limits, and data gaps. It is complete enough to call correctly, though it does not describe the shape or structure of the returned catalog data.

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 input schema has 100% description coverage for the single `lang` parameter, including default behavior and enum meanings. The description adds no parameter-level details, so the schema fully carries this burden and a 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?

Uses a specific verb and enumerates the catalog contents it returns: periods, latest months, levels, tool routing, keyless limits, and source-data gaps. It is clear what the tool does, but it does not explicitly differentiate itself from the sibling `get_meta` tool, which is a likely overlap.

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 instruction 'Call this first' gives a clear ordering cue for when to use the tool before others. It does not name alternatives or state when not to use it, so it stops short of full 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 cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description only needs to add scope context. It adds that multiple metrics are returned in a single call and that results are scoped to one country, which helps an agent anticipate a multi-metric payload. It does not mention freshness or units, which is a minor residual 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?

Two sentences, front-loaded with the use case and followed by the routing alternative, with no filler. The bilingual mirroring is deliberate given the ja/en lang parameter, so duplication 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?

For a read-only, four-parameter tool with a fully documented schema, the description covers purpose, usage routing, and output scope. No output schema exists, but the metric list in the description effectively communicates the shape of the result.

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 enum and pattern constraints already documented, so baseline is 3. The description only implies the country scoping and says nothing about month, window, or lang beyond what the schema states.

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 a specific resource and enumerates exactly what the response contains (exports, imports, balance, YoY, main items) for one country. Explicitly distinguishes itself from get_partners, a named sibling, so an agent can route without opening schemas.

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?

States the when ('want the overall picture for one country in one call') and the counter-case with the alternative to pick instead ('for one item's breakdown by partner, use get_partners'). That is an explicit when/when-not/alternative pattern.

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 burden is lifted. The description adds real behavioral context by disclosing the payload's scope (hierarchy boundaries, unit, covered period) versus quantitative figures, which steers correct tool choice. It stops short of stating behavior for unknown/invalid codes or whether child listings are exhaustive.

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 substantive content is front-loaded and short, but the English half repeats the navigation clause twice ('Use this to navigate the hierarchy' / 'use this to navigate parent and child levels'), and the entire text is then duplicated in Japanese. The bilingual pairing is defensible given the lang parameter, yet the redundant clause wastes attention.

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 4-parameter read tool with no output schema, the description still sketches the return payload (hierarchy levels, unit, months covered) and routes to get_item_summary for figures. Only edge behavior (invalid code, missing level) is left unaddressed, which the schema partially covers.

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 enum descriptions for flow, lang and level, and the code parameter already points to search_items for lookup. The description adds nothing beyond the schema about how code, flow or level interact (e.g., level inference from code length is only in the schema). Baseline 3 applies when the schema does the heavy lifting.

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 resource and its returned content: 'Item details: parent and child levels, unit, and the months covered.' It also explicitly separates itself from the sibling get_item_summary ('For an item's figures, partners and growth, use get_item_summary'), so an agent can distinguish the two without opening either 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?

Gives both the when ('use this to navigate parent and child levels') and the when-not with a named alternative ('For an item's figures, partners and growth, use get_item_summary'). The routing decision is fully specified rather than implied.

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 fully covered. The description adds real value on top by disclosing the breadth of the computed output (YoY, 3-year change, growing/declining partners, concentration), which tells the agent this is an expensive aggregated read rather than a raw lookup. It does not mention response size limits or the currency/unit of the values, so it stops short of 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 English half is well front-loaded: the core purpose and the 'use first' directive are stated before the content list. The structure costs points because the entire text is duplicated in Japanese, roughly halving information density, and the long mid-sentence inventory of outputs 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 carries the burden of describing return values, and it does so thoroughly by naming every component of the payload. The remaining gap is that it never states the unit/currency of the monetary values or the approximate shape of the response (e.g., whether partners are ranked or capped), which matters for a multi-metric aggregation 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% and three of four parameters carry enums with descriptions, so the schema does the heavy lifting. The description adds nothing about parameter behavior — notably it does not clarify how `level` interacts with the code length inference or what changing `lang` affects beyond the schema's own note. 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+resource framing ("One call for an item overview") and then enumerates the exact contents returned: 12-month value with YoY and 3-year change, partners and their growth, new markets, seasonality, yearly trend, concentration, and a one-line summary. This enumeration clearly distinguishes it from the narrower siblings (get_partners, get_seasonality, get_series) by positioning it as the aggregated overview.

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 an explicit routing rule twice ("Use this first for questions about an item" / "品目について聞かれたら、まずこれを使います"), which is strong first-choice guidance. However, it never states when NOT to use it — e.g., that get_series should be used for full time series or get_partners for partner-level depth — so the agent must infer the boundary from the sibling names.

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 carry the full safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lower. The description still adds real context by spelling out the returned coverage/source metadata, though it says nothing about error behavior or response shape.

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?

Content is dense and front-loaded, with the alternative routing placed last as a clean closer. The only cost is that the entire body is duplicated in Japanese, roughly doubling length without adding information for any single reader.

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 must describe return values itself — and it does, listing every metadata field an agent would receive. Combined with the annotation coverage of side effects, nothing an agent needs to call this correctly is missing.

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 the single `lang` parameter is fully documented in the schema, including its ja default and enum. The description contributes no additional parameter meaning, so the baseline 3 is correct.

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 enumerates exactly what is returned: latest month plus per-month status for exports and imports, the latest month common to both, first data month per level (chapters/sections from 1988), and sources. That is a specific, unambiguous statement of scope, and it explicitly separates the tool from get_catalog.

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 names the alternative and the condition that selects it: 'For which tool to use and known data gaps, use get_catalog instead.' The boundary between the two tools is stated outright, leaving nothing to inference.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false, closed-world), so the bar is lower. The description earns credit by defining the actual detection logic for both categories, which the annotations cannot convey. However, it says nothing about result ordering, whether both lists are always present, or how limit applies across the two categories, and the fixed 'USD 100,000' prior-period threshold sits oddly against the min_value parameter documented as applying to 'last 12 months or the 12 before'.

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?

One front-loaded sentence that leads with the classification rule rather than preamble, plus a faithful parallel Japanese rendering. Slightly redundant in its bilingual duplication, but no filler 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?

There is no output schema, and the description gives no hint of the response shape — whether results are two separate arrays, whether volumes/growth rates are included, or how the 1-100 limit is distributed across the new and surged sets. For a tool that returns two distinct classifications, that leaves a meaningful gap.

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 every parameter including code, flow, lang, level, limit and min_value is already documented; baseline 3 applies. The description adds the key semantic that two different time windows are compared, but it introduces ambiguity by hard-coding USD 100,000 for the prior period while min_value's default of 1,000,000 is described as applying to either window.

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 precise computed resource — partners that newly appeared vs. partners that surged — with concrete quantitative rules (last 12 months at/above the minimum, prior 12 months under USD 100,000; surge ≥ 2x). That makes it clearly distinguishable from get_partners or get_ranking in substance. It never names a sibling, though, so routing is inferred rather than stated.

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: the agent can infer this is for discovering emerging trade partners, but there is no stated when-to-use, when-not-to-use, or alternative (e.g., get_partners for a full listing, get_ranking for top partners). No prerequisites or scope caveats are given.

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 that this is a read-only, idempotent, non-destructive operation. The description adds useful domain behavior by clarifying that exports return destinations, imports return origins, and results include shares over either one month or twelve months.

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 the core operation and output scope stated immediately. The bilingual repetition is reasonable for the tool's localization and does not obscure the main point.

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 analytical tool with complete parameter descriptions and no output schema, the description gives enough context to understand the operation and output dimension. It could be stronger by naming the sibling alternatives or clarifying what 'shares' means precisely.

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 all nine parameters. The description adds some semantic meaning for flow and time window, but it does not explain many other parameters such as sort, level, limit, or min_value beyond what the schema provides.

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 resource and scope: partner-country breakdown and shares for an item, with distinct export/import direction. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as get_country_summary, get_ranking, or get_series.

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 contextual signals such as one month vs. last 12 months and destinations for exports vs. origins for imports. However, it does not explicitly say when to use this tool instead of sibling tools like get_country_summary or get_ranking.

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 that this is a read-only, idempotent, non-destructive operation. Beyond that, the description adds meaningful behavioral rules: flow=both must use balance, and order=asc surfaces the largest deficits. It does not cover pagination or return-shape behavior, but the annotations lower the burden.

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 English portion is concise and front-loaded, starting with the core resource and then giving the key combination rules. The bilingual duplication doubles the length, but each version serves a distinct audience and neither contains 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 9-parameter ranking tool with no output schema, the description covers the most important semantic constraints around flow, by, order, and country. It relies on the fully documented schema for the remaining parameters, which is reasonable, though it could say more about what the ranked response contains.

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 useful cross-parameter semantics not fully captured by the schema: export/import pair with value or yoy, both pairs with balance, and country scopes the ranking to trade with one partner. It does not explain level, month, limit, or lang, but those are well documented in 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 that this returns an item ranking and immediately specifies the valid flow/by combinations, which gives the agent a concrete sense of the tool's output. It does not explicitly differentiate itself from siblings such as get_item_summary or get_partners, 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?

The description gives conditional guidance for parameter combinations (export/import with value or yoy; both with balance and order=asc). However, it does not state when to prefer this tool over sibling tools like get_item_summary, get_partners, or get_series, so usage against alternatives is only implied.

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 genuinely new behavioral context: the fixed three-year lookback window, the default top-5-partner aggregation versus single-country restriction, and the derived metrics returned (yoy range, peak/low months). It stops short of explaining the min_value filtering effect on which partners appear, or any truncation 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?

The English sentence is front-loaded and dense with the key facts — scope, metrics, and aggregation default — with no filler. The full Japanese restatement doubles the length, which is defensible for a bilingual server but is still redundant text for a single agent.

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 carries the burden of describing return values and does so concretely (monthly shares, yoy range, peak/low months, partner breakdown). Combined with the fully documented six-parameter schema, an agent has enough to call this correctly and interpret the result without further guessing.

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 description coverage the baseline is 3, and the description earns a bump by clarifying the aggregation default that the schema does not encode: without `country` the result aggregates the world plus the top 5 partners, while supplying `country` returns just that country. That is real added meaning beyond the property 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 names a specific resource (seasonality) and spells out exactly what it computes: monthly shares over the last three full years, the year-to-year range, peak and low months, for the world and the top 5 partners or a single country. This is clearly distinguishable from siblings like get_series and get_partners, which return raw series or partner lists rather than a derived seasonality profile.

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 implies when the tool is appropriate by describing the shape of the answer (three-year monthly shares, peak/trough) and notes that passing `country` narrows to one country instead of the default top-5 set. However, it never states when to prefer this over get_series or get_item_summary, nor does it mention prerequisites or exclusions, leaving the routing decision to inference.

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 substantial behavioral context beyond the read-only annotations, including data start dates by code level and the important caveat that some import chapters/sections return gap="source" because the e-Stat source table lacks data, not because there was no trade. This is valuable transparency, though it does not cover every possible operational detail.

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 content is front-loaded and each sentence carries useful information about scope, defaults, or data caveats. The bilingual duplication makes it longer than necessary in one language, but that is appropriate for a bilingual tool and does not obscure the structure.

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 an eight-parameter read-only tool with no output schema, the description is complete enough to call it correctly: it explains the core output fields, data start dates, freq/from behavior, flow=both semantics, and the special gap="source" case. Remaining parameter details are covered by the fully populated schema.

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 all parameters. The description still adds meaning beyond the schema, especially for flow=both returning exports, imports, and balance side by side, and for freq=year versus monthly behavior and the from fallback.

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 that this tool returns a monthly series for an item, including value, quantity, unit price, YoY, MoM, and preliminary/revised status. It is specific about the resource and output content, but it does not explicitly differentiate itself from sibling tools such as get_item_summary or get_country_summary.

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 usage context: use freq=year for long-term trends, set from for older months, and without from months start in January 2022. It also explains that flow=both puts exports, imports, and the balance side by side. However, it does not explicitly say when to choose this tool over sibling summary or ranking 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 adds useful behavioral context beyond the annotations: it reports issues to the operator and explicitly returns no figures. It does not contradict the annotations, which mark the tool as non-read-only, non-destructive, and non-idempotent, consistent with submitting a report.

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 short, front-loaded with the purpose, and includes the key output caveat. The bilingual duplication is compact and does not obscure the primary English statement.

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 four fully documented parameters, no output schema, and annotations covering side-effect hints, the description is largely complete. It could say more about what confirmation or response the reporter receives, but the key behavioral constraint is stated.

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 explains the code, flow, month, and message parameters in detail. The description adds no parameter-specific meaning beyond the schema 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 states a specific verb and resource: report a data problem to the operator. It gives concrete examples of issue types (differs from official figures, missing, wrong name) and distinguishes the tool from data-retrieval siblings by noting that no figures are returned.

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 clearly explains when to use the tool by describing the kinds of data problems that should be reported. It does not explicitly name alternatives or exclusions, but the reporting purpose is sufficiently distinct from the sibling retrieval 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds genuinely non-obvious domain behavior: 9-digit codes use different schemes for exports vs imports and each result's flow field must be checked. It does not describe result shape or paging, but the code-collision warning is the useful part.

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 the one-line purpose, then the usage rule, then the code caveat. The bilingual duplication doubles the length, but for a Japanese-first tool that is justified rather than waste.

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, an agent still gets the crucial interpretation note that results must be disambiguated by flow, which is the main thing that could go wrong here. Minor gap: it does not say results are a list of name/code/flow entries, so the return shape is only implied.

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 all five params carry their own descriptions, including the enum meanings, so the baseline is 3. The description only reinforces the flow parameter's significance and says nothing extra about q matching rules beyond what the schema already states.

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 ("Find items by name or code") and adds an implicit split from the lookup siblings via "Use this first when you do not know the code." It never names get_item explicitly, so the differentiation with the by-code lookup tools is inferable rather than stated.

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?

"Use this first when you do not know the code" gives a clear selection rule against the get_item/get_item_summary family. No explicit exclusion (e.g. when to skip straight to get_item) is spelled out, but the ordering guidance is actionable.

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