Skip to main content
Glama

search_listings

Read-only

Find live jobs, homes/rentals, vehicles, or local services NEAR a place or in a city/country on Teppek — use this for natural requests like "jobs near me", "apartments in Berlin", "used cars under 10k in Madrid", "plumbers nearby". Covers 27 countries with fresh, location-aware listings refreshed daily. For MEANING-based or fuzzy natural-language intent (not exact keywords or filters), use semantic_search instead. Mechanics: search by vertical (career/real_estate/vehicle/service), role, text, price and a radius around a lat/lon point. The role is the perspective you search AS and returns the COUNTERPARTY listings: to find JOB POSTINGS use role="career_seeker" (NOT career_employer, which searches candidate CVs). Always send role with text_query: without it the call fails with an error, and vertical alone is not enough. country, category and near work without role; a call with none of text_query, country, category or near returns nothing. Real estate inventory is currently very limited, so an empty real_estate result does not mean the search failed. The response meta.total is the REAL match count (independent of limit); for a multi-word text_query it counts listings matching ANY of the words, so to count a whole occupation/category include its synonyms (e.g. "waiter waitress server"). Use the country field for country-scoped totals. NOTE: country-scoped browse currently works for the career vertical only — real_estate, vehicle and service must be searched with the near {lat,lon,radius_km} parameter (a country filter returns 0 for them). meta.ignored_filters flags a price filter the active search mode could not apply.

Input Schema

NameRequiredDescriptionDefault
nearNoRadius search around a point, and the way to search real_estate, vehicle and service by place. Works without role or text_query. Example: { "lat": 48.85, "lon": 2.35, "radius_km": 25 }.
roleNoThe perspective you search AS — results are the matching COUNTERPARTY listings, not your own side. To browse JOB POSTINGS use "career_seeker" (you act as a job seeker looking for jobs); "career_employer" instead searches candidate/CV listings. Likewise: estate_buyer → properties for sale, estate_renter → rentals, vehicle_buyer → vehicles for sale, vehicle_renter → vehicles for rent, service_client → service providers. REQUIRED whenever text_query is sent; also works with near.
limitNoMaximum results to return per page, 1-50. Default 20. Example: 10.
offsetNoHow many results to skip, for paging. Default 0. Example: 20 returns the second page when limit is 20.
countryNoOptional ISO-3166 alpha-2 country code (e.g. "us", "gb", "de") to scope results to one country and get a real total count for it. Career vertical only. Combine with role + text_query to count/list within a country (e.g. role:"career_seeker", country:"de", text_query:"kellner"); use country alone (no text_query) to get the total number of listings in that country.
sort_byNoOptional ordering: "price_asc" = cheapest first, "price_desc" = most expensive first. Use price_asc for "cheapest ..." requests. Omit for the default (most recent first). Currency-naive raw-number sort, so scope by vertical/country when mixing currencies.
categoryNoOptional PRECISE occupation/category filter using the source category slug (e.g. "hospitality-catering-jobs" for waiters/chefs/bar, "it-jobs", "retail-jobs"). This is far more accurate than keyword text_query for counting an occupation. With no text_query, the response meta.total is the exact count for that category (optionally + country), and meta.categories lists the available category slugs with counts — call once with country alone to discover them.
verticalNoListing category: career (jobs and CVs), real_estate, vehicle or service. It does not replace `role`: a text_query still needs role. Example: "vehicle".
price_maxNoMaximum price/salary. Currency-naive raw-number compare (see price_min). If unapplied it appears in meta.ignored_filters. Example: 2000.
price_minNoMinimum price/salary. CURRENCY-NAIVE: compared as a raw number against the listing price without normalizing currencies, so scope with `country` (or a role/vertical) when mixing regions. If the response cannot apply it, price_min is listed in meta.ignored_filters. Example: 500.
text_queryNoKeywords matched against listing text. Always send `role` with it: without role the search fails or returns nothing, and vertical alone is not enough. Several words match listings containing ANY of them. Example: "toyota".
intent_typeNoWhich side of the market to return: supply = things on offer (job postings, homes, vehicles, services), demand = people looking for them. Usually unnecessary when role is set. Example: "supply".

Output Schema

NameRequiredDescriptionDefault
dataYes
metaNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  2. Changed13 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"Optional ISO-3166 alpha-2 country code (e.g. \"us\", \"gb\", \"de\") to scope results to one country and get a real total count for it. Combine with text_query to count/list within a country (e.g. country:\"us\" + text_query:\"waiter\"); use country alone (no text_query) to get the total number of listings in that country."New value: +"Optional ISO-3166 alpha-2 country code (e.g. \"us\", \"gb\", \"de\") to scope results to one country and get a real total count for it. Career vertical only. Combine with role + text_query to count/list within a country (e.g. role:\"career_seeker\", country:\"de\", text_query:\"kellner\"); use country alone (no text_query) to get the total number of listings in that country."
    • addedInput schema / properties / intent_type / description
      Added value: +"Which side of the market to return: supply = things on offer (job postings, homes, vehicles, services), demand = people looking for them. Usually unnecessary when role is set. Example: \"supply\"."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum results to return per page, 1-50. Default 20. Example: 10."
    • addedInput schema / properties / near / description
      Added value: +"Radius search around a point, and the way to search real_estate, vehicle and service by place. Works without role or text_query. Example: { \"lat\": 48.85, \"lon\": 2.35, \"radius_km\": 25 }."
    • addedInput schema / properties / near / properties / lat / description
      Added value: +"Latitude in decimal degrees. Example: 48.85."
    • addedInput schema / properties / near / properties / lon / description
      Added value: +"Longitude in decimal degrees. Example: 2.35."
    • addedInput schema / properties / near / properties / radius_km / description
      Added value: +"Search radius in kilometres, up to 200. Default 10. Example: 25."
    • addedInput schema / properties / offset / description
      Added value: +"How many results to skip, for paging. Default 0. Example: 20 returns the second page when limit is 20."
    • changedInput schema / properties / price_max / description
      Previous value: -"Maximum price/salary. Currency-naive raw-number compare (see price_min). If unapplied it appears in meta.ignored_filters."New value: +"Maximum price/salary. Currency-naive raw-number compare (see price_min). If unapplied it appears in meta.ignored_filters. Example: 2000."
    • changedInput schema / properties / price_min / description
      Previous value: -"Minimum price/salary. CURRENCY-NAIVE: compared as a raw number against the listing price without normalizing currencies, so scope with `country` (or a role/vertical) when mixing regions. If the response cannot apply it, price_min is listed in meta.ignored_filters."New value: +"Minimum price/salary. CURRENCY-NAIVE: compared as a raw number against the listing price without normalizing currencies, so scope with `country` (or a role/vertical) when mixing regions. If the response cannot apply it, price_min is listed in meta.ignored_filters. Example: 500."
    • changedInput schema / properties / role / description
      Previous value: -"The perspective you search AS — results are the matching COUNTERPARTY listings, not your own side. To browse JOB POSTINGS use \"career_seeker\" (you act as a job seeker looking for jobs); \"career_employer\" instead searches candidate/CV listings. Likewise: estate_buyer → properties for sale, estate_renter → rentals, vehicle_buyer → vehicles for sale, vehicle_renter → vehicles for rent, service_client → service providers. Pair with text_query and/or near."New value: +"The perspective you search AS — results are the matching COUNTERPARTY listings, not your own side. To browse JOB POSTINGS use \"career_seeker\" (you act as a job seeker looking for jobs); \"career_employer\" instead searches candidate/CV listings. Likewise: estate_buyer → properties for sale, estate_renter → rentals, vehicle_buyer → vehicles for sale, vehicle_renter → vehicles for rent, service_client → service providers. REQUIRED whenever text_query is sent; also works with near."
    • addedInput schema / properties / text_query / description
      Added value: +"Keywords matched against listing text. Always send `role` with it: without role the search fails or returns nothing, and vertical alone is not enough. Several words match listings containing ANY of them. Example: \"toyota\"."
    • addedInput schema / properties / vertical / description
      Added value: +"Listing category: career (jobs and CVs), real_estate, vehicle or service. It does not replace `role`: a text_query still needs role. Example: \"vehicle\"."
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "data": {
      +      "items": {
      +        "additionalProperties": {},
      +        "properties": {
      +          "currency": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "id": {
      +            "type": "string"
      +          },
      +          "price": {
      +            "anyOf": [
      +              {
      +                "type": "number"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "status": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "title": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "url": {
      +            "type": "string"
      +          },
      +          "vertical": {
      +            "anyOf": [
      +              {
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "meta": {
      +      "additionalProperties": {},
      +      "properties": {},
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "data"
      +  ],
      +  "type": "object"
      +}
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare readOnlyHint and openWorldHint, but the description adds substantial non-annotation behavior: text_query without role fails, vertical alone is insufficient, a call with no text_query/country/category/near returns nothing, country browse only works for career vertical, and meta.ignored_filters signals unapplied filters. These are real failure modes disclosed up front.

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 purpose and examples, then mechanics, then edge cases — a logical flow. It is dense and long, with role guidance effectively repeated from the schema, but nearly every sentence carries operational value rather than filler.

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?

A 12-parameter, nested-object tool with already rich schema and an output schema, and the description still covers the failure modes, mode-specific limitations, and meta-field interpretations an agent needs. Nothing material for correct invocation is missing.

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 100%, so individual parameters are already well-documented. The description still adds cross-parameter semantics not fully captured per-field: role must accompany text_query or the call fails, vertical does not replace role, and country-scoped search is career-only — practical relationships between params.

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 ('Find live jobs, homes/rentals, vehicles, or local services') with scope qualifiers (NEAR a place, city/country, 27 countries). Immediately distinguishes itself from the semantic_search sibling and gives concrete example queries an agent can pattern-match against.

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 when to use this tool, when to use semantic_search instead ('MEANING-based or fuzzy natural-language intent'), and which parameter combinations are required vs optional. Also gives the crucial caveat that empty real_estate results mean limited inventory, not failure — actionable guidance an agent would otherwise misread.

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