Torify — Japan Locale APIs for AI Agents

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description explains the composite nature, optional parameter behavior, and a specific caveat about government agency responses being correct per Japanese tax law.

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 dense sentences plus a note, front-loaded with key info, no redundancy, every sentence serves a purpose (purpose, use-case, caveat).

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 two parameters, output schema exists, and external API dependencies, the description covers input format, composite behavior, optional parameter, and a critical edge case, making it fully adequate.

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 adds value by explaining the number parameter as '13-digit corporate number' and the verify_invoice parameter's effect (triggers invoice.verify) and default false, plus a behavioral note on invoice status.

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 it's a 'one-call composite' that retrieves corporate info and optional invoice registration via two NTA APIs, specifying input (13-digit corporate number) and distinguishing from separate calls to houjin.lookup and invoice.verify.

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 says 'Use when you need both corporate identity and invoice status in one step — saves an extra API call vs calling houjin.lookup + invoice.verify separately,' and adds a behavioral note about government agencies, guiding correct use.

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 that no authentication is required, specifies the API source (GSI AddressSearch), and indicates output is lat/lng. These details go beyond annotations (readOnlyHint, openWorldHint, idempotentHint) and provide useful behavioral context for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences plus a bold callout, front-loading the key action and constraints. The Japanese translation adds value without redundancy.

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 geocoding tool with an output schema (not shown), the description covers input format, API source, auth, and usage guidance comprehensively. No gaps remain.

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 already covers the single parameter 'q' with a detailed description including format example, so the description adds reinforcement but no new syntactic information. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states the tool geocodes Japanese addresses to lat/lng via a specific API, and explicitly excludes landmarks/stations. This distinguishes it from sibling tools like reverseGeocode or postal.lookup.

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 provides explicit guidance: call this for real coordinates, do not estimate from memory, and notes that only address format works. However, it does not explicitly mention when to use alternatives, leaving room for improvement.

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 provide readOnlyHint, openWorldHint, and idempotentHint. The description adds context about the external API dependency (GSI) and the output granularity (municipality code and town name). It does not disclose rate limits or error behaviors, but with annotations covering safety, this is acceptable.

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 extremely concise: two sentences plus a bold directive, with no wasted words. The main purpose is front-loaded, and the Japanese language variant provides localized clarity.

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 the presence of an output schema and strong annotations, the description covers essential aspects: external API, output fields, and usage context. It lacks details on error handling or performance, but for a reverse geocoder this is generally sufficient.

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 both 'lat' and 'lon' having descriptions including Japanese ranges (e.g., '緯度（日本領域: 20-46）'). The description adds no further meaning beyond the schema, so 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?

The description clearly states the tool's purpose: 'Reverse geocode lat/lng to municipality code and town name' via a specific API (GSI). It distinguishes itself from the sibling tool 'geo.geocode' (likely forward geocoding) by explicit action and resource.

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 bold directive 'Use to map real coordinates to an official municipality — do not infer from memory' provides clear guidance on when to use and a strong caution against inference. However, it does not explicitly mention alternatives like 'geo.geocode' for forward geocoding, leaving room for slight ambiguity.

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, openWorldHint, and idempotentHint. The description adds that the tool uses the NTA official API (external dependency) and provides authoritative data not available from model weights, enriching the behavioral context without contradiction.

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 extremely concise: two sentences plus a bold usage note. Front-loaded with action and output, then critical guidance. No redundancy or 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 single-parameter lookup tool with full schema coverage, annotations, and an output schema, the description fully covers the purpose, source, and usage context. It explains the output fields and warns about model weight limitations, making it 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% with a Japanese description of the number parameter. The tool description adds the English equivalent ('13 digits') and reinforces the format, providing extra clarity for bilingual users beyond the schema alone.

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?

Description clearly states the tool looks up a Japanese corporate number (13 digits) and returns company name, address, kind, and status via the official NTA API. It distinguishes itself from siblings like company.fullProfile by focusing specifically on corporate number lookups.

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 explicitly says 'Call this for authoritative company info' and warns that corporate registry data cannot be recalled from model weights, providing clear when-to-use guidance. It does not explicitly mention alternatives but the purpose is sufficiently distinct.

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 indicate read-only, idempotent, and open-world behavior. The description adds valuable context: it combines two government APIs, returns combined results, and notes that registered=false is expected under Japanese tax law. This goes beyond what annotations provide and helps set agent expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a clear English purpose statement, a Japanese version for native speakers, a usage trigger sentence, and a behavioral note. Every sentence serves a purpose. No unnecessary words.

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 annotations covering safety and idempotency, and an output schema (not shown but exists), the description provides sufficient context: it explains the composite nature, the expected input format, the combined output (invoice + corporate), and a domain-specific nuance about government responses. No gaps.

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 one parameter with full description coverage (100%), including format and example in Japanese. The description repeats the format (T+13 digits) but does not add new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate given high schema coverage.

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 identifies the tool as a one-call composite that returns both invoice registration status and corporate details from a T-number. It uses specific language ('T-number (T + 13 digits)', 'invoice registration status', 'corporate details') and distinguishes itself from siblings like invoice.validate or houjin.lookup by being a combined call.

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 explicitly states when to use the tool: when an AI agent receives a T-number and needs to validate both invoice compliance and company identity in one step. It also provides a caveat about government agencies returning registered=false. While it doesn't explicitly mention when not to use or alternatives, the context is clear and actionable.

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 and idempotentHint=true, indicating safe, read-only operation. Description adds crucial context that validation is offline and does not confirm registry existence, enhancing transparency 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?

Two concise sentences plus a bolded caveat. Every sentence is purposeful—states function, format, limit, and alternative. Front-loaded with key info, no 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?

For a simple validation tool with 1 parameter and output schema (implied), description covers what the tool does, its limitation, and when to use sibling. No gaps remain.

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 has 100% coverage with description of parameter 'number' (example provided). Description adds value by specifying format 'T + 13 digits' and mentioning check-digit validation, which is not in schema description. Baseline is 3, but the added context justifies a 4.

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?

Description clearly states it validates Japanese qualified invoice number format and check digit, specifying 'T + 13 digits'. It distinguishes from sibling tool invoice.verify by noting it does NOT confirm existence in NTA registry, so purpose is highly specific and 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?

Explicitly states when to use (offline format/check-digit validation) and when not to use (for real registration, use invoice.verify). Provides clear alternative, enabling correct tool selection.

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?

Adds context beyond annotations: requires INVOICE_APP_ID (with application instructions), notes that registration status cannot be known from model weights and changes daily, and specifies return fields. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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?

Well-structured with all necessary information: purpose, returns, prerequisite, critical usage warning, and sibling differentiation. The Japanese sentence adds value for bilingual contexts but could be considered slightly verbose, still earning a high score.

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?

Covers all necessary aspects: purpose, prerequisite (INVOICE_APP_ID), return fields, usage urgency, and differentiation from sibling. With an output schema present (implied by 'returns'), the description is fully 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?

Only one parameter (number) with 100% schema description. The description adds an example format and context, but doesn't provide additional semantic meaning beyond what the schema already offers. 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?

The description clearly states it verifies invoice number registration against the NTA public registry API and returns specific fields (registrant name, address, registration date). It also distinguishes itself from sibling invoice.validate by noting 'For offline format checks only, use invoice.validate.'

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 'Always call this before trusting any Japanese invoice number' and explains why (registration status changes daily). Also provides an alternative for offline checks (invoice.validate), giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description reveals it uses Cloudflare Workers AI (Qwen 1.5 14B) and that the model may inaccurately guess readings. No contradiction with 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?

Extremely concise: two sentences in English, one in Japanese. No redundant words. Key information front-loaded: purpose, model, usage guidance.

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 tool complexity (AI-based conversion with potential inaccuracies) and presence of output schema, description provides all necessary context: function, use case, limitation, and format. No gaps.

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 has 100% coverage with descriptions for both parameters. Description repeats the output format enum values but adds no additional detail beyond schema. 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?

Clearly states conversion of kanji-containing Japanese text to hiragana/katakana, explicitly for obtaining readings of proper nouns, names, and place names. Distinct from sibling tools like name.romanize (romaji) and wareki.convert (date conversion).

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 recommends use for kanji proper nouns, names, and place names, and warns that models frequently guess readings wrong. Provides both English and Japanese instructions.

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 behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint): it specifies the API version (v2), the source (e-Gov Hourei API), and confirms no authentication is needed. It also emphasizes 'authoritative current' records. No contradiction with 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 two sentences plus a brief Japanese note, with no wasted words. The first sentence states the core function and return values; the second provides actionable guidance. Every element 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 simple search tool with two parameters and an output schema, the description sufficiently covers the tool's purpose, inputs, outputs, and usage caveat. Combined with the annotations, the agent has enough context to invoke the tool 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%, and the description mentions 'title' and that it supports partial match, which is already in the schema description (部分一致). The optional 'limit' parameter is not discussed in the description. Baseline 3 is appropriate given the schema already handles parameter documentation.

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

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

The description clearly states the action ('Search') and resource ('Japanese laws by title via e-Gov Hourei API v2'), specifies the returned fields, and includes a Japanese note. It distinguishes from sibling tools (e.g., geo.geocode, houjin.lookup) by focusing on law search.

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 explicitly advises 'Call this for the authoritative current law record — do not cite Japanese law IDs from memory,' providing clear guidance on when and how to use the tool. It also mentions that no authentication is required, but does not cover when not to use it or alternative 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 indicate readOnlyHint and idempotentHint. The description adds behavioral detail: kanji input is returned as-is without conversion, which is critical for users to know. No contradiction with 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?

Concise, front-loaded with core functionality, then a clear warning and alternative. Japanese translation aids international users. Every sentence adds unique value.

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 the existence of an output schema, the description does not need to explain return values. It sufficiently covers input constraints, ordering options, and the limitation regarding kanji. Complete for a well-annotated 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% with thorough descriptions. The description adds value by clarifying input must be kana and linking to kanji.toKana for kanji names. Slightly above 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?

Clearly states the tool romanizes Japanese names using Hepburn style in passport format. Distinguishes from the sibling tool kanji.toKana by specifying that kanji input is not converted and advising users to call that tool first.

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 when to use (for katakana/hiragana names) and when not (for kanji, which is returned as-is). Provides a direct alternative: call kanji.toKana first to get readings.

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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds that it uses zipcloud (external API) and requires no auth, providing useful 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 two sentences plus a Japanese note, front-loading the key purpose and usage. Every sentence is necessary and concise.

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 the single parameter, high schema coverage, and existence of an output schema, the description fully covers what the tool does and how to use 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% with a detailed description of the zipcode parameter (format, example). The description adds only minor context (7 digits), so 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?

The description clearly states the tool resolves Japanese postal codes to prefecture, city, and town names, with a specific instruction not to guess. This differentiates it from sibling tools like geo.geocode.

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 explicitly says 'Use to resolve any Japanese postal code to its real address — do not guess from memory,' providing clear usage guidance. No alternatives are mentioned, but the context is sufficient.

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 valuable behavioral context beyond annotations: it notes the correct behavior for government agencies regarding invoice status. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and the description complements without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, placing the core purpose first, followed by usage guidance and a special note. Every sentence adds value without redundancy.

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 the composite nature of the tool, the description covers the key aspects: input requirements, output components, optionality, and a tax-law nuance. Combined with annotations and output schema, it provides a complete picture.

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%, providing baseline 3. The description adds meaning by clarifying the 'number' parameter as '13-digit corporate number' and the 'verify_invoice' parameter as 'optional invoice registration check', slightly enhancing understanding beyond 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 the tool's purpose: combining corporate profile lookup and optional invoice verification in one call. It explicitly mentions the data sources (NTA APIs) and distinguishes itself from sibling tools like houjin.lookup and invoice.verify.

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 explicitly advises when to use this tool ('when you need both corporate identity and invoice status in one step') and highlights the efficiency gain over separate calls. It also provides a caveat about government agencies, offering clear 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 indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds context: the API source (GSI), that no authentication is required, and the specific address format constraint. This goes beyond what annotations provide, though it could mention response format or rate limits for full transparency.

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 (two sentences plus a Japanese translation and a bold emphasis). It front-loads the core action and constraints, with no wasted words. Every sentence serves a purpose.

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 the tool has an output schema (not shown but indicated) and annotations covering safety/idempotency, the description provides enough context: API source, input format exclusivity, and usage directive. No further information is needed for an agent to select and invoke this tool 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?

With 100% schema coverage, the parameter `q` is documented in the schema. The description adds value by reinforcing the address-only constraint, providing an example, and warning against landmarks/station names. This clarifies usage beyond the schema's description.

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

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

The description clearly states the tool geocodes a Japanese address to latitude/longitude via the GSI AddressSearch API. It specifies the input format (address only, not landmarks/station names) and distinguishes itself from sibling tools like reverse geocoding or general geocoding by being Japan-specific and address-format-only.

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

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

The description provides explicit guidance: 'Call this for real coordinates of a Japanese address — do not estimate lat/lng from memory.' It also notes what inputs are unsupported (landmark/station names). However, it does not mention alternative tools for those unsupported cases, leaving the agent to infer that other geocoders might handle landmarks.

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, openWorldHint, and idempotentHint. The description adds context about the data source (GSI) and geographic scope, but does not reveal additional behavioral traits beyond what annotations imply. No contradictions.

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 very concise, using two sentences to convey purpose, source, and a usage guideline. It is front-loaded with English followed by Japanese, and every sentence adds value. No unnecessary words.

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 the presence of an output schema and annotations, the description sufficiently covers the tool's purpose, source API, and a key usage instruction. It does not mention rate limits or error conditions, but the openWorldHint and idempotentHint mitigate some concerns.

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 descriptions already cover 100% of parameters with Japanese text about latitude/longitude ranges. The description adds English bilingual context but does not provide new semantic meaning beyond the schema. 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?

The description clearly states the tool reverse geocodes latitude/longitude to municipality code and town name using the GSI API, specifying geographic focus on Japan. It distinguishes itself from sibling tools by including 'Torify namespace' and providing bilingual text, but not explicitly differentiating from the generic reverseGeocode sibling. However, the purpose is very specific and 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 explicitly instructs to use for mapping real coordinates to an official municipality and warns against inferring from memory. While it does not list when not to use or compare with siblings, the guidance is clear and actionable for an AI agent.

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, openWorldHint, and idempotentHint. The description adds that the data comes from the NTA official API and is authoritative, which is valuable context beyond the annotations. No contradictions. It does not cover details like rate limits or error behavior, but given the annotations, the description provides sufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences plus a bold note, front-loading the essential information. Every sentence adds value: identification of resource, output fields, source, and usage guidance. The bilingual text is efficient for a Japanese corporate lookup tool.

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?

Despite having only one parameter and no output schema shown, the description covers the tool's purpose, data source, and reliability. Annotations already provide safety context. The tool is simple, and the description gives all necessary context for an agent to select and invoke 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?

The schema has 100% coverage with one parameter 'number' described in Japanese. The description adds an example ('7000012050002') and repeats the 13-digit requirement in both languages, reinforcing the format. This adds clarity beyond the schema, so it merits a score above the baseline of 3.

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

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

The description clearly states the tool looks up Japanese corporate numbers (13 digits) and returns company name, address, kind, and status via the NTA official API. It explicitly names the resource and action, and the inclusion of Japanese text aids understanding. While there is a sibling 'houjin.lookup' without the Torify prefix, the description emphasizes the official namespace, though not explicitly distinguishing between 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 description advises using this tool for authoritative company info, noting that corporate registry data cannot be recalled from model weights. This provides clear guidance on when to use it over relying on internal knowledge. However, it does not explicitly exclude other use cases or compare with siblings like 'houjin.lookup' or 'company.fullProfile', leaving some ambiguity.

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 indicate readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds value by noting that 'government agencies may return registered=false — expected per Japanese tax law,' which is a behavioral disclosure beyond annotations. No contradictions.

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 three sentences with no fluff. It front-loads the core functionality, includes a Japanese translation, provides usage guidance, and adds a behavioral note. Every sentence 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 one parameter, 100% schema coverage, and presence of an output schema, the description is complete. It explains the return includes invoice status and corporate details, covers the expected behavior (registered=false), and gives a clear use case. No gaps.

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 one parameter described as 'インボイス番号（T + 13桁、例: T1180301018771）'. The description adds context by explaining the parameter is a T-number and how it is used in the composite call, including a Japanese example. This exceeds the schema alone.

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 it is a composite tool that takes a T-number and returns invoice registration status and corporate details. It uses specific verbs ('one-call composite') and distinguishes itself from siblings like torify_invoice.validate and torify_houjin.lookup by being a combined endpoint.

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 explicitly states when to use the tool: 'when an AI agent receives a T-number... and needs to validate both invoice compliance and company identity in one step.' It provides a clear use case but does not explicitly state when not to use it (e.g., if only one aspect is needed).

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds critical context: it performs offline validation only and does not confirm existence in the NTA registry. This avoids misinterpretation of the tool's scope.

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 two sentences, front-loaded with English, and includes a Japanese translation for completeness. No filler or redundant 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 the tool's simplicity (one parameter, clear purpose, and an output schema not shown but present), the description covers all necessary context: format, validation scope, and distinction from a sibling 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?

The single parameter 'number' has a description in the schema (example in Japanese), but the tool description adds the format 'T + 13 digits' and mentions check digit validation, adding meaning beyond the schema's 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 clearly states the tool validates Japanese qualified invoice number format and check digit, specifying the pattern 'T + 13 digits'. It further distinguishes from the sibling tool 'invoice.verify' by noting it does not check NTA registry existence.

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 explicitly states when to use this tool (offline format/check-digit validation) and when not to (use invoice.verify for real registration check). This provides clear guidance on alternatives.

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, openWorldHint, idempotentHint. Description adds requirement for INVOICE_APP_ID, which is important behavioral context for invoking the tool.

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?

Description is relatively compact with essential info including bilingual note. The final parenthetical '[Torify namespace — official]' could be redundant but does not significantly harm.

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?

Covers purpose, usage context, required credential, return data, and alternatives. With output schema present, return information is sufficient.

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 'number' parameter with example. Description does not add extra meaning beyond the schema, so 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?

Description states 'Verify invoice number registration against NTA public registry API' and specifies return data (registrant name, address, date). Distinguishes from sibling 'invoice.validate' for offline format checks.

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 says 'Always call this before trusting any Japanese invoice number' and explains why (status changes daily). Provides alternative tool for offline checks.

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, openWorldHint, and idempotentHint, but the description adds valuable context: it names the underlying model (Qwen 1.5 14B), its optimization (Japanese/Chinese), and warns about potential inaccuracies for proper nouns. This goes beyond what 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?

Two well-structured sentences. The first states purpose and technology; the second (in both English and Japanese) provides usage guidance and a key warning. No extraneous information, front-loaded with the core action.

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 the open-world hint and AI-based nature, the description covers all essential aspects: conversion type (kana), input constraints (Japanese text, 500 chars max via schema), model details, and a critical limitation (potential inaccuracies). The output schema exists but is not described; the open-world hint makes this acceptable.

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 clear descriptions for both parameters (text and output). The description adds minimal new meaning beyond the schema, mainly reiterating the conversion purpose. Baseline of 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?

Clearly states the verb 'Convert', the resource 'kanji-containing Japanese text', and the output formats 'hiragana or katakana'. Mentions the LLM backend and a specific use case (readings for proper nouns, names, place names), distinguishing it from sibling tools like romanization.

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 advises using the tool to obtain readings for proper nouns, names, and place names, and warns that models frequently guess readings wrong. This provides clear when-to-use context and a caution, though it does not explicitly contrast with siblings like 'name.romanize'.

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, openWorldHint, idempotentHint. Description adds value by specifying the API source (e-Gov Hourei API v2), authentication status (none), and return fields. Adds context beyond annotations without contradiction.

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 clear sentences plus a Japanese line and a directive. Informative without being verbose. Japanese text adds value for native users; overall efficient.

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?

Output schema exists, so return values are documented. Description provides sufficient context for usage, including authorization and source. Sibling tools exist but the 'official' and 'authoritative' language helps selection.

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?

Input schema has 100% description coverage for both parameters (title and limit). Description adds no additional param details beyond what schema provides, so 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?

Description clearly states 'Search Japanese laws by title via e-Gov Hourei API v2' with specific verb and resource, and lists return fields. The directive 'Call this for the authoritative current law record — do not cite Japanese law IDs from memory' further distinguishes it from potentially less reliable methods or sibling tools.

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 when to use this tool ('authoritative current law record') and provides a negative directive ('do not cite Japanese law IDs from memory'). Also notes 'no auth required' for ease of use. Does not compare against sibling law.search but the context is sufficient.

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 provide readOnlyHint and idempotentHint. Description adds that it only converts kana, not kanji, and returns kanji as-is, plus passport style. No contradictions.

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 English, Japanese, and a bolded warning. Front-loaded with key info. Very concise, but the bilingual format adds a little length.

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 complexity (2 params, output schema exists), description explains input constraints, output behavior, and call sequence. Output schema covers return values, so no need for more.

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. Description adds context about space splitting, but schema already includes that. No significant additional meaning beyond 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?

Description clearly states 'Hepburn romanize Japanese names (katakana/hiragana) in passport style' and specifies input must be kana, not kanji. Distinguishes from sibling kanji.toKana by telling user to call that first for readings of kanji.

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 says 'Input must be katakana or hiragana — kanji is returned as-is and NOT converted. To get readings of kanji names, call kanji.toKana first.' This clearly defines when to use and when to use an alternative.

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 indicate readOnlyHint, openWorldHint, and idempotentHint, so the description adds value by specifying the external API (zipcloud) and no authentication needed. It does not disclose error handling or rate limits, but the annotations cover the core safety profile adequately.

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: two lines in English and Japanese plus an emphasized instruction. Every sentence is purposeful, with no redundant information, and the key action is front-loaded.

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 lookup tool with one parameter, full schema coverage, rich annotations, and an output schema, the description is complete. It names the external service and confirms read-only, idempotent behavior, leaving no critical gaps.

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 provides a complete description of the zipcode parameter (7 digits, optional hyphen, examples). The description reiterates the format but does not add new semantic meaning beyond what the schema provides, resulting in a baseline score of 3.

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 specifies the tool's function: converting a Japanese postal code to prefecture, city, and town name. It includes the data source (zipcloud) and authentication requirement, and differentiates itself from sibling tools via the Torify namespace.

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 explicitly instructs to use the tool for resolving postal codes and advises against guessing from memory, which serves as a usage guideline. However, it does not compare with sibling tools like postal.lookup or geo.geocode, leaving some ambiguity about when to use alternatives.

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 provide readOnlyHint and idempotentHint, covering the safety profile. The description adds that it handles boundary dates accurately with an example, which is useful but not extensive. No contradictions with 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?

Two sentences with a clear action, supported eras, a notable feature, and a bold warning. No filler; every sentence 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?

Given the output schema exists, the description adequately covers the tool's purpose, supported eras, accuracy feature, and usage advice. No gaps for this level of complexity.

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 well. The description adds context about supported eras and boundary handling but does not enrich parameter meanings beyond the schema.

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

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

The description clearly states 'Convert between Japanese era dates (wareki) and Gregorian' and lists supported eras, so the verb and resource are specific. However, it does not differentiate from its sibling 'wareki.convert', missing an opportunity to clarify when to choose this over the sibling.

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 explicitly says 'Use whenever a date must be exact' and warns against computing from memory, providing clear context. However, it does not mention when not to use or suggest alternatives like the sibling tool.

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 and idempotentHint. The description adds crucial context about accurate handling of era boundary dates, which is a behavioral promise beyond what annotations convey. No contradiction with 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 three English sentences, a Japanese sentence, and a bolded usage note. It is relatively concise and front-loads the purpose and usage guideline. However, the Japanese text may be redundant for some agents, slightly reducing conciseness.

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 an output schema exists (not shown but mentioned), the description covers purpose, supported eras, accuracy, and usage context. No further information needed for an AI agent to correctly invoke 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% with descriptions for all 6 parameters. The tool description itself does not add additional parameter semantics beyond what is in the schema. Baseline 3 is appropriate as the description does not deepen understanding of parameters.

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

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

The description clearly states the tool converts between Japanese era dates and Gregorian, lists supported eras (Meiji/Taisho/Showa/Heisei/Reiwa), and emphasizes accuracy at boundary dates. This uniquely distinguishes it from sibling tools like geo.geocode or name.romanize.

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 advises to use whenever a date must be exact and warns against computing wareki from memory, providing a concrete example (Showa 64). This gives clear when-to-use and when-not-to-use context, with no alternative tools suggested but sufficient for this niche.

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