Samsara MCP — Tools Reference
Samsara MCP tools and the 44-query read-only GA catalog, with example prompts.
GA catalog. Samsara MCP provides the Samsara Assistant plus deterministic access to 44 approved, read-only queries. The query catalog is loaded on demand rather than placing 44 separate tools in your client's tool list.
For connection instructions and regional endpoints, see the main MCP guide.
How the tool surface works
Samsara MCP exposes five tools. Your organization may see the Assistant surface, the deterministic query surface, or both, depending on its configuration.
| Tool | What it does |
|---|---|
samsara_assistant(question) | Sends one self-contained natural-language question to the Samsara Assistant and returns a synthesized prose answer. |
read_reference_card() | Returns a compact catalog of the query IDs available to your organization. |
describe_query(query_id) | Returns a query's purpose, required variables, examples, and output columns. |
run_query(query_id, variables) | Runs one approved read-only query. Your organization is supplied automatically from your credentials. |
report_agent_experience(...) | Records feedback when an agent encounters missing data, unclear tools, or other friction. |
The deterministic surface uses three tools—read_reference_card, describe_query, and run_query—instead of registering one MCP tool for each query. This keeps the client's tool list compact as the catalog grows.
Samsara Assistant
Use samsara_assistant for questions that benefit from the Samsara Assistant selecting and combining the right Samsara capabilities.
You can ask:
- "Which drivers have at least four hours of drive time remaining?"
- "Which vehicles have active faults that need attention?"
- "Summarize our highest-impact safety behaviors this week."
Each call is single-turn and stateless. Include the relevant vehicle, driver, tag, time range, units, and earlier findings directly in the question. The Assistant does not receive prior conversation turns or results from your client's other tools. Do not include an organization ID; Samsara supplies it from your authenticated connection.
The answer is synthesized prose. Use the deterministic query surface when your workflow needs a specific query, known fields, or structured rows.
Deterministic query catalog
The GA catalog includes the 44 query IDs below through run_query. Call read_reference_card to retrieve the catalog currently available to your organization, and use describe_query before the first call when you need the exact variables or output fields.
Core entities and resolution
| Query ID | What it provides |
|---|---|
query://global_search | Resolves drivers, vehicles, assets, and trailers by name or identifier. |
query://drivers/list | Driver roster, tags, current vehicle, and available location context. |
query://tags/list | Organization tag hierarchy and entity counts. |
query://tags/descendants | Expands tags to include their descendant tags for scoped queries. |
query://locations/places | Saved places and geofence metadata. |
query://locations/resolve | Resolves a place name or address to coordinates. |
Fleet, vehicles, and equipment
| Query ID | What it provides |
|---|---|
query://assets/list | Fleet roster, identifiers, status, location, assignment, and tags. |
query://assets/list_extended | Additional asset, driver, tag, vehicle, and trailer context. |
query://assets/engine_gauges | Engine readings such as fuel level, RPM, and supported tire data. |
query://assets/maintenance | Fleet-wide check-engine-light and diagnostic trouble-code status. |
query://assets/trip_history | Trips and stops for one vehicle over a time range. |
query://assets/fault_history | Fault occurrence history for one vehicle. |
query://assets/preventive_maintenance | Upcoming preventive-maintenance items and due information. |
query://assets/utilization | Utilization, dormancy, and overutilization metrics. |
Example questions:
- "Which vehicles have active diagnostic trouble codes?"
- "Show trips and stops for Unit 118 yesterday."
- "Which assets were under 30% utilization last month?"
Safety
| Query ID | What it provides |
|---|---|
query://safety/events | Individual safety events with driver, vehicle, behavior, severity, and available media links. |
query://safety/event_details | Full details for one safety event. |
query://safety/event_trends | Safety-event counts over time. |
query://safety/speeding_trips_vehicle | Speeding trips for one vehicle. |
query://safety/speeding_trips_driver | Speeding trips for one driver. |
query://safety/scores/driver | Driver safety scores and ranking. |
query://safety/scores/vehicle | Vehicle safety scores. |
query://safety/fleet_summary | Fleet-wide safety, behavior, and speeding summary. |
query://safety/behavior_stats | Behavior frequency and safety-score impact. |
Example questions:
- "Show severe safety events from the last seven days."
- "Which drivers had the most severe speeding trips this month?"
- "Which behaviors had the greatest impact on our fleet safety score?"
Safety-event media links are permission-scoped and time-limited. Location-based filtering of safety events is not currently supported; filter by driver, vehicle, tag, behavior, severity, and time where available.
Compliance and inspections
| Query ID | What it provides |
|---|---|
query://compliance/hos/status | Current duty status and remaining HOS clocks. |
query://compliance/hos/violations | HOS violation intervals and types. |
query://compliance/hos/daily_duty_time | Daily duty-time totals by driver. |
query://compliance/hos/log_entries | Regulated duty-status intervals. |
query://compliance/hos/eld_events | Unified ELD event timeline. |
query://compliance/hos/violation_explanation | Rule-grounded explanation of one HOS violation. |
query://dvir/list_v2 | Unified list of Driver Vehicle Inspection Reports. |
query://dvir/details | Details for one inspection, including available resolution information and media. |
query://dvir/defects/list | Individual DVIR defects and resolution state. |
Example questions:
- "Which drivers have at least four hours of drive time remaining?"
- "Show HOS violations for the night-shift tag last week."
- "List unresolved DVIR defects from yesterday."
Routes and dispatch
| Query ID | What it provides |
|---|---|
query://dispatch/nearby_assets_current | Assets currently near a location, with distance and estimated travel time. |
query://dispatch/nearby_assets_historical | Assets near a location during a bounded past time window. |
query://dispatch/travel_time | Road distance and estimated travel time between two points. |
query://routes/list | Route definitions and schedules. |
query://routes/jobs | Dispatched route instances and their jobs or stops. |
query://routes/details | Full details for one route, including stops, driver, and vehicle where available. |
Example questions:
- "Which available vehicles are closest to the Dallas warehouse?"
- "How long will it take Unit 118 to reach the customer site?"
- "Show today's dispatched routes and stops."
Fuel and efficiency
| Query ID | What it provides |
|---|---|
query://sustainability/fuel_efficiency/by_vehicle | Vehicle fuel efficiency, consumption, distance, and idle percentage. |
query://sustainability/fuel_purchases/purchases | Fuel-card purchase transactions. |
Example questions:
- "Which vehicles had the lowest fuel efficiency last month?"
- "Show fuel purchases over $300 this week."
Trailers, dwell, and detention
| Query ID | What it provides |
|---|---|
query://assets/dwell_summary | Site-level trailer and asset dwell summaries. |
query://assets/detention | Trailer detention records and available billing context. |
query://assets/cargo_trailers_near_geofence | Trailers with a selected cargo status inside or near a place. |
query://trailers/risk/brake_faults | Trailer ABS, ATIS, and EBS fault status. |
Example questions:
- "Which trailers have been sitting at customer yards for more than 48 hours?"
- "Where are our available empty trailers near the Baton Rouge yard?"
- "Which trailers have active brake-system faults?"
Usage notes
- Read-only. The GA catalog cannot change Samsara data or settings. If another connector creates a work order or ticket, that action is governed by the other system.
- Permissions. Results follow the signed-in user's current Samsara organization, dashboard role, and tag scope.
- Data availability. Results depend on the products, devices, permissions, and data configured for the organization. Some queries return no rows when the corresponding product or data source is not in use.
- Bound the request. Include specific IDs, tags, and time ranges. Historical and fleet-wide queries may enforce result or time-window limits.
- Refresh after updates. Reconnect or refresh your MCP client to pick up changes to the tool surface and catalog.
- Feedback. When a request fails, share the smallest relevant, sanitized conversation transcript with your Samsara contact. Never share passwords, tokens, cookies, authorization headers, or SSO data.
For the complete machine-readable catalog, call read_reference_card() from your connected client.
Updated 1 day ago