Server Quality Checklist

Tool Scores

• search_addressA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses behavior such as automatic absorption of variant characters (ケ/ヶ/ヵ) and implies output includes URIs by referencing passing them to get_address_location. It does not mention performance limits or whether it is read-only, but for a search tool this is reasonably transparent.

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

  Conciseness5/5

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

  The description consists of two succinct sentences. The first sentence states the core action and data source, and the second provides important behavioral detail and a pointer to a sibling tool. Every sentence earns its place with no wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is reasonably complete for a search tool: it explains the matching method, variant handling, and that shape data must be obtained elsewhere. However, it does not detail the exact output format or fields (e.g., whether results include labels or just URIs), and with no output schema or annotations, this gap remains. The note about passing URI to get_address_location partially compensates.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds no parameter-specific information. The schema covers query and prefecture with descriptions (67% coverage), but the tool description does not elaborate on limit or provide any additional meaning beyond what the schema states. Since coverage is not high (>80%) and the description does not compensate, this is a weak area.

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

  Purpose5/5

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

  The description clearly states the tool searches for address candidates by partial matching of address labels using Address LOD. It distinguishes itself from siblings by explicitly directing users to pass the resulting URI to get_address_location for shape data, clarifying its role as a search tool.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance for using an alternative: pass the URI to get_address_location when shapes are needed. It implies search_address is for finding candidate URIs, but does not mention other sibling tools like list_prefectures or reverse_geocode_address, so it is not fully exhaustive.

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

• list_banchiA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses auto-completion of input variations (gun names, city omissions, variant characters), output scope (banchi only, not building numbers), and chome aggregation behavior. These are meaningful behavioral insights beyond the schema, though it does not mention error handling or pagination.

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

  Conciseness5/5

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

  The description is a compact three-sentence paragraph, each sentence adding distinct information: core function, chome behavior, and input normalization. No filler or redundancy; it is efficiently structured and front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no output schema, the description sufficiently explains inputs and behavioral nuances. It covers town normalization, chome handling, and limitations, making it self-contained for selecting and invoking the tool. Minor gaps like return format and limit semantics prevent a perfect score.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 67%, so the description adds valuable context for the 'town' parameter by explaining auto-completion, and for 'chome' by clarifying that omission returns all chome results aggregated. The 'limit' parameter is not described, but other parameters receive depth beyond their schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool enumerates banchi (lot numbers) for a specified town, matching the title. It differentiates from siblings by specifying the resource type (banchi under a town) and notes chome handling, which is distinct from generic address search or child address listing.

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

  Usage Guidelines4/5

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

  The description gives clear context on when to use the tool (to list banchi for a town) and explains behavior for towns with and without chome. It also states a limitation (building numbers are not obtainable), but doesn't explicitly name alternative tools or provide exclusion criteria, so it falls short of a 5.

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

• list_child_addressesA
  4.4/5.0
  Behavior4/5

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

  With no annotations supplied, the description discloses key behaviors: it only handles direct children, cannot go below chome, and automatically attempts to compensate for omissions and variant spellings. It does not mention return format or pagination limits, but the core behavioral traits are transparently stated.

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

  Conciseness5/5

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

  The description is compact and well-structured: a single main purpose sentence, a usage note, and a final note about auto-completion. Every sentence earns its place, no fluff or repetition of schema data beyond what adds clarity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a list tool with 2 parameters and no output schema, the description covers purpose, hierarchical constraints, exclusions, and special handling. It lacks explicit return value details (e.g., whether results include names/URIs), but given the tool's simplicity and sibling context, it is reasonably complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 50%; the parent parameter is thoroughly described in the schema (hierarchy scope, auto-completion), and the description repeats this. The limit parameter has no description in either schema or description, so the tool description adds no new meaning for it. The contribution is limited to reinforcing parent semantics without covering the gap for limit.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: '指定した住所(都道府県/市区町村/町丁目)の直接の子要素一覧を取得する' (fetches direct child elements of a specified address). It explicitly names the hierarchy levels and distinguishes itself from sibling tools like list_prefectures and list_banchi by focusing on drill-down from prefecture to city to town.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use: '都道府県→市区町村→町丁目のドリルダウンに使う' and clear exclusions: '丁目→番地の列挙はこのToolでは扱えない', indirectly directing users to other tools for lower levels. It also notes auto-completion behaviors, making conditions for use well-defined.

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

• reverse_geocode_addressA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description carries full burden. It discloses precision limit (町丁目レベル), geohash limitation, approximate search nature, and potential missing candidates near prefecture boundaries. This goes beyond the schema and explains behavioral traits.

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

  Conciseness5/5

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

  The description is two sentences, with the first sentence stating the core purpose and the second adding critical limitations. Every sentence earns its place; no fluff.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is simple with 3 well-documented params and no output schema. The description explains what it does, addresses precision, and limitations. It could explicitly state the return format (e.g., list of candidates), but '住所候補' implies multiple results, making it sufficiently complete for context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so baseline is 3. The description's precision limit explanation mirrors schema's precision parameter details, but adds no new meaning beyond the schema. The schema already fully documents lat, long, and precision.

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

  Purpose5/5

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

  The description states '緯度経度から近傍の町丁目レベルの住所候補を検索する' (search nearby town/chome-level address candidates from lat/long), which is a specific verb+resource. It distinguishes from siblings by specifying reverse geocoding and precision limits, unlike forward geocoding tools like search_address.

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

  Usage Guidelines4/5

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

  The description explicitly notes this is not strict point-in-polygon geocoding ('点在ジオコーディング...ではない'), implying when not to use. It also mentions approximate nature and boundary-related miss risk, providing context for when to use it (when approximate reverse geocoding is acceptable). No explicit alternative tool names, but the exclusion is clear.

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

• list_prefecturesA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden. It clarifies the tool is read-only (returns a list) and discloses a subtle behavioral trait: topology sharing is only guaranteed within a single call, so using the full list prevents boundary misalignment. It does not mention any error conditions or performance, but for a static list that 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.

  Conciseness4/5

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

  The description is front-loaded with the purpose, followed by usage guidance and rationale. All sentences earn their place, but the explanation about topology sharing is relatively lengthy for a simple list tool, making it slightly less concise than it could be. Still highly structured and informative.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's simplicity (no params, no output schema), the description fully covers its purpose, return format, and integration with a sibling tool. It even addresses an edge-case risk (omissions and boundary misalignment) and provides a complete solution. Nothing essential is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description explicitly states 'no parameters', reinforcing the schema but adding no additional semantics. Nothing else is needed.

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

  Purpose5/5

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

  The description uses a specific verb ('返す' / returns) with a clear resource (47 prefecture official names as an array) and states it has no parameters. It distinguishes itself from sibling tools by being the canonical list source, not a search or geocoding tool.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance: pass this tool's result directly to addresses when creating a Japan map via get_address_locations. It also tells the agent not to rely on LLM memory or piecemeal fetching, explaining the topology sharing risk. This clearly frames the tool as the correct choice over other address-related tools.

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

• save_address_locations_to_fileA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description correctly carries the full burden. It discloses that the tool writes to the local filesystem, does not include the file contents in the MCP response, returns only a path and summary, overwrites existing files, and can create parent directories. It also explains the technical reason (1MB response limit) and the practical consequence that Claude cannot draw maps from the written file.

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

  Conciseness4/5

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

  The description is long but well-structured with a bold warning up front, followed by clear use-case boundaries, technical rationale, and a final caution. The repetition of the 'not for map-building' rule is somewhat redundant, but it is a critical safety constraint that warrants emphasis. Overall, each section contributes useful context for correct tool selection and invocation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is complete for a complex tool with no output schema and no annotations. It explains the return value (path and summary), the invisibility of file contents to Claude, the difference from get_address_locations, the 1MB workaround, filesystem write behavior, and links to sibling tools like list_prefectures. Combined with the very detailed input schema, there is no significant missing context for invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3. The input schema already provides detailed semantics for all parameters, including addresses, outputPath, simplify, dropSmallIslands, and degenerateIslands. The main description adds some usage context, such as recommending list_prefectures for 47 prefectures and clarifying that the 1MB limit does not require splitting, but these are reinforcement of schema information rather than new parameter-level semantics.

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

  Purpose5/5

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

  The description clearly states a specific verb+resource: exporting multiple addresses to a single GeoJSON FeatureCollection file, returning only path and summary. It explicitly distinguishes itself from get_address_locations, which returns data in the MCP response, while this tool writes to a local file and avoids the 1MB response limit. The title also reinforces the export/save purpose.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use and when-not-to-use guidance: it must not be used for building maps or visualizations in place, and get_address_locations must be used instead for such requests. It states that this tool is only appropriate when the user explicitly asks for file export/save and Claude does not need to read the contents. It also explains when it is better than splitting into 5 groups, e.g., for 47 prefectures.

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

• get_address_locationsA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behaviors: partial failures are excluded and noted as unresolved, only all-fail triggers isError, simplification preserves topology across features, dropSmallIslands is restricted to prefecture-level inputs, and the server automatically switches to the lightest combination as a safety valve. It also states that the output is RFC 7946 GeoJSON directly usable by map libraries.

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

  Conciseness4/5

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

  The description is front-loaded with the main purpose and uses bold warnings and paragraphs to structure critical rules. It is lengthy and repeats the 'map vs. file' directive twice, plus the exhaustive 47-prefecture splitting detail could arguably be moved to the parameter description, but the overall structure is clear and each section earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Despite having no output schema and no annotations, the description covers all essential operational aspects: return format, failure handling, parameter constraints, size limitations, and alternatives. It leaves almost no ambiguity about how the tool behaves in complex scenarios, making it highly complete for a tool of this complexity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the practical impact of simplify levels (e.g., low/medium for wards, high as last resort), the prefecture-only rule for dropSmallIslands, the condition for degenerateIslands, and the recommended address grouping strategy for large sets. While some of this overlaps with schema property descriptions, the narrative guidance helps parameter selection.

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

  Purpose5/5

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

  The description clearly states the tool's function: '複数の住所をまとめて取得し、1つのGeoJSON FeatureCollectionとして返す' (gets multiple addresses at once and returns as one GeoJSON FeatureCollection). It explicitly distinguishes it from the single-address get_address_location and from save_address_locations_to_file, making its purpose and scope immediately clear.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: use this tool instead of calling get_address_location multiple times, and never use save_address_locations_to_file when the AI needs to build a map in the response. It also provides detailed splitting instructions for 47 prefectures to avoid 1MB client limits, including a concrete 5-group example.

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

• get_address_locationA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does so excellently. It discloses that the tool fetches TTL and converts to GeoJSON client-side to reduce server load, auto-completes omitted county/city names and variant characters, uses centroid fallback when LOD lacks representative points (with point_source property), returns RFC 7946 GeoJSON compatible with mapping libraries, and explains simplify/dropSmallIslands side effects. This goes far beyond a basic action statement.

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

  Conciseness5/5

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

  The description is long but every sentence delivers actionable information. It is front-loaded with the core purpose, then systematically covers conversion, auto-completion, centroid fallback, GeoJSON compatibility, alternative tools, and parameter usage nuances. There is no redundancy or filler; despite its length, it remains efficiently organized and directly relevant to tool selection and invocation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity—three parameters with nuanced behavior, no output schema, and no annotations—the description is remarkably complete. It explains the return format (GeoJSON Feature), the point_source marker for centroids, how to use with mapping libraries, limitations (e.g., banchi points only, no building numbers), and when to use sibling tools. It leaves no practical gaps for an agent deciding whether and how to call this tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Even though schema coverage is 100%, the description adds substantial meaning beyond the schema. For 'address' it explains levels (prefecture to chome polygon, banchi point, gou not possible), URI example, and auto-completion. For 'simplify' it provides concrete point counts for different administrative levels and warns against 'high' as default. For 'dropSmallIslands' it explains the area threshold, applicability only to prefectures, and rationale. These details are not in the schema descriptions.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: '住所LODから、指定した住所のポリゴンまたはポイントをGeoJSON Featureとして取得する' (retrieves polygon or point for a specified address from Address LOD as a GeoJSON Feature). It clearly distinguishes from sibling get_address_locations by explicitly stating that for multiple addresses, one should use get_address_locations instead of calling this tool multiple times.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool vs alternatives: for single addresses use this, for multiple use get_address_locations. It also gives detailed usage conditions for parameters: simplify recommended at city/prefecture levels with specific point counts, dropSmallIslands only for prefectures, and 'high' simplify as a last resort. These are clear when/when-not and alternative recommendations.

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