Skip to main content
Glama
Sign In

pifini

by net.pifini
OverviewDiscussionsAdmin

Search events

search_events
Read-onlyIdempotent

Search upcoming events (festivals, carnivals, concerts, food + cultural events) across the Caribbean, Latin America, and beyond. Returns event names, dates, locations, category, price (when known), and page URLs. Strongest coverage: Barbados, Trinidad, Jamaica, Bahamas, Mexico.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
cityNoCity name filter
limitNoMax results, 1-50 (default 10)
queryNoFree-text search over title and description
offsetNoSkip this many matching results (for paging past the limit)
countryNoISO-3166 alpha-2 country code, e.g. BB, TT, JM
categoryNoFilter by event category
near_latNoLatitude to search near (pair with near_lng)
near_lngNoLongitude to search near (pair with near_lat)
radius_kmNoSearch radius in km around near_lat/near_lng (default 25, max 500)
entry_modelNoFilter by how someone gets in: 'free' = confirmed free entry, 'ticketed' = Pifini sells tickets, 'external' = paid but sold elsewhere, 'mixed' = umbrella event with both free and paid components, 'unknown' = not yet confirmed either way.
include_pastNoInclude past events (default false)
starts_afterNoEarliest start. A bare date ('2026-08-01') matches the event's LOCAL calendar date in its own timezone and is inclusive — this is what you want for 'what's on this weekend'. A full ISO timestamp ('2026-08-01T18:00:00Z') is compared as an exact UTC instant instead.
starts_beforeNoLatest start, same rules as starts_after. A bare date is inclusive of that whole local day, so starts_after='2026-08-13' with starts_before='2026-08-13' returns everything happening on the 13th where it happens.

Output Schema

NameRequiredDescriptionDefault
countYesNumber of events in this page of results
totalYesTotal events matching the filters, across all pages. Use this before claiming how many exist.
eventsYes
has_moreYesTrue when more matches exist beyond this page.
next_offsetNoPass as `offset` to fetch the next page. Null when this is the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / starts_after / description
      Previous value: -"Only events starting on/after this date, e.g. '2026-08-01' or a full ISO timestamp"New value: +"Earliest start. A bare date ('2026-08-01') matches the event's LOCAL calendar date in its own timezone and is inclusive — this is what you want for 'what's on this weekend'. A full ISO timestamp ('2026-08-01T18:00:00Z') is compared as an exact UTC instant instead."
    • changedInput schema / properties / starts_before / description
      Previous value: -"Only events starting on/before this date, e.g. '2026-08-31' or a full ISO timestamp"New value: +"Latest start, same rules as starts_after. A bare date is inclusive of that whole local day, so starts_after='2026-08-13' with starts_before='2026-08-13' returns everything happening on the 13th where it happens."
  2. Changed9 schema fields changed
    • addedOutput schema / properties / events / items / properties / local_date
      Added value: +{
+  "description": "The date the event actually happens where it happens, YYYY-MM-DD. Quote this one.",
+  "type": "string"
+}
    • addedOutput schema / properties / events / items / properties / local_time
      Added value: +{
+  "description": "Local start time, HH:MM 24h. Null when start_time_known is false — say nothing about the time in that case.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / events / items / properties / start_time_known
      Added value: +{
+  "description": "False when only the date is known and the stored hour is a placeholder. Never present a start time when this is false.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / events / items / properties / starts_at / description
      Added value: +"Exact start instant, ISO-8601 UTC. Do NOT format this for a human — it is the wrong calendar day in most of the region. Use local_date / local_time."
    • addedOutput schema / properties / events / items / properties / timezone
      Added value: +{
+  "description": "IANA timezone of the venue, e.g. America/Mexico_City. Null when unknown.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / has_more
      Added value: +{
+  "description": "True when more matches exist beyond this page.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / next_offset
      Added value: +{
+  "description": "Pass as `offset` to fetch the next page. Null when this is the last page.",
+  "type": [
+    "number",
+    "null"
+  ]
+}
    • addedOutput schema / properties / total
      Added value: +{
+  "description": "Total events matching the filters, across all pages. Use this before claiming how many exist.",
+  "type": "number"
+}
    • changedOutput schema / required
      Previous value: -[
-  "count",
-  "events"
-]New value: +[
+  "count",
+  "total",
+  "has_more",
+  "events"
+]
  3. Changed10 schema fields changed
    • addedInput schema / properties / category
      Added value: +{
+  "description": "Filter by event category",
+  "enum": [
+    "music",
+    "arts",
+    "culture",
+    "festival",
+    "sports",
+    "food",
+    "business",
+    "nightlife"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / entry_model
      Added value: +{
+  "description": "Filter by how someone gets in: 'free' = confirmed free entry, 'ticketed' = Pifini sells tickets, 'external' = paid but sold elsewhere, 'mixed' = umbrella event with both free and paid components, 'unknown' = not yet confirmed either way.",
+  "enum": [
+    "free",
+    "ticketed",
+    "external",
+    "mixed",
+    "unknown"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / limit / description
      Previous value: -"Max results, 1-25 (default 10)"New value: +"Max results, 1-50 (default 10)"
    • addedInput schema / properties / near_lat
      Added value: +{
+  "description": "Latitude to search near (pair with near_lng)",
+  "type": "number"
+}
    • addedInput schema / properties / near_lng
      Added value: +{
+  "description": "Longitude to search near (pair with near_lat)",
+  "type": "number"
+}
    • addedInput schema / properties / offset
      Added value: +{
+  "description": "Skip this many matching results (for paging past the limit)",
+  "type": "number"
+}
    • addedInput schema / properties / radius_km
      Added value: +{
+  "description": "Search radius in km around near_lat/near_lng (default 25, max 500)",
+  "type": "number"
+}
    • addedInput schema / properties / starts_after
      Added value: +{
+  "description": "Only events starting on/after this date, e.g. '2026-08-01' or a full ISO timestamp",
+  "type": "string"
+}
    • addedInput schema / properties / starts_before
      Added value: +{
+  "description": "Only events starting on/before this date, e.g. '2026-08-31' or a full ISO timestamp",
+  "type": "string"
+}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of events in this page of results",
+      "type": "number"
+    },
+    "events": {
+      "items": {
+        "properties": {
+          "attendee_count": {
+            "type": "number"
+          },
+          "category": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "city": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "country": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "cover_image_url": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "distance_km": {
+            "description": "Only present when near_lat/near_lng were given",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "ends_at": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "entry_model": {
+            "type": "string"
+          },
+          "organizer_name": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "price": {
+            "properties": {
+              "currency": {
+                "type": "string"
+              },
+              "max": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "min": {
+                "type": "number"
+              },
+              "note": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "slug": {
+            "type": "string"
+          },
+          "starts_at": {
+            "type": "string"
+          },
+          "summary": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "count",
+    "events"
+  ],
+  "type": "object"
+}
  4. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by noting coverage limitations ('Strongest coverage: Barbados, Trinidad...') and return field specifics including the 'price (when known)' caveat, which helps set expectations.

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 two sentences with no waste. It front-loads the action ('Search upcoming events...') and scope, then concisely lists return fields and coverage strengths.

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 rich schema (13 params, all documented) and the presence of an output schema, the high-level description is sufficient. It orients the agent to the tool's purpose and geographic focus without needing to restate parameter semantics. Slightly more context about filtering capabilities would push it to 5, but it is complete enough.

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?

All 13 parameters have detailed descriptions in the schema (100% schema description coverage), including nuanced explanations for starts_after and starts_before date handling. The tool description adds no parameter-level detail beyond what the schema already provides, so the baseline score of 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 description clearly states it searches upcoming events (festivals, carnivals, concerts, food + cultural events) across a specific geography. It distinguishes itself from sibling tools like search_places and get_event by focusing on multi-event search for the Caribbean/Latin America region.

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?

It provides clear context for when to use the tool (event discovery in specific regions) but does not explicitly mention when not to use it or name alternatives. The context is sufficient for an agent to infer it is the right tool for finding events as opposed to places or single-event details.

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

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