Skip to main content
Glama

read

Idempotent

Fetch concept values for an entity across dates, resolving concepts to ranked sources with cache and failover; optionally return all source rows for comparison.

Instructions

Read a concept for an entity over dates (read-through cache + ranked dispatch).

Local concepts: concept_id is the numeric id; entity_type/entity_id/dates are required; source pins the read (and any dispatch) to one source; all_sources returns every held row per date, best-ranked first, without dispatching — for cross-source comparison.

Registry-only indicators (catalog rows with id=None): pass the semantic_code (or native_code) as concept_id — the read is routed transparently through the indicator's source-database read channel and returns the same row shape; entity carries the region/country/city name when the channel needs one (world_bank requires it). Provenance travels in source_used.

scope (optional): restrict this call to a named retrieval scope — an indicator outside the scope returns an explicit out-of-scope response; the reserved name unscoped forces the full corpus.

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": {
      "concept_id": "<concept_id>"
    },
    "name": "read"
  }
}

Input Schema

NameRequiredDescriptionDefault
datesNo
scopeNo
entityNo
sourceNo
entity_idNo
concept_idYes
all_sourcesNo
entity_typeNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Beyond the annotations, the description discloses genuinely useful behavior: read-through caching, ranked dispatch to a source-database channel, that all_sources suppresses dispatch, that out-of-scope indicators return an explicit out-of-scope response, and that provenance travels in source_used. It also implicitly explains why readOnlyHint is false (cache/dispatch side effects) and fits openWorldHint=true. Rate limits, auth requirements, and failure modes are not covered.

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 purpose is front-loaded in the first sentence, then the definition is organized by mode (local, registry-only, scope), which matches how an agent would branch. It is dense but nearly every clause carries information; the backtick-heavy formatting adds minor visual noise.

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?

This is a complex eight-parameter tool with no schema descriptions, and the description supplies the mode logic, dispatch semantics, provenance field, and scope behavior an agent needs to call it correctly; an output schema exists so return values needn't be restated. The unresolved contradiction about which fields are required is the main completeness gap.

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 description coverage is 0%, so the description must carry all eight parameters, and it largely does: concept_id (numeric id or semantic_code/native_code string), entity, entity_type, entity_id, dates, source, all_sources, and scope (including the reserved 'unscoped' value) are all explained. One flaw: it asserts 'entity_type/entity_id/dates are required' while the schema requires only concept_id and defaults dates to null, so the agent gets a conflicting picture of requiredness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource plus scope: 'Read a concept for an entity over dates (read-through cache + ranked dispatch)'. It also carves out two distinct modes (local concepts vs registry-only indicators), so an agent can recognize what the tool does. It stops short of distinguishing itself from siblings such as read_series or fetch, which read data in adjacent ways.

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

Usage Guidelines3/5

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

Guidance is given at the parameter level rather than the tool level: 'source pins the read', 'all_sources ... for cross-source comparison', and 'scope ... restrict this call'. That tells an agent which mode to pick within the tool, but nothing says when to choose this tool over another read-style sibling, and no when-not conditions are stated.

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