Skip to main content
Glama

SocialAPIs

by io.github.SocialAPIsHub
OverviewDiscussionsAdmin

Facebook: Marketplace

facebook_marketplace
Read-only

Facebook Marketplace: search listings, vehicles and rentals, listing and seller details, categories and city coordinates.

Actions:

  • action=search: Search general Facebook Marketplace listings (items for sale) by keyword or category near a location, with price, condition, radius and sort filters. Returns listings with their listing_id, plus an end_cursor. For cars and other vehicles use action=vehicles; for homes and rooms to rent use action=rentals. Get coordinates from action=city_coordinates. Pricing: 1 credit per call. Inputs: query (optional), category_url (optional), commerce_search_sort_by (optional), commerce_search_and_rp_condition (optional), filter_location_latitude (optional), filter_location_longitude (optional), filter_price_lower_bound (optional), filter_price_upper_bound (optional), filter_radius_km (optional), posted_today (optional), exact_match (optional), limit (optional), end_cursor (optional).

  • action=vehicles: Search Facebook Marketplace vehicle listings (cars, trucks, motorcycles) near a location, with price, radius and seller-type filters. Returns listings with title, price, mileage, year and listing_id, plus an end_cursor. For non-vehicle items, use action=search. Pricing: 1 credit per call. Inputs: sort_by (optional), filter_location_latitude (optional), filter_location_longitude (optional), filter_price_lower_bound (optional), filter_price_upper_bound (optional), filter_radius_km (optional), is_c2c_listing_only (optional), end_cursor (optional).

  • action=rentals: Search Facebook Marketplace rental listings (apartments, houses, rooms) near a location, with price, bedroom, bathroom and radius filters. Returns rental listings with their listing_id, plus an end_cursor. For items for sale, use action=search. Pricing: 1 credit per call. Inputs: sort_by (optional), filter_location_latitude (optional), filter_location_longitude (optional), filter_price_lower_bound (optional), filter_price_upper_bound (optional), filter_radius_km (optional), filter_bedrooms_min (optional), filter_bedrooms_max (optional), filter_bathrooms_min (optional), filter_bathrooms_max (optional), end_cursor (optional).

  • action=listing: Get one Marketplace listing in full: title, price, description, condition, all photos, location and seller. Needs the listing_id from a Marketplace search result. Pricing: 1 credit per call. Inputs: listing_id (required).

  • action=seller: Get a Marketplace seller's profile: name, join date, rating, review count and badges. Needs the seller_id from action=listing. Pricing: 1 credit per call. Inputs: seller_id (required).

  • action=categories: List Marketplace categories with their IDs and category_url values. Use a category_url to filter action=search. Pricing: 1 credit per call. Inputs: none.

  • action=city_coordinates: Convert a city name to the latitude and longitude that the Marketplace search tools expect in filter_location_latitude / filter_location_longitude. Pricing: 1 credit per call. Inputs: city (required), country (optional), exactly_one (optional).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cityNoCity name, e.g. Austin. Required for: city_coordinates.
limitNoMaximum number of items to return. Default: 24. Optional for: search.
queryNoKeyword to search listings for, e.g. iphone 15. Optional for: search.
actionYesWhich operation to run. See the tool description for what each action returns and which parameters it needs.
countryNoCountry name or code. Optional for: city_coordinates.
sort_byNoSort order. vehicles: CREATION_TIME_DESCEND, PRICE_ASCEND, VEHICLE_MILEAGE_ASCEND, … · rentals: CREATION_TIME_DESCEND, PRICE_ASCEND, BEST_MATCH. Optional for: vehicles, rentals.
seller_idNoSeller ID, from the seller field of action=listing. Required for: seller.
end_cursorNoPagination cursor. Optional for: search, vehicles, rentals.
listing_idNoMarketplace listing ID, from a Marketplace search result. Required for: listing.
exact_matchNoWhen "true", exact match search. Optional for: search.
exactly_oneNoWhen "true", return exactly one result. Optional for: city_coordinates.
category_urlNoCategory URL slug. Optional for: search.
posted_todayNoWhen "true", limit to items posted today. Optional for: search.
filter_radius_kmNoSearch radius around the center in kilometres, e.g. 40. Optional for: search, vehicles, rentals.
filter_bedrooms_maxNoMaximum number of bedrooms. Optional for: rentals.
filter_bedrooms_minNoMinimum number of bedrooms, e.g. 2. Optional for: rentals.
is_c2c_listing_onlyNoIndividual sellers only. Optional for: vehicles.
filter_bathrooms_maxNoMaximum number of bathrooms. Optional for: rentals.
filter_bathrooms_minNoMinimum number of bathrooms, e.g. 1. Optional for: rentals.
commerce_search_sort_byNoSort: BEST_MATCH, CREATION_TIME_DESCEND, PRICE_ASCEND, etc. Optional for: search.
filter_location_latitudeNoLatitude of the search center, e.g. 30.2672 (from action=city_coordinates). Optional for: search, vehicles, rentals.
filter_price_lower_boundNoMinimum price in the local currency, whole number, e.g. 100. Optional for: search, vehicles, rentals.
filter_price_upper_boundNoMaximum price in the local currency, whole number, e.g. 2000. Optional for: search, vehicles, rentals.
filter_location_longitudeNoLongitude of the search center, e.g. -97.7431 (from action=city_coordinates). Optional for: search, vehicles, rentals.
commerce_search_and_rp_conditionNoCondition: new, used_like_new, used_good, used_fair. Optional for: search.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYesJSON response from the SocialAPIs REST endpoint, unchanged. Object or array depending on the endpoint; most include a `meta` block (statusCode, duration, creditsCharged, creditsRemaining).
creditsChargedNoCredits charged for this call, or null if the endpoint did not report it.
creditsRemainingNoCredits left on the API key after this call, or null if not reported.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed24 schema fields changed
    • changedInput schema / properties / category_url / description
      Previous value: -"search (optional): Category URL slug."New value: +"Category URL slug.\nOptional for: search."
    • changedInput schema / properties / city / description
      Previous value: -"city_coordinates (required): City name, e.g. Austin."New value: +"City name, e.g. Austin.\nRequired for: city_coordinates."
    • changedInput schema / properties / commerce_search_and_rp_condition / description
      Previous value: -"search (optional): Condition: new, used_like_new, used_good, used_fair."New value: +"Condition: new, used_like_new, used_good, used_fair.\nOptional for: search."
    • changedInput schema / properties / commerce_search_sort_by / description
      Previous value: -"search (optional): Sort: BEST_MATCH, CREATION_TIME_DESCEND, PRICE_ASCEND, etc."New value: +"Sort: BEST_MATCH, CREATION_TIME_DESCEND, PRICE_ASCEND, etc.\nOptional for: search."
    • changedInput schema / properties / country / description
      Previous value: -"city_coordinates (optional): Country name or code."New value: +"Country name or code.\nOptional for: city_coordinates."
    • changedInput schema / properties / end_cursor / description
      Previous value: -"search, vehicles, rentals (optional): Pagination cursor."New value: +"Pagination cursor.\nOptional for: search, vehicles, rentals."
    • changedInput schema / properties / exact_match / description
      Previous value: -"search (optional): When \"true\", exact match search."New value: +"When \"true\", exact match search.\nOptional for: search."
    • changedInput schema / properties / exactly_one / description
      Previous value: -"city_coordinates (optional): When \"true\", return exactly one result."New value: +"When \"true\", return exactly one result.\nOptional for: city_coordinates."
    • changedInput schema / properties / filter_bathrooms_max / description
      Previous value: -"rentals (optional): Maximum number of bathrooms."New value: +"Maximum number of bathrooms.\nOptional for: rentals."
    • changedInput schema / properties / filter_bathrooms_min / description
      Previous value: -"rentals (optional): Minimum number of bathrooms, e.g. 1."New value: +"Minimum number of bathrooms, e.g. 1.\nOptional for: rentals."
    • changedInput schema / properties / filter_bedrooms_max / description
      Previous value: -"rentals (optional): Maximum number of bedrooms."New value: +"Maximum number of bedrooms.\nOptional for: rentals."
    • changedInput schema / properties / filter_bedrooms_min / description
      Previous value: -"rentals (optional): Minimum number of bedrooms, e.g. 2."New value: +"Minimum number of bedrooms, e.g. 2.\nOptional for: rentals."
    • changedInput schema / properties / filter_location_latitude / description
      Previous value: -"search, vehicles, rentals (optional): Latitude of the search center, e.g. 30.2672 (from action=city_coordinates)."New value: +"Latitude of the search center, e.g. 30.2672 (from action=city_coordinates).\nOptional for: search, vehicles, rentals."
    • changedInput schema / properties / filter_location_longitude / description
      Previous value: -"search, vehicles, rentals (optional): Longitude of the search center, e.g. -97.7431 (from action=city_coordinates)."New value: +"Longitude of the search center, e.g. -97.7431 (from action=city_coordinates).\nOptional for: search, vehicles, rentals."
    • changedInput schema / properties / filter_price_lower_bound / description
      Previous value: -"search, vehicles, rentals (optional): Minimum price in the local currency, whole number, e.g. 100."New value: +"Minimum price in the local currency, whole number, e.g. 100.\nOptional for: search, vehicles, rentals."
    • changedInput schema / properties / filter_price_upper_bound / description
      Previous value: -"search, vehicles, rentals (optional): Maximum price in the local currency, whole number, e.g. 2000."New value: +"Maximum price in the local currency, whole number, e.g. 2000.\nOptional for: search, vehicles, rentals."
    • changedInput schema / properties / filter_radius_km / description
      Previous value: -"search, vehicles, rentals (optional): Search radius around the center in kilometres, e.g. 40."New value: +"Search radius around the center in kilometres, e.g. 40.\nOptional for: search, vehicles, rentals."
    • changedInput schema / properties / is_c2c_listing_only / description
      Previous value: -"vehicles (optional): Individual sellers only."New value: +"Individual sellers only.\nOptional for: vehicles."
    • changedInput schema / properties / limit / description
      Previous value: -"search (optional): Maximum number of items to return. Default: 24."New value: +"Maximum number of items to return. Default: 24.\nOptional for: search."
    • changedInput schema / properties / listing_id / description
      Previous value: -"listing (required): Marketplace listing ID, from a Marketplace search result."New value: +"Marketplace listing ID, from a Marketplace search result.\nRequired for: listing."
    • changedInput schema / properties / posted_today / description
      Previous value: -"search (optional): When \"true\", limit to items posted today."New value: +"When \"true\", limit to items posted today.\nOptional for: search."
    • changedInput schema / properties / query / description
      Previous value: -"search (optional): Keyword to search listings for, e.g. iphone 15."New value: +"Keyword to search listings for, e.g. iphone 15.\nOptional for: search."
    • changedInput schema / properties / seller_id / description
      Previous value: -"seller (required): Seller ID, from the seller field of action=listing."New value: +"Seller ID, from the seller field of action=listing.\nRequired for: seller."
    • changedInput schema / properties / sort_by / description
      Previous value: -"vehicles (optional): Sort: CREATION_TIME_DESCEND, PRICE_ASCEND, VEHICLE_MILEAGE_ASCEND, etc. rentals (optional): Sort: CREATION_TIME_DESCEND, PRICE_ASCEND, BEST_MATCH."New value: +"Sort order. vehicles: CREATION_TIME_DESCEND, PRICE_ASCEND, VEHICLE_MILEAGE_ASCEND, … · rentals: CREATION_TIME_DESCEND, PRICE_ASCEND, BEST_MATCH.\nOptional for: vehicles, rentals."
  2. Changed24 schema fields changed
    • changedInput schema / properties / category_url / description
      Previous value: -"For search: Category URL slug."New value: +"search (optional): Category URL slug."
    • changedInput schema / properties / city / description
      Previous value: -"For city_coordinates: City name, e.g. Austin."New value: +"city_coordinates (required): City name, e.g. Austin."
    • changedInput schema / properties / commerce_search_and_rp_condition / description
      Previous value: -"For search: Condition: new, used_like_new, used_good, used_fair."New value: +"search (optional): Condition: new, used_like_new, used_good, used_fair."
    • changedInput schema / properties / commerce_search_sort_by / description
      Previous value: -"For search: Sort: BEST_MATCH, CREATION_TIME_DESCEND, PRICE_ASCEND, etc."New value: +"search (optional): Sort: BEST_MATCH, CREATION_TIME_DESCEND, PRICE_ASCEND, etc."
    • changedInput schema / properties / country / description
      Previous value: -"For city_coordinates: Country name or code."New value: +"city_coordinates (optional): Country name or code."
    • changedInput schema / properties / end_cursor / description
      Previous value: -"For search, vehicles, rentals: Pagination cursor."New value: +"search, vehicles, rentals (optional): Pagination cursor."
    • changedInput schema / properties / exact_match / description
      Previous value: -"For search: When \"true\", exact match search."New value: +"search (optional): When \"true\", exact match search."
    • changedInput schema / properties / exactly_one / description
      Previous value: -"For city_coordinates: When \"true\", return exactly one result."New value: +"city_coordinates (optional): When \"true\", return exactly one result."
    • changedInput schema / properties / filter_bathrooms_max / description
      Previous value: -"For rentals: Maximum number of bathrooms."New value: +"rentals (optional): Maximum number of bathrooms."
    • changedInput schema / properties / filter_bathrooms_min / description
      Previous value: -"For rentals: Minimum number of bathrooms, e.g. 1."New value: +"rentals (optional): Minimum number of bathrooms, e.g. 1."
    • changedInput schema / properties / filter_bedrooms_max / description
      Previous value: -"For rentals: Maximum number of bedrooms."New value: +"rentals (optional): Maximum number of bedrooms."
    • changedInput schema / properties / filter_bedrooms_min / description
      Previous value: -"For rentals: Minimum number of bedrooms, e.g. 2."New value: +"rentals (optional): Minimum number of bedrooms, e.g. 2."
    • changedInput schema / properties / filter_location_latitude / description
      Previous value: -"For search, vehicles, rentals: Latitude of the search center, e.g. 30.2672 (from action=city_coordinates)."New value: +"search, vehicles, rentals (optional): Latitude of the search center, e.g. 30.2672 (from action=city_coordinates)."
    • changedInput schema / properties / filter_location_longitude / description
      Previous value: -"For search, vehicles, rentals: Longitude of the search center, e.g. -97.7431 (from action=city_coordinates)."New value: +"search, vehicles, rentals (optional): Longitude of the search center, e.g. -97.7431 (from action=city_coordinates)."
    • changedInput schema / properties / filter_price_lower_bound / description
      Previous value: -"For search, vehicles, rentals: Minimum price in the local currency, whole number, e.g. 100."New value: +"search, vehicles, rentals (optional): Minimum price in the local currency, whole number, e.g. 100."
    • changedInput schema / properties / filter_price_upper_bound / description
      Previous value: -"For search, vehicles, rentals: Maximum price in the local currency, whole number, e.g. 2000."New value: +"search, vehicles, rentals (optional): Maximum price in the local currency, whole number, e.g. 2000."
    • changedInput schema / properties / filter_radius_km / description
      Previous value: -"For search, vehicles, rentals: Search radius around the center in kilometres, e.g. 40."New value: +"search, vehicles, rentals (optional): Search radius around the center in kilometres, e.g. 40."
    • changedInput schema / properties / is_c2c_listing_only / description
      Previous value: -"For vehicles: Individual sellers only."New value: +"vehicles (optional): Individual sellers only."
    • changedInput schema / properties / limit / description
      Previous value: -"For search: Maximum number of items to return. Default: 24."New value: +"search (optional): Maximum number of items to return. Default: 24."
    • changedInput schema / properties / listing_id / description
      Previous value: -"For listing: Marketplace listing ID, from a Marketplace search result."New value: +"listing (required): Marketplace listing ID, from a Marketplace search result."
    • changedInput schema / properties / posted_today / description
      Previous value: -"For search: When \"true\", limit to items posted today."New value: +"search (optional): When \"true\", limit to items posted today."
    • changedInput schema / properties / query / description
      Previous value: -"For search: Keyword to search listings for, e.g. iphone 15."New value: +"search (optional): Keyword to search listings for, e.g. iphone 15."
    • changedInput schema / properties / seller_id / description
      Previous value: -"For seller: Seller ID, from the seller field of action=listing."New value: +"seller (required): Seller ID, from the seller field of action=listing."
    • changedInput schema / properties / sort_by / description
      Previous value: -"For vehicles: Sort: CREATION_TIME_DESCEND, PRICE_ASCEND, VEHICLE_MILEAGE_ASCEND, etc. For rentals: Sort: CREATION_TIME_DESCEND, PRICE_ASCEND, BEST_MATCH."New value: +"vehicles (optional): Sort: CREATION_TIME_DESCEND, PRICE_ASCEND, VEHICLE_MILEAGE_ASCEND, etc. rentals (optional): Sort: CREATION_TIME_DESCEND, PRICE_ASCEND, BEST_MATCH."
  3. Added

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. Beyond that, the description discloses per-call credit pricing, pagination via end_cursor, and the required upstream identifiers for listing/seller calls, which are genuinely useful operational facts the annotations do not carry. It stops short of auth or rate-limit detail, so a 4 rather than 5.

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 length is justified by seven actions and 25 parameters, and structure is strong: a front-loaded overview followed by one labeled block per action with purpose, returns, alternatives, and inputs. The repeated 'Pricing: 1 credit per call' line is mildly redundant but earns its place by informing cost decisions per action.

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 high-complexity, multi-action tool the description covers every action's purpose, alternatives, prerequisites, and returns, and an output schema exists to handle response shape. Nothing an agent needs in order to pick the right action and supply the right arguments is 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% and each parameter already carries its own 'Required for:'/'Optional for:' tagging, so the schema does the heavy lifting. The per-action 'Inputs:' lists in the description mirror that mapping but add no syntax, format, or constraint detail beyond what the schema states (e.g., condition values, coordinate examples). Baseline 3 is appropriate.

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 opening sentence names the resource (Facebook Marketplace) and enumerates every operation it covers: listings, vehicles, rentals, listing/seller details, categories, and city coordinates. Each action entry begins with a specific verb+resource (e.g., 'Search Facebook Marketplace vehicle listings'), and the Marketplace scope clearly separates it from sibling tools like facebook_search or facebook_post.

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?

Routing is explicit at every decision point: 'For cars and other vehicles use action=vehicles; for homes and rooms to rent use action=rentals. Get coordinates from action=city_coordinates,' and the reverse guards ('For non-vehicle items, use action=search'). It also states the dependency chain (listing needs listing_id from a search; seller needs seller_id from listing), so an agent never has to infer the correct action.

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

All SocialAPIs toolsInspect
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