Skip to main content
Glama

Japan Agent API

by io.github.mk-career-planning
OverviewDiscussionsAdmin

Japan volcanic alert levels (JMA)

jp_volcanoes
Read-only

What is the current JMA Volcanic Alert Level (1-5, or warning kind) of this volcano or of every JMA-monitored volcano? Name in English or Japanese, or 3-digit JMA code. Returns JMA English and Japanese names, level, previous level and change, issue time, prefectures named in JMA bulletins, source URL and freshness receipt. Relay only; no forecast or interpretation. Gaps filled from JMA website lists (newer wins). No JMA source seen = not_seen_in_checked_feeds, never assumed level 1.

Input Schema

NameRequiredDescriptionDefault
volcanoNoOptional. JMA volcano name in English (e.g. "Sakurajima", "Asamayama") or Japanese (e.g. "桜島"), or the 3-digit JMA volcano code (e.g. "506"). Omit to list all volcanoes.

Output Schema

NameRequiredDescriptionDefault
noteYes
countYes
termsYesURL of the terms of service.
sourceYesData source and processor.
coverageYescomplete = every volcano has a usable state (from an XML bulletin, warning.json or the monthly national summary) and no bulletin is pending or failed.
volcanoesYesOne entry per volcano.
provenanceYesFreshness receipts for every upstream source used.
license_noteYes
responded_atYes
retrieved_atYesWhen the upstream data was retrieved (ISO 8601).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedOutput schema / properties / coverage / description
      Added value: +"complete = every volcano has a usable state (from an XML bulletin, warning.json or the monthly national summary) and no bulletin is pending or failed."
    • addedOutput schema / properties / coverage / properties / volcanoes_not_seen
      Added value: +{
+  "type": "number"
+}
    • changedOutput schema / properties / coverage / required
      Previous value: -[
-  "status",
-  "tracking_since",
-  "volcanoes_total",
-  "volcanoes_listed"
-]New value: +[
+  "status",
+  "tracking_since",
+  "volcanoes_total",
+  "volcanoes_listed",
+  "volcanoes_not_seen"
+]
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "count": {
+      "type": "number"
+    },
+    "coverage": {
+      "additionalProperties": {},
+      "properties": {
+        "status": {
+          "enum": [
+            "complete",
+            "partial"
+          ],
+          "type": "string"
+        },
+        "tracking_since": {
+          "type": "string"
+        },
+        "volcanoes_listed": {
+          "type": "number"
+        },
+        "volcanoes_total": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "status",
+        "tracking_since",
+        "volcanoes_total",
+        "volcanoes_listed"
+      ],
+      "type": "object"
+    },
+    "license_note": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "provenance": {
+      "description": "Freshness receipts for every upstream source used.",
+      "items": {
+        "additionalProperties": {},
+        "description": "Freshness receipt for one upstream source.",
+        "properties": {
+          "content_sha256": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "fetch_status": {
+            "description": "found / empty / stale / unavailable / unsupported (see catalog fetch_status_values).",
+            "enum": [
+              "found",
+              "empty",
+              "stale",
+              "unavailable",
+              "unsupported"
+            ],
+            "type": "string"
+          },
+          "parser_version": {
+            "type": "string"
+          },
+          "processed_by": {
+            "type": "string"
+          },
+          "retrieved_at": {
+            "description": "When this service retrieved the upstream data (null if unknown).",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source": {
+            "additionalProperties": {},
+            "description": "Publisher and URL of the upstream document or dataset.",
+            "properties": {
+              "publisher": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "publisher",
+              "url"
+            ],
+            "type": "object"
+          },
+          "upstream_updated_at": {
+            "description": "Update time stated by the upstream, or null when it states none.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "source",
+          "upstream_updated_at",
+          "retrieved_at",
+          "content_sha256",
+          "parser_version",
+          "fetch_status",
+          "processed_by"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "responded_at": {
+      "type": "string"
+    },
+    "retrieved_at": {
+      "description": "When the upstream data was retrieved (ISO 8601).",
+      "type": "string"
+    },
+    "source": {
+      "description": "Data source and processor.",
+      "type": "string"
+    },
+    "terms": {
+      "description": "URL of the terms of service.",
+      "type": "string"
+    },
+    "volcanoes": {
+      "description": "One entry per volcano.",
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "alert_level": {
+            "description": "Volcanic Alert Level 1-5, or null for volcanoes without levels.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "code": {
+            "description": "3-digit JMA volcano code.",
+            "type": "string"
+          },
+          "issued_at": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "name": {
+            "additionalProperties": {},
+            "properties": {
+              "en": {
+                "type": "string"
+              },
+              "ja": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "ja",
+              "en"
+            ],
+            "type": "object"
+          },
+          "provenance": {
+            "description": "Freshness receipts for every upstream source used.",
+            "items": {
+              "additionalProperties": {},
+              "description": "Freshness receipt for one upstream source.",
+              "properties": {
+                "content_sha256": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "fetch_status": {
+                  "description": "found / empty / stale / unavailable / unsupported (see catalog fetch_status_values).",
+                  "enum": [
+                    "found",
+                    "empty",
+                    "stale",
+                    "unavailable",
+                    "unsupported"
+                  ],
+                  "type": "string"
+                },
+                "parser_version": {
+                  "type": "string"
+                },
+                "processed_by": {
+                  "type": "string"
+                },
+                "retrieved_at": {
+                  "description": "When this service retrieved the upstream data (null if unknown).",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "source": {
+                  "additionalProperties": {},
+                  "description": "Publisher and URL of the upstream document or dataset.",
+                  "properties": {
+                    "publisher": {
+                      "type": "string"
+                    },
+                    "url": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "publisher",
+                    "url"
+                  ],
+                  "type": "object"
+                },
+                "upstream_updated_at": {
+                  "description": "Update time stated by the upstream, or null when it states none.",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "source",
+                "upstream_updated_at",
+                "retrieved_at",
+                "content_sha256",
+                "parser_version",
+                "fetch_status",
+                "processed_by"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "source_url": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "enum": [
+              "listed",
+              "not_seen_in_checked_feeds",
+              "unavailable"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "name",
+          "status",
+          "alert_level",
+          "issued_at",
+          "source_url",
+          "provenance"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "coverage",
+    "count",
+    "volcanoes",
+    "note",
+    "provenance",
+    "source",
+    "retrieved_at",
+    "responded_at",
+    "license_note",
+    "terms"
+  ],
+  "type": "object"
+}
  3. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the readOnly/openWorld annotations, the description discloses the full return shape, the relay-only/no-interpretation contract, the provenance rule ('Gaps filled from JMA website lists (newer wins)'), and the critical failure semantics ('No JMA source seen = not_seen_in_checked_feeds, never assumed level 1'). That last clause is exactly the kind of anti-hallucination guidance an agent needs and that annotations cannot supply.

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 question-form opening is front-loaded and every clause carries weight: formats, return fields, relay policy, provenance, and the not_seen_in_checked_feeds rule. It is dense rather than padded, though the enumerated return fields are partly redundant with the output schema.

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?

An output schema exists so return values did not need describing, yet the operational gaps are all covered: scope, input formats, provenance, currency (issue time, freshness receipt), and the no-source failure mode. Slightly over-explains the payload, but 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.

Parameters3/5

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

Schema description coverage is 100% and the single parameter already documents the accepted name formats and omission behavior, so the schema carries the burden. The description restates the same formats and adds only the scope phrase 'of every JMA-monitored volcano', giving it marginal value over structured data.

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+resource: 'current JMA Volcanic Alert Level (1-5, or warning kind)' for a named volcano or all JMA-monitored volcanoes. Success criteria and lookup keys (English/Japanese name or 3-digit JMA code) are stated, and the volcanic domain distinguishes it from siblings like jp_typhoons and jp_warnings.

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?

Usage context is clear: pass a name/code for one volcano, omit to list every JMA-monitored volcano. It also sets a downstream behavioral expectation ('Relay only; no forecast or interpretation'). It does not explicitly name alternatives or when-not-to-use cases against the sibling warning/typhoon tools, 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.

All Japan Agent API toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources