Skip to main content
Glama

list_concepts

Read-onlyIdempotent

List and filter data concepts by query, entity type, or concept family, with pagination, to discover variables and verified indicator entries for reading.

Instructions

List concepts (Variables) with their concept family; optionally filtered.

Paginated: rows are ordered by (entity_type, code, id) and a page returns at most limit rows (clamped to 1000). Page with increasing offset until a page comes back shorter than limit — that enumerates the full catalog even when one entity type exceeds the per-call cap.

The catalog also serves verified entries of the unified indicator registry (world_bank / gta_panel / china_city_panel / fd_open_data mirror sources). Registry rows are appended after the native rows, ordered by (domain, semantic_code); they carry additive native_code and source_db fields, so an entry is findable by either identifier, and a read_via hint naming the domain tool that serves its values. Reading a registry-only indicator: pass its semantic_code (or native_code) as concept_id to read / read_series — the read routes transparently through the indicator's source-database read channel. Entries whose semantic_code duplicates a non-deprecated native concept code are deduped (native row wins); deprecated legacy rows never shadow a verified entry.

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": "list_concepts"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNopage size, 1..1000 (default 500)
queryNooptional case-insensitive substring matched against code / name_en / name_zh (and native_code on registry rows); default None = unfiltered
offsetNorows to skip (default 0)
entity_typeNorestrict to one entity type (country, stock, ...) — registry rows carry no entity type and are excluded by this filter
concept_familyNorestrict to one concept family id (GDP, Population, ...) — registry rows carry no family and are excluded by this filter

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: result ordering by (entity_type, code, id), the 1000-row clamp, how to fully enumerate a large entity type, registry rows appended after native rows ordered by (domain, semantic_code), additive native_code/source_db fields, and the dedup rule where native rows win and deprecated rows never shadow verified entries.

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 line and pagination guidance follows immediately, so an agent can act on it quickly. The registry paragraph is dense with backticked identifiers and dedup corner cases, but each clause carries behavioral information rather than filler; only the dedup/shadowing sentence feels marginally over-detailed for a listing tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paginated catalog tool that merges native concepts with registry entries, the description covers enumeration strategy, ordering, filter interactions, dedup precedence, and how to follow a discovered registry indicator into read/read_series. With annotations supplying the safety profile and an output schema supplying return shape, nothing an agent needs in order to call this 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%, so limit/query/offset/entity_type/concept_family are already documented, including the clamp to 1000 and the fact that registry rows are excluded by entity_type/concept_family filters. The description adds real meaning about ordering relative to offset paging and the page-shortness termination signal, but most parameter behavior is duplicated from the schema, keeping this at the baseline 3.

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?

States a specific verb and resource ('List concepts (Variables) with their concept family'), plus the optional-filter scope in the same sentence. The second half clarifies that the catalog also surfaces unified-registry entries, so the agent knows the result set is broader than native concepts. It does not explicitly distinguish itself from siblings such as list_concept_families or list_registry_entries, which keeps it below a 5.

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?

Gives actionable routing guidance: 'Reading a registry-only indicator: pass its semantic_code (or native_code) as concept_id to read / read_series', which tells the agent this tool is for discovery and read/read_series for values. It also prescribes the paging procedure (increase offset until a page is shorter than limit). No explicit when-not-to-use statement or comparison to list_registry_entries, so not a 5.

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