Nationwide Japanese ramen shop database — 62,000+ shops across all 47 prefectures. Geo search (lat/lng + radius), prefecture/city filter, 14-value ramen-style taxonomy, nearest-station data, and monthly closure tracking. No auth required.
Scored across 5 tools
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.
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.
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.
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.
Monthly change feed for the ramen DB — new shops, closure candidates (missing from the monthly web source 2 consecutive checks or marked disused/closed), web-verified closures (closed_confirmed, with evidence URL) and reopenings. This is the freshness signal you cannot cache: poll it to keep a local copy honest. Optional since (YYYY-MM-DD) returns only events on/after that date.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Optional ISO date (YYYY-MM-DD), inclusive. |
| Name | Required | Description |
|---|---|---|
| count | No | Number of events. |
| since | No | Echo of the since filter. |
| events | No | Change events (new / closure_candidate / closed_confirmed / reopened). |
| window | No | Time window covered. |
| dataset | No | Dataset id. |
| data_as_of | No | Dataset freshness date. |
| attribution | No | Data source(s), license and provenance — an object, or an array of sources. |
| definitions | No | Event-type definitions (or a note string in the no-auth preview). |
| generated_at | No | Feed generation timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it details what event types are included (closure candidates with 'missing from the monthly web source 2 consecutive checks' and 'web-verified closures with evidence URL'), and emphasizes it's a freshness signal that should not be cached. This goes beyond the annotations without contradicting them.
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 a bit long but every sentence adds value. It front-loads the core purpose ('Monthly change feed') then elaborates on event types and the caching caveat. The structure is logical and not redundant. It's slightly verbose but still efficiently communicates the essential details.
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 (though not shown here), the description doesn't need to explain return values. It covers what events are reported, the freshness/caching aspect, and the optional date filter. It's complete for an agent to understand what to expect and how to call it. Minor gaps like pagination or size limits are not mentioned, but those are likely in the output schema.
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 100% coverage: the `since` parameter is fully described as 'Optional ISO date (YYYY-MM-DD), inclusive.' The description's mention of 'Optional since (YYYY-MM-DD) returns only events on/after that date' essentially repeats the schema. Since the schema already carries the parameter meaning, the description adds minimal value here. 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: 'Monthly change feed for the ramen DB' and enumerates specific event types (new shops, closure candidates, web-verified closures, reopenings). This distinguishes it from siblings like get_ramen_shop (single shop lookup) and search_ramen/vibe_search (search tools). The unique capability of being a change feed is 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 gives explicit guidance on when to use this tool: 'This is the freshness signal you cannot cache: poll it to keep a local copy honest.' This clearly indicates it's for syncing and updates. It also mentions the optional `since` parameter for date filtering. While it doesn't explicitly say 'don't use this for X', the context strongly implies the right use case. It lacks explicit exclusions but is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one ramen shop by its stable id (rk_000001 style) — full record incl. address, coordinates, ramen style (keito), nearest station (Japan Station Master st_xxxx id + distance), tri-state payment facts, and the freshness block (first_seen/last_seen/status/closure evidence URL). No id? Pass name + pref instead and the best match is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Stable shop id, e.g. rk_000851. Preferred. | |
| city | No | Municipality (e.g. 松戸市) — alternative to pref; prefecture auto-resolved. | |
| name | No | Shop name (Japanese) — used with pref or city when id is unknown. | |
| pref | No | Prefecture (千葉県; short form 千葉 also OK) — pref or city required with name. |
| Name | Required | Description |
|---|---|---|
| shop | No | |
| error | No | Set when the shop was not found. |
| data_as_of | No | Dataset freshness date. |
| attribution | No | Data source(s), license and provenance — an object, or an array of sources. |
| definitions | No | Field definitions (or a note string in the no-auth preview). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond that: the 'best match' behavior when no id is supplied, and the fact that the full record contains specific fields including coordinates, station info, payment facts, and freshness block. 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?
A single dense sentence that front-loads the primary usage (fetch by id), then offers the alternative path, and lists the record contents efficiently. Every phrase earns its place, with no filler or 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 an output schema exists, the description does not need to explain return fields. The tool is a simple single-shop fetch with moderate complexity. The description covers both invocation paths and hints at the richness of the record. Annotations cover safety, and the schema covers parameters. Nothing essential is missing for an agent to call this 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 input schema covers all four parameters with descriptions, so coverage is 100% (baseline 3). The description adds value by signaling that 'id' is the preferred parameter and that name+pref (or city) are used as a fallback. It also clarifies the relationship between name and location parameters, which the schema does not explicitly connect.
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 verb 'Fetch' and the resource 'one ramen shop' with a stable id. It also explains the alternative lookup by name+pref, and the explicit list of fields distinguishes it from sibling tools like search_ramen or get_ramen_changes.
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 clear guidance on when to use the id parameter versus the name+pref alternative: 'No id? Pass name + pref instead'. It implies this tool is for fetching a single specific shop, but does not explicitly exclude scenarios where search_ramen would be more appropriate. The context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connection test / health check — call this first to confirm the server is reachable. Returns server identity, deploy version, and live data freshness (active shop count + the latest weekly-crawl date) so you can confirm the data is current, not just that the server is up. No auth, no arguments, lightweight.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| server | No | Server name. |
| status | No | Always "ok" when the server is reachable. |
| version | No | Deploy version. |
| coverage | No | Geographic coverage. |
| shops_active | No | Live count of active ramen shops in the dataset. |
| last_weekly_crawl | No | Date the dataset was last refreshed (YYYY-MM-DD). |
| rate_limit_noauth | No | No-auth rate limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: what the response contains (server identity, deploy version, active shop count, latest weekly-crawl date) and why it matters (confirming data currency, not just liveness). It also states 'no auth' and 'lightweight', which the annotations do not convey. This adds context without contradicting anything.
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?
Three sentences with zero filler, all functionally meaningful. The purpose is front-loaded in the first clause ('Connection test / health check — call this first'), and the return-value explanation and usage notes follow cleanly without redundancy. Each 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?
The tool has zero parameters and an output schema already present, so the description need not explain return values in detail. What it does add — that the response encodes data freshness, which is the non-obvious value of calling ping — elevates it beyond the minimum. Nothing an agent needs 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema, so baseline is 4. The description confirms 'no arguments' explicitly, and states no auth is required. There is no parameter naming, type, or format burden to carry, and the description aligns with the empty schema. Nothing more is needed.
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 uses a specific verb and resource ('call this first to confirm the server is reachable') and goes beyond a mere health check by stating the freshness purpose ('so you can confirm the data is current'). It clearly distinguishes itself from the sibling data-fetching tools (get_ramen_changes, get_ramen_shop, search_ramen, vibe_search), which all retrieve data rather than test connectivity.
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 gives explicit when-to-use guidance: 'call this first' to confirm the server is reachable. It frames ping as the pre-flight step before data queries. It does not name alternatives or spell out when not to use it, but the context is clear — siblings are all data-retrieval tools, and ping is positioned as the initial connectivity check. A brief mention of an alternative would have pushed this to a 5, but the placement is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| 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. |
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.
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.
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.
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.
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.
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.
Semantic / vibe search over the same nationwide ramen DB — describe what you feel like eating in natural language, English or Japanese ("rich creamy pork broth", "あっさり淡麗な醤油", "oily mazesoba", "tsukemen near Ebisu station"), and get the closest shops by meaning, each with a similarity score. Powered by multilingual embeddings (bge-m3), so English queries find shops with Japanese-only names. Role split: use search_ramen for exact facts (shop name lookup, keito/prefecture/status filters, geo radius) — use vibe_search for descriptive/fuzzy queries where no exact filter fits. Style rankings reflect only classified shops (~25%); unclassified shops still match by name and place. Tip: concrete food words (style, broth, richness, place, hours) match far better than abstract mood words ("stylish", "hardcore") — translate moods into concrete attributes before querying. Prefecture intent in the query text (北海道, 博多の…) is auto-applied as a filter (pref_source: inferred); region-style names (札幌ラーメン, 喜多方, 佐野…) stay pure style words and never restrict location. Dish-concept words (オロチョン, カラシビ, 台湾ラーメン/まぜそば, 勝浦タンタンメン) are expanded into their constituent style vocabulary before embedding (transparent via concept_expansion in the echoed query) — expansion never adds filters, so shops serving the dish always stay eligible; spicy-implying concepts additionally give spice-verified shops a small rank boost (concept_boost — a soft rerank, still no filter). Richness/hours inferred from the query text likewise act as a soft rank boost (attr_boost; attr_matched is informational) — only explicit richness/hours params and spiciness intent filter strictly.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Natural-language description, English or Japanese (e.g. "rich creamy pork bone broth", "辛い味噌", "brothless oily noodles"). | |
| pref | No | Optional prefecture filter, Japanese (東京都/千葉県, short 千葉 OK) or romaji (tokyo/osaka). | |
| hours | No | Optional hours filter: morning / late_night / 24h. Auto-inferred from the query text (朝/深夜/24時間…) when omitted. | |
| limit | No | Max results (default 10, max 20). | |
| spice | No | Deprecated alias of spice_level (kept for backward compatibility). | |
| status | No | Optional: active (default) / closed_confirmed / all. | |
| richness | No | Optional broth-richness filter from official-site enrichment: assari / kotteri / futsu / menu_varies. Auto-inferred from the query text (あっさり/こってり…) when omitted. | |
| venue_type | No | Optional venue filter: "permanent" (DEFAULT) / "popup" (limited-run event & department-store-fair appearances, excluded by default so results are places you can actually visit) / "all". | |
| spice_level | No | Optional spiciness ATTRIBUTE filter: "spicy" (shops whose signature is spiciness — chain signage or shop-name signal, dual-verified; ~1% of shops). Explicit value wins over query-text inference (辛い/激辛/spicy…; negations like 辛くない do not trigger). IMPORTANT: do NOT set this for dish/menu-name queries (オロチョンラーメン, カラシビ, 台湾まぜそば, 勝浦タンタンメン…) — many shops SERVING those dishes have no spice adjudication yet, so this hard filter would exclude them; leave it unset and the engine reaches them via concept expansion + menu-name matching. Set it only when the user asks for spicy shops in general. Orthogonal to keito: keito is style lineage, spice_level is an attribute — tantanmen alone never implies spicy. |
| Name | Required | Description |
|---|---|---|
| note | No | Human-readable note. |
| count | No | Results returned. |
| query | No | Echo of the resolved query — includes scene_expansion / concept_expansion when a scenario or dish-concept word (オロチョン, カラシビ, 台湾まぜそば…) was expanded into style vocabulary before embedding. |
| shops | No | Closest shops by meaning, best first. |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already signal safety, but the description adds substantial behavioral nuance: style rankings only cover ~25% of shops, prefecture intent auto-applied as a filter, concept expansion mechanics, soft vs hard filters (concept_boost, attr_boost), and the explicit warning that prefecture/region-style names stay pure style words. This is far beyond what annotations convey and fully transparent.
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?
Long but densely informative; every sentence earns its place. Purpose and usage split are front-loaded, followed by precise mechanics. No filler or redundancy. The structure flows from high-level guidance to nuance, making it easy to scan for the key decision (which tool to use) before diving into edge cases.
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 9 parameters, complex inference behavior, and soft/hard filter semantics, the description covers all relevant aspects: query language support, auto-application, concept expansion, rank boosts, and the unclassified-shop caveat. Output schema exists, so return values need no explanation. Nothing an agent needs to use this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter has a description, but the tool description adds critical meaning beyond schema: it explains auto-inference for pref/hours/richness, that explicit values win over inference, the spice_level pitfall for dish-name queries, and the distinction between hard filters and soft boosts. This adds semantic depth that the schema alone does not provide.
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 states a specific verb ('semantic / vibe search'), resource ('same nationwide ramen DB'), and output ('closest shops by meaning, each with a similarity score'). It explicitly distinguishes itself from the sibling tool search_ramen ('use search_ramen for exact facts... use vibe_search for descriptive/fuzzy queries'), so an agent can immediately tell them apart.
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?
Clear when-to-use vs when-not: 'use search_ramen for exact facts... use vibe_search for descriptive/fuzzy queries.' It also gives practical advice on query formulation (concrete food words vs abstract moods) and explicitly notes the split between exact filters and fuzzy search. This is actionable, not just generic context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_ramen_shop1 field changedOutput schema / properties / shop / properties / shop_typeAdded value: +{
+ "description": "senmon (ramen specialist) / machichuka (Chinese diner serving ramen); absent = unknown (never guessed)."
+}search_ramen7 fields changedInput schema / properties / shop_typeAdded value: +{
+ "description": "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.",
+ "type": "string"
+}Input schema / properties / venue_typeAdded value: +{
+ "description": "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.",
+ "type": "string"
+}Output schema / properties / fallbackAdded value: +{
+ "description": "true only when nothing matched and a relaxed alternative is offered (shops stays empty)."
+}Output schema / properties / fallback_reasonAdded value: +{
+ "description": "{code, message} — what was relaxed and why; relay this caveat to the user."
+}Output schema / properties / fallback_shopsAdded value: +{
+ "description": "Suggestions from the relaxed query. NOT matches for the original query.",
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / fallback_stepAdded value: +{
+ "description": "Which relaxation produced fallback_shops: semantic / spice_attribute / pref_summary."
+}Output schema / properties / shops / items / properties / shop_typeAdded value: +{
+ "description": "senmon (ramen specialist) / machichuka (Chinese diner serving ramen); absent = unknown (never guessed)."
+}vibe_search2 fields changedInput schema / properties / venue_typeAdded value: +{
+ "description": "Optional venue filter: \"permanent\" (DEFAULT) / \"popup\" (limited-run event & department-store-fair appearances, excluded by default so results are places you can actually visit) / \"all\".",
+ "type": "string"
+}Output schema / properties / shops / items / properties / shop_typeAdded value: +{
+ "description": "senmon (ramen specialist) / machichuka (Chinese diner serving ramen); absent = unknown (never guessed)."
+}vibe_search1 field changedInput schema / properties / spice_level / descriptionPrevious value: -"Optional spiciness ATTRIBUTE filter: \"spicy\" (shops whose signature is spiciness — chain signage or shop-name signal, dual-verified; ~1% of shops). Explicit value wins over query-text inference (辛い/激辛/オロチョン/spicy…; negations like 辛くない do not trigger). Orthogonal to keito: keito is style lineage, spice_level is an attribute — tantanmen alone never implies spicy."New value: +"Optional spiciness ATTRIBUTE filter: \"spicy\" (shops whose signature is spiciness — chain signage or shop-name signal, dual-verified; ~1% of shops). Explicit value wins over query-text inference (辛い/激辛/spicy…; negations like 辛くない do not trigger). IMPORTANT: do NOT set this for dish/menu-name queries (オロチョンラーメン, カラシビ, 台湾まぜそば, 勝浦タンタンメン…) — many shops SERVING those dishes have no spice adjudication yet, so this hard filter would exclude them; leave it unset and the engine reaches them via concept expansion + menu-name matching. Set it only when the user asks for spicy shops in general. Orthogonal to keito: keito is style lineage, spice_level is an attribute — tantanmen alone never implies spicy."vibe_search1 field changedOutput schema / properties / query / descriptionPrevious value: -"Echo of the resolved query."New value: +"Echo of the resolved query — includes scene_expansion / concept_expansion when a scenario or dish-concept word (オロチョン, カラシビ, 台湾まぜそば…) was expanded into style vocabulary before embedding."search_ramen1 field changedInput schema / properties / keito / descriptionPrevious value: -"Optional ramen-style filter. Coarse bucket (tonkotsu, miso, shoyu, shio, tsukemen, spicy, 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."New value: +"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."search_ramen1 field changedInput schema / properties / spice_levelAdded value: +{
+ "description": "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.",
+ "type": "string"
+}vibe_search2 fields changedInput schema / properties / spice / descriptionPrevious value: -"Optional spiciness filter: \"spicy\" (shops whose signature is spiciness — chain signage or shop-name signal, dual-verified; ~1% of shops). Auto-inferred from the query text (辛い/激辛/オロチョン/spicy…, negations like 辛くない do not trigger). tantanmen alone never implies spicy."New value: +"Deprecated alias of spice_level (kept for backward compatibility)."Input schema / properties / spice_levelAdded value: +{
+ "description": "Optional spiciness ATTRIBUTE filter: \"spicy\" (shops whose signature is spiciness — chain signage or shop-name signal, dual-verified; ~1% of shops). Explicit value wins over query-text inference (辛い/激辛/オロチョン/spicy…; negations like 辛くない do not trigger). Orthogonal to keito: keito is style lineage, spice_level is an attribute — tantanmen alone never implies spicy.",
+ "type": "string"
+}vibe_search1 field changedInput schema / properties / spiceAdded value: +{
+ "description": "Optional spiciness filter: \"spicy\" (shops whose signature is spiciness — chain signage or shop-name signal, dual-verified; ~1% of shops). Auto-inferred from the query text (辛い/激辛/オロチョン/spicy…, negations like 辛くない do not trigger). tantanmen alone never implies spicy.",
+ "type": "string"
+}vibe_search2 fields changedInput schema / properties / hoursAdded value: +{
+ "description": "Optional hours filter: morning / late_night / 24h. Auto-inferred from the query text (朝/深夜/24時間…) when omitted.",
+ "type": "string"
+}Input schema / properties / richnessAdded value: +{
+ "description": "Optional broth-richness filter from official-site enrichment: assari / kotteri / futsu / menu_varies. Auto-inferred from the query text (あっさり/こってり…) when omitted.",
+ "type": "string"
+}search_ramen1 field changedInput schema / properties / chain_subAdded value: +{
+ "description": "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.",
+ "type": "string"
+}search_ramen1 field changedInput schema / properties / chainAdded value: +{
+ "description": "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.",
+ "type": "string"
+}vibe_searchget_ramen_shop1 field changedOutput schema / properties / shop / properties / keito / descriptionPrevious value: -"Ramen style(s) if classified — string or array; usually absent."New value: +"Ramen style(s) if classified — fine 19-value vocabulary (tonkotsu/champon/toripaitan/asahikawa…); [] = unclassified."search_ramen2 fields changedInput schema / properties / keito / descriptionPrevious value: -"Optional ramen-style filter (coarse enum): tonkotsu, miso, shoyu, shio, tsukemen, spicy, other. (tonkotsu also covers iekei/家系 & jiro/二郎.) Only ~16% of shops carry a style; the rest are unclassified."New value: +"Optional ramen-style filter. Coarse bucket (tonkotsu, miso, shoyu, shio, tsukemen, spicy, 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."Output schema / properties / shops / items / properties / keito / descriptionPrevious value: -"Ramen style(s) if classified — string or array; usually absent."New value: +"Ramen style(s) if classified — fine 19-value vocabulary (tonkotsu/champon/toripaitan/asahikawa…); [] = unclassified."get_ramen_changesget_ramen_shoppingsearch_ramen
Add one secure layer between your agents and this server.