Gachi-Ramen

search_ramen

Read-onlyIdempotent

Search a nationwide Japanese ramen-shop database (67,000+ shops, all 47 prefectures) with a verifiable freshness layer: monthly source checks, closure candidates, and web-verified closures with evidence URLs. English-first: shop names and places are searchable in Japanese OR romaji. To answer "is there a ramen shop called X?", pass q alone — it searches NATIONWIDE by name (e.g. q=一蘭 or q=ichiran, no prefecture needed). Or filter by prefecture (東京都/大阪府/〇〇県 or romaji tokyo/osaka/saitama), city (松戸市 or romaji kawaguchi), ramen style (keito), status (active/closed_candidate/closed_confirmed), or search near a coordinate (lat/lng + radius up to 5 km). Facts only — no rankings, no reviews. Payment/midnight fields are tri-state (true/false/null=unknown). If a NAME search matches nothing, the response adds fallback_shops (suggestions from a relaxed query — closest by meaning, or spiciness-signature shops) alongside an empty shops[]; fallback_reason says what was relaxed, so relay that caveat rather than presenting them as matches.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Shop-name substring, Japanese OR romaji/English (e.g. 一蘭 or ichiran, 豚坂下 or butasakashita). Works NATIONWIDE on its own — pass q with no pref/city to check if a shop exists anywhere.
`lat`	No	Optional latitude for nearby search (with lng).
`lng`	No	Optional longitude for nearby search (with lat).
`city`	No	Municipality, Japanese (松戸市, 世田谷区) OR romaji (kawaguchi, setagaya). Works alone — prefecture is auto-resolved (add pref if the romaji is ambiguous).
`pref`	No	Prefecture, Japanese (千葉県; short forms 千葉/東京) OR romaji (chiba/tokyo/saitama/osaka). Optional if city, q, or lat/lng is given.
`chain`	No	Optional chain filter on the curated chain label (e.g. chain=ラーメンショップ matches the whole family incl. ラーショ/うまいラーメンショップ variants; also 山岡家, 一蘭, 天下一品…). Works nationwide alone or combined with pref/city/nearby. Unlike q, this is curated membership, not a name substring.
`keito`	No	Optional ramen-style filter (style LINEAGE — for spiciness use the spice_level attribute instead). Coarse bucket (tonkotsu, miso, shoyu, shio, tsukemen, tantanmen, other) matches every school in the bucket — tonkotsu also covers iekei/家系 & jiro/二郎. Or an exact fine value from the 19-value vocabulary: iekei, jiro, tsukemen, tantanmen, abura_mazesoba, chuka_tanrei, champon, toripaitan, sapporo, asahikawa, kitakata_aizu, shirakawa, sano, onomichi… (keito=champon returns only champon shops). ~23% of shops carry a style; the rest are unclassified.
`limit`	No	Max results (default 20, max 50).
`match`	No	How q matches: 'partial' (default, substring) or 'exact' (whole word on the romaji name — q=ojiya finds 王子家/Ojiya but not 糀谷/Kojiya). Use exact to avoid coincidental substring hits.
`status`	No	Optional: active (default: all) / closed_candidate / closed_confirmed.
`radius_m`	No	Nearby search radius in metres (default 1500, max 5000).
`chain_sub`	No	Optional sub-lineage within a chain (currently for chain=ラーメンショップ): tsubaki (椿系), aji_q (アジキュー系), new_rasho (ニュー系), satsumakko (さつまっ子系), 105, kaizan (かいざん系). Exact value match; combine with chain or use alone.
`shop_type`	No	Optional venue-style ATTRIBUTE filter: "senmon" (ramen specialist), "machichuka" (machi-chuka — a neighbourhood Chinese diner that also serves ramen) or "unknown" (not yet classified). Classified only from shop-name signal rules confirmed by a dual-LLM audit — never guessed, so most shops are unclassified (null). Exact match; "unknown" matches the null shops.
`venue_type`	No	Optional venue filter: "permanent" (DEFAULT — fixed storefronts) / "popup" (records of limited-run appearances at events and department-store fairs: 物産展, ラーメンショー…) / "all". Popups are excluded by default because the shop is no longer at that address; pass "popup" only to research event history. Shopping-mall tenants (イオンモール, ららぽーと, マルシェ-branded station buildings) count as permanent.
`spice_level`	No	Optional spiciness ATTRIBUTE filter: "spicy" (357 shops whose signature is spiciness — dual-verified, never guessed) or "unknown" (no spice data). Orthogonal to keito: keito is the style lineage, spice_level is an attribute — keito=spicy (coarse bucket, effectively tantanmen) does NOT mean the shop is spicy.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Human-readable note.
`count`	No	Results returned.
`query`	No	Echo of the resolved query.
`shops`	No	Matching shops.
`fallback`	No	true only when nothing matched and a relaxed alternative is offered (shops stays empty).
`data_as_of`	No	Dataset freshness date (YYYY-MM-DD).
`attribution`	No	Data source(s), license and provenance — an object, or an array of sources.
`fallback_step`	No	Which relaxation produced fallback_shops: semantic / spice_attribute / pref_summary.
`total_matched`	No	Total matches before limit.
`fallback_shops`	No	Suggestions from the relaxed query. NOT matches for the original query.
`fallback_reason`	No	{code, message} — what was relaxed and why; relay this caveat to the user.

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already mark readOnlyHint=true, idempotentHint=true, destructiveHint=false. On top of that the description adds substantial behavioral texture: the monthly freshness/source-check layer, web-verified closures with evidence URLs, fallback-with-relaxed-query semantics, tri-state payment/midnight fields, popups excluded by default because the shop is no longer at that address, and classification limits ('never guessed'). Consistent with the read-only annotation — a search that returns facts — so no contradiction.

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?

Long (~300 words) but every section earns its place for a 15-parameter tool: purpose and scope front-loaded, followed by query patterns, then the caveats (facts-only, tri-state, fallback, popup exclusion). Structured and information-dense; could be tightened marginally but contains no filler.

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 output schema exists (so return shape needs no explanation), the description covers everything else: the fallback contract (empty shops[] + fallback_shops + fallback_reason), the freshness and closure layers, classification coverage rates (~23% style, most shops unclassified), venue semantics, and tri-state fields. A 15-parameter tool with zero required params is fully navigable after reading this.

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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema alone cannot convey: q searches NATIONWIDE on its own, keito is a lineage bucket while spice_level is an orthogonal attribute (keito=spicy does NOT mean the shop is spicy), chain is curated membership vs q's substring, match=exact semantics on romaji names, and the machichuka-vs-unknown classification. These clarifications materially change how an agent would pick parameter values.

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 (search), resource (67,000+ shop nationwide Japanese ramen database, all 47 prefectures), and immediately frames scope as fact-only with no rankings/reviews. It names the exact query patterns it supports and is unmistakably distinct from sibling get_ramen_shop (single shop) and get_ramen_changes (change log). The 'facts only' line plus the explicit freshness-layer statement fully disambiguate the tool's role.

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?

Gives detailed usage patterns: 'To answer...pass q alone,' nationwide name search, filtering by prefecture/city/keito/status/coordinates, and how fallback_shops appear on empty results with fallback_reason to relay. This is clear operational context, but it never names alternatives or states when NOT to use this tool (e.g., no pointer toward vibe_search or get_ramen_shop). Lacks explicit exclusions, so a 4 rather than 5.

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

All Gachi-Ramen tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: ping for health, get_ramen_shop for single-record fetch, search_ramen for exact/filtered queries, vibe_search for semantic/fuzzy queries, and get_ramen_changes for the data freshness feed. The overlap between search_ramen and vibe_search is explicitly addressed in their descriptions, eliminating ambiguity.

Naming Consistency4/5

Tool names follow a consistent verb_noun pattern in snake_case (get_ramen_changes, get_ramen_shop, search_ramen, vibe_search), with ping being the only exception as a bare verb health check. This is a minor deviation but still readable and predictable.

Tool Count5/5

With 5 tools, the server is well-scoped for a read-only database/search service. Each tool covers a necessary operation without redundancy, and the count is neither thin nor bloated.

Completeness5/5

The server provides full retrieval coverage: single-record retrieval, exact search, semantic search, and a change feed for data freshness. As a read-only service, it does not need create/update/delete operations, and the existing surface covers all plausible agent needs for querying ramen shop data.

Resources

Need Help?