Skip to main content
Glama
kisasa

populi-mcp

by kisasa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Download from Populi to a file

populi_download

Save Populi API routes, PDF/XLS/CSV exports, transcripts, reports, and paginated lists to files instead of returning them, keeping large results out of the conversation.

Instructions

GET a Populi route and save the response to a file in the files folder instead of returning it. Use it for routes that return files (PDF/XLS/CSV exports, transcripts and grade reports, Data Slicer results, file and backup downloads, images) and to keep a big list or full export out of the conversation (use all_pages). Takes the same arguments as populi_get. Never overwrites: an existing name gets -1, -2, ... appended. Returns the saved path and a short preview.

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, ...)
save_asNoFile name to save under (no folders). Defaults to the name Populi suggests, or a timestamp
all_pagesNoFollow pagination and merge every page into one list
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.9/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the never-overwrite naming convention (-1, -2 suffixes), the saved-path-plus-preview return shape, and the all_pages/max_records loop behavior. Nothing contradicts annotations: readOnlyHint=false correctly reflects local file writes, and destructiveHint=false matches the never-overwrite guarantee.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core behavior, then use cases, then the non-obvious file-naming and return behavior. No filler or restatement of the tool name.

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?

Ten parameters with nested objects and no output schema, yet the description covers purpose, when-to-use, the pagination escape hatch, file collision behavior, and what comes back (path + preview). An agent has everything needed to call it correctly.

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. The description earns above-baseline credit by explaining collision handling for save_as and the purpose of all_pages, details the schema does not state, though it does not clarify page/limit/expand semantics beyond the schema.

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 a Populi route) plus the key divergence — result goes to a file instead of the conversation. Explicitly differentiates from the sibling populi_get by saying it takes the same arguments but saves output, so an agent can pick between them without opening either 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?

Names concrete when-to-use cases: file-returning routes (PDF/XLS/CSV, transcripts, Data Slicer, backups, images) and oversized lists/exports where all_pages should be used. The 'instead of returning it' phrasing implicitly routes non-file, small-payload reads to populi_get.

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