Key Takeaways
- Geologic AI tools can answer “what is recorded in the area this map shows?”, such as past earthquakes or known faults. First, though, the program needs to know where on Earth the map sits.
- If someone has already pinned the map to real coordinates, the program reuses that saved position. You do not have to type the area in again.
- The program does not write the answer itself. It hands back records and warnings, and the AI assistant you are talking to turns them into a reply.
TL;DR
Once you load a scanned map into the program, which gives it an ID (this is what “registered” means), and pin it to the Earth, you can ask about it by that ID. The program works out the area from what it saved earlier and looks up what is recorded there. The most common reason it fails is simple: nobody pinned the map.
What Is geomap_query_map?
geomap_query_map is the map-aware knowledge lookup in Stratigraphic Amenity, Eigenform’s open-source (MIT) MCP server for scanned geologic maps. It takes a registered map’s map_id or map_uri, but not both, and works out which area and legend labels to ask about.
A registered map is a scanned map that has already been loaded into the server with geomap_register_map. Registration gives it a permanent ID and a geomap://maps/<id> address, like a catalogue number in a library. It does not place the map on the Earth: tying it to real coordinates is a separate step called georeferencing.
Then it runs the same query as looking up earthquakes, faults and minerals for a bounding box. It accepts every option that tool does: include, exclude, record limits and provider_options.
The result is the same knowledge bundle, with one difference: it links to the map. The server lists it against that map, so geologic AI agents can trace which results belong to which sheet.
How Does geomap_query_map Fill In Bounds and Labels?
For each input it takes the first value it finds, in a fixed order.
Bounds: explicit, then metadata, then stored georeference
The tool checks the bounds argument first, then bounds inside the metadata object. Only then does it read the map’s stored georeference, the latest revision that the georef.json alias points to.
That order has two practical effects. Explicit bounds win even on a georeferenced map, so an agent can query a smaller box inside the sheet. And georeferencing the map again changes the bounds every later query uses.
Legend labels: explicit, then metadata, then stored processing
Labels follow the same pattern. The tool reads the legend_labels argument, then labels in metadata, either as a legend_labels list or as legend entries with a label or text field. Last, it reads the labels saved during map processing.
That last step finds nothing in this build. Map part detection reads no text, so every stored legend label is null. Labels only reach the rock-type and rock-age providers when the user, or a separate OCR or vision model, supplies them.
When there is nothing to go on
With no bounds and no labels from any source, the call fails with georef_required: “query_map needs stored georef bounds, explicit bounds, or legend labels.” The usual fix is to georeference the map first.
The MCP tool does not work out bounds from control points passed in metadata. Only the Python SDK’s KnowledgeService.query_map does that.
What the Question Does, and What It Doesn’t
The tool passes the question argument on as query_text. Only the three semantic search providers use it (rock_knowledge, component_usage_knowledge and downstream_task_knowledge), and all three are off by default. They also need the knowledge-semantic extra, which installs Sentence Transformers.
Without include, a question changes nothing about the earthquake or fault records. The result simply notes that the semantic providers were not consulted, for example “Compatible provider ‘rock_knowledge’ was not consulted because it is disabled by default.”
So the server does not answer in sentences. It returns records, warnings and provenance, and the geologic AI agent writes the answer from them. Each call also saves a new bundle, so repeating a question adds another bundle rather than replacing the last one.
FAQs
Do I need to georeference a map before using geomap_query_map?
In practice, yes. The tool needs bounds or legend labels, and detection stores no labels in this build. A georeferenced map supplies bounds automatically. Without one, pass bounds or legend_labels yourself, or the call fails with georef_required and names what is missing.
Why does my map query find no legend labels?
The detector finds legend swatches but reads no text, so stored labels are null. The tool then has no labels to send to the rock-type and rock-age providers. Supply labels in legend_labels, from the user or a separate OCR or vision model, never by guessing from the picture.
Can I query a smaller area than the whole map?
Yes. Explicit bounds take priority over the map’s stored georeference, so you can pass a box around one part of the sheet. The bundle still links to the map. Keep the box inside the sheet if you plan to plot the results on it.
Does geomap_query_map answer my question in words?
No. The question only feeds the semantic search providers, and only when they are included. The tool returns a knowledge bundle of records, warnings and provenance. A geologic AI agent reads that bundle and writes the answer, citing the sources and reporting empty results as gaps rather than proof.
Try It With Geocluster
Stratigraphic Amenity is one of the Geocluster tools, MCP servers that let AI agents work with geology data and maps.
Before the first map query, an agent checks what the map server can do, including which knowledge providers are ready.
