Skip to main content
Glama

mcp

by com.crisphive

listJobRequestChanges

Read-onlyIdempotent

Poll for new & changed job requests (sync feed)

Keep an external system (your CRM, ERP or field-service 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax changes per poll (default 15, max 1000). If the page fills, has_more=true.
sinceNoRFC3339 cursor from the prior response's next_since. OMIT on the first poll to prime the cursor at server-now.
priorityNoPriority filter (p0|p1|p2|p3)
customer_idNoOnly changes to this customer's jobs (UUID)
status_keysNoComma-separated status slugs — only surface changes to jobs in these statuses
scheduled_toNoFilter to (YYYY-MM-DD = end of that day in the business timezone, or RFC3339), exclusive
technician_idNoOnly changes to jobs assigned to this technician (UUID)
scheduled_fromNoFilter from (YYYY-MM-DD = start of that day in the business timezone, or RFC3339); range is [from, to)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataNo
errorsNoField-level validation details; present only for VALIDATION_ERROR responses.
messageNoHuman-readable message ("Success" or an error description), localized via the X-Locale header.
error_codeNo0 on success; a stable string error code on failure (e.g. CUSTOMER_NOT_FOUND).

TDQS

A4.9/5.0
Behavior5/5

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

The annotations already mark it read-only and idempotent, and the description adds substantial behavioral context beyond that: a ~5s re-scan safety window, duplicate job reappearance, oldest-change-first ordering, cursor priming on first poll, and `has_more` semantics. This is exactly the kind of runtime behavior an agent needs to know.

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?

Despite being detailed, the description is well-organized: a clear one-line purpose, a numbered usage sequence, and a short contrast with pagination. Every sentence serves a purpose, and critical guidance (omit `since`, don't blindly append) is front-loaded.

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 complex sync-feed tool with 8 optional parameters and an output schema, the description provides everything an agent needs: initial priming, cursor handling, duplicate risk, ordering, polling cadence, and differentiation from the bulk-load endpoint. The existence of an output schema means returning values do not need to be described in detail.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful value by explaining the cursor lifecycle (`since`/`next_since`), `limit` behavior with `has_more`, and the overall filtering intent. It doesn't need to restate each parameter because the schema already covers them.

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 and resource ('Poll for new & changed job requests') and clearly frames it as a time-keyed change feed. It explicitly contrasts itself with the paginated list tool and explains what it returns, making sibling differentiation obvious.

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 step-by-step usage protocol: omit `since` first, store `next_since`, pass it back, use `has_more` to decide when to poll again. It also names the alternative ('Use the paginated GET /job-requests for the initial bulk load') and tells when this endpoint is appropriate for staying live.

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

All mcp toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.7/5.0
Disambiguation4/5

Most tools target a distinct resource and action, and the heavy use of noun-qualified names (listJobRequestBookingWindows vs listMatchingSlots vs listNearbyTechnicians) keeps close concepts separable. A few availability/skill-listing endpoints could be misselected on first pass, but their descriptions are specific enough to recover.

Naming Consistency4/5

The dominant pattern is clear camelCase verb_noun: createCustomer, getTechnician, listSkills, replaceTechnicianBuddies, previewJobRequestMove. Slight irregularities exist (quoteJobRequest and confirmJobRequest are action-style rather than resource-CRUD, and listJobRequestChanges vs listJobRequests mixes singular/plural), but the overall convention is predictable.

Tool Count2/5

43 tools is well above the 25+ threshold for 'too many', even for a broad field-service domain. The emergency flow alone has three dedicated endpoints and the many replaceTechnician* tools could plausibly be consolidated without hurting clarity.

Completeness2/5

Customer, technician, and job-request reading/creation are well covered, plus a rich scheduling/move/emergency surface. However, the job lifecycle is incomplete: there is no update, cancel, delete, assign, or complete endpoint, and reference entities like vehicles, job types, service areas, and skills lack write operations.

Resources