Skip to main content
Glama
Sign In

NicheDB

by dev.nichedb
OverviewDiscussionsAdmin

population

Read-onlyIdempotent

Population and demography, drilled down from the world to the ZIP code. Give a key (us, us-ca, us-ca-los-angeles, gb, gb-england-london), a US zip, or a place name in q; no argument is the world. Answers with the area (population, year, measures: age, income, home value, rent, poverty, education, unemployment, race and Hispanic origin for the US; growth, age structure, births, deaths, fertility, life expectancy, migration, GDP per head and Gini for countries), how many areas of each level it contains, and the largest of its children at level (country, state, city or zip). Sources: World Bank, US Census ACS 5-year, GeoNames.

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

Input Schema

NameRequiredDescriptionDefault
qNoA place name to look up, e.g. Springfield (optional)
keyNoArea key, e.g. us, us-ca, us-ca-los-angeles, us-90210, de (optional)
zipNoA US ZIP code (optional), 5 digits, e.g. 90210
levelNoWhich children to list: country, state, city or zip (optional)
limitNoChildren to list, default 20, max 500
offsetNoSkip this many children, for paging

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / zip / description
      Previous value: -"A US ZIP code (optional)"New value: +"A US ZIP code (optional), 5 digits, e.g. 90210"
  2. Added

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, non-destructive, closed-world, so the safety profile is covered. The description goes further by disclosing the response payload (area totals, year, measure sets that differ for US vs countries, per-level child counts, largest child at `level`) and the upstream data sources (World Bank, ACS 5-year, GeoNames) — meaningful context beyond structured fields. It omits anything about result caching, rate limits, or data vintage limits.

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?

Front-loaded with the purpose, then argument forms, then return shape, then sources — a logical order with no filler sentences. It runs long and repeats key examples already present in the schema, which is the only reason it is not a 5.

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?

With no output schema, the description carries the burden of explaining what comes back and does so thoroughly, including the US-vs-country measure split and the child-listing behavior. Remaining gaps are minor: ambiguity handling for `q`, paging semantics, and whether measures are always present for every area.

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 real meaning: the hierarchical key format with examples, the fact that key/zip/q are alternative addressing modes, and the world default when none is supplied. It does not clarify how `q` resolves ambiguity or how `limit`/`offset` interact with the 'largest children' listing beyond what the schema already says.

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 and resource — population and demography drilled from world down to ZIP code — and spells out the three ways to address an area (key, zip, q) plus the no-argument world default. No sibling tool overlaps this domain, so an agent can identify it immediately from the first clause.

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 concrete invocation patterns with example keys (us, us-ca-los-angeles, gb-england-london) and explicitly states that omitting all arguments returns the world. It does not state exclusions or failure conditions (e.g. ambiguous place names in q), but there is no competing sibling to route away from, so the guidance is nearly complete.

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

All NicheDB toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources