mcp

listJobRequestChanges

Read-onlyIdempotent

Poll for new & changed job requests (sync feed)

Keep an external system (your CRM, ERP or field-operations tool) in sync with bookings WITHOUT re-listing everything: returns the job requests (work orders) whose state changed (created, status transition, reschedule, soft-delete/archive) at or after the since cursor, ordered oldest-change-first (updated_at ASC).

How to use it: (1) On your first poll OMIT since — the server primes the cursor at "now", returns no items and a next_since. (2) Store next_since and pass it as since on the next poll. (3) Apply each returned item to your store by UPSERTING on id (the server re-scans a ~5s safety window, so the same job may appear again — never blindly append). (4) If has_more is true the page filled to limit and more changes are already waiting — poll again immediately; otherwise wait your normal interval (e.g. 5–15s).

This is NOT pagination — it is a time-keyed change feed. Use the paginated GET /job-requests for the initial bulk load, then this endpoint to stay live. Filters (status_keys, customer_id, …) narrow the feed to the slice you care about.

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": "listJobRequestChanges"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Max changes per poll (default 15, max 1000). If the page fills, has_more=true.
`since`	No	RFC3339 cursor from the prior response's next_since. OMIT on the first poll to prime the cursor at server-now.
`priority`	No	Priority filter (p0\|p1\|p2\|p3)
`customer_id`	No	Only changes to this customer's jobs (UUID)
`status_keys`	No	Comma-separated status slugs — only surface changes to jobs in these statuses
`scheduled_to`	No	Filter to (YYYY-MM-DD = end of that day in the business timezone, or RFC3339), exclusive
`technician_id`	No	Only changes to jobs assigned to this technician (UUID)
`scheduled_from`	No	Filter from (YYYY-MM-DD = start of that day in the business timezone, or RFC3339); range is [from, to)

Output Schema

Name	Required	Description
`data`	No
`errors`	No	Field-level validation details; present only for VALIDATION_ERROR responses.
`message`	No	Human-readable message ("Success" or an error description), localized via the X-Locale header.
`error_code`	No	0 on success; a stable string error code on failure (e.g. CUSTOMER_NOT_FOUND).

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 29, 2026

addedOutput schema / $defs / JobRequest / properties / priority_surcharge

Added value: +{
+  "allOf": [
+    {
+      "$ref": "#/$defs/JobRequestPrioritySurcharge"
+    }
+  ],
+  "description": "The priority-surcharge RULE that applied when the job was BOOKED, frozen at that moment: a later priority change, SLA escalation, job-type reclassification or settings edit never changes it. Display only — Crisphive has no base price and never computes or stores a total. Omitted when no surcharge applied."
+}

addedOutput schema / $defs / JobRequestPrioritySurcharge

Added value: +{
+  "properties": {
+    "amount_minor": {
+      "description": "Amount in the currency's minor unit for kind=fixed (500 = 5.00). Absent for percent.",
+      "example": 500,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "currency": {
+      "description": "ISO-4217 code of amount_minor. Present for fixed only.",
+      "example": "CAD",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "kind": {
+      "description": "\"percent\" or \"fixed\".",
+      "enum": [
+        "percent",
+        "fixed",
+        null
+      ],
+      "example": "percent",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "percent_bp": {
+      "description": "Basis points for kind=percent (1000 = +10%). Absent for fixed.",
+      "example": 1000,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "priority": {
+      "description": "The priority the job was booked at, which the rule belongs to. A later priority change does NOT move this.",
+      "enum": [
+        "p0",
+        "p1",
+        "p2",
+        "p3",
+        null
+      ],
+      "example": "p0",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "snapshot_at": {
+      "description": "When the rule was captured (the booking instant, UTC).",
+      "format": "date-time",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}

First observedOct 18, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare it read-only/idempotent/non-destructive, which is a weaker guarantee than the agent needs for a tailing feed. The description adds the non-obvious traits: first poll returns zero items and primes the cursor, a ~5s server re-scan window means duplicate deliveries are possible so callers must upsert rather than append, and ordering is updated_at ASC. Those are the exact behaviors that determine whether an integration corrupts state.

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 a one-line summary, then a step-numbered usage protocol and a final disambiguation sentence — easy to scan and act on. It is slightly long, and parenthetical asides like '(your CRM, ERP or field-operations tool)' and the '(e.g. 5–15s)' interval are mild padding rather than load-bearing content.

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?

Eight parameters, no required fields, an output schema present, and rich annotations — the description covers the remaining gap, namely the stateful cursor lifecycle and duplicate-delivery handling that no structured field expresses. An agent has everything needed to run a correct sync loop on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the per-parameter mechanics are already documented and the baseline is 3. The description still adds meaning beyond the schema by explaining the end-to-end relationship between `since`, `next_since`, `limit` and `has_more` (page filled = more waiting; poll immediately), plus the role of filters in narrowing the feed to a slice.

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+resource ('Poll for new & changed job requests') and immediately scopes it as a 'sync feed' returning items whose state changed at/after a cursor, ordered oldest-change-first. It explicitly separates itself from `listJobRequests` ('This is NOT pagination... Use the paginated GET /job-requests for the initial bulk load'), so the agent can route correctly 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?

Provides a concrete numbered protocol: omit `since` on the first poll, store `next_since`, upsert by `id`, and poll again immediately when `has_more` is true versus sleeping otherwise. It also names the alternative endpoint and the exact condition under which it should be used instead, leaving nothing to inference.

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

All mcp 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.