Primavera

Create a list

create_list

Idempotent

Export the places of a search into a new list, with their contact details (up to 50,000 rows). Price: 1 credit per place never delivered to this account (Agency: included under fair use); withEmail: only places with an email address (found ones first, then guessed and verified ones); verifyEmails: plus 1 credit per address verified. maxCredits is never exceeded: send the "cost" of estimate_list, once the user agreed. One export at a time per account. While the list says "creating", follow it with get_list.

Paid: maxCredits (the most credits this call may spend, never exceeded) and idempotencyKey (a new UUID v4 for this operation) are required; without them nothing runs. To retry after an error or a timeout, send the same idempotencyKey with the same arguments: nothing is charged twice. Ask the user before calling it.

Same call as POST /api/v1/lists 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": {
      "name": "<name>",
      "search": "<search>",
      "maxCredits": "<maxCredits>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "create_list"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	List name, as shown in "My lists".
`rows`	No	Rows wanted (at most 50000). With withEmail: email addresses wanted. Required unless wholeArea is true.
`search`	Yes	The search, as returned by /categories/suggest (then narrowed with /areas, filters…). The "search" object returned by suggest_categories (target, area, filters, sort), sent as is or edited; its full schema is the "search" input of count_search. An invalid search is refused with invalid_request and the fields to fix.
`wholeArea`	No	Rarely searched area only (estimate returned kind "zone"): fill the list with the whole area instead of a number of rows.
`withEmail`	No	true = the "With email" choice of the app: places with an email address only; found addresses are delivered first, others are guessed on the websites then checked (1 credit per valid address), and the verification of the addresses is reserved at creation (1 credit per address, unused credits returned).
`maxCredits`	Yes	The most credits this call may spend (required on every paid call, with an Idempotency-Key header). Never exceeded.
`verifyEmails`	No	true = the "Verify emails" box of the app: the addresses this list delivers are verified (deliverable, risky, undeliverable), 1 credit per address, reserved at creation and inside maxCredits (send maxCredits ≥ export cost + rows); unused credits are returned. Up to 10000 rows; not for rarely searched areas; included in withEmail lists.
`idempotencyKey`	Yes	A 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.

First observedNov 12, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only say readOnly=false, idempotent=true, destructive=false; the description goes far beyond with per-place and per-verification credit pricing, the maxCredits ceiling that is never exceeded, refunds of unused verification credits, concurrency limits, and the fact that retries with the same key are not charged twice.

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?

Purpose and the paid-call requirement are front-loaded, and the sentences carry real information. The long semicolon-and-parenthesis-chained first paragraph is dense and partially duplicates schema wording for withEmail/verifyEmails, costing a little clarity.

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?

Covers pricing, prerequisites, polling, retry and concurrency for an 8-parameter mutation with a nested search object and no output schema. The one gap is the return value: it implies a status field ('creating') and presumably an id, but never states the 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 already 100%, yet the description adds operational meaning: maxCredits should be the estimate cost (and ≥ export cost + rows when verifyEmails is on), idempotencyKey is a UUID v4 for this specific operation, and rows interacts with withEmail. Some of this restates schema text, so it is additive rather than transformative.

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?

Opens with a specific verb+resource+output: 'Export the places of a search into a new list, with their contact details'. It also implicitly separates itself from estimate_list (must be run first) and get_list (used to poll), so an agent can place it in the workflow immediately.

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 sequencing guidance: take the cost from estimate_list, ask the user before calling, then poll with get_list while status is 'creating'. It also states the 'one export at a time per account' exclusion and the retry condition (same idempotencyKey, same args).

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

All Primavera tools Inspect

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.