Claro AI by Casafari

Refine a search

claro_refine_search

Read-only

Change part of an earlier search in plain words ("bigger, at least 200 m²", "Barcelona too", "drop the corner") and run it again as a new search with its own search_id and pages. Takes the search_id from claro_search_premises; searches are kept 24 hours. Results as claro_search_premises gives them; next_cursor as cursor gets the next page. On the Free plan, each call (and each page) is one of 4 searches. Costs 100 tokens a call. Each page is a call.

Input Schema

Name	Required	Description	Default
`lang`	No	Language of the text the answer writes (titles, notes, labels, reasons, error messages): en (default) or de (German). Place names, agency names, property titles and quotes from a property's own text stay as written.	en
`check`	No	Read the top results' text against the criteria for a fit verdict (adds a few seconds). Off above 50 results a page and on later pages.
`limit`	No	Results a page, up to 200; above 50 check is off.
`change`	No	What to change, in plain words. Required unless cursor is sent.
`cursor`	No	next_cursor from an earlier answer: returns that search's next page, same criteria and order. Send without brief, criteria or change.
`offset`	No	With search_id (no brief, criteria or change): the page of that stored search starting at this place in its ranked matches. Same order as its cursors.
`insights`	No
`search_id`	Yes	The search_id from search_premises or an earlier refine_search (kept 24 hours).
`stated_only`	No	Only the matches that state every criterion (met). Matches with a criterion not stated or not met are left out of results and of page.total; counts keeps both totals. With search_id and no brief/criteria/change: pages that stored search.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026

addedInput schema / properties / lang

Added value: +{
+  "default": "en",
+  "description": "Language of the text the answer writes (titles, notes, labels, reasons, error messages): en (default) or de (German). Place names, agency names, property titles and quotes from a property's own text stay as written.",
+  "enum": [
+    "en",
+    "de"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 18, 2026

removedInput schema / properties / insights / description

Removed value: -"Add `insights`, charts as data over every match, each with a one-sentence answer, its count, scope, source and date: per criterion how many matches meet it, leave it unsaid or contradict it (and how many would state everything without it); with one price limit, what it reaches among premises of this kind and place before the limit, else what the matches ask per m²; and where the matches are by district or town. Asking prices; each unit counted once."

First observedOct 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: searches persist for 24 hours, each call and each page counts against the Free plan's 4 searches, and each call costs 100 tokens. It also explains that results match claro_search_premises and that next_cursor pages through results.

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?

The purpose and operational constraints are front-loaded and easy to scan. There is minor redundancy around calls and pages counting as searches, but the paragraph remains compact and useful.

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 9-parameter search-refinement tool with no output schema, the description covers the missing pieces an agent needs: source of search_id, pagination behavior, retention, quota impact, token cost, and return-shape reference to claro_search_premises.

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 high, so the schema already documents most parameters. The description still adds useful meaning for the key change parameter with concrete plain-language examples, and reinforces the search_id retention and cursor pagination semantics.

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 action: change part of an earlier search and rerun it as a new search with its own search_id and pages. This clearly distinguishes it from claro_search_premises, the initial search tool.

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?

Explicitly says to take search_id from claro_search_premises, gives plain-language examples for change, and explains cursor pagination. It also clarifies when cursor requires no change/brief/criteria, leaving little ambiguity about when to use this tool versus alternatives.

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

All Claro AI by Casafari 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.

Resources

Need Help?