Foursquare

Search Places

search_places

Read-onlyIdempotent

Search Foursquare places. Combine query (e.g., "coffee", "hardware store") with a location anchor — either near ("Brooklyn, NY") or latitude+longitude. Returns name, fsq_place_id, categories, address, distance, lat/lon, popularity.

Input Schema

TableJSON Schema

Name	Required	Description
`near`	No	Place name anchor ("Brooklyn, NY", "Tokyo")
`sort`	No	RELEVANCE (default) \| DISTANCE \| RATING \| POPULARITY
`limit`	No	Results (1-50, default 10)
`query`	No	Free-text query
`latitude`	No	Center latitude (pair with longitude)
`radius_m`	No	1-100000 metres (only with lat/lon)
`longitude`	No	Center longitude
`categories`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	Yes	Number of results returned
`results`	Yes

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed1 schema field changedJun 21, 2026

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."

Changed2 schema fields changedMay 24, 2026

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"
+}

First observedMay 12, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds value by specifying the exact return fields and highlighting a constraint on the `categories` parameter (must be numeric IDs from prior results). There is no contradiction with annotations.

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 extremely concise, consisting of two sentences that front-load the primary purpose and then list the return fields. Every sentence adds necessary information without redundancy.

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?

Given the tool's complexity (8 parameters, output schema present, rich annotations), the description covers the core functionality and return format adequately. It does not discuss sorting behavior or pagination, but those are documented in the schema.

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% with detailed descriptions for each parameter, including examples and constraints (e.g., `categories` explanation is thorough). The tool description does not add new meaning beyond that, so the baseline of 3 is appropriate.

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 clearly states it searches Foursquare places and specifies the required combination of query and location anchor. It also lists the output fields. However, it does not explicitly distinguish from the sibling tool `nearby_places`, which might serve a different use case (e.g., query-less nearby search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that either `near` or `latitude`+`longitude` must be used with `query`, providing some usage context. But it offers no guidance on when to prefer this tool over `nearby_places` or other sibling tools, and no exclusions or prerequisites are mentioned.

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

All Foursquare tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.