Japan Business Tools

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the start date is not counted, and weekends/holidays are skipped (with the bank-calendar nuance living in the schema). It does not describe output format, but for a pure computation the added rules are substantive.

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 operation before the worked example. It is slightly inflated by full bilingual duplication, but no sentence is wasted and the counting rule is the right thing to lead with.

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, but the description states what is returned (the resulting date) and the counting convention, while the schema fully covers the holiday/calendar inputs. Complete enough to call correctly, with only minor gaps around edge cases like out-of-range N.

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 every parameter (including calendar, extra_holidays, extra_business_days) is documented bilingually in the schema. The description only restates the negative-days convention, adding no syntax or format detail 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?

States a specific verb (return the date) plus the operation (N business days after/before), and the Friday-to-Monday example makes the shift semantics unambiguous versus siblings like count_business_days or check_business_day. An agent can distinguish this offset-return tool from the counting/checking siblings without opening any 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?

Usage is implied by the semantics (compute a date offset by N business days), and the negative-N rule is stated, but there is no explicit when-to-use versus adjust_to_business_day or check_business_day, nor any exclusions or prerequisites. Adequate but leaves routing 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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds behavioral context the annotations cannot: the identity/no-op outcome when the date is already a business day, and the next/previous shift semantics.

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 rule is front-loaded in the first clause, followed by the use case. Content is duplicated across English and Japanese, which doubles length, but each sentence still 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?

With no output schema, the description carries the return-value burden and does so adequately by explaining what date is returned for both branches. Given rich schema coverage and annotations, nothing critical for invoking the tool 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 description coverage is 100%, so all five parameters (including calendar, extra_holidays, extra_business_days) are already documented in the schema. The description only echoes the direction values, adding no syntax or format detail beyond what the schema provides, so the baseline of 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?

States a specific verb+resource ('adjust a date to a business day') and precisely defines the transformation rule including the no-op case. An agent can distinguish it from siblings like check_business_day (which only tests) or add_business_days (which shifts by N).

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 case ('payment due dates that fall on holidays') and explains the two direction modes. It does not explicitly name when to prefer check_business_day or add_business_days instead, but the context needed to select it is clear.

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 safety is covered. The description adds real behavioral value by disclosing that the response explains the reason for closure (weekend, named holiday, bank closure, custom closed day), which goes beyond what the annotations state. It stops short of describing the exact response shape or precedence when a date qualifies under multiple reasons.

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?

A single front-loaded sentence that states the action and the returned reasons, with zero filler. The bilingual duplication doubles the surface length, but that appears to be an environment convention rather than 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 read-only, idempotent boolean-style check with a fully documented 4-parameter schema and no output schema, the agent has enough to call it correctly and knows what a negative result conveys. Only the concrete return structure (flag plus reason field names) is left unspecified.

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 the calendar enum and both extra_holidays/extra_business_days arrays fully documented inline, so the description carries no additional parameter burden. It doesn't add syntax or precedence detail (e.g., what happens if a date appears in both extra lists), leaving this at the baseline for a fully documented 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 (check) and resource (a date's business-day status) scoped to Japan, and even enumerates the possible negative results (weekend, holiday name, bank closure, custom closed day). This clearly separates it from siblings like count_business_days, add_business_days, and last_business_day_of_month, which perform arithmetic rather than a boolean check.

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: an agent can infer this is the tool for 'is date X a business day?' but the description never says when to prefer it over adjust_to_business_day or how it relates to list_holidays. No explicit when-to-use, when-not, or alternative routing is provided.

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), so the bar is lower, and the description adds real behavioral detail: both endpoints are counted, a reversed range returns 0, and the maximum supported span is 3,660 days. It stops short of saying what happens (error vs. clipping) when that limit is exceeded.

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 (in each language) with zero padding; the core behavior, the reverse-range rule, and the size limit are all front-loaded and easy to scan.

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 reasonably implies the return value is a day count and explicitly handles the degenerate reversed-range case. For a read-only counting tool this is nearly complete, though it could clarify error behavior for over-limit ranges.

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 all five parameters including the calendar enum and the extra_holidays/extra_business_days arrays are already documented in the schema. The description adds no additional meaning about parameter interactions (e.g., precedence between extra_holidays and extra_business_days), so the baseline of 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?

States a specific verb (count) and resource (business days between start and end), with inclusive-boundary scope spelled out. This is clearly distinguishable from siblings like add_business_days and check_business_day 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?

It gives useful edge-case context (start after end yields 0, max range 3,660 days / ~10 years), which implicitly tells the agent when the tool is valid. However, it never explicitly says when to choose this over check_business_day or add_business_days, leaving routing 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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond the annotations: it does not say what format the result takes, whether holidays are considered, or that the calendar parameter changes the outcome.

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?

A single, front-loaded sentence with no filler. The bilingual duplication is functional for this toolset rather than padding, though it does add length without adding 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?

For a simple computation tool with a fully documented schema, the description is minimally adequate. With no output schema, it should have stated the return format (e.g. YYYY-MM-DD) and that the result reflects the selected calendar, but it omits both.

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 the schema itself explains the standard/bank calendar distinction and the extra_holidays/extra_business_days semantics in detail. The description contributes no additional parameter meaning, so the baseline of 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?

States a specific verb ('Return') and a precisely scoped resource ('the last business day of the given month'), which is unmistakably distinct from sibling tools like count_business_days or adjust_to_business_day. It does not, however, explicitly route the agent away from any sibling, so it stops short of the top band.

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?

There is no guidance on when to prefer this over adjust_to_business_day, check_business_day, or count_business_days, nor any stated prerequisites such as whether the date is already known. Usage must be inferred entirely from the name.

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?

Annotations already cover read-only/idempotent/no-open-world, so the bar is lower; the description adds real behavioral context by warning that one code can map to several towns and that business/PO-box codes surface in `offices`. It does not say what happens for an unknown or malformed code, which is the 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?

Front-loaded with the action and input format, and each sentence carries information. The fully duplicated bilingual text doubles the length, which is a convention rather than waste, but it is not maximally tight.

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 key return fields (`town_detail`, `offices`) and the possibility of multiple results, so an agent knows what to expect. It stops short of describing error handling or result ordering.

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 a single parameter and 100% schema coverage the baseline is 3, but the description adds accepted input variants (bare 7 digits, hyphenated, and the 〒 prefix) that the schema's 'hyphen optional' does not enumerate.

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 (look up) and resource (address for a 7-digit Japanese postal code) with the exact data source (Japan Post). The exact-code input requirement implicitly separates it from the sibling search_postal_code, which would take free-text address input.

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 required input form ('accepts forms like 1000001, 100-0001 or 〒100-0001') implies when the tool applies, but the description never explicitly names search_postal_code as the alternative for the reverse or fuzzy lookup. Usage is inferable but not stated.

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), but the description adds substantial behavior beyond them: it lists the input variants it absorbs (full/half-width, spacing, kanji vs. arabic numerals, ヶ/ケ, omitted county names), the prefecture inference rule when the city is unique, and explicit limitations (no block-level verification, no coordinates). That is exactly the kind of expectation-setting an agent needs.

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: the first clause states the operation and its output before caveats. The bilingual duplication roughly doubles the length, but the Japanese text plausibly serves the target audience rather than being filler, so the cost is modest. Every clause 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?

There is no output schema, so the description must carry return semantics — it does, naming the four-part split and the postal-code candidates, and it flags the two key limitations. It could be slightly more precise about the shape/count of returned candidates, but for a single-input, single-purpose tool this is close to complete.

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 schema already supplies an example, so the baseline would be 3. The description still adds value by characterizing the input domain — a free-form Japanese address tolerant of width, spacing, numeral and orthography variants — which tells the agent it can pass raw user-typed text without pre-cleaning.

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 (split/normalize) and resource (Japanese address), and names the exact decomposition it produces (prefecture, city, town, rest) plus the postal-code candidates it returns. This is clearly distinguishable from siblings like lookup_postal_code and search_postal_code, which start from a postal code rather than a raw address.

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 the use case (you have a messy Japanese address that needs parsing) and draws a useful boundary by stating it does NOT verify block/house numbers and returns no coordinates. However, it never names an alternative or says when to prefer this over lookup_postal_code, which overlaps on the postal-code-candidate output. Usage is inferable but not guided.

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/openWorldHint=false, so the safety profile is covered. The description adds value beyond that by naming the data source (Japan Post data) and disclosing a result cap ('Returns up to 100 matches'), which the agent needs to interpret truncation. No auth, rate-limit, or ordering 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?

Front-loaded with the core purpose and the mode switch in the first two sentences, and the 100-match limit is placed where it matters. The full Japanese restatement roughly doubles the length, which is defensible for a Japanese-data tool but is pure duplication for a reader of one 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 carries the return burden and does state what comes back (postal codes, up to 100 matches). It leaves unstated whether the response includes the matched address/town and whether multiple codes per town can be returned, which matters for a partial-match search.

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, but the description adds real semantics the schema does not carry: that `office_name` does not merely filter but switches the search to business-specific codes by name, and that `city` must be the formal municipality with the county name optionally dropped.

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 Japanese postal codes by prefecture, city and (optionally) part of the town name') and clearly delineates a second mode via `office_name` for business-specific codes (大口事業所個別番号). It never names the near-identical sibling `lookup_postal_code`, so an agent cannot tell from this text which of the two postal tools to pick.

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 input preconditions ('the city must be the full municipality name, e.g. 札幌市中央区; the county name may be omitted') and explains the conditional branch that changes behavior when `office_name` is supplied. It stops short of any when-not-to-use guidance or an explicit alternative tool.

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