Skip to main content
Glama

Ask a free-text question about a place

emem_ask

Answers a free-text question about a specific real-world place in one call, returning a packaged answer with signed satellite, elevation, water and built-up evidence.

Instructions

Answer a free-text question about a real-world location in one call. Signed satellite, elevation, water and built-up receipts support the answer. The tool sends the place and the question through the locate, recall and algorithm chain on the server, and returns one packaged envelope.

When to use: Call this when the question is about a specific place and the answer must carry its evidence. Send the question as q, with place, cell or lat+lng. Over MCP a point answer is a projection. It has answer, direct_answer (verdict, band, rule, date, limits), receipt (cite receipt.fact_cids), place_resolved, routed_to, context and spatial_trace. It has model_answer if you sent model, and _projection, which names what the projection removed. research_nearby holds pointers to signed research conclusions; read them with emem_inferences. POST /v1/ask has more, such as caveats and reasoning. A past date never gets the newest reading. Send context.context_id as context_id to continue a thread. For how X changed, use emem_intent did_change or emem_diff.

Example arguments: {"q":"is this neighbourhood flood-prone for a flat purchase","place":"Ashok Nagar, Ranchi"}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "emem_ask"
  }
}

Input Schema

NameRequiredDescriptionDefault
qYesUser's natural-language question about the place (e.g. "is this neighbourhood flood-prone").
latNoWGS-84 latitude (paired with `lng`; alternative to `place` / `cell`).
lngNoWGS-84 longitude (paired with `lat`).
cellNocell64 string (alternative to `place`, use when you have one from a prior emem_locate / emem_recall response). Provide this OR `place` OR `lat`+`lng`.
dateNoYYYY-MM-DD, YYYY-MM or YYYY.
modelNoOptional. Compose an EXTRA prose answer with a named model, returned as `model_answer` beside the deterministic `answer`. It does not replace it: `answer` is synthesised from the structured fields and never calls a model, so every number in it traces to a fact_cid, and asking for a model must not turn a checkable answer into an unchecked one. `model_answer` carries provenance.class = model_output. Name it by base_model (`nvidia/Cosmos3-Edge`), by family (`cosmos3_edge`, `gemma`), or by any fragment naming exactly one of them (`cosmos`); a fragment matching several is refused and names them; an unroutable name is refused with the list of routable ones, and a routable model whose service is not answering is refused as busy or down rather than silently substituted. Cosmos is refused while its host has no GPU.
placeNoFree-text place name (e.g. "Mount Fuji", "Ashok Nagar, Ranchi"). REQUIRED unless `cell` or `lat`+`lng` is provided. Extract the noun phrase from the user's turn; the responder geocodes via OSM Nominatim.
queryNoAlias for `q`.
includeNoOpt-in REST envelope sections. `reasoning` drops `algorithms_for_question`; add `algorithms` to keep it. The MCP projection ignores these.
verboseNoREST only: true adds per-algorithm formulas, band metadata and long prose. The MCP projection is small (about 7 KB) either way; the REST envelope is larger.
questionNoAlias for `q`.
context_idNo`context.context_id` from an earlier answer.
include_imageNoBundle a Sentinel-2 RGB scene URL for the resolved cell. Adds ~1-2 s on first call.

Output Schema

NameRequiredDescriptionDefault
cellNoThe cell64 the question resolved to: emem's address for the place.
_meansNo
answerNoThe prose answer. Also in the content block, which carries the MCP projection; POST /v1/ask has the full envelope.
schemaYes
questionNoThe question as asked.
spatial_traceYesA spatial memory trace: what this responder has measured at this place, as primitives a model can reason over rather than a picture a person looks at.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.4.6
    • addedInput schema / properties / context_id
      Added value: +{
      +  "description": "`context.context_id` from an earlier answer.",
      +  "type": "string"
      +}
    • addedInput schema / properties / date
      Added value: +{
      +  "description": "YYYY-MM-DD, YYYY-MM or YYYY.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / spatial_trace / properties / layers / items / properties / points / items / properties / value / description
      Previous value: -"The measured value, in the band's own units. `null` where the band was looked for and not found: an absence is a reading."New value: +"A scalar, in the band's units. null for a vector or record: see value_kind and value_summary."
  2. Changed5 schema fields changedv2.4.4
    • changedInput schema / properties / include / description
      Previous value: -"Opt-in heavy response sections. Default response is slim (~5 KB): answer + algorithm key + fact_cids + caveats. Name specific sections to include them. Ignored when verbose=true (which includes everything)."New value: +"Opt-in REST envelope sections. `reasoning` drops `algorithms_for_question`; add `algorithms` to keep it. The MCP projection ignores these."
    • changedInput schema / properties / include / items / enum
      Previous value: -[
      -  "band_observations",
      -  "algorithm_outcomes",
      -  "facts_full",
      -  "temporal_composition",
      -  "foundation_embeddings",
      -  "scene",
      -  "inventory"
      -]New value: +[
      +  "band_observations",
      +  "algorithm_outcomes",
      +  "facts_full",
      +  "temporal_composition",
      +  "scene",
      +  "inventory",
      +  "reasoning",
      +  "algorithms"
      +]
    • changedInput schema / properties / model / description
      Previous value: -"Optional. Compose an EXTRA prose answer with a named model, returned as `model_answer` beside the deterministic `answer`. It does not replace it: `answer` is synthesised from the structured fields and never calls a model, so every number in it traces to a fact_cid, and asking for a model must not turn a checkable answer into an unchecked one. `model_answer` carries provenance.class = model_output. Name it by base_model (`nvidia/Cosmos3-Edge`), by family (`cosmos3_edge`, `gemma`), or by any fragment naming exactly one of them (`cosmos`); a fragment matching several is refused and names them; an unroutable name is refused with the list of routable ones, and a routable model whose service is not answering is refused as busy or down rather than silently substituted. Cosmos deliberates and typically takes 13-22 s."New value: +"Optional. Compose an EXTRA prose answer with a named model, returned as `model_answer` beside the deterministic `answer`. It does not replace it: `answer` is synthesised from the structured fields and never calls a model, so every number in it traces to a fact_cid, and asking for a model must not turn a checkable answer into an unchecked one. `model_answer` carries provenance.class = model_output. Name it by base_model (`nvidia/Cosmos3-Edge`), by family (`cosmos3_edge`, `gemma`), or by any fragment naming exactly one of them (`cosmos`); a fragment matching several is refused and names them; an unroutable name is refused with the list of routable ones, and a routable model whose service is not answering is refused as busy or down rather than silently substituted. Cosmos is refused while its host has no GPU."
    • changedInput schema / properties / verbose / description
      Previous value: -"When true, return the full envelope: per-algorithm formula strings, temporal_recipe blocks, per-fact band_metadata duplicates, and the long _explanation prose. Default (since 2026-05-05) is false so the response fits MCP's 25 KB cap; the signed receipt + fact CIDs + algorithm keys + algorithms_cid are always retained. Pass true to get the full body when debugging."New value: +"REST only: true adds per-algorithm formulas, band metadata and long prose. The MCP projection is small (about 7 KB) either way; the REST envelope is larger."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "_means": {
      +      "type": "string"
      +    },
      +    "answer": {
      +      "description": "The prose answer. Also in the content block, which carries the MCP projection; POST /v1/ask has the full envelope.",
      +      "type": "string"
      +    },
      +    "cell": {
      +      "description": "The cell64 the question resolved to: emem's address for the place.",
      +      "type": "string"
      +    },
      +    "question": {
      +      "description": "The question as asked.",
      +      "type": "string"
      +    },
      +    "schema": {
      +      "const": "emem.ask_structured.v1",
      +      "type": "string"
      +    },
      +    "spatial_trace": {
      +      "description": "A spatial memory trace: what this responder has measured at this place, as primitives a model can reason over rather than a picture a person looks at.",
      +      "properties": {
      +        "absent": {
      +          "description": "Bands this responder looked for and did not find. Absence is evidence: without it a consumer infers coverage nobody measured.",
      +          "items": {
      +            "properties": {
      +              "band": {
      +                "type": "string"
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "at": {
      +          "description": "[lat, lng] of the cell, so a point has a position without a second call.",
      +          "items": {
      +            "type": "number"
      +          },
      +          "type": "array"
      +        },
      +        "cell": {
      +          "type": "string"
      +        },
      +        "counts": {
      +          "description": "Totals taken BEFORE any cap, so truncation can be seen rather than guessed.",
      +          "properties": {
      +            "absent": {
      +              "type": "integer"
      +            },
      +            "absent_shown": {
      +              "type": "integer"
      +            },
      +            "points_shown": {
      +              "type": "integer"
      +            },
      +            "present": {
      +              "type": "integer"
      +            }
      +          },
      +          "type": "object"
      +        },
      +        "layers": {
      +          "description": "Points grouped by what kind of evidence they are: surface (what the ground is), built (what stands on it), now (what is happening there), embedding (vectors for similarity). A layer absent from this list means the question never reached that kind of evidence; a band looked for and not found is in `absent` instead.",
      +          "items": {
      +            "properties": {
      +              "layer": {
      +                "enum": [
      +                  "surface",
      +                  "built",
      +                  "now",
      +                  "embedding",
      +                  "other",
      +                  "ground"
      +                ],
      +                "type": "string"
      +              },
      +              "points": {
      +                "description": "One per signed reading.",
      +                "items": {
      +                  "properties": {
      +                    "age_s": {
      +                      "description": "How old the reading was when this answer was written.",
      +                      "type": "integer"
      +                    },
      +                    "band": {
      +                      "type": "string"
      +                    },
      +                    "class": {
      +                      "description": "Provenance class: direct_sensor, deterministic_index, estimator, model_output, attested_execution, human_curated, unclassified. What KIND of claim this is.",
      +                      "type": "string"
      +                    },
      +                    "f": {
      +                      "description": "Index into `receipt.fact_cids` (or the list `_projection.fact_cids_at` names). Dereference it for the signed bytes.",
      +                      "type": "integer"
      +                    },
      +                    "unit": {
      +                      "type": "string"
      +                    },
      +                    "value": {
      +                      "description": "The measured value, in the band's own units. `null` where the band was looked for and not found: an absence is a reading.",
      +                      "type": [
      +                        "number",
      +                        "string",
      +                        "boolean",
      +                        "null"
      +                      ]
      +                    }
      +                  },
      +                  "required": [
      +                    "band",
      +                    "value"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              }
      +            },
      +            "required": [
      +              "layer",
      +              "points"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "schema": {
      +          "const": "emem.spatial_trace.v1",
      +          "type": "string"
      +        },
      +        "stage": {
      +          "description": "Which stage of the answer grounded these readings.",
      +          "type": "string"
      +        },
      +        "truncated": {
      +          "type": "boolean"
      +        }
      +      },
      +      "required": [
      +        "schema",
      +        "layers",
      +        "counts"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "schema",
      +    "spatial_trace"
      +  ],
      +  "type": "object"
      +}
  3. Changed1 schema field changedv2.2.1
    • addedInput schema / properties / model
      Added value: +{
      +  "description": "Optional. Compose an EXTRA prose answer with a named model, returned as `model_answer` beside the deterministic `answer`. It does not replace it: `answer` is synthesised from the structured fields and never calls a model, so every number in it traces to a fact_cid, and asking for a model must not turn a checkable answer into an unchecked one. `model_answer` carries provenance.class = model_output. Name it by base_model (`nvidia/Cosmos3-Edge`), by family (`cosmos3_edge`, `gemma`), or by any fragment naming exactly one of them (`cosmos`); a fragment matching several is refused and names them; an unroutable name is refused with the list of routable ones, and a routable model whose service is not answering is refused as busy or down rather than silently substituted. Cosmos deliberates and typically takes 13-22 s.",
      +  "type": "string"
      +}
  4. Changed2 schema fields changedv1.3.8
    • addedInput schema / properties / query
      Added value: +{
      +  "description": "Alias for `q`.",
      +  "type": "string"
      +}
    • addedInput schema / properties / question
      Added value: +{
      +  "description": "Alias for `q`.",
      +  "type": "string"
      +}
  5. Changed1 schema field changedv1.3.1
    • changedInput schema / properties / cell / description
      Previous value: -"cell64 string (alternative to `place` — use when you have one from a prior emem_locate / emem_recall response). Provide this OR `place` OR `lat`+`lng`."New value: +"cell64 string (alternative to `place`, use when you have one from a prior emem_locate / emem_recall response). Provide this OR `place` OR `lat`+`lng`."
  6. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations declare openWorld, non-read-only and non-idempotent, and the description adds real behaviour the annotations cannot: the MCP response is a projection with `_projection` naming what was removed, POST /v1/ask carries more fields, a past date never returns the newest reading, and `include_image` costs ~1-2 s. It never explains the side effect that makes the call non-read-only/idempotent, which is the one gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the when-to-use clause follows immediately, but the middle section enumerates envelope fields and explains the MCP-vs-REST projection at length, which is denser than an agent needs before invoking. Some of that belongs in the output schema, which already exists.

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?

For a 13-parameter, open-world tool with an output schema, the description covers inputs, projection limits, model refusal behaviour and the follow-up path via `research_nearby`. Missing only what the non-read-only annotation implies about server-side side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/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 beyond it: send `context.context_id` as `context_id` to continue a thread, `q` needs one of `place`/`cell`/`lat`+`lng`, and `model` produces an extra `model_answer` without replacing the deterministic answer. Those routing and provenance rules are not obvious from the schema.

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?

"Answer a free-text question about a real-world location in one call" gives a specific verb and resource, and the description separates it from emem_intent did_change/emem_diff and points to emem_inferences for reading research pointers. An agent can tell what this does and roughly where it sits in the family.

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?

An explicit "When to use" clause sets the condition (question about a specific place whose answer must carry evidence), and it names an alternative for change-over-time questions. It does not cover when to prefer emem_locate or emem_recall for lookup-only needs, so the alternative space is only partly mapped.

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