PixelFlow

List events

list_events

Read-onlyIdempotent

List the tracked events on one site as rows, up to 100 per call. Each row has the time, event, page URL, traffic source, value, visitor and session ids, UTM tags with first and last touch, consent, and send status per pixel with any ad platform error. For an event's full payload, pass its id to get_event_payloads. Use it to answer questions about tracked events, such as what one visitor did, which conversions failed to send, or which pages purchases came from.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "site_id": "<site_id>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "list_events"
  }
}

Input Schema

Name	Required	Description
`to`	Yes	Range end. YYYY-MM-DD means the end of that day in `timezone`, so the whole day is included; a full ISO 8601 timestamp is used as is.
`from`	Yes	Range start. YYYY-MM-DD means the start of that day in `timezone`; a full ISO 8601 timestamp is used as is.
`sort`	No	Default newest.
`limit`	No	Page size. Default 25.
`cursor`	No	next_cursor from the previous page, with the same sort. Omit for the first page.
`events`	No	Events to include, such as Purchase. Names are in list_supported_values's `events`. Default all.
`site_id`	Yes	Site to act on, as returned by list_sites.
`sources`	No	Traffic source buckets, such as facebook, google, organic, or direct. Names are in list_supported_values's `sources`.
`timezone`	No	IANA time zone such as Europe/Berlin. Default UTC. Returned times and day buckets use it.
`utm_term`	No	Same, for UTM term (usually the ad set).
`pixel_ids`	No	Only events sent to these pixels, ids from get_site_status. Rows still list every pixel.
`visitor_id`	No	One visitor's events, visitor_id from an earlier row.
`utm_content`	No	Same, for UTM content (usually the ad).
`utm_campaign`	No	Match the visitor's UTM campaign seen in the lookback_days before the event (returned in the result). (not set) matches a blank value.
`is_sent_successfully`	No	Whether to return only delivered events (true) or only failed and still-sending events (false); rows with an error are real failures. Default all.

Output Schema

Name	Required	Description
`events`	Yes	Events, in the requested sort.
`window`	Yes	Exact range read, after applying timezone.
`timezone`	Yes	IANA time zone used for dates and times. UTC when none was passed.
`event_count`	Yes	Rows on this page.
`next_cursor`	Yes	Pass as cursor for the next page. null: last page.
`lookback_days`	Yes	Days before each event in which the visitor's UTM tags count, for the UTM filters and fields.

Schema Changelog

Changes observed during successful MCP inspections.

Changed52 schema fields changedNov 2, 2026

addedOutput schema / properties / events / items / properties / consent / properties / decision_at / anyOf

Added value: +[
+  {
+    "format": "date-time",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / consent / properties / decision_at / format
```
Removed value: -"date-time"
```
removedOutput schema / properties / events / items / properties / consent / properties / decision_at / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / consent / properties / regime / anyOf

Added value: +[
+  {
+    "enum": [
+      "opt_in",
+      "opt_out"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / consent / properties / regime / enum
```
Removed value: -[
-  "opt_in",
-  "opt_out",
-  null
-]
```
removedOutput schema / properties / events / items / properties / consent / properties / regime / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedOutput schema / properties / events / items / properties / consent / properties / source / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedOutput schema / properties / events / items / properties / consent / properties / source / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedOutput schema / properties / events / items / properties / consent / properties / state / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedOutput schema / properties / events / items / properties / consent / properties / state / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / currency / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / currency / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / error / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / error / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / event_id / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / event_id / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
removedOutput schema / properties / events / items / properties / first_touch / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / events / items / properties / first_touch / anyOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Source, such as facebook or organic."
+      },
+      "utm_campaign": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM campaign."
+      },
+      "utm_content": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM content (usually the ad)."
+      },
+      "utm_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM id."
+      },
+      "utm_medium": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM medium."
+      },
+      "utm_term": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM term (usually the ad set)."
+      }
+    },
+    "required": [
+      "source",
+      "utm_campaign",
+      "utm_term",
+      "utm_content",
+      "utm_medium",
+      "utm_id"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / first_touch / properties

Removed value: -{
-  "source": {
-    "description": "Source, such as facebook or organic.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_campaign": {
-    "description": "UTM campaign.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_content": {
-    "description": "UTM content (usually the ad).",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_id": {
-    "description": "UTM id.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_medium": {
-    "description": "UTM medium.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_term": {
-    "description": "UTM term (usually the ad set).",
-    "type": [
-      "string",
-      "null"
-    ]
-  }
-}

removedOutput schema / properties / events / items / properties / first_touch / required

Removed value: -[
-  "source",
-  "utm_campaign",
-  "utm_term",
-  "utm_content",
-  "utm_medium",
-  "utm_id"
-]

removedOutput schema / properties / events / items / properties / first_touch / type
```
Removed value: -[
-  "object",
-  "null"
-]
```
removedOutput schema / properties / events / items / properties / last_touch / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / events / items / properties / last_touch / anyOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "source": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Source, such as facebook or organic."
+      },
+      "utm_campaign": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM campaign."
+      },
+      "utm_content": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM content (usually the ad)."
+      },
+      "utm_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM id."
+      },
+      "utm_medium": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM medium."
+      },
+      "utm_term": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "UTM term (usually the ad set)."
+      }
+    },
+    "required": [
+      "source",
+      "utm_campaign",
+      "utm_term",
+      "utm_content",
+      "utm_medium",
+      "utm_id"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / last_touch / properties

Removed value: -{
-  "source": {
-    "description": "Source, such as facebook or organic.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_campaign": {
-    "description": "UTM campaign.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_content": {
-    "description": "UTM content (usually the ad).",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_id": {
-    "description": "UTM id.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_medium": {
-    "description": "UTM medium.",
-    "type": [
-      "string",
-      "null"
-    ]
-  },
-  "utm_term": {
-    "description": "UTM term (usually the ad set).",
-    "type": [
-      "string",
-      "null"
-    ]
-  }
-}

removedOutput schema / properties / events / items / properties / last_touch / required

Removed value: -[
-  "source",
-  "utm_campaign",
-  "utm_term",
-  "utm_content",
-  "utm_medium",
-  "utm_id"
-]

removedOutput schema / properties / events / items / properties / last_touch / type
```
Removed value: -[
-  "object",
-  "null"
-]
```
addedOutput schema / properties / events / items / properties / pixels / items / properties / ad_platform / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedOutput schema / properties / events / items / properties / pixels / items / properties / ad_platform / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / session_id / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / session_id / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / source / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / source / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / url / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / url / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / utm_campaign / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / utm_campaign / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / utm_content / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / utm_content / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / utm_id / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / utm_id / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / utm_medium / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / utm_medium / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / utm_source / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / utm_source / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / utm_term / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / utm_term / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / value / anyOf

Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / value / type
```
Removed value: -[
-  "number",
-  "null"
-]
```

addedOutput schema / properties / events / items / properties / visitor_id / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / events / items / properties / visitor_id / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedOutput schema / properties / next_cursor / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / next_cursor / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

Changed25 schema fields changedNov 2, 2026

changedInput schema / properties / cursor / description

Previous value: -"next_cursor from the previous list_events page. Omit for the first page. Keep the same sort"New value: +"next_cursor from the previous page, with the same sort. Omit for the first page."

removedInput schema / properties / event_type

Removed value: -{
-  "description": "One event type value, such as Purchase. Omit for every type. Do not also pass event_types",
-  "type": "string"
-}

removedInput schema / properties / event_types

Removed value: -{
-  "description": "Several event type values, such as Purchase. Do not also pass event_type",
-  "items": {
-    "type": "string"
-  },
-  "maxItems": 50,
-  "type": "array"
-}

addedInput schema / properties / events

Added value: +{
+  "description": "Events to include, such as Purchase. Names are in list_supported_values's `events`. Default all.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 50,
+  "type": "array"
+}

changedInput schema / properties / from / description

Previous value: -"Range start. YYYY-MM-DD is the start of that calendar day in timezone. A full ISO instant is that instant"New value: +"Range start. YYYY-MM-DD means the start of that day in `timezone`; a full ISO 8601 timestamp is used as is."

changedInput schema / properties / is_sent_successfully / description

Previous value: -"true is sent. false includes an event that has not finished. false with error not null is a real failure. Omit for every status"New value: +"Whether to return only delivered events (true) or only failed and still-sending events (false); rows with an error are real failures. Default all."

changedInput schema / properties / limit / description

Previous value: -"Page size from 1 to 100. Omitted means 25"New value: +"Page size. Default 25."

addedInput schema / properties / limit / maximum
```
Added value: +100
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

changedInput schema / properties / limit / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / pixel_ids / description

Previous value: -"Pixel ids from get_site_status. Sent to still lists every pixel on the row"New value: +"Only events sent to these pixels, ids from get_site_status. Rows still list every pixel."

changedInput schema / properties / pixel_ids / items / type
```
Previous value: -"number"New value: +"integer"
```

removedInput schema / properties / site

Removed value: -{
-  "description": "Domain, id, or external id from list_sites",
-  "type": "string"
-}

addedInput schema / properties / site_id

Added value: +{
+  "description": "Site to act on, as returned by list_sites.",
+  "type": "integer"
+}

changedInput schema / properties / sort / description

Previous value: -"newest or oldest. Omitted means newest. The cursor must use the same sort"New value: +"Default newest."

addedInput schema / properties / sort / enum

Added value: +[
+  "newest",
+  "oldest"
+]

changedInput schema / properties / sources / description

Previous value: -"Source buckets such as facebook, google, organic, or direct"New value: +"Traffic source buckets, such as facebook, google, organic, or direct. Names are in list_supported_values's `sources`."

changedInput schema / properties / timezone / description

Previous value: -"IANA timezone. Omitted means UTC, and the response says UTC"New value: +"IANA time zone such as Europe/Berlin. Default UTC. Returned times and day buckets use it."

changedInput schema / properties / to / description

Previous value: -"Range end. YYYY-MM-DD is the end of that calendar day in timezone, so later events that day are included. A full ISO instant is that instant"New value: +"Range end. YYYY-MM-DD means the end of that day in `timezone`, so the whole day is included; a full ISO 8601 timestamp is used as is."

changedInput schema / properties / utm_campaign / description

Previous value: -"90-day campaign tags. (not set) matches a blank campaign"New value: +"Match the visitor's UTM campaign seen in the lookback_days before the event (returned in the result). (not set) matches a blank value."

changedInput schema / properties / utm_content / description

Previous value: -"90-day ad tags. (not set) matches a blank ad"New value: +"Same, for UTM content (usually the ad)."

changedInput schema / properties / utm_term / description

Previous value: -"90-day ad set tags. (not set) matches a blank ad set"New value: +"Same, for UTM term (usually the ad set)."

changedInput schema / properties / visitor_id / description

Previous value: -"One person, from an earlier row. Read pixelflow://glossary before using it"New value: +"One visitor's events, visitor_id from an earlier row."

changedInput schema / required

Previous value: -[
-  "site",
-  "from",
-  "to"
-]New value: +[
+  "site_id",
+  "from",
+  "to"
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "event_count": {
+      "description": "Rows on this page.",
+      "type": "integer"
+    },
+    "events": {
+      "description": "Events, in the requested sort.",
+      "items": {
+        "additionalProperties": false,
+        "description": "One event.",
+        "properties": {
+          "consent": {
+            "additionalProperties": false,
+            "description": "Consent on the event: `state`, `source` (consent tool), `decision_at` (date-time, in timezone) (string or null each), and `regime` (enum: opt_in, opt_out; or null). opt_in: consent is needed before tracking. opt_out: tracking is allowed until the visitor refuses. null when not recorded.",
+            "properties": {
+              "decision_at": {
+                "description": "When the visitor decided.",
+                "format": "date-time",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "regime": {
+                "description": "Consent rule for the visitor's region. opt_in: consent is needed before tracking. opt_out: tracking is allowed until the visitor refuses. null when not recorded.",
+                "enum": [
+                  "opt_in",
+                  "opt_out",
+                  null
+                ],
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "source": {
+                "description": "Consent tool.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "state": {
+                "description": "Consent state.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "state",
+              "source",
+              "decision_at",
+              "regime"
+            ],
+            "type": "object"
+          },
+          "currency": {
+            "description": "Event currency.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "error": {
+            "description": "Ad platform error. Set only on a real failure.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "event": {
+            "description": "Event recorded, such as Purchase.",
+            "type": "string"
+          },
+          "event_id": {
+            "description": "Deduplication id shared with the browser pixel.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "first_touch": {
+            "additionalProperties": false,
+            "description": "First and last visit credited: `source`, `utm_campaign`, `utm_term`, `utm_content`, `utm_medium`, `utm_id` (string or null). null when no touch was recorded.",
+            "properties": {
+              "source": {
+                "description": "Source, such as facebook or organic.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_campaign": {
+                "description": "UTM campaign.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_content": {
+                "description": "UTM content (usually the ad).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_id": {
+                "description": "UTM id.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_medium": {
+                "description": "UTM medium.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_term": {
+                "description": "UTM term (usually the ad set).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "source",
+              "utm_campaign",
+              "utm_term",
+              "utm_content",
+              "utm_medium",
+              "utm_id"
+            ],
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Id of this event row. get_event_payloads takes it in ids. Not the same as event_id.",
+            "type": "integer"
+          },
+          "is_sent_successfully": {
+            "description": "Whether the event was delivered to the ad platforms.",
+            "type": "boolean"
+          },
+          "last_touch": {
+            "additionalProperties": false,
+            "description": "First and last visit credited: `source`, `utm_campaign`, `utm_term`, `utm_content`, `utm_medium`, `utm_id` (string or null). null when no touch was recorded.",
+            "properties": {
+              "source": {
+                "description": "Source, such as facebook or organic.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_campaign": {
+                "description": "UTM campaign.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_content": {
+                "description": "UTM content (usually the ad).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_id": {
+                "description": "UTM id.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_medium": {
+                "description": "UTM medium.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "utm_term": {
+                "description": "UTM term (usually the ad set).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "source",
+              "utm_campaign",
+              "utm_term",
+              "utm_content",
+              "utm_medium",
+              "utm_id"
+            ],
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "pixels": {
+            "description": "Per pixel: `pixel_id`, `name`, `ad_platform`, `state` (enum: sent, failed, pending).",
+            "items": {
+              "additionalProperties": false,
+              "description": "One pixel.",
+              "properties": {
+                "ad_platform": {
+                  "description": "Ad platform name.",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "name": {
+                  "description": "Pixel name.",
+                  "type": "string"
+                },
+                "pixel_id": {
+                  "description": "Pixel id.",
+                  "type": "integer"
+                },
+                "state": {
+                  "description": "Send status, as in list_events.",
+                  "enum": [
+                    "sent",
+                    "failed",
+                    "pending"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "pixel_id",
+                "name",
+                "ad_platform",
+                "state"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "session_id": {
+            "description": "Session id.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source": {
+            "description": "Traffic source bucket credited.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "time": {
+            "description": "When the event arrived, in timezone.",
+            "format": "date-time",
+            "type": "string"
+          },
+          "url": {
+            "description": "Page URL.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utm_campaign": {
+            "description": "UTM tag of the visitor in the lookback_days before the event.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utm_content": {
+            "description": "UTM tag of the visitor in the lookback_days before the event.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utm_id": {
+            "description": "UTM tag of the visitor in the lookback_days before the event.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utm_medium": {
+            "description": "UTM tag of the visitor in the lookback_days before the event.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utm_source": {
+            "description": "UTM tag of the visitor in the lookback_days before the event.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utm_term": {
+            "description": "UTM tag of the visitor in the lookback_days before the event.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "value": {
+            "description": "Event value.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "visitor_id": {
+            "description": "Visitor id.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "time",
+          "event",
+          "url",
+          "source",
+          "value",
+          "currency",
+          "event_id",
+          "visitor_id",
+          "session_id",
+          "is_sent_successfully",
+          "error",
+          "utm_source",
+          "utm_medium",
+          "utm_campaign",
+          "utm_term",
+          "utm_content",
+          "utm_id",
+          "first_touch",
+          "last_touch",
+          "consent",
+          "pixels"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "lookback_days": {
+      "description": "Days before each event in which the visitor's UTM tags count, for the UTM filters and fields.",
+      "type": "integer"
+    },
+    "next_cursor": {
+      "description": "Pass as cursor for the next page. null: last page.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "timezone": {
+      "description": "IANA time zone used for dates and times. UTC when none was passed.",
+      "type": "string"
+    },
+    "window": {
+      "additionalProperties": false,
+      "description": "Exact range read, after applying timezone.",
+      "properties": {
+        "from": {
+          "description": "First instant included.",
+          "format": "date-time",
+          "type": "string"
+        },
+        "to": {
+          "description": "Last instant included.",
+          "format": "date-time",
+          "type": "string"
+        }
+      },
+      "required": [
+        "from",
+        "to"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "window",
+    "timezone",
+    "event_count",
+    "next_cursor",
+    "lookback_days",
+    "events"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedOct 27, 2026

changedInput schema / properties / from / description

Previous value: -"Range start, ISO date"New value: +"Range start. YYYY-MM-DD is the start of that calendar day in timezone. A full ISO instant is that instant"

changedInput schema / properties / to / description

Previous value: -"Range end, ISO date"New value: +"Range end. YYYY-MM-DD is the end of that calendar day in timezone, so later events that day are included. A full ISO instant is that instant"

First observedOct 23, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds value beyond that by sketching the row shape (per-pixel send status with ad platform error, first/last-touch UTMs, consent) so an agent knows what evidence is available. It omits continuation behavior for large result sets, which the schema covers via cursor.

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?

Front-loaded with the core action and row limit, then routing, then use cases in a logical order. The middle sentence enumerating every row field is long and partly duplicates the output schema, but it is one sentence and genuinely aids tool selection.

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 15-parameter read tool with a full output schema and rich annotations, the description supplies everything the structured fields do not: purpose, the sibling split, and the analytic questions it answers. Return values and parameter details are correctly delegated to the output schema and schema descriptions.

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%, so every one of the 15 parameters is already documented in the schema, including subtle semantics like the (not set) UTM matching and pixel filtering that still lists all pixels. The description mentions no parameters directly, so it adds nothing over the schema; baseline 3 applies.

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?

States a specific verb (list), resource (tracked events), and scope (one site, up to 100 rows per call). It also draws the boundary against the sibling get_event_payloads, so an agent can tell the two apart without opening either schema.

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?

It names the alternative (get_event_payloads, reached by passing an event id) and the condition that selects it, then gives three concrete question shapes the tool is meant to answer (visitor journey, failed conversions, purchase pages). Nothing about when to reach for this tool is left to inference.

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

All PixelFlow tools Inspect

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.