Skip to main content
Glama
Sign In

Primavera

by com.primaverapp
OverviewDiscussionsAdmin

Prepare a file

prepare_list_file
Idempotent

Prepare the CSV file (every column) or the Excel file (the columns you choose) of a ready list. Then call get_list_file until the file is ready. A file stays available 7 days.

Free. idempotencyKey (a new UUID v4) is required; reuse it only to retry the very same call.

Same call as POST /api/v1/lists/{id}/files of the REST API.

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": {
      "listId": "<listId>",
      "format": "<format>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "prepare_list_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
formatYes
listIdYesId of a list of the account (from create_list or list_lists).
columnsNoxlsx only: column keys (see GET /lists/{id}/items, "columns"). A CSV always holds every column.
idempotencyKeyYesA new UUID v4 for this operation (sent as the Idempotency-Key of the API). Reuse it only to retry the very same call: the saved result comes back, nothing is charged twice.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the schema repeats the idempotency contract. The description does add genuinely new behavioral facts beyond the annotations: the asynchronous pattern requiring polling, the 7-day file TTL, and that the operation is free. It does not say what happens when the same list/format is prepared twice or what this call's own response contains, so the added value is real but partial.

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?

Four short sentences, front-loaded with the action, then the follow-up, then the retention limit, then the cost and idempotency rules. No restatement of the title and no filler; the REST endpoint mapping is a single compact line that earns its place for developers.

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 happens after the call, and it does: an asynchronous file that must be polled via get_list_file and expires after 7 days. It does not describe what this call returns (a job id, a status), which is the one remaining gap for a 4-parameter async tool.

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 75%, so the baseline is already a 3. The description adds the non-obvious mapping between the format parameter and the columns parameter (columns is xlsx-only; CSV always holds every column), which the schema only hints at via a description string, and it reiterates that idempotencyKey must be a new UUID v4 reused only for the same retry.

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?

The description states a specific verb and resource ('Prepare the CSV file ... or the Excel file ... of a ready list') and immediately distinguishes the format semantics: CSV takes every column, xlsx takes the chosen ones. It also names the follow-up tool get_list_file, so an agent knows which sibling continues the flow rather than initiating one.

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 an explicit next step ('Then call get_list_file until the file is ready'), which is the key workflow guidance for an async job tool. It also states the retry/idempotency rule precisely. It stops short of naming when not to use it (e.g. when a cached file already exists) or contrasting with estimate_list, so it is clear but not exhaustive.

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

All Primavera 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