PegaRex MCP Server

Search vehicle listings

search_vehicles

Read-onlyIdempotent

Search 1.8M+ Brazilian car and motorcycle listings from 96 platforms. Compare each vehicle's price to FIPE reference and deal score to identify below-market deals.

Instructions

Search 1.8M+ Brazilian vehicle listings aggregated from 96 platforms (OLX, Webmotors, Napista, etc.). Returns listings with price, year, mileage, location, source platform, the original ad URL, FIPE reference price and a deal_score (% vs FIPE; negative means priced below FIPE).

Tips for best results:
- Free-text `query` matches the listing TITLE only (e.g. "Onix LTZ turbo").
- For exact brand/model/version filtering, resolve names to ids first with
  list_brands / list_models / list_versions and pass brand_id/model_id/
  version_id — it is faster and more accurate than the text fields.
- `location` is a 2-letter UF (e.g. "SP") or a city name.
- `sort_by="newest"` (default) lists the most recently LISTED cars first —
  the date a listing first appeared on its source, not when we last saw it.
- `sort_by="best_deal"` ranks by lowest price-to-FIPE ratio.
- `per_page` is capped at 50. Use `page` to paginate; `total_count` and
  `total_pages` are returned.

Input Schema

TableJSON Schema

Name	Required	Default
`page`	No
`brand`	No
`model`	No
`query`	No
`source`	No
`sort_by`	No	newest
`version`	No
`brand_id`	No
`category`	No	Cars
`location`	No
`model_id`	No
`per_page`	No
`year_max`	No
`year_min`	No
`fuel_type`	No
`price_max`	No
`price_min`	No
`body_style`	No
`version_id`	No
`mileage_max`	No
`mileage_min`	No
`transmission`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 25, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds substantial nuance: aggregation scope, deal_score meaning, sort_by behavior, per_page cap, and pagination fields. This goes well beyond the structured annotations and tells the agent what to expect when calling the tool.

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?

The description is front-loaded with the core purpose and return shape, then organized into bulleted tips under a clear 'Tips for best results' heading. Every sentence adds operational value; the length is justified by the tool's 22-parameter complexity.

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?

There is no output schema, so the description correctly enumerates return fields and pagination metadata. It also covers the most error-prone behaviors like title-only matching and sort semantics. A few parameter meanings are left implicit, but the overall context is sufficient for an agent to select and invoke the tool correctly.

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?

The schema has 0% description coverage across 22 parameters, so the description must compensate. It does clarify the most confusing parameters (query, brand_id/model_id/version_id, location, sort_by, page/page_size), but it leaves many filters undocumented in prose, such as source, category, body_style, fuel_type, transmission, year_min/max, price_min/max, and mileage_min/max. The description is helpful but not complete enough for a parameter-heavy tool with zero schema descriptions.

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: searching over 1.8M+ Brazilian vehicle listings aggregated from 96 platforms. It also names the concrete return payload (price, year, mileage, location, source URL, FIPE price, deal_score), which makes the tool's purpose unmistakable and distinct from siblings like get_listing_details or get_vehicle_by_id.

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?

The description offers clear, practical usage tips: free-text query matches title only, exact brand/model/version filtering should go through list_brands/list_models/list_versions first, location expects a 2-letter UF or city, and sort_by semantics are explained. It does not explicitly state when not to use this tool versus other siblings, but it gives strong contextual guidance for the main decisions.

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

Deploy Server

Search vehicle listings

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools