japan-data-mcp

search_japan_official_data

Read-onlyIdempotent

Fetch and filter records from one Japanese public dataset by prefecture, municipality code, corporate number, or keyword. Use after obtaining a dataset ID for single-table lookups and sampling.

Instructions

Fetch and filter actual data records from a single dataset using standardized parameters (prefecture name, 5-digit JIS municipality code, 13-digit corporate number, or free-text keyword). Multiple filters are combined using logical AND. WHEN TO USE: Use for fast, single-table record lookups and filtered sampling once you know the 'dataset_id'. WHEN NOT TO USE: Do not use for discovering dataset IDs (use 'list_japan_datasets'), inspecting column schemas (use 'describe_japan_dataset'), or performing cross-table JOINs and GROUP BY aggregations (use 'execute_japan_megabank_sql').

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Optional case-insensitive free-text substring search across company names, facility names, address fields, or contract titles (e.g., 'Cloud', 'Hospital').
`limit`	No	Maximum number of matching records to return (1 to 100, default: 10).
`dataset_id`	Yes	Target dataset ID obtained from 'list_japan_datasets' (e.g., 'demographics', 'procurement', 'medical', 'companies', 'real_estate').
`prefecture`	No	Optional prefecture filter in English romaji or Japanese kanji (e.g., 'Tokyo', 'Osaka', 'Hokkaido', '東京都'). Case-insensitive.
`corporate_number`	No	Optional exact 13-digit Japan National Tax Agency corporate number string (e.g., '1000012010019') or 10-digit US SEC CIK.
`municipality_code`	No	Optional 5-digit JIS municipality code string with leading zero preserved (e.g., '13101' for Chiyoda-ku, '01101' for Sapporo).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	No	Number of records returned or matched.
`records`	No	Array of normalized record objects matching the filter criteria.

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv1.0.4Oct 15, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / corporate_number / description

Previous value: -"13-digit Japan National Tax Agency corporate number (or 10-digit US SEC CIK)."New value: +"Optional exact 13-digit Japan National Tax Agency corporate number string (e.g., '1000012010019') or 10-digit US SEC CIK."

changedInput schema / properties / dataset_id / description

Previous value: -"Target dataset ID (e.g., 'demographics', 'procurement', 'medical', 'companies', 'real_estate')."New value: +"Target dataset ID obtained from 'list_japan_datasets' (e.g., 'demographics', 'procurement', 'medical', 'companies', 'real_estate')."

changedInput schema / properties / limit / description

Previous value: -"Number of records to return (default: 10, max: 100)."New value: +"Maximum number of matching records to return (1 to 100, default: 10)."

addedInput schema / properties / limit / maximum
```
Added value: +100
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

changedInput schema / properties / municipality_code / description

Previous value: -"5-digit JIS municipality code with leading zero preserved (e.g., '13101', '01101')."New value: +"Optional 5-digit JIS municipality code string with leading zero preserved (e.g., '13101' for Chiyoda-ku, '01101' for Sapporo)."

changedInput schema / properties / prefecture / description

Previous value: -"Prefecture name in English or Japanese (e.g., 'Tokyo', 'Osaka', 'Hokkaido', '東京都')."New value: +"Optional prefecture filter in English romaji or Japanese kanji (e.g., 'Tokyo', 'Osaka', 'Hokkaido', '東京都'). Case-insensitive."

changedInput schema / properties / q / description

Previous value: -"Free-text search keyword (company name, facility name, contract title, etc.)."New value: +"Optional case-insensitive free-text substring search across company names, facility names, address fields, or contract titles (e.g., 'Cloud', 'Hospital')."

addedOutput schema / properties / count / description

Added value: +"Number of records returned or matched."

addedOutput schema / properties / records / description

Added value: +"Array of normalized record objects matching the filter criteria."

First observedv0.1.0Oct 15, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), lowering the burden. The description adds genuine behavioral context beyond that: filters combine with logical AND and the operation is single-table and 'fast'. It stops short of discussing pagination or result shape.

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?

Front-loaded with the core action, then cleanly partitioned into labeled WHEN TO USE / WHEN NOT TO USE clauses. Every sentence earns its place with no redundancy.

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?

An output schema exists, so return values need not be described. For a filtered single-dataset lookup, the description covers scope, filter semantics, and routing to all relevant alternatives. Nothing needed to call it correctly is missing.

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 coverage is 100%, so the baseline is 3. The description enumerates the filter types (prefecture, 5-digit JIS code, 13-digit corporate number, keyword) but adds no format or edge-case detail beyond what the schema already documents.

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?

States a specific verb and resource ('Fetch and filter actual data records from a single dataset') and immediately scopes it to single-table work, explicitly contrasting with cross-table SQL and metadata tools. An agent can distinguish it from every sibling by name alone.

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 WHEN NOT TO USE sections, naming the exact alternative for each excluded case ('list_japan_datasets', 'describe_japan_dataset', 'execute_japan_megabank_sql'). The selecting condition ('once you know the dataset_id') is spelled out.

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

Deploy Server