Allows interaction with your Foursquare Swarm account to retrieve check-in history, venue details, and statistics.
Provides tools to access and analyze your Swarm check-in data, including history, stats, top venues, and search with filters.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@swarm-mcp Show me my recent Swarm check-ins"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that provides access to your Foursquare Swarm check-in data. Use it with Claude Desktop, Claude Code, or any MCP-compatible client to analyze your check-in history.
Tool | Description |
| Get paginated check-in history |
| Get check-ins within a specific date range |
| Get check-ins from the past X days |
| Get details about a specific check-in |
| Get venue info: ratings, hours, tips, photos |
| Retrieve your entire check-in history |
| Get statistics (total count, date range, averages) |
| List all unique categories in your history with counts |
| Get your most visited venues with filters |
| Search with filters: query, category, city, state, country, date range |
| Get server metadata, data sources, and tool costs |
All responses include a _meta block with transparency info (completeness, API calls made, data scope) to help AI models make informed decisions about expensive operations.
Tool | Cost | Notes |
| Low | Single paginated request |
| Low | Single request with date filters |
| Low | Single request with time filter |
| Low | Single check-in lookup |
| Low | Single venue lookup |
| Low | 2 API calls (newest + oldest) |
| High | Scans history to discover unique categories |
| High | Scans history to aggregate venue visits |
| None | Local introspection only |
| High | 1 API call per 250 check-ins |
| High | Client-side filtering; scans up to 5000 items |
_meta ResponseEvery tool response includes metadata like this:
{
"_meta": {
"is_complete": true,
"returned_count": 50,
"total_available": 1847,
"limit_applied": 50,
"api_calls_made": 1,
"data_source": "foursquare_swarm_api",
"data_scope": "authenticated_user_checkins"
},
"checkins": [...]
}Related MCP server: BeeMCP
uvx swarm-mcppip install swarm-mcpYou'll need a Foursquare OAuth2 access token:
Create a new app (or use an existing one)
Note your Client ID and Client Secret
Generate an access token using the OAuth2 flow, or use the API Explorer to get a token quickly
Security: Treat
FOURSQUARE_TOKENlike a password—don't commit it, paste it in issues, or share screenshots with it visible.
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"swarm": {
"command": "uvx",
"args": ["swarm-mcp"],
"env": {
"FOURSQUARE_TOKEN": "your-access-token-here"
}
}
}
}claude mcp add swarm uvx swarm-mcp -e FOURSQUARE_TOKEN=your-access-token-hereOr add manually to your config:
{
"Swarm": {
"command": "uvx",
"args": ["swarm-mcp"],
"env": {
"FOURSQUARE_TOKEN": "your-access-token-here"
}
}
}Once configured, you can ask Claude things like:
"Show me my recent Swarm check-ins"
"How many times have I checked into coffee shops this year?"
"What are my top 10 most visited coffee shops?"
"Show me all my check-ins in California"
"What are my check-in stats?"
"Get details about [venue name]" (ratings, hours, tips)
"What are the ratings for my favorite restaurants?"
📊 SWARM CHECK-IN STATS
=============================================
Total check-ins: 12,456
Years active: 10.2 years
Days active: 3,726
Avg check-ins/day: 3.34
📅 First check-in: March 15, 2014 at Coffee Shop (NYC)
📍 Most recent: Today at Office (San Francisco)# Clone the repo
git clone https://github.com/alexpriest/swarm-mcp.git
cd swarm-mcp
# Install in development mode
pip install -e .
# Run the server
FOURSQUARE_TOKEN=your-token swarm-mcpThis server uses the Foursquare API v2:
MIT License - see LICENSE for details.
Get ALL check-ins by paginating through the entire history. EXPENSIVE: Makes 1 API call per 250 check-ins (e.g., 5000 check-ins = 20 API calls). Prefer get_checkins with manual pagination for incremental access.
| Name | Required | Description | Default |
|---|---|---|---|
| max_checkins | No | Maximum total check-ins to retrieve (default 1000, use -1 for unlimited) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the expensive pagination behavior, including the exact formula for API calls and the default max_checkins value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, cost warning with example, and alternative recommendation. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers pagination, cost, and alternative, but could mention return format or ordering. Still, sufficient for an experienced user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context beyond the schema by explaining the cost implications of the max_checkins parameter and providing a concrete example of API call count.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves ALL check-ins by paginating through the entire history, distinguishing it from siblings like get_checkins and get_recent_checkins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns about the high cost (1 API call per 250 check-ins) and directs users to prefer get_checkins with manual pagination for incremental access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all unique venue categories from your check-in history with counts. Useful for discovering what categories exist before filtering. EXPENSIVE: Scans entire history.
| Name | Required | Description | Default |
|---|---|---|---|
| max_scan | No | Maximum items to scan (default 10000, use -1 for unlimited) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description warns that the tool is 'EXPENSIVE: Scans entire history', which discloses a critical behavioral trait beyond the schema. It also implies output includes counts, adding context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then usage guidance and warning. Every sentence is valuable with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description explains output (unique categories with counts) and cost. It lacks details on pagination or format, but is sufficient for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, with 'max_scan' described. The description adds meaning by connecting max_scan to the cost warning, enhancing understanding of its purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'unique venue categories', and the output 'with counts'. It distinguishes this tool from siblings like get_checkin_stats or get_top_venues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit guidance 'Useful for discovering what categories exist before filtering' and warns 'EXPENSIVE: Scans entire history', but does not explicitly state when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific check-in by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| checkin_id | Yes | The ID of the check-in to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'get detailed information' without disclosing read-only nature, authentication needs, or rate limits. The behavior is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the action and efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 parameter, no output schema, no nested objects), the description is minimally complete. However, it is vague about what 'detailed information' includes, and lacks context to differentiate from siblings. It does not explain the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter 'checkin_id' has a description. The description adds 'detailed information' which matches the schema but does not provide additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get', the resource 'detailed information about a specific check-in', and the required input 'by ID'. It distinguishes from sibling tools like 'get_all_checkins' which likely list multiple check-ins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives such as 'search_checkins' or 'get_checkins_by_date_range'. The description does not mention exclusions or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the authenticated user's check-in history. Returns check-ins with venue info, timestamps, and optional photos.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of check-ins to return (max 250, default 50) | |
| offset | No | Offset for pagination (default 0) | |
| sort | No | Sort order: 'newestfirst' or 'oldestfirst' | newestfirst |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It implies a read-only operation but does not explicitly state safety, rate limits, or side effects beyond what is obvious from 'Get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Efficiently conveys the core purpose and return content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description covers what is returned. It mentions scope (authenticated user) and return fields. However, it could be more complete given the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds some context about return fields but does not enhance parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the authenticated user's check-in history' with verb and resource, and specifies returned fields. However, it does not differentiate from sibling tools like 'get_all_checkins' or 'get_checkins_by_date_range'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. There is no mention of context or exclusions, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get check-ins within a specific date range.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | Start date in ISO format (YYYY-MM-DD) | |
| end_date | Yes | End date in ISO format (YYYY-MM-DD) | |
| limit | No | Maximum number of check-ins to return (max 250) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It only states the basic function without revealing what happens with empty results, pagination, ordering, or error conditions. This is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return format or behavior (e.g., ordering, limit handling). It does not, and the parameter limit (max 250) is only in schema. Missing details on pagination or result structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 3 parameters have descriptions). The description adds no extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get check-ins within a specific date range' clearly states the verb (get), resource (check-ins), and filter (date range), distinguishing it from siblings like get_all_checkins (no date filter) and get_recent_checkins (specific recent period).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a date range is needed, but does not explicitly mention when not to use it or provide alternatives. The context is clear, though no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about your check-in history (total count, date range, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions return of statistics but lacks details on exactly which stats, authentication requirements, or side effects. For a read-only stats tool, it is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It is appropriately front-loaded and efficient for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is sufficiently complete for its purpose. It could mention the format of returned data, but the current description covers the essential functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so baseline is 4. The description adds nothing about parameters, but this is acceptable given the empty schema. No further information needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets statistics about check-in history, with examples like total count and date range. It effectively distinguishes from sibling tools that list individual checkins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for aggregate stats but does not explicitly state when to use this tool over siblings like get_checkins_by_date_range. No alternative recommendations or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get check-ins from the past X days.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look back (default 7) | |
| limit | No | Maximum number of check-ins to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It does not disclose whether the tool is read-only, requires authentication, or what the output format is. The only behavior implied is fetching check-ins, with no additional constraints or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose efficiently. No redundant words. However, it is somewhat terse and could benefit from additional context without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of 11 sibling tools and no output schema, the description is insufficient. It does not explain what is meant by 'check-ins' (e.g., details vs. summary), or if it applies to the current user or all users. An agent might confuse this with other checkin tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter has a clear description in the schema. The tool description repeats the concept of 'past X days' but does not add new meaning beyond the schema. Baseline score of 3 is appropriate as description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves check-ins from a recent time period. The verb 'Get' and resource 'check-ins' with the qualifier 'from the past X days' aligns with the tool name. However, it does not explicitly distinguish it from sibling tools like 'get_checkins_by_date_range', which could also handle recent ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of when not to use it, such as for custom date ranges or historical data. The agent would need to infer from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about this MCP server: data sources, privacy scope, available tools, and their costs. Cheap introspection call with no external API requests.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly states that the call makes no external API requests and is cheap, which is valuable behavioral context. No contradictory annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the key information and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description adequately covers what the tool returns and its low-cost behavior. It is complete for this simple introspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add meaning beyond the schema. Baseline 4 applies per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving server metadata (data sources, privacy scope, available tools, costs). It uses a specific verb ('Get') and distinguishes itself from sibling tools, which all focus on checkins and venues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that it is a 'cheap introspection call with no external API requests,' implying it is safe and low-cost to invoke. However, it does not explicitly mention when to use it over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your most visited venues with visit counts. EXPENSIVE: Scans check-in history to aggregate venue visits.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of top venues to return (default 10) | |
| category | No | Filter by category (e.g., 'Coffee Shop', 'Bar'). Case-insensitive. | |
| city | No | Filter by city name (case-insensitive) | |
| state | No | Filter by state/region (case-insensitive) | |
| country | No | Filter by country (case-insensitive) | |
| max_scan | No | Maximum check-ins to scan (default 10000, -1 for unlimited) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses expensive scanning behavior and aggregation process. Lacks details on read-only nature or output format, but adds significant behavioral context beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second adds critical behavioral note. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters and no output schema, description explains the operation and cost. Lacks explicit output format details (e.g., fields returned), but overall sufficient for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. Description provides additional context for max_scan parameter and clarifies that visits are aggregated with counts, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'most visited venues with visit counts'. Distinguishes from siblings like get_checkins or get_recent_checkins by focusing on aggregation and ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions it is expensive due to scanning check-in history, implying use when aggregation is needed. Does not specify when not to use or name alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a venue by ID, including ratings, hours, tips, and photos. Venue IDs are included in check-in data.
| Name | Required | Description | Default |
|---|---|---|---|
| venue_id | Yes | The Foursquare venue ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the data fields returned (ratings, hours, tips, photos) but omits side effects (likely read-only), authentication needs, rate limits, or behavior on invalid ID. Acceptable for a simple lookup but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose and contents, second provides practical source for the parameter. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description covers purpose and parameter source adequately. Could mention output format or error handling but is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (venue_id) with 100% schema coverage. The description adds value beyond the schema by explaining where to find the ID ('included in check-in data'), aiding the agent in understanding how to obtain the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'detailed information about a venue', listing included fields (ratings, hours, tips, photos). It clearly distinguishes from sibling tools like get_checkins which focus on check-ins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States that venue IDs come from check-in data, providing a clear usage context. However, it does not explicitly say when not to use or list alternatives, though this is implicitly clear from the tool's name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search check-ins with flexible filters. EXPENSIVE: Requires client-side filtering. Use filters to narrow results. For comprehensive searches, increase max_scan.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Text to match against venue names or categories (case-insensitive substring). Optional if using other filters. | |
| category | No | Category match (e.g., 'Coffee Shop', 'Airport', 'Bar'). Case-insensitive. Matches both primary and parent categories (e.g., 'Coffee Shop' matches 'Café'). | |
| city | No | Filter by city name (case-insensitive substring match) | |
| state | No | Filter by state/region (case-insensitive substring match) | |
| country | No | Filter by country (case-insensitive substring match) | |
| start_date | No | Start date in ISO format (YYYY-MM-DD). Only return check-ins on or after this date. | |
| end_date | No | End date in ISO format (YYYY-MM-DD). Only return check-ins on or before this date. | |
| limit | No | Maximum results to return (default 50) | |
| max_scan | No | Maximum items to scan (default 5000). Increase for comprehensive searches, use -1 for unlimited. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions EXPENSIVE and client-side filtering, which adds transparency beyond the schema. However, it lacks details on authentication, rate limits, or potential destructive effects, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, followed by a warning and usage hint. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description is incomplete. It does not describe the return format, pagination, or performance expectations beyond the expense warning. The schema covers inputs, but more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds only the expense warning and max_scan hint, which provides marginal additional context. Baseline 3 is appropriate as the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches check-ins with flexible filters, distinguishing it from sibling tools like get_all_checkins and get_checkins_by_date_range. The verb 'search' and resource 'check-ins' are specific and convey the tool's purpose effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that it is expensive and requires client-side filtering, guiding when to use filters and increase max_scan. It implies when not to use (e.g., for simple retrieval, use alternative tools), but does not explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.0get_all_checkinsget_categoriesget_checkin_detailsget_checkin_statsget_checkinsget_checkins_by_date_rangeget_recent_checkinsget_server_infoget_top_venuesget_venue_detailssearch_checkinsEach tool has a clearly distinct purpose: get_all_checkins vs get_checkins differ in pagination cost, get_checkins_by_date_range vs get_recent_checkins target different time ranges, and others cover categories, stats, venues, and server info. Descriptions explicitly clarify overlaps.
All tool names follow a consistent get_verb_noun pattern in snake_case (e.g., get_all_checkins, get_categories, get_checkin_stats). No mixing of naming conventions, making it easy to infer function.
With 11 tools, the server covers all major retrieval needs for check-in history and venue data without being bloated. The count is well-scoped for a focused analytics domain.
The server provides comprehensive read access: full history, filtered, stats, categories, top venues, and venue details. Missing write/update tools aligns with use case. A minor gap is no direct tool to list check-ins for a specific venue, but search_checkins can approximate this.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Flight search MCP server providing search, pagination, and itinerary details for AI assistants.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/alexpriest/swarm-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
