Skip to main content
Glama
kisasa

populi-mcp

by kisasa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Read from Populi

populi_get
Read-onlyIdempotent

Retrieve read-only data from any Populi API v2 route using filters, pagination, and related-record expansion for people, academics, admissions, and billing records.

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.

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. 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 cover read-only/idempotent/open-world, and the description adds context they cannot: ~50 requests/min rate limit, 200-record default page size, and the failure mode where all_pages stops mid-run but returns fetched pages plus a next_page to resume. That is exactly the operational behavior an agent needs before invoking.

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 core action and path shape, then pagination, filtering, rate limits, and the sibling escape hatch in a logical order. The inline filter JSON literal is dense but earns its place as a copyable template; slightly heavy overall.

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 passthrough with no output schema, it covers paths, pagination, filtering, expansion, rate limits, partial-failure recovery, and the file-route alternative. The only thin spot is describing the single-object (non-list) response shape.

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 the baseline is 3, but the description adds real meaning: a concrete filter object example, the note that expand names must come from populi_describe_api, and how page/limit/all_pages interact. It stops short of explaining params/max_chars/max_records beyond the schema text.

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+resource ('GET any Populi API v2 route') plus the read-only constraint and a concrete path shape with examples. It also distinguishes itself from siblings by naming populi_describe_api for expand names and populi_download for file-returning routes.

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 when-to-use (generic /api2 route reads), explicit when-not (PDF/XLS exports, transcripts, Data Slicer, file downloads → populi_download), and an efficiency rule ('prefer one filtered call over many unfiltered ones'). Nothing is left to inference.

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

Deploy Server

Other Tools