Skip to main content
Glama

data_stats

Read-onlyIdempotent

Summarize observation coverage and catalog health with aggregate counts or filtered per-concept details on stored rows, gaps, stale data, and source stores.

Instructions

Observation coverage: a fast aggregate summary, or per-concept detail.

Default (no arguments): an aggregate summary — total_concepts (catalog size), covered_concepts (routable and crawled, the same figure coverage_report reports), concepts_with_observations (raw distinct concepts holding rows), total_stored_rows, gap_concepts / stale_concepts, and a per-entity-type rollup — plus a stores section from the latest data census (local master exact + each shard's catalog-based estimate, chunk count, data time-range end). total_stored_rows counts stored ROWS: sources coexist per point, so two sources on one point count twice; the per-concept listing below counts distinct observation points instead.

The per-concept listing (point count, latest date, distinct sources, most recent fetch) is returned only when narrowed — pass concept_id or entity_type for a filtered listing, or detail=True for the unfiltered one. That listing sweeps the observations table and is deliberately not the default.

Read-only: census rows are READ, never collected (refresh via the panel action or the census CLI). The same data powers the panel's /panel/data page.

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

Input Schema

NameRequiredDescriptionDefault
detailNoReturn the full per-concept listing even without filters.
concept_idNoRestrict the per-concept listing to one concept.
entity_typeNoRestrict the per-concept listing to one entity type.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered by structured data. The description's real additions are cost behavior (the unfiltered listing sweeps the observations table) and the counting semantics of total_stored_rows versus distinct observation points, which are useful non-obvious traits. The side note that 'the same data powers the panel's /panel/data page' is filler rather than behavioral disclosure.

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?

The mode distinction is front-loaded and the cost warning is well placed, but the text is bloated with parentheticals, backticked field lists, and repetition of 'the per-concept listing' across two paragraphs. The closing sentence about the /panel/data page and the census-CLI aside could be cut without losing any decision-relevant information.

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?

An output schema exists, so the lengthy return-value enumeration is over-delivery rather than a requirement, yet the description still covers the mode selection, the cost asymmetry, and the read-only guarantee fully. Nothing an agent needs to call this correctly or interpret the response 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 coverage is 100% and each of the three parameters already carries a description, so the baseline is 3. The description does add meaning by explaining the interaction between the no-argument default and the narrowing parameters, plus that detail=True bypasses the filter requirement, but it largely restates what the schema fields say.

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 line names the resource and the two modes: an aggregate coverage summary or a per-concept detail listing. It goes further by enumerating the exact aggregate fields returned (total_concepts, covered_concepts, gap_concepts, stores, etc.), so an agent can predict the payload. It also explicitly notes that covered_concepts is 'the same figure coverage_report reports', which partly differentiates it from that sibling, though it stops short of stating a clean division of labor.

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?

It gives concrete routing rules: no arguments yields the aggregate, concept_id/entity_type narrow to a filtered listing, and detail=True forces the expensive unfiltered listing. It also warns that the listing 'sweeps the observations table and is deliberately not the default', which is exactly the cost trade-off an agent needs, and redirects refresh work to the panel action or the 'census' CLI. The only gap is that it never says when to prefer coverage_report over data_stats, despite acknowledging they report the same figure.

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