Skip to main content
Glama
Sign In

Foursquare

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Search Places

search_places
Read-onlyIdempotent

Search Foursquare places (keyless — Pipeworx supplies the key). Combine query (e.g., "coffee", "hardware store") with a location anchor — either near ("Brooklyn, NY", "San Francisco, CA") or latitude+longitude. sort:"RATING" orders results by Foursquare rating (best first); the rating NUMBER itself is a Foursquare Premium field and is returned only where enabled — check rating_included / rating_reason in the response, and read rating_note before telling a caller a place is unrated. Returns name, fsq_place_id, categories, address, distance, lat/lon, tel, website.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "near": "San Francisco, CA",
      "sort": "RATING",
      "limit": 10,
      "query": "coffee"
    },
    "name": "search_places"
  }
}

Input Schema

NameRequiredDescriptionDefault
nearNoPlace name anchor ("Brooklyn, NY", "Tokyo")
sortNoRELEVANCE (default) | DISTANCE | RATING | POPULARITY
limitNoResults (1-50, default 10)
queryNoFree-text query
latitudeNoCenter latitude (pair with longitude)
radius_mNo1-100000 metres (only with lat/lon)
longitudeNoCenter longitude
categoriesNoOPTIONAL. Comma-separated numeric fsq_category_id values ONLY (e.g. from a prior search_places result). Do NOT invent IDs or pass category names — use the `query` text for that (e.g. query:"coffee"). Unknown IDs are ignored.

Output Schema

NameRequiredDescriptionDefault
countYesNumber of results returned
resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "limit": 10,
-    "near": "Brooklyn, NY",
-    "query": "coffee",
-    "sort": "RELEVANCE"
-  },
-  {
-    "latitude": 40.7128,
-    "limit": 20,
-    "longitude": -74.006,
-    "query": "hardware store",
-    "radius_m": 1000,
-    "sort": "DISTANCE"
-  }
-]New value: +[
+  {
+    "limit": 10,
+    "near": "San Francisco, CA",
+    "query": "coffee",
+    "sort": "RATING"
+  },
+  {
+    "limit": 10,
+    "near": "Brooklyn, NY",
+    "query": "coffee",
+    "sort": "RELEVANCE"
+  },
+  {
+    "latitude": 40.7128,
+    "limit": 20,
+    "longitude": -74.006,
+    "query": "hardware store",
+    "radius_m": 1000,
+    "sort": "DISTANCE"
+  }
+]
  2. Changed1 schema field changed
    • changedInput schema / properties / categories / description
      Previous value: -"Comma-separated Foursquare category IDs (fsq_category_id)"New value: +"OPTIONAL. Comma-separated numeric fsq_category_id values ONLY (e.g. from a prior search_places result). Do NOT invent IDs or pass category names — use the `query` text for that (e.g. query:\"coffee\"). Unknown IDs are ignored."
  3. Changed2 schema fields changed
    • addedInput schema / examples
      Added value: +[
+  {
+    "limit": 10,
+    "near": "Brooklyn, NY",
+    "query": "coffee",
+    "sort": "RELEVANCE"
+  },
+  {
+    "latitude": 40.7128,
+    "limit": 20,
+    "longitude": -74.006,
+    "query": "hardware store",
+    "radius_m": 1000,
+    "sort": "DISTANCE"
+  }
+]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of results returned",
+      "type": "number"
+    },
+    "results": {
+      "items": {
+        "properties": {
+          "address": {
+            "description": "Formatted address",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "categories": {
+            "description": "Place category names",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "category_ids": {
+            "description": "Foursquare category IDs",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "chain": {
+            "description": "Chain name if applicable",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "country": {
+            "description": "Country name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "description": {
+            "description": "Place description",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "distance_m": {
+            "description": "Distance in metres from search centre",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "foursquare_url": {
+            "description": "Foursquare profile URL",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "fsq_place_id": {
+            "description": "Foursquare place ID",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "hours": {
+            "description": "Hours of operation display text",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "latitude": {
+            "description": "Latitude coordinate",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "locality": {
+            "description": "City or locality name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "longitude": {
+            "description": "Longitude coordinate",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "name": {
+            "description": "Place name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "open_now": {
+            "description": "Whether place is open now",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "popularity": {
+            "description": "Popularity score",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "postcode": {
+            "description": "Postal code",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "price": {
+            "description": "Price level",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "rating": {
+            "description": "Place rating",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "region": {
+            "description": "State or region",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "tel": {
+            "description": "Phone number",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "timezone": {
+            "description": "Time zone",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "website": {
+            "description": "Place website URL",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "count",
+    "results"
+  ],
+  "type": "object"
+}
  4. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Adds substantial non-obvious behavior beyond the annotations: the service is keyless because Pipeworx supplies the key, and the Foursquare rating NUMBER is a Premium field only conditionally returned. Directing the agent to inspect `rating_included` / `rating_reason` and read `rating_note` before declaring a place unrated prevents a real correctness error. The read-only/idempotent safety profile is already covered by annotations, but this output-availability caveat is genuinely new information.

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?

Four tight sentences, front-loaded with the core purpose and the anchor-composition rule before the rating caveat. The trailing enumeration of returned fields is slightly redundant given an output schema exists, but it is brief and does not bury the important guidance.

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 an 8-parameter, zero-required search tool with a full output schema and complete annotations, the description covers the essentials: purpose, required composition pattern, sort semantics, and the critical conditional-rating caveat. Nothing an agent needs to call or interpret this tool correctly 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 the baseline is 3, but the description adds semantic meaning: concrete `query` values ('coffee', 'hardware store'), concrete `near` values ('Brooklyn, NY'), and the meaning of sort:"RATING" (best first). These clarify intent beyond the raw enum and type definitions.

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?

States a specific verb+resource ('Search Foursquare places') and defines the query-plus-location-anchor composition model, which is clear enough to distinguish it from a plain listing. However, it never names or contrasts with the closest siblings (nearby_places, get_place, search_within), so differentiation is left to inference.

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?

Gives concrete usage context: combine `query` with either `near` or `latitude`+`longitude`, with worked examples for each anchor type. No explicit when-not or alternative-tool routing is provided, so the agent must infer when to prefer this over nearby_places.

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

All Foursquare 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