Skip to main content
Glama

Search listings

search_listings
Read-onlyIdempotent

Search what is for sale or rent in Vietnam on this marketplace: apartments and rooms, motorbikes and cars, electronics, furniture, jobs, services and more. Words can include a district ("2 bedroom apartment district 7", "căn hộ quận 2"). Returns up to 20 live listings with price in VND and a link to each listing's page, where the person sees the photos and contacts the seller.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_listings"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoWhat to look for, in English or Vietnamese; a district or area in the words narrows to it
langNoLanguage of the titles (default "en")
sortNo"best" (the default) ranks by relevance and freshness; "recent" is newest first
typeNoWhat the listing offers: for sale, for rent, a job, or a wanted ad
limitNoHow many listings, 1–20 (default 10)
offsetNoSkip this many results, for the next page (up to 200)
categoryNoA category slug from list_categories, e.g. "rentals", "vehicles", "electronics"
provinceNoCity or province name, e.g. "Ho Chi Minh", "Ha Noi", "Da Nang"
conditionNoItem condition: "new" (includes like_new items) or "used"; other values do not filter
price_maxNoHighest price in VND
price_minNoLowest price in VND
subcategoryNoA subcategory slug of that category, from list_categories

Output Schema

NameRequiredDescriptionDefault
totalYesAbout how many live listings match on the site
cappedYestrue when more listings match but this server only pages through the first 220: narrow the search instead
listingsYesThis page of results
next_offsetYesPass as `offset` for more results; null when there are no more, or when `capped` is true

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / condition / description
      Previous value: -"Item condition, e.g. \"new\" or \"used\""New value: +"Item condition: \"new\" (includes like_new items) or \"used\"; other values do not filter"
  2. First observed

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld=false, so safety is covered. The description adds that results are live listings capped at 20, priced in VND, each with a link, which is genuine extra context, but it says nothing about empty-result behavior or pagination depth beyond what the schema states.

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?

Two sentences, front-loaded with what is searchable, followed by query-shaping guidance. The closing clause about the person seeing photos and contacting the seller is mildly extraneous for an API consumer, though it usefully signals what search does not return.

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 an output schema present and full parameter documentation, the description only needs to establish scope and query behavior, which it does. Minor gaps (result-when-empty, pagination guidance, sibling routing) keep it from being fully complete for a 12-parameter search tool.

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 coverage is 100%, so every parameter is already documented, and the query examples here largely restate what the q description says about district terms. The description adds no semantics for the other ten parameters (type, lang, sort, price bounds, condition, offset), so it stays at baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb and resource with a clear scope: searching for-sale or rental listings in Vietnam, itemized by domain (apartments, vehicles, electronics, jobs, services). It implies the boundary with get_listing_details by noting that each result links to the listing's own page where photos and seller contact live, but it never names or explicitly contrasts with the siblings.

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 concrete query patterns and tells the agent that including a district name in the words narrows results, with examples in both English and Vietnamese. It does not state when not to use this tool or explicitly route to list_categories/get_listing_details, though the category and link references hint at them.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources