Japan Business Tools

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower. The description adds genuinely non-obvious behavioral rules not present in structured fields: the start date is not counted, and the counting respects holidays, with the Friday/Monday example making the semantics concrete. It does not discuss calendar variants or limits, which the schema covers instead.

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 core operation and backed by one illustrative example; no filler. The bilingual duplication is intentional for a JA/EN tool, so it does not count against conciseness, though it doubles the surface text.

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 return-value burden and does so ('return the date'), plus it explains the counting convention. It stops short of explaining how extra_holidays/extra_business_days interact with the calendar, leaving that to the schema, which is acceptable at 100% coverage.

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's only parameter-relevant content (negative N means before, holidays matter) restates what the schema already says for 'days' and the calendar fields, adding little 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?

States a specific verb and resource ('Return the date that is N business days after/before the given date') and includes a concrete Friday-to-Monday example. It implicitly separates itself from siblings like adjust_to_business_day and count_business_days by describing an offset operation, though it never names or explicitly contrasts them.

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 semantics imply when this tool applies (offsetting a date by N business days), but there is no explicit when-to-use/when-not guidance or mention of the alternative siblings such as adjust_to_business_day or count_business_days. Usage must be inferred from the operation described.

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 openWorldHint=false, so the safety profile is covered. The description adds the key behavioral rule: unchanged when already a business day, shifted by direction otherwise, plus the default-to-next behavior. It doesn't state the return format (a date string) or what happens at range boundaries.

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 parallel sentences (EN/JA) that are front-loaded with the core rule and free of filler. The bilingual duplication roughly doubles length but is a deliberate convention here, not padding.

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 single-value transform with a fully documented 5-parameter schema, this covers the decision logic and the intended use case. Gaps are minor: no statement of the returned value type or behavior when no business day is found within the extra-* constraints.

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 enum parameters (calendar, direction) are already fully documented in the schema, including the bank-holiday distinction. The description only restates 'next'/'previous' semantics, adding little 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?

States a specific verb+resource ('adjust a date to a business day') and spells out the two directional behaviors. It is distinguishable from add_business_days (offset) and check_business_day (predicate), though it never names those siblings explicitly.

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 a concrete use context ('payment due dates that fall on holidays') and implicitly defines the scenario via the business-day/non-business-day branch. It stops short of explicitly excluding or routing to sibling 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/closed-world, so the bar is lower, yet the description adds real behavioral detail absent from structured fields: reason is Japanese text, reason_code values, null on business days, and the meaning of the estimated/unverified flags. Only the estimate-year threshold behavior is left slightly implicit.

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 core purpose and reason codes; the bilingual duplication roughly doubles the length without adding new information, but the content itself is dense and free of 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?

With no output schema, the description correctly compensates by documenting the returned fields (reason, reason_code values, flags). For a read-only single-date predicate this is close to complete; only explicit sibling routing and the estimate-year boundary are 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 description coverage is 100%, so the schema already documents date, calendar, extra_holidays, and extra_business_days, including the enum semantics of standard vs bank. The description restates the bank-closure and custom-holiday concepts but adds no format or precedence information beyond the schema, so the 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?

Starts with a specific verb+resource: 'Check whether a date is a business day in Japan, and if not, why.' It even enumerates the possible reasons (weekend, holiday name, bank closure, custom closed day), which cleanly separates it from siblings like adjust_to_business_day and count_business_days.

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 usage is implied by the description (a predicate-style lookup for a single date), but there is no explicit when-to-use/when-not or pointer to the sibling tools that modify or enumerate business days. An agent must infer the boundary itself.

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 (readOnlyHint, idempotentHint, openWorldHint=false), but the description adds real behavioral detail beyond them: inclusive endpoints, a defined degenerate case ('Returns 0 if start is after end'), and a hard limit of 3,660 days. It does not explain how the calendar/override parameters interact, which keeps it below a 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 lead sentence front-loads the core operation and the second and third sentences cover the two edge cases efficiently. It loses a point only because the full text is duplicated verbatim in Japanese, doubling length without adding information for a single-language 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?

For a 5-parameter tool with 100% schema coverage and no output schema, the description supplies the key semantics an agent needs: what is counted, inclusive boundaries, the degenerate result, and the maximum span. The interaction between calendar and the two override arrays is left entirely to the schema, which is a minor gap given full coverage.

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 start, end, calendar, extra_holidays, and extra_business_days with format and enum semantics. The description adds nothing parameter-specific beyond restating the start/end relationship, so the 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 states a specific verb and resource ('Count business days from start to end') plus a scope qualifier ('inclusive of both ends'), which lets an agent distinguish it from siblings like add_business_days and check_business_day. It does not, however, explicitly name or contrast those siblings.

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 implied by the verb 'count' within a date range, and boundary behavior is stated, but the description never says when to prefer this over adjust_to_business_day, check_business_day, or list_holidays. No exclusions or alternative-selection criteria 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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantive behavior: how out-of-era dates are handled (still counted, within_era=false, outside_era flag) and weekday validation (weekday_matches=false, weekday_mismatch). It does not describe error behavior for unparseable input, which is the main remaining 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?

The core conversion and output-format facts are front-loaded in the first sentence, and the edge cases are ordered logically. The bilingual duplication restates the same content in Japanese, which is reasonable for a Japanese-date tool but costs some density.

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 explaining returns and does so via within_era, weekday_matches, and the flags object. Minor omissions remain (invalid input handling, era range limits), but an agent has enough to call and interpret it 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% for the single wareki parameter, so baseline is 3, but the description adds genuinely new semantics: kanji numerals, weekday suffixes, full-width characters, and formats like H31/4/30 and Reiwa 8.10.7 are not enumerated in the schema. This meaningfully expands what the agent knows it can pass.

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+resource (convert Japanese era date to Gregorian) and gives the output format YYYY-MM-DD. It is clearly the inverse of the sibling to_japanese_era, so an agent can route between them 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?

Conveys the context well by enumerating many accepted input shapes and the out-of-era conversion behavior, which implicitly tells the agent when this tool applies. It never explicitly names to_japanese_era as the alternative for the reverse direction, so it stops short of a 5.

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, and openWorldHint=false, so safety is covered. The description adds nothing beyond them: it does not state the return format (presumably YYYY-MM-DD), nor that the 'calendar' and extra holiday/business-day parameters change the computed result.

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 short sentences, purpose front-loaded, but the English sentence is simply duplicated in Japanese with no added information, and the whole entry is terse to the point of under-specification.

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 5 parameters, two calendar modes, and custom holiday overrides but no output schema, the description should at least characterize the returned value and how the holiday options affect it. It omits both, leaving the agent to infer the result format entirely.

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%, including detailed enum semantics for 'calendar' and patterns for the date arrays, so the schema carries the full parameter burden. The description adds no parameter meaning beyond it, which is the baseline 3 case.

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: returns the last business day of a given month. An agent understands the output immediately. However, it does not distinguish itself from closely related siblings like adjust_to_business_day or check_business_day, which also reason about business days.

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?

No guidance on when to choose this over adjust_to_business_day, check_business_day, or count_business_days, and no mention of prerequisites. The usage context is implied by the name alone.

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 read-only/idempotent/closed-world profile, and the description adds real value on top: the data provenance (Cabinet Office CSV), the inclusion of substitute holidays and citizens' holidays, and the distinction between the two returned name fields. It does not discuss limits or edge cases like years outside the supported 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?

Purpose and scope are front-loaded in the first sentence, with field semantics following. The bilingual duplication doubles the length, but each half is tight and no sentence is wasted.

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 usefully explains the two result fields (name, official_name), which an agent would otherwise have to guess. It still leaves the date representation of each holiday unstated, a minor gap for a simple read tool whose annotations already cover safety.

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 `year` parameter already documents its 1980-2099 bounds in the schema. The description's 'for a year' adds no format or syntax detail beyond that, so the schema is doing 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?

The description names a specific verb and resource ('List all Japanese national holidays and substitute holidays for a year') and even grounds it in the National Holidays Act and Cabinet Office CSV. It is unambiguous against the business-day and postal-code siblings, though it never explicitly names or contrasts an alternative tool.

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: an agent can infer this is the tool for retrieving a year's holiday calendar, but there is no statement of when to prefer it over check_business_day or adjust_to_business_day, and no exclusions or prerequisites 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?

With annotations already covering readOnly/idempotent/closed-world, the description adds real behavioral context: the data source (NTA monthly bulk data), check-digit pre-validation that reports a wrong first digit as an input error, and decoded flag semantics (`closed`, `excluded_from_search`, `not_found`) including the instruction to tell the user about closure. This is well beyond what the annotations provide.

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 front-loaded and dense with no filler, leading with the input, then the returned fields, then validation behavior, then flags. The full Japanese mirror doubles the length, which is defensible for a bilingual audience but is redundant text 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?

With no output schema, the description carries the return-value burden and does so by enumerating every returned field plus the flag vocabulary. Combined with the validation and exclusion notes, an agent has everything needed to call it and interpret 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% for the single parameter, so the baseline is 3. The description adds meaning the schema does not: the first digit is a check digit that is verified and surfaces as an input error rather than a not-found result, which materially affects how the agent interprets a failure.

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 (look up a 13-digit Japanese corporate number) and immediately enumerates the returned fields. It also distinguishes itself from two adjacent concepts: the sibling search_corporation_by_name (name-based) and the invoice/qualified-invoice-issuer registry, which it explicitly rules out.

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 negative exclusion ('this is not the invoice registry') and the input type ('13-digit corporate number') make the use case clear: call this when you already hold a corporate number. It stops short of explicitly naming search_corporation_by_name as the alternative for name-based lookups, so the routing guidance is implied rather than spelled out.

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 read-only, idempotent, and closed-world behavior, so the description is free to add richer call semantics. It discloses that one code can return multiple towns, explains the town_detail field's parenthesized content, and states that business-specific or PO box codes return offices – all valuable behavioral context beyond the structured metadata.

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 front-loaded and efficient, covering purpose, input formats, multi-result behavior, and special-case output fields in a few sentences. The bilingual duplication adds length, but given the tool's bilingual title it is purposeful rather than purely redundant.

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 single-parameter lookup with no output schema, the description explains the main return components (prefecture, city, town, town_detail, offices) and the key edge cases. It could be more explicit about the overall response shape or error behavior, but it is largely complete for an agent to invoke 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?

The input schema already documents the single postal_code parameter with hyphen-optional guidance, so the baseline would be 3. The description adds concrete accepted forms (1000001, 100-0001, 〒100-0001), which extends the schema's meaning with useful input flexibility.

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: looking up a Japanese address from a 7-digit postal code, using Japan Post data. It clearly defines the operation, but it does not differentiate this tool from its sibling search_postal_code, leaving the agent to infer which one to use.

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 implied: use when you have a postal code and need the corresponding address. However, there is no explicit when-not guidance and no mention of the sibling search_postal_code as an alternative, so the agent must infer the boundary from context rather than the description.

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 cover safety (readOnly, idempotent, closed-world), and the description adds substantial context beyond them: which input variants it absorbs (full/half-width, spacing, kanji vs. arabic numerals, ヶ/ケ, omitted county names), that it does not verify block numbers and returns no coordinates, the meaning of `level` 0-3, nullability below level 2, and the `partial`/`ambiguous` flags.

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?

Purpose is front-loaded, followed by behavior, level semantics, then flags in a logical order. The bilingual English/Japanese rendering roughly doubles the length, and the Japanese portion drops some details (flags, city_candidates note), so there is mild redundancy rather than pure 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, the description correctly carries the burden of explaining return values: `level`, `city_candidates`, `postal_codes`, `address`, `municipality_code`, and the flags. For a single-parameter tool, an agent has everything needed to call and interpret it.

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 there is only one parameter, so the baseline is 3. The description adds genuine input semantics beyond the schema example by explaining the tolerated input variation (full/half-width, spacing, numeral styles) and the prefecture-fill behavior, which helps the agent format input.

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 ('Split a Japanese address into prefecture, city, town and the rest') and defines the exact scope ('to town level'). The tool is clearly distinguishable from siblings like lookup_postal_code by its parsing/decomposition behavior, and it explicitly declares its boundaries ('Does NOT verify block/house numbers and has no coordinates').

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 implied rather than stated: the agent learns it handles messy/omitted address forms and should ask the user or show all candidates when `ambiguous`. However, it never says when to prefer this over lookup_postal_code or search_postal_code, so alternative selection is left 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 (readOnly, idempotent, not open-world), and the description goes well beyond them: legal-form words ignored at either end, full/half-width and space normalization, the truncated/exact_match_only/not_found flags, the 100-result cap with total/returned/truncated, and is_closed semantics. This is the kind of behavioral detail an agent needs to interpret results.

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-loads the core semantics and constraints, and every sentence carries information. It is dense with flags, normalization rules and return-shape details, and the full English/Japanese duplication doubles the length, but for a tool with this many quirks the size is justified.

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 exists, yet the description enumerates the returned fields, the flag values that signal edge cases, and the result cap. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call and interpret this 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%, so baseline is 3. The description nevertheless adds real meaning: it explains that the name parameter is a prefix (not substring) and that legal-form words and width/spacing differences are normalized away, which the schema's terse 'Beginning of the corporate name' does not convey.

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+resource ('Find Japanese corporations whose name starts with the given text') plus the data source (NTA monthly bulk data). It clearly distinguishes itself from lookup_corporate_number, which it names as the detail-fetching counterpart.

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 supported mode (prefix match), unsupported modes ('Matching in the middle of a name and furigana search are not supported'), and routes the agent to lookup_corporate_number for details. Also notes that NTA-excluded corporations are absent, which tells the agent what it should NOT expect.

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/closed-world, and the description adds value beyond them: a hard cap of up to 100 matches, the Japan Post data source, and partial-match semantics for town and office_name. It does not explain behavior when 100 matches are exceeded (truncation vs paging).

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 primary lookup, then the office_name branch and the result limit. The bilingual duplication roughly doubles length, but it is purposeful for a Japanese-jurisdiction tool and each sentence carries information.

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 supplies the key return detail (up to 100 matches) and the input-format rules an agent needs. The remaining gap is routing versus the similar lookup_postal_code sibling.

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, and the description adds real meaning on top: city must be the full municipality name, the county name may be omitted, and office_name reinterprets the query as business-name matching rather than town matching.

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+resource (find Japanese postal codes) and scopes the search keys (prefecture, city, town). It is clearly about forward lookup, but it never distinguishes itself from the sibling lookup_postal_code, which appears to be the closest alternative, so it falls short of 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?

Gives concrete conditions: city required, town optional, and office_name switches to business-specific (大口事業所個別番号) lookup by name. It does not say when to prefer this over lookup_postal_code or normalize_address, so no explicit exclusion/alternative routing.

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 annotations already establish this as a read-only, idempotent, closed-world operation. The description goes much further, disclosing the supported date range, all era boundary dates, the 元年 convention for year 1, the zero-padded output format, and the assumes_current_era flag for future dates. This is rich 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?

The description is front-loaded with the conversion and an example, then packs in constraints and flags efficiently. It is somewhat longer than necessary because the Japanese translation duplicates much of the English content, but every English sentence contributes useful information.

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 one simple parameter, no output schema, and rich annotations, the description is complete. It explains what the tool returns through format examples, covers valid date range, era mapping, edge cases, and the future-date flag, leaving no material gap 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 schema has 100% description coverage for the single date parameter, but the description adds meaningful semantic constraints beyond the regex pattern, notably that supported dates begin at 1873-01-01 and that dates after today may carry era-change uncertainty. It also clarifies the expected Gregorian format with a concrete example.

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 precise verb and resource: converting a Gregorian date to the Japanese era calendar. It distinguishes itself from the inverse tool by explicitly naming the input and output direction (2026-10-07 → 令和8年10月7日), and the output format examples make the purpose unambiguous.

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 useful domain constraints such as the supported range starting 1873-01-01 and the future-date caveat via assumes_current_era, but it never explicitly says when to choose this over from_japanese_era or other date tools. Usage is implied by the tool's conversion purpose rather than stated.

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