Skip to main content
Glama

unhcr-refugees-mcp-server

Describe staged dataframes

unhcr_dataframe_describe
Read-onlyIdempotent

Describe a dataframe (df_XXXXX_XXXXX) staged by the unhcr_get_* tools — any response carrying a dataset or nowcast_dataset handle staged its full result here — or list them all where this deployment allows listing. Each entry gives the source tool, query parameters, creation and expiry time, row count, whether the upstream fetch was complete, and the column schema. Read the columns here before writing SQL for unhcr_dataframe_query.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "unhcr_dataframe_describe"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoOne dataframe to describe, as df_XXXXX_XXXXX (uppercase letters and digits): the dataset.name or nowcast_dataset.name a unhcr_get_* result returned, or a register_as name. Omit to list every staged dataframe; a deployment that serves unauthenticated callers over HTTP turns listing off, and there the name is required.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when nothing is staged or the named dataframe is gone.
dataframesNoStaged dataframes, newest first. Empty when none are staged.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / name / description
      Previous value: -"One dataframe to describe, as df_XXXXX_XXXXX (uppercase letters and digits): the dataset.name a unhcr_get_* result returned, or a register_as name. Omit to list every staged dataframe; a deployment that serves unauthenticated callers over HTTP turns listing off, and there the name is required."New value: +"One dataframe to describe, as df_XXXXX_XXXXX (uppercase letters and digits): the dataset.name or nowcast_dataset.name a unhcr_get_* result returned, or a register_as name. Omit to list every staged dataframe; a deployment that serves unauthenticated callers over HTTP turns listing off, and there the name is required."
  2. Changed2 schema fields changed
    • addedOutput schema / properties / dataframes / items / properties / incomplete_sources
      Added value: +{
      +  "description": "Original incomplete upstream handles retained through saved descendants, even after those ancestors expire or are evicted.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / dataframes / items / required
      Previous value: -[
      -  "name",
      -  "source_tool",
      -  "query_params",
      -  "created_at",
      -  "expires_at",
      -  "row_count",
      -  "complete",
      -  "providers",
      -  "column_schema"
      -]New value: +[
      +  "name",
      +  "source_tool",
      +  "query_params",
      +  "created_at",
      +  "expires_at",
      +  "row_count",
      +  "complete",
      +  "incomplete_sources",
      +  "providers",
      +  "column_schema"
      +]
  3. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world safety, so the bar is lower, and the description still adds non-obvious behavior: every get_* response carrying a dataset or nowcast_dataset handle automatically staged its full result here. The entry-contents enumeration (source tool, query params, expiry, row count, completeness flag) is largely duplicated by the output schema, but the staging and listing-availability behavior is genuine added context.

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?

Two sentences, front-loaded with the core action and handle format, then the listing caveat. The mid-sentence list of entry fields is somewhat redundant with the output schema and lengthens the first sentence, but nothing is off-topic.

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 one-parameter read tool with full schema coverage, annotations, and an output schema, the description covers origin of the handle, listing behavior, preconditions, and the follow-up tool. Return-value detail is already in the output schema, so the remaining field enumeration is bonus rather than a gap.

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 coverage is 100% and the single name parameter is fully documented in the schema, including the pattern and the omit-to-list behavior, so baseline 3 applies. The description adds only light reinforcement (where the handle comes from, register_as), not syntax or format detail beyond 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?

States a specific verb (describe) and resource (a staged dataframe df_XXXXX_XXXXX), and ties it to the sibling family that produces those handles (unhcr_get_*) as well as the consumer tool (unhcr_dataframe_query). An agent can distinguish this from the query and get_* siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing: call this before writing SQL for unhcr_dataframe_query to learn the columns. It also flags the conditional mode (list-everything only 'where this deployment allows listing') and the fallback that name becomes required, which is exactly the kind of precondition an agent needs.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.