Skip to main content
Glama

Read from Populi

populi_get
Read-onlyIdempotent

Retrieve read-only Populi API v2 data from any /api2 route, with filtering, expansion, and pagination controls to fetch and merge records for people, academics, admissions, or billing.

Instructions

GET any Populi API v2 route (read-only). Path is under /api2, e.g. /people/123, /academicterms, /people/123/leads. Lists return up to 200 records per page; use page, limit, or all_pages. Use expand to inline related records (see populi_describe_api for the allowed names) and filter to narrow lists. A filter looks like {"0":{"logic":"ALL","fields":[{"name":"first_name","value":{"type":"CONTAINS","text":"john"},"positive":1}]}}. Populi allows about 50 requests/min per key, so prefer one filtered call over many unfiltered ones. Routes that return a file (PDF/XLS exports, transcripts, Data Slicer results, file downloads) can't be shown here: use populi_download for those. If a rate limit stops all_pages part-way, the pages already fetched are returned with a next_page to resume from.

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": {
      "path": "<path>"
    },
    "name": "populi_get"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage of results, 1-based. With all_pages, the page to start from
pathYesRoute under /api2, with real ids, e.g. /people/24469940/leads
limitNoRecords per page
expandNoRelated properties to include
filterNoPopuli filter object (list routes)
paramsNoAny other documented parameters for the route (sort, report options, format, ...)
all_pagesNoFollow pagination and merge every page into one list
max_charsNoTruncate the response text beyond this many characters
timeout_msNoPer-request timeout. Raise for slow reports and exports (default 120000)
max_recordsNoWith all_pages: stop once at least this many records are collected (the last page is kept whole). The result says whether it finished and, if not, the next_page to continue from

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. First observedv0.2.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes well beyond them: 200-record page size, ~50 requests/min per key, the exact shape of the partial-failure case for all_pages ('pages already fetched are returned with a next_page to resume from'), and the constraint that file-returning routes cannot be shown. This is the operational detail an agent needs before calling.

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 verb and resource, then ordered by importance: pagination, expand/filter, rate limits, the download alternative, and partial-failure semantics. The inline filter JSON is bulky but earns its place since the schema types `filter` as an opaque object; a few clauses could still be tightened.

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 10-parameter, open-world generic GET wrapper with no output schema, the description covers path discipline, pagination, rate limits, filtering, expansion, truncation-adjacent failure modes, and the sibling handoff for downloads. Nothing material an agent needs to call it correctly is missing.

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 schema lacks: a concrete filter object example for the untyped `filter` parameter, the page/limit versus all_pages interaction, and the pointer to populi_describe_api for valid `expand` values. It stops short of explaining max_chars and timeout_ms behavior, which remain schema-only.

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: 'GET any Populi API v2 route (read-only)', and immediately scopes the resource with path examples under /api2. An agent can distinguish it from populi_download (file routes) and populi_describe_api (expand names) 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?

Explicit routing rules: use populi_download for PDF/XLS exports, transcripts, Data Slicer results and file downloads; use populi_describe_api to look up allowed expand names; prefer one filtered call over many unfiltered ones because of the ~50 req/min key limit. Both when-to-use and when-not-to-use are stated.

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