user-access-trail-tool
Trace a user's physical access events across all doors. Retrieve badge-in history by user UUID or email address.
Instructions
This tool traces a specific user's physical access events across all doors and access points. It answers questions like "Where did this person badge in?" or "Show me all access events for this user."
It has the following modes of operation, determined by the "requestType" parameter:
get-access-events-by-user: Get access events using a known userUuid. Requires userUuid.
get-access-events-by-email: Get access events by looking up the user's email first. Requires email. Automatically resolves the user UUID.
Both modes support optional startTimeMs, endTimeMs, and limit parameters. Use the user-tool to find user UUIDs if needed, or use the email-based lookup directly.
Output filtering (all tools):
includeFields(string[]): Dot-notation paths to keep in the response (e.g."vehicleEvents.vehicleLicensePlate"). Omit to return all fields.filterBy(array): Predicates to filter array items. Each entry:{field, op, value}where op is one of= != > >= < <= contains. All conditions are ANDed. Example:[{field:"vehicleLicensePlate", op:"=", value:"ABC123"}]WARNING: some tool responses exceed 400k characters — use these params to request only the data you need.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| requestType | Yes | The type of access trail request. | |
| userUuid | Yes | User UUID. Required for 'get-access-events-by-user'. | |
| Yes | User email address. Required for 'get-access-events-by-email'. Will resolve to userUuid automatically. | ||
| startTimeMs | Yes | Start time filter in milliseconds since epoch. | |
| endTimeMs | Yes | End time filter in milliseconds since epoch. | |
| limit | Yes | Maximum number of events to return. Defaults to 100. | |
| includeFields | Yes | Dot-notation field paths to include in the response (e.g. "vehicleEvents.vehicleLicensePlate"). Pass null to return all fields. WARNING: some responses can exceed 400k characters — use includeFields to request only the data you need. For high-volume tools this may be required to get a complete answer. | |
| filterBy | Yes | Filter array items in the response by field values. All conditions are ANDed. Example: [{field: "vehicleLicensePlate", op: "=", value: "ABC123"}, {field: "confidence", op: ">", value: 0.8}] Use alongside includeFields to get only the specific records and fields you need. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| userUuid | No | Resolved user UUID | |
| userName | No | Resolved user name | |
| accessEvents | No | List of access control events for the user, ordered by time | |
| error | No | An error message if the request failed. |