Primavera

Turn a target into categories

suggest_categories

Idempotent

Entry point for ANY target: call it before any search, and never invent category ids. Give the target in plain words, WITHOUT the place ("independent car repair shops", "restaurants that could use an online booking tool") and the area from find_areas. Primavera's engine picks the Google Maps categories in groups and counts them in the area. Returns "selection" (groups, categories left out and why, what the data cannot tell) and "search", the object that count_search, get_search_metrics, preview_search, estimate_list and create_list take: pass it on as is, or edited. Costs 100 credits (maxCredits ≥ 100), refunded when no selection comes back. A request too vague is refused with clarification_needed, refunded: ask the user the question in error.details, then call again with the answer.

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/categories/suggest 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": {
      "request": "<request>",
      "maxCredits": "<maxCredits>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "suggest_categories"
  }
}

Input Schema

Name	Required	Description
`area`	No	Area to search, as returned by GET /areas (field "area"). Default: that of "search", else the whole country.
`search`	No	A search to refine: its area, filters, exclusions and groups are kept (the groups become the previous selection). 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.
`country`	No	Country to search (default: that of "search", else fr).
`request`	Yes	The target as the user would say it, WITHOUT the place: "independent car repair shops", "restaurants that could use a booking tool". What the client sells works too.
`previous`	No	The selection to update (default: the groups of "search"); null starts afresh.
`maxCredits`	Yes	Must be at least 100: the price of a suggestion.
`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.6/5.0

Behavior5/5

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) it discloses cost (100 credits, maxCredits ≥ 100), the refund conditions (no selection returned, or a clarification refusal), and the idempotency contract (same key plus same arguments on retry never double-charges). It also surfaces the consent requirement ('ask the user before calling it'), which annotations cannot express.

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 instruction and the never-invent-ids warning, and the dense paragraph carries pricing and retry semantics without filler. It is long and slightly repetitive about idempotency, but each sentence carries operational information the agent needs.

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 7-parameter paid tool with nested objects and no output schema, it describes both returned keys ('selection' with excluded categories and limits, 'search' as the pass-through object) and the failure modes. Nothing an agent needs to call it correctly and handle the result appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in structured form, and the description largely restates those definitions (request without the place, maxCredits minimum 100, idempotencyKey reuse rules). The added value is mostly contextual routing – that 'search' is the object the downstream tools consume and may be sent as-is or edited – rather than new per-parameter meaning.

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 ('turn a target into Google Maps categories') and positions itself explicitly as the entry point that must run before any search, with 'never invent category ids' distinguishing it from find_categories. An agent can identify what it does and where it sits in the workflow without opening a 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?

Gives explicit when-to-use ('call it before any search'), how to phrase input ('target in plain words, WITHOUT the place'), where the area comes from ('find_areas'), and what to do downstream (pass the returned 'search' object to count_search, get_search_metrics, preview_search, estimate_list, create_list). It also covers the refusal path (clarification_needed → ask the user the question in error.details → call again) and the retry path.

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.