How do I use BackCrew ServiceM8 MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BackCrew ServiceM8 MCP Server Find client Acme Corp and show open jobs" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

BackCrew ServiceM8 MCP Server

by jayson-svg

Overview Schema Source Related Servers Discussions Admin

TypeScript

BackCrew ServiceM8 MCP Server

Think of this like a brand-new employee on their first day, not a business partner. A new hire only does the exact tasks you've shown them, nothing more, until you decide they're ready for more responsibility.

It lets you connect an AI assistant like Claude or ChatGPT to your ServiceM8 account, so you can ask for things in plain English (think "find this client," "what's on the schedule today," or "add a note to this job") instead of clicking through the ServiceM8 app yourself. On day one, it only knows how to look things up. You decide if and when to train it up to doing more.

Built by BackCrew, part of a series of free tools like this for the software pest control companies use every day.

Not a developer? That's fine. Everything up through "Testing it safely" is written for you, no coding background needed.
Already know ServiceM8 has its own official AI connector? Jump to Why use an independent MCP server instead of ServiceM8's official one?

Related MCP server: RepairDesk MCP Server

What this actually does

Let's be upfront about what this is, because it's easy to oversell: this is not an all-knowing office assistant that understands your business and handles things for you. It's a specific, listed set of actions (like "look up a client," "create a job," or "add a note") that an AI assistant is allowed to trigger when you ask for them in plain English. The AI doesn't have judgment about your business; it matches what you ask for to the closest action on its list and does exactly that, nothing more.

That's still genuinely useful. Instead of this:

Open ServiceM8 → search clients → click into the record → find the right job → scroll to find the note you're after...

You can just say:

"Find the client named Dana Ruiz and show me her open jobs."

And the assistant does the clicking for you, using the same actions you'd take yourself, just faster and in plain English.

Why use an independent MCP server instead of ServiceM8's official one?

Fair question, and we looked into this carefully before building. ServiceM8 does ship an official, hosted MCP integration (https://api.servicem8.com/mcp) that connects directly through ChatGPT's or Claude's built-in connector UI via OAuth: no code, no self-hosting. Based on ServiceM8's own support documentation, it currently covers: searching/listing clients, jobs, job filters, staff, queues, allocation windows, forms, categories, badges, tax rates, and job templates; viewing job details, diary entries, and notes; creating jobs from templates; adding notes; checking staff availability; scheduling jobs; sending jobs to queues; changing job status; and sending job-linked email/SMS.

That's a genuinely good, zero-setup option if it covers what you need. And if your ServiceM8 account already gives you (or your workspace admin) permission to add a custom connector, there's no reason not to use it alongside this one. Worth noting up front: ServiceM8's official connector is itself an MCP server, so it already sidesteps one of the usual reasons to go independent: you're not locked into a proprietary in-app chat, you can point it at Claude or ChatGPT either way.

Where this project differs:

Broader coverage. ServiceM8's official list doesn't appear to include client/company record management (creating or editing a client), job payments, materials/line items, suppliers, company contacts, attachments, or a general cross-object search. This project covers all of those, because they're part of ServiceM8's public REST API even though the official MCP doesn't expose them yet.
No workspace-admin approval needed. ServiceM8's official connector requires "permission to add a custom app or connector," which in Claude Team/Enterprise accounts means an Owner has to add it for the org first. This project just needs an API key you generate yourself from your own account settings, so a solo operator can use it without asking anyone.
Cross-platform, not walled off. ServiceM8's official connector only talks to ServiceM8. This project can run alongside another BackCrew server covering a different part of your business, attached to the same AI assistant, so it can work across your whole stack in one conversation.
Self-hosted and readable. This runs on your own machine, not ServiceM8's infrastructure. You (or anyone) can read exactly what each tool does in src/tools/: nothing is a black box.
The same tiered-safety model as the rest of this series. Read-only by default, with an explicit readonly-owner / office-ops / admin profile system you control: see How this keeps you safe by default. ServiceM8's official connector is governed by its own OAuth scopes and workspace admin settings instead.
Consistent with our other builds. If you're also using other BackCrew servers, this one follows the identical pattern: same mental model, same setup steps, same safety controls.

In short: use ServiceM8's official connector for zero-setup job search/scheduling/communication. Use this one if you want broader coverage, don't have connector-approval permissions, or want it working alongside your other business systems in one conversation.

Also from BackCrew

This is one of several MCP connectors BackCrew builds, same idea, different software. We've also got QuickBooks for the accounting side, plus CRM connectors like HubSpot and GoHighLevel for lead and marketing data. Full list and what's live right now: see ROADMAP.md.

Beyond this repo: once a business gets comfortable with an AI assistant reading its data, there's often more it wants to do with it, like catching missed calls faster, processing invoices and paperwork automatically, following up on quotes without someone having to remember, reactivating customers who've gone quiet, or pulling reports without digging through the software. That's a separate, scoped conversation, not part of this free, open-source repo. Same contact as in Built by BackCrew below if it's something you want to explore.

Some words you'll see, explained

API: short for "Application Programming Interface." A locked door into ServiceM8's data that only software (not a person clicking a mouse) can open. This project is a key that opens that door, so an AI can read and update your data directly instead of needing a screen to click through.
MCP: short for "Model Context Protocol." The standard way an AI assistant like Claude or ChatGPT is told "here's exactly what you're allowed to do, and how to do it." This project speaks that standard, which is why it plugs into Claude, ChatGPT, and similar tools with no custom setup.
Server: a small program that sits between your AI assistant and ServiceM8, translating requests back and forth. You start it once and leave it running; you never interact with it directly.
Repo (short for "repository"): the folder of code for this whole project. "Clone the repo" just means "download a copy of this project."
API key: a long, private password-like code that proves a request is really coming from you. You generate it from your own ServiceM8 account (steps below) and never share it.
Terminal: a plain-text window where you type commands instead of clicking buttons. Setup involves a few terminal commands, listed step-by-step below.
Tool: one specific action the AI is allowed to take, like "look up a client" or "create a job." Each one is listed and named individually; there's no hidden catch-all action.

How this keeps you safe by default

The new-hire idea from the top is the real architecture, not just a nice way of putting it:

Out of the box, this server can only look things up. It ships in read-only mode: nothing it does can create, change, or delete anything in your ServiceM8 account, because those actions aren't even switched on.
When you're ready for more, you choose a responsibility level, not an all-or-nothing switch. Turning on write access (SM8_MCP_MODE=read_write, see setup) still requires picking a profile that caps what's allowed:
- readonly-owner: same as the default. Look-ups only.
- office-ops: everyday work, add/update a client, create and update jobs, schedule activities, add notes and tasks, attach files. No deletes, no staff-record changes, no recording payments. Those stay off even in this mode.
- admin: everything, including deletes, staff records (which include login email and location data), and recording job payments.
A typo can't accidentally hand out more trust than you intended. If the profile setting is ever misspelled or invalid, the server falls back to the safest option (read-only) rather than the most permissive one.

What it can look up (always safe)

These actions only read data; nothing here can change a record or cost you anything to run. This is what's available in the default setup, with no extra steps:

What it covers	Examples of what it can look up
Clients	Search and view client profiles and their contacts
Jobs	View job details, scheduled activities, contacts, line items, payment history
Staff	View technicians and office staff
Catalog	View materials, job categories, dispatch queues, suppliers, tax rates
Notes & tasks	View notes and to-do tasks
Attachments	View files (photos, quotes, invoices) linked to jobs and clients
Inbox	View incoming lead/message inbox
Job templates	View pre-built job templates
Search	Free-text search across everything

36 look-up actions in total.

⚠️ What it can change (off by default)

Everything below this line can create, edit, or delete something real in your ServiceM8 account. None of it is available until you deliberately turn it on (see How this keeps you safe by default). This section exists so you know exactly what you'd be turning on, not because it's active right now.

office-ops level (everyday actions):

What it covers	Examples of what it can do
Clients	Add or update a client and their contacts
Jobs	Create/update a job, schedule activities, add job contacts and line items
Catalog	Add or update materials, categories, queues, suppliers, tax rates
Notes & tasks	Add notes, create/update tasks
Attachments	Attach a file to a job or client
Inbox	Convert a message to a job, attach it to a job, mark read/archived/snoozed, add a note
Job templates	Create a job from a template

admin level only (hard to reverse, financially sensitive, or HR-facing, kept separate from everyday office work on purpose):

Deleting any record (clients, jobs, materials, tasks, etc.)
Creating or updating staff records (kept separate from front-desk work since they include login email and GPS location fields)
Creating or updating job payments (financially consequential)

How to set it up

No context-switching here: do these three steps in order, and you won't need to jump back and forth.

You'll need a computer with Node.js installed (free software this project runs on) before you start.

Step 1: Make a folder for this on your computer

Open Finder (Mac) or File Explorer (Windows), go to your Desktop or Documents, and create a new folder. Give it a name you'll recognize later, like backcrew-mcp-servicem8.

That's it for now. Just know where this folder is. Everything else gets put inside it.

Step 2: Get your ServiceM8 API key

Unlike ServiceM8's official connector, this doesn't need a Developer Center account or app registration: just a key from your own account. Do this now, before touching the terminal:

Log into your ServiceM8 account
Go to Settings → API Keys
Click to generate a key, then copy it into a temporary note somewhere; you'll paste it in during Step 3

Reference: developer.servicem8.com/docs/authentication.

Step 3: Install it

With your folder made and your API key in hand, this is one continuous run: don't skip ahead or double back.

Open a terminal. On a Mac, press Cmd+Space, type "Terminal," and hit enter. On Windows, click the Start menu, type "PowerShell," and hit enter. Use PowerShell rather than Command Prompt: a couple of the commands below, like pwd, only work in PowerShell.
Type cd (with a space after it), then drag your Step 1 folder from Finder/File Explorer straight into the terminal window; it'll paste the folder's path in automatically. Press enter.
Paste this exact command and press enter, which downloads the project directly into the folder you made (the trailing . matters, it means "put it here, not in a new folder"):
```
git clone https://github.com/jayson-svg/backcrew-mcp-servicem8.git .
```
Paste this and press enter, which installs the project's dependencies:
```
npm install
```
Paste this and press enter, which builds the project:
```
npm run build
```
Paste this and press enter, which prints the full folder path. Don't close this terminal window yet; you'll need this exact text in the next section.
```
pwd
```
Paste this and press enter, which creates your settings file from a template:
```
cp .env.example .env
```
Open that new .env file in a text editor. On a Mac, paste open -e .env into the terminal and press enter. On Windows, paste notepad .env and press enter.
Find the line that says SERVICEM8_API_KEY=. Paste in the key you copied in Step 2, right after the =, with no extra spaces or quotes.
Leave SM8_MCP_MODE=read_only and SM8_MCP_PROFILE=readonly-owner exactly as they are for now. That's the safe default. Save the file and close the editor.

Connecting it to Claude

This step comes last on purpose: it needs the exact folder location from Step 3, and now you have it.

Claude Desktop / Claude Code

Open Claude's settings file (for Claude Desktop, this is claude_desktop_config.json) and add:

{
  "mcpServers": {
    "servicem8": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/dist/index.js"],
      "env": {
        "SERVICEM8_API_KEY": "your_key_here",
        "SM8_MCP_MODE": "read_only",
        "SM8_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Replace PASTE_YOUR_PWD_OUTPUT_HERE with the exact text the pwd command printed back in Step 3 (keep the /dist/index.js part after it). If you're on Windows, swap any backslashes in that path for forward slashes (for example C:/Users/yourname/Desktop/... instead of C:\Users\yourname\Desktop\...), since the config file needs regular slashes.

Restart Claude. You should see ServiceM8 show up as something Claude can use, with only the look-up actions available, by default.

This also works with other MCP-compatible AI tools (ChatGPT, Cursor, Windsurf, and others); the setup step is basically the same.

Things you can try asking

With the default (read-only) setup:

"Find the client named Dana Ruiz"
"What jobs are scheduled for today?"
"Show me the notes on this job"
"What's in the inbox that hasn't been triaged yet?"

If you later turn on office-ops:

"Create a new client for this address and add a job for a termite inspection"
"Add a note to this job saying the gate code changed"
"Convert that inbox message into a job"
"Schedule this job for tomorrow morning and assign it to Mike"

Testing it safely

If and when you decide to turn on write access, a few habits go a long way:

Start in read-only mode and stay there for a while. Get a feel for how the AI interprets your requests before you ever let it change anything.
When you do turn on office-ops, test on a clearly fake client first. Create a test client named something obvious like "ZZZ Test Client: Do Not Use" and try your first few write actions on that record, not a real one.
Never go straight to admin mode. Deletes, staff records, and payments are hard or impossible to undo. office-ops covers real day-to-day work without exposing any of that.
Never share your API key: in chat, in a screenshot, in a support ticket, anywhere. Treat it like a password, because it functions like one.
If something looks wrong, switch back to SM8_MCP_MODE=read_only immediately. That alone guarantees nothing further can be changed, regardless of what profile is set.

For developers

Everything below this point assumes a coding background.

Tool reference

Run the server and call tools/list from any MCP client to see exact input/output schemas: every tool's description includes both the ServiceM8 API operation it maps to and its access tier (e.g. Maps to POST /job.json. [tier: office-ops]). Each domain lives in its own file under src/tools/.

Why this repo uses a CRUD factory instead of hand-written tools per resource

Most other repos in this series hand-write each tool individually, because those APIs genuinely have bespoke, non-uniform endpoints per resource. ServiceM8's REST API is different: nearly every resource (Client, Job, Staff, Material, Task, and so on) exposes the exact same list / get / create / update / delete shape, just with different field names. Hand-writing that ~15 times over would be pure repetition, so this repo has one small factory, registerCrudResource() in src/crud.ts, that generates the five tools for a resource from one config object (resource path, field list, access tiers). Each generated tool is still a fully separate, individually named, individually gated MCP tool: the factory only removes boilerplate, it doesn't merge or hide any capability. Resources with a non-uniform shape (Inbox messages, Search, Job Templates, Notes, Attachments) are still hand-written in their own files, same as the other repos.

The tier/profile system

Every tool declares a tier: "readonly-owner" | "office-ops" | "admin". At startup, src/toolkit.ts reads SM8_MCP_MODE and SM8_MCP_PROFILE once, computes the maximum exposed tier, and any tool above that tier is never registered with the MCP server: it's genuinely absent from tools/list, not just hidden. SM8_MCP_MODE=read_only always wins over SM8_MCP_PROFILE; only read_write lets the profile setting take effect. An unrecognized profile value falls back to readonly-owner. Same pattern as the rest of this series: see ROADMAP.md.

Project layout

src/
  index.ts          Server entrypoint, registers every tool group and starts stdio transport
  client.ts          Minimal fetch-based ServiceM8 API client (auth header, cursor pagination, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  crud.ts             Factory that generates list/get/create/update/delete tools for uniform-CRUD resources
  tools/
    clients.ts         (Client/Company + Company Contacts)
    jobs.ts             (Jobs, Job Activities, Job Contacts, Job Materials, Job Payments)
    staff.ts
    catalog.ts          (Materials, Job Categories, Job Queues, Suppliers, Tax Rates)
    notesAndTasks.ts
    attachments.ts
    inbox.ts
    templates.ts        (Job Templates)
    search.ts

Notes on the ServiceM8 API

Base URL: https://api.servicem8.com/api_1.0/{resource}.json
Auth header: X-Api-Key: <api_key>
Filtering: OData-style $filter query param (eq, ne, gt, lt; up to 10 conditions joined with and); lt/gt are supported but le/ge are not
Pagination: cursor-based. Start with cursor=-1, use the x-next-cursor response header for the next page (up to 1000 records/page); its absence means you've reached the end
Full reference: developer.servicem8.com

This server was built by reading ServiceM8's public API documentation directly, including the full OpenAPI schema their docs site serves (confirmed via the API reference pages themselves), not by guessing or reverse-engineering another project. If you spot a field that's drifted from what ServiceM8 actually returns, please open an issue or PR.

This repo intentionally stops at honest API access. It does not include business-logic features (like a prioritized collections queue, technician capacity analysis, or automated escalation rules). Those live in BackCrew's managed offering, built on top of this open layer, not in this public repo. See ROADMAP.md.

Scope

ServiceM8's API covers roughly 40 resources; this repo covers the ~24 most central to day-to-day field service operations (88 tools). Not yet covered: Allocation Windows, Asset Types/Asset Type Fields/Assets, Availabilities, Badges, Bundles/Job Material Bundles, Document Templates, Email Templates, Feedback, Forms/Form Fields/Form Responses, Job Allocations, Job Checklists, Knowledge Articles, Locations, Security Roles, SMS Templates, Staff Messages, and the read-only Email/SMS/Vendor endpoints. Contributions welcome.

What's next

See ROADMAP.md for the rest of the planned series and the pattern this repo follows.

Built by BackCrew

This project is free and open for anyone to use, copy, or build on; that's the whole point.

It's also a sample of the kind of work BackCrew does: we build tools, automations, and AI setups like this one for pest control and field service businesses, including the business-logic layer (collections, capacity planning, escalation rules) that intentionally isn't part of this open repo. If you like what this does but don't want to set it up and maintain it yourself, or you want something built specifically for how your business runs, that's exactly the kind of project we take on.

Want this set up for you? Reach out: jayson@backcrew.co

No pressure either way: everything above works on its own, for free.

License

MIT

Available Tools

28 tools

get_clientC

Get a single customer/client record. Required on create: name by UUID. Maps to GET /company/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

C2.9/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It indicates a read-only operation via mapping to GET and a 'readonly-owner' tier hint, but doesn't detail behavior on missing UUID or any side effects. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with some redundancy. The second sentence 'Required on create: name by UUID' is unclear and could be removed. The mapping and tier info are useful. Could be more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get tool with one parameter, the description is mostly adequate but lacks information on return structure or error handling. Without an output schema, this gap is notable.

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

Parameters2/5

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

The schema has 0% description coverage. The description only mentions 'by UUID' for the parameter, adding little meaning beyond the schema field name. It doesn't explain the format or constraints of UUID.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get a single customer/client record' with a specific verb and resource. It maps to a specific endpoint. However, the phrase 'Required on create: name by UUID' is confusing and slightly detracts from clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus siblings like list_clients or get_client_contact. The description lacks context for appropriate usage scenarios.

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

get_client_contactA

Get a single contact person for a client company by UUID. Maps to GET /companycontact/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

Without annotations, description only provides HTTP method (GET) and tier (readonly-owner), implying non-destructive read. Lacks details on auth needs, error handling, or rate limits. Partially transparent.

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?

Two sentences, front-loaded with purpose and endpoint mapping. No redundant information; concise and structured well.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity (1 param, no output schema), description is mostly adequate but lacks behavioral details (e.g., what is returned) that would aid agent decision-making.

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

Parameters2/5

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

Schema coverage is 0%, and description does not elaborate on the 'uuid' parameter beyond stating 'by UUID'. No format or source guidance provided, adding minimal value over schema.

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?

Description clearly states 'Get a single contact person for a client company by UUID', which is a specific verb and resource. It distinguishes from list_client_contacts by indicating it retrieves a single entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance. Implies use when you have a UUID, but does not mention alternatives like list_client_contacts for bulk retrieval.

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

get_inbox_messageC

Get a single inbox message. Maps to GET /inboxmessage/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It only states the endpoint and tier, omitting behavioral traits such as error handling, permissions, or return format.

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?

The description is exceptionally concise with two short sentences plus a tag. Every sentence adds value, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description does not cover essential context like response structure, error behavior, or when to use this over list_inbox_messages. It feels incomplete for a new agent.

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

Parameters1/5

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

Schema coverage is 0% for the single parameter 'uuid', and the description adds no information about its meaning or format. The parameter is left completely unexplained.

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?

The description clearly states 'Get a single inbox message,' which is a specific verb and resource. It also provides the exact API endpoint, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions a tier ('readonly-owner') but does not guide when to use this tool versus alternatives like list_inbox_messages. No explicit context for comparison or exclusions is given.

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

get_jobA

Get a single job (work order). Required on create: status by UUID. Maps to GET /job/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

No annotations, but description adds HTTP mapping and tier hint '[tier: readonly-owner]' suggesting read-only behavior. Lacks details on error cases or authorization bounds.

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?

Three short sentences, but the second sentence 'Required on create: status by UUID' is ambiguous and dilutes clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers basic purpose and HTTP route, but with no output schema, annotations, or parameter descriptions, leaves gaps for a complete understanding.

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

Parameters2/5

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

Schema has one parameter 'uuid' with no description. Description does not clarify what uuid represents (e.g., job UUID) beyond the tool name.

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?

Clearly states 'Get a single job (work order)' with verb and resource. Distinguishes from list_jobs by specifying single vs list. Also includes HTTP mapping.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for retrieving a single job after creation via the 'Required on create' note, but no explicit when-to-use or alternatives provided.

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

get_job_activityC

Get a single scheduled booking or recorded time entry on a job by UUID. Maps to GET /jobactivity/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description should fully disclose behavioral traits. It only mentions an endpoint and tier, which implies a read operation, but lacks details on permissions, rate limits, or any side effects. This is insufficient for full transparency.

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?

The description is concise and front-loaded with the primary purpose. It provides essential metadata (endpoint, tier) without extra words. However, it could be slightly improved by incorporating parameter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and parameter descriptions, the description is incomplete. It provides the basic purpose but leaves out critical context about input format, output, and permissions needed for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not explain the 'uuid' parameter beyond 'by UUID'. It does not specify the format or source of the UUID, leaving the agent to infer meaning.

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?

The description clearly states the tool's action (Get), resource (scheduled booking or recorded time entry), and identifier (UUID). It maps to a specific endpoint and mentions a tier, making the purpose precise and distinguishable from sibling tools like get_job or list_job_activities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not specify when to use this tool versus alternatives, nor does it give any prerequisites or exclusions.

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

get_job_contactA

Get a single contact person attached to a specific job by UUID. Maps to GET /jobcontact/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A4/5.0

Behavior4/5

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

No annotations provided, so description carries burden. Includes '[tier: readonly-owner]' hinting at access control. No contradictions.

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?

Two concise sentences with endpoint and tier tag. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple single-param retrieval; description covers purpose and endpoint. Lacks output format details but acceptable without output schema.

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 coverage 0% but single parameter 'uuid'. Description says 'by UUID' but adds no format/validation info. Adds marginal value over schema.

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?

Clearly states it retrieves a single contact person by UUID. Differentiates from sibling 'list_job_contacts' (plural). Maps to API endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies need for a UUID but no explicit when-to-use vs alternatives like 'list_job_contacts' or 'get_client_contact'. No usage exclusions.

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

get_job_materialA

Get a single line item (material/labour/service) on a job's quote or invoice. Required on create: quantity by UUID. Maps to GET /jobmaterial/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

No annotations provided; description adds 'tier: readonly-owner' indicating read-only access, but lacks details on side effects, authentication, or response behavior. Incomplete disclosure for an unannotated tool.

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?

Three concise sentences; first is clear, second is cryptic, third is technical. No unnecessary words, but could be restructured for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers basic purpose and endpoint mapping for a simple single-param tool, but omits output details and typical use context. Adequate but not comprehensive.

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 coverage is 0%; description adds 'Required on create: quantity by UUID' which suggests uuid identifies a line item, but does not clarify format or purpose beyond the schema's type 'string'.

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?

Clearly states 'Get a single line item (material/labour/service) on a job's quote or invoice.' This provides a specific verb and resource, distinguishing it from list_job_materials and other retrieval tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies use when you have a specific UUID, but does not explicitly compare to alternatives like list_job_materials. The phrase 'Required on create: quantity by UUID' is ambiguous and does not clearly state when to use this tool.

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

get_job_paymentA

Get a single payment recorded against a job. Financially sensitive — kept at admin tier rather than everyday office-ops by UUID. Maps to GET /jobpayment/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

No annotations were provided, but the description discloses the tool is read-only (maps to GET endpoint) and financially sensitive, implying authorization requirements. This adds valuable behavioral context beyond the basic action.

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?

The description is three concise sentences: the purpose, the access sensitivity, and the endpoint mapping. Every sentence adds unique value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple 1-parameter tool with no output schema, the description adequately covers purpose, usage restrictions, and endpoint. It could be improved by briefly noting the return format (e.g., a payment object) but is otherwise complete.

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?

The input schema has one required parameter 'uuid' with no description (0% coverage). The tool description does not elaborate on the parameter beyond its name, which is self-explanatory but minimal. The description adds no extra meaning over the schema, earning a baseline score of 3.

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?

The description clearly states 'Get a single payment recorded against a job.' It specifies the verb (Get), resource (single payment), and context (recorded against a job). The sibling tool 'list_job_payments' suggests listing, so this distinguishes as a single-item retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'Financially sensitive — kept at admin tier rather than everyday office-ops by UUID,' indicating that access is restricted and that the tool is for specific lookups by UUID. This provides context on when to use (admin scenarios) but does not explicitly name alternatives like 'list_job_payments' for listing.

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

get_materialC

Get a single catalog material, product, or labour rate. Required on create: name by UUID. Maps to GET /material/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

C2.7/5.0

Behavior3/5

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

Without annotations, the description carries full burden. It notes the tool maps to a GET endpoint and is 'readonly-owner', implying no side effects. However, it does not describe error handling, return format, or behavior on missing UUID. The mention of creation requirements is irrelevant and potentially misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively short but contains extraneous information about creation that does not belong. The sentence about mapping to the API is useful. Could be more streamlined by removing the creation reference.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get tool with no output schema, the description fails to cover important details like return value structure, potential errors, or any special behavior. It leaves significant context gaps for an AI agent to correctly understand the tool's full behavior.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must explain parameters. It fails to do so: the only parameter 'uuid' is not described, and the phrase 'Required on create: name by UUID' does not clarify its role. No meaning is added beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get a single catalog material, product, or labour rate.' It distinguishes from siblings like 'list_materials' by emphasizing 'single'. However, the inclusion of 'Required on create: name by UUID' adds confusion about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. While it implies fetching a single item, there is no direct comparison to siblings like 'list_materials' or 'get_job_material'. No usage exclusions are provided.

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

get_staff_memberA

Get a single employee/technician record — includes login email and location tracking fields, so kept at admin tier rather than everyday office-ops. Required on create: first, last by UUID. Maps to GET /staff/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description adds value by disclosing the limited admin access, the GET method, and the included sensitive fields (login email, location tracking). It does not cover rate limits or side effects, but it provides sufficient behavioral context for a read operation.

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?

The description is concise (three sentences), front-loaded with the primary purpose, and every sentence provides distinct information (sensitive fields, admin tier, endpoint mapping). No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is nearly complete. It could mention what fields are returned, but without an output schema, the given detail is adequate.

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?

The single parameter 'uuid' is described as 'by UUID' and linked to the endpoint path (GET /staff/{uuid}.json), adding meaning beyond the schema's simple string type. The confusing phrase 'Required on create: first, last by UUID' slightly detracts but does not undermine the parameter's semantic clarity.

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?

The description clearly states the tool retrieves a single employee/technician record, includes the specific sensitive fields (login email, location tracking), and provides the HTTP endpoint mapping. This distinguishes it from sibling tools like get_client.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that this is an admin-tier tool, not for everyday office-ops, implying when to use it. It also references required fields for create, but it lacks explicit when-not-to-use or alternative tools.

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

get_supplierA

Get a single vendor/supplier record by UUID. Maps to GET /supplier/{uuid}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses the [tier: readonly-owner] and maps to GET, indicating a read-only operation. However, it omits details like error handling or response status for missing UUIDs.

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?

The description is minimal: two sentences covering action, resource, identifier, and endpoint. No wasted words; every sentence serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one parameter and no output schema, the description adequately covers the core function and HTTP method. It could mention the return format but is otherwise complete.

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?

The only parameter, uuid, has 0% schema description coverage, but the description explicitly says 'by UUID', confirming its role as the record identifier. This adds minimal value beyond the schema, but the parameter is self-explanatory.

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?

The description clearly states it retrieves a single vendor/supplier record by UUID, matching the tool name and specifying the HTTP endpoint. It distinguishes from listing tools like list_suppliers by implying singular retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given on when to use this tool vs. alternatives (e.g., list_suppliers). The description only states the action, leaving context for choice unaddressed.

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

list_attachmentsA

List attachments (photos, quotes, invoices, documents) linked to jobs, clients, or other records. Maps to GET /attachment.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No
`filter`	No	OData-style filter, e.g. "related_object_uuid eq '...'"

TDQS

A3.6/5.0

Behavior3/5

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

With no annotations provided, the description discloses the readonly nature via the tier tag and the GET method. However, it does not explain pagination behavior (cursor parameter), rate limits, or what happens with empty results. The tier adds some context but is minimal.

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?

The description is concise with two sentences: one functional and one with endpoint/tier. Every sentence adds value and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two optional parameters and no output schema, the description covers the core functionality and endpoint but lacks details on pagination (cursor usage), filter syntax beyond the example, and the structure of the response (what fields are returned). It is adequate but not complete for agents needing full context.

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

Parameters2/5

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

The description adds no information about parameters beyond what is already in the input schema. While the filter parameter has a schema description, the cursor parameter is undocumented. With 50% schema coverage, the description does not compensate for the missing parameter context.

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?

The description clearly states the tool lists attachments (photos, quotes, invoices, documents) linked to jobs, clients, or other records. It includes the HTTP method and endpoint, and distinguishes from sibling list tools by specifying the resource type (attachments) and linking to other records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing attachments related to various records but does not provide explicit guidance on when to use this tool versus alternatives like search or search_by_type. The tier hint is useful but not enough for clear decision-making.

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

list_client_contactsA

List contact person for a client company records, optionally filtered. Maps to GET /companycontact.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

A3.6/5.0

Behavior4/5

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

No annotations provided, but description includes endpoint and tier 'readonly-owner', indicating a read-only operation. This adds behavioral context beyond the schema, though no contradictions exist.

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?

Description is concise with two sentences plus endpoint and tier notation. No wasted words, but lacks structure like bullet points or sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks return value or output schema description. For a list tool, it covers purpose and parameters adequately but omits pagination details (cursor explained in schema) and response format, leaving some gaps.

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 coverage is 100% with detailed parameter descriptions. The description adds no additional meaning beyond 'optionally filtered', so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List contact person for a client company records' with optional filtering. It distinguishes from sibling tool get_client_contact and maps to a specific endpoint, providing a clear purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or alternatives mentioned. Context implies usage via 'optionally filtered' and comparison with get_client_contact for single records, but lacks direct guidance on selecting this tool over others.

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

list_clientsB

List customer/client record. Required on create: name records, optionally filtered. Maps to GET /company.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations provided, the description carries full burden. It notes 'Maps to GET /company.json' and '[tier: readonly-owner]', indicating a read-only operation, but does not disclose other behaviors like pagination limits or error conditions beyond what the schema implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but includes an unclear fragment ('Required on create: name records') that is not helpful. The key verb and resource are front-loaded, but the confusing part reduces overall conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a simple list with two well-documented parameters and no output schema, the description adequately covers the HTTP method, tier, and basic purpose. It is sufficiently complete for its complexity.

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 the description adds no extra meaning beyond what the schema already provides for both parameters 'cursor' and 'filter'. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists customer/client records, which distinguishes it from sibling tools like get_client (singular) and list_client_contacts. However, the phrase 'Required on create: name records' is confusing and detracts slightly from clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The tier hint '[tier: readonly-owner]' implies a read-only context, but there is no mention of prerequisites, exclusions, or comparison with other list tools.

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

list_inbox_messagesC

List inbox messages (incoming leads/inquiries). Maps to GET /inboxmessage.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No
`filter`	No

TDQS

C2.7/5.0

Behavior2/5

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

No annotations provided; description only mentions a 'readonly-owner' tier label but does not disclose pagination behavior, idempotency, or other traits beyond the implication of a read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief, consisting of a single sentence plus endpoint and tier hints, but it sacrifices necessary detail for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given two undocumented parameters, no output schema, and multiple sibling list tools, the description fails to cover pagination, filtering, or output structure, making it incomplete for effective use.

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

Parameters1/5

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

Schema description coverage is 0% and the description adds no information about the 'cursor' or 'filter' parameters, leaving their purpose and format entirely unspecified.

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?

The description clearly states the action (list), resource (inbox messages), and scope (incoming leads/inquiries), distinguishing it from sibling list tools like list_clients and from get_inbox_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives (e.g., search, get_inbox_message). The tier hint is provided but not contextualized.

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

list_job_activitiesB

List scheduled booking or recorded time entry on a job records, optionally filtered. Maps to GET /jobactivity.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

B3.3/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It specifies the HTTP method (GET) and tier (readonly-owner), indicating a safe read operation, but does not describe pagination, rate limits, or any side effects. The information is adequate but minimal.

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?

The description is a single sentence plus endpoint and tier note, with no redundancy or unnecessary words. It is front-loaded with the core action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple list tool with a well-documented schema. However, it lacks guidance on output format (no output schema) and does not differentiate from the sibling get_job_activity. Additional context about when to paginate or use filters would improve completeness.

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?

The input schema provides 100% coverage with detailed descriptions for both parameters (cursor and filter). The description adds no new semantic information beyond 'optionally filtered', which aligns with the schema. Baseline of 3 is appropriate given the schema richness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'scheduled booking or recorded time entry on a job records', which is interpretable as job activities. It also mentions optional filtering and the HTTP endpoint, distinguishing it from the singular get_job_activity sibling. However, phrasing is slightly awkward and could be more precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like get_job_activity or other list tools. There is no mention of prerequisites, limitations, or context where other tools would be better suited.

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

list_job_categoriesA

List job category used to classify and organize jobs. Required on create: name records, optionally filtered. Maps to GET /category.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses that it is a read-only operation (via tier tag and endpoint mapping) and that it is required on create. However, it does not elaborate on pagination behavior beyond the schema, or other behavioral traits.

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?

The description is two sentences plus a tier tag, all front-loaded with key information. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with no output schema, the description covers purpose, endpoint, usage context, and filtering. It could mention typical fields returned or more detail on pagination, but it is sufficiently complete for a simple read operation.

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 the baseline is 3. The description mentions filtering is optional and connects it to create requirements, but adds minimal additional meaning beyond the schema.

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?

The description clearly states the verb 'list' and the resource 'job category'. It distinguishes from sibling list tools by specifying the resource type. It also adds context about being required on create, which clarifies its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions when it is needed (on create) and that it can be optionally filtered. It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to decide.

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

list_job_contactsC

List contact person attached to a specific job records, optionally filtered. Maps to GET /jobcontact.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

C2.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It notes the HTTP method (GET) and tier ('readonly-owner'), implying safety, but does not disclose pagination behavior (1000 records per page) or whether the job is inferred from context.

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?

The description is a single concise sentence plus a note. It is front-loaded with the action but could be better structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Key information is missing: how to specify the job (no job_id parameter) and return structure. Given the lack of output schema and the missing job reference, the description is incomplete for an agent to use correctly.

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 the baseline is 3. The description adds minimal value beyond the schema, only stating 'optionally filtered' and the endpoint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'List contact person attached to a specific job records', but the input schema lacks a job_id parameter, making it unclear how to specify the job. This vagueness undermines clarity and distinguishes poorly from sibling tools like 'get_job_contact'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives such as 'get_job_contact' or 'list_client_contacts'. There is no mention of prerequisites or context.

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

list_job_materialsC

List line item (material/labour/service) on a job's quote or invoice. Required on create: quantity records, optionally filtered. Maps to GET /jobmaterial.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It reveals the tool is read-only via '[tier: readonly-owner]' but does not disclose rate limits, authentication requirements, side effects, or failure modes. The implementation detail 'Maps to GET /jobmaterial.json' adds little behavioral insight. Behavior around pagination (up to 1000 records) is in schema but not in description.

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?

The description is brief at two sentences plus a URL and tag. Every part adds some value: purpose, optionality, endpoint mapping, and access tier. However, 'Required on create' is confusing and could be omitted or clarified. Overall, it is reasonably concise and front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema and no annotations, the description should explain what is returned (e.g., list of job materials with fields) and how to handle pagination beyond the cursor parameter. It only mentions 'quantity records' in an unclear context. The description is incomplete for an agent to understand the full scope of the tool's output and usage patterns.

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%, with clear definitions for cursor and filter. The description adds the phrase 'optionally filtered', which confirms the filter parameter's optionality but adds no new meaning. The mention of 'Required on create' is unrelated to parameters. Baseline 3 applies as schema does the heavy lifting and description does not improve parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List line item (material/labour/service) on a job's quote or invoice', which identifies the verb and resource. It distinguishes from siblings like 'get_job_material' (single item) and 'list_materials' (all materials) by specifying the scope. However, 'Required on create: quantity records' is ambiguous and does not clarify the tool's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. It mentions optional filtering but does not contrast it with search tools or other list operations among the 30+ sibling tools. No when-not-to-use or alternative recommendations are given.

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

list_job_paymentsA

List payment recorded against a job. Financially sensitive — kept at admin tier rather than everyday office-ops records, optionally filtered. Maps to GET /jobpayment.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description must carry the burden. It discloses the tool is readonly (tier: readonly-owner) and maps to a GET endpoint, which is helpful. However, it lacks details on authentication requirements, rate limits, or error behavior.

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?

The description is extremely concise: two brief sentences plus a tier tag. Every word provides value, with no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two fully documented parameters, the description provides important context about financial sensitivity and tier restrictions. It lacks details on return value format or pagination behavior, but the cursor parameter is well-documented in the schema.

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 the parameters are already well-documented. The description adds only 'optionally filtered', which is redundant with the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists payments against a job, using the verb 'list'. It provides additional context (financially sensitive, admin tier). However, it does not explicitly distinguish from the sibling tool 'get_job_payment' or other list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage is restricted to admin users due to financial sensitivity, giving some guidance on when to use. But it does not explicitly state when not to use or provide alternatives (e.g., get_job_payment for a single payment).

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

list_job_queuesC

List dispatch queue jobs can be placed into for assignment records, optionally filtered. Maps to GET /queue.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

C2.9/5.0

Behavior2/5

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

The description provides limited behavioral information: it maps to GET /queue.json (idempotent read) and includes a tier hint '[tier: readonly-owner]'. No side effects, rate limits, or additional traits are disclosed. Without annotations, the burden is on the description, which is minimal.

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?

The description is concise: one sentence plus tags. It front-loads the action and resource. No unnecessary words, though additional structure could improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not explain return values or pagination behavior (cursor is in schema but not mentioned in description). The description is incomplete for understanding the full context of the tool's capabilities.

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 coverage is 100%, so the schema already documents both parameters thoroughly. The description adds only 'optionally filtered', which adds minimal value beyond the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the purpose: list dispatch queues for assignment records. It clearly indicates the resource (queues) and action (list), but the phrasing is slightly awkward. It differentiates from siblings like list_jobs by focusing on queues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description does not mention when not to use it or provide context for selecting this tool over siblings like list_jobs or search tools.

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

list_jobsB

List job (work order). Required on create: status records, optionally filtered. Maps to GET /job.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It discloses the HTTP method (GET) and access tier (readonly-owner), implying a safe read operation. However, it lacks details on authentication, rate limits, or side effects beyond being read-only.

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?

The description is concise, consisting of a single sentence and a tag. However, the structure is slightly run-on, and the key points could be better separated for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description provides adequate context: purpose, endpoint, and a use case. However, it omits mention of pagination behavior (described only in the schema) and does not describe the return format, which would be helpful for a list tool.

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 coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions 'optionally filtered' which aligns with the filter parameter, but adds no new insights into parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List job (work order)', specifying the verb and resource. It differentiates from sibling tools by focusing on jobs, though it does not explicitly distinguish from other list tools for related entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description hints at a specific use case ('Required on create: status records') but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it.

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

list_job_templatesB

List job templates configured for the account (e.g. a standard 'Quarterly Pest Treatment' template). Maps to GET /jobtemplate.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No
`filter`	No

TDQS

B3.2/5.0

Behavior3/5

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

Description adds endpoint mapping (GET) and tier, which implies read-only, but lacks details on pagination, result format, or authorization beyond tier label.

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?

Two sentences plus a tag, no fluff, front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Minimal but missing parameter descriptions and output info; for a listing tool with no output schema, more context would help agents correctly invoke it.

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

Parameters1/5

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

Schema has two parameters (cursor, filter) with 0% coverage; description does not explain them, leaving their purpose unclear.

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?

The description clearly states the tool lists job templates for the account and gives a concrete example, distinguishing it from sibling tools like list_jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like list_jobs; the tier tag hints at access but no explicit when/when-not.

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

list_materialsB

List catalog material, product, or labour rate. Required on create: name records, optionally filtered. Maps to GET /material.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

B3.3/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It provides behavioral context: readonly (tier: readonly-owner), pagination via cursor, up to 1000 records per page, and filtering. However, it does not describe error handling, rate limits, or what happens on invalid filters. The 'Required on create' statement is confusing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and includes a mapping to the REST endpoint and a tier tag. However, the phrase 'Required on create: name records' is unclear and reduces efficiency. Overall, it is concise but could be clearer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has two parameters, full schema coverage, and no output schema. Description covers pagination and filtering but does not explain the return structure or fields. The confusing 'Required on create' part does not add value, leaving gaps in completeness.

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 coverage is 100%; both parameters are documented in the input schema. The description adds minimal extra meaning: it mentions 'optionally filtered', but not cursor or details. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists catalog materials, products, or labor rates, distinguishing it from siblings like get_material (single item) and list_job_materials (job-specific). The phrase 'Required on create: name records' is ambiguous, but the overall purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing catalog items via the resource listing, but does not explicitly state when to use this tool versus alternatives like get_material or list_job_materials. No when-not or exclusion criteria are provided.

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

list_suppliersC

List vendor/supplier record records, optionally filtered. Maps to GET /supplier.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It adds the HTTP method and tier hint but does not discuss side effects, auth requirements, rate limits, or pagination behavior beyond what is in the schema.

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?

The description is very concise with one sentence and a tier tag. No redundancy, though the 'record records' phrase could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description omits details about response structure, pagination (e.g., nextCursor), and result semantics. It is minimally complete for basic invocation but lacks depth.

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 the description adds little value for parameters. The phrase 'optionally filtered' echoes the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List vendor/supplier record records' with optional filtering, making the action and resource explicit. However, it does not explicitly distinguish from sibling tools like `get_supplier` or other list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It only mentions optional filtering and a readonly tier, but no exclusions or context for choosing this over `get_supplier` or `list_clients`.

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

list_tax_ratesA

List configured tax rate records, optionally filtered. Maps to GET /taxrate.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No	Pagination cursor from a previous call's nextCursor. Omit for the first page (defaults to "-1"). Each page returns up to 1000 records.
`filter`	No	OData-style filter, e.g. "status eq 'Work Order'" or "active eq 1 and company_uuid eq '...'". Operators: eq, ne, gt, lt. Up to 10 conditions joined with 'and'.

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses the underlying API endpoint and the readonly-owner tier, implying read-only behavior, but lacks details on authentication, rate limits, or side effects.

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?

The description is extremely concise: one sentence plus endpoint and tier label. It is front-loaded with the action and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with optional filtering and pagination, the description is adequate given the schema already covers parameter details. However, it could be improved by briefly noting return format or default behavior, though not strictly required.

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 coverage is 100%, with both parameters (cursor and filter) already described in the schema. The description adds no additional parameter semantics beyond the endpoint mapping and tier label.

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?

The description clearly states 'List configured tax rate records, optionally filtered', using a specific verb and resource. It also maps to a specific endpoint, distinguishing it from other list tools in the sibling set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description only states what it does, without mentioning exclusions or alternative tools for specific scenarios.

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

searchA

Free-text search across all ServiceM8 record types. Maps to GET /search.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description	Default
`q`	Yes
`limit`	No

TDQS

A3.8/5.0

Behavior3/5

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

No annotations provided. Description mentions readonly-owner tier and maps to API endpoint. Basic behavioral context for a read-only search, but lacks details on pagination or limits.

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?

Two concise sentences with no waste. Front-loaded with core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations or output schema, description covers core behavior but omits param semantics and return value details. Adequate but incomplete for a 2-param tool.

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

Parameters2/5

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

Schema has 0% coverage. Description only implies 'q' is search query, does not explain 'limit' or its maximum/minimum. Fails to compensate for lack of schema descriptions.

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?

Description clearly states 'Free-text search across all ServiceM8 record types', specifying verb, resource, and scope. Distinguishes from siblings that target specific record types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for broad free-text queries across record types, with siblings for specific records. No explicit exclusions or when-not-to-use, but context is clear.

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

search_by_typeA

Free-text search scoped to one record type (e.g. 'job', 'company'). Maps to GET /search/{objectType}.json. [tier: readonly-owner]

ParametersJSON Schema

Name	Required	Description
`q`	Yes
`limit`	No
`objectType`	Yes	Record type to search, e.g. 'job', 'company', 'staff'

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description carries full behavioral disclosure burden. It mentions the endpoint (GET /search/{objectType}.json) and a tier label 'readonly-owner', indicating read-only operation. However, it lacks details on side effects, rate limits, pagination, or required permissions beyond the tier label.

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?

The description is extremely concise with two sentences: the first states the purpose and scope, and the second provides the endpoint and access tier. Every sentence adds value with no superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with no output schema, the description covers the purpose, endpoint, and access tier. However, it lacks details on the response format, result ordering, or how the 'limit' parameter affects results. This leaves some gaps for agent understanding.

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 only 33% (only objectType has a description). The description adds meaning by clarifying that 'q' is a free-text query for the search, partially compensating for the gap. However, it does not explain the 'limit' parameter, leaving some parameters under-documented.

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?

The description clearly states it performs a free-text search scoped to one record type, with examples like 'job' and 'company'. It distinguishes from the generic 'search' sibling tool by explicitly mentioning the scoping to a single type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when searching a single record type, but it does not explicitly state when not to use it or mention alternatives like the sibling 'search' tool for multiple types. Guidance is implied but not explicit.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

28 tool updatesv0.1.0Jul 25, 2026
- First observedget_client
- First observedget_client_contact
- First observedget_inbox_message
- First observedget_job
- First observedget_job_activity
- First observedget_job_contact
- First observedget_job_material
- First observedget_job_payment
- First observedget_material
- First observedget_staff_member
- First observedget_supplier
- First observedlist_attachments
- First observedlist_client_contacts
- First observedlist_clients
- First observedlist_inbox_messages
- First observedlist_job_activities
- First observedlist_job_categories
- First observedlist_job_contacts
- First observedlist_job_materials
- First observedlist_job_payments
- First observedlist_job_queues
- First observedlist_job_templates
- First observedlist_jobs
- First observedlist_materials
- First observedlist_suppliers
- First observedlist_tax_rates
- First observedsearch
- First observedsearch_by_type

Deploy Server

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

TDQS

B3.2/5.0

Scored 2026-09-09 18:05 across 28 tools

Disambiguation5/5

Every tool maps to a distinct resource/action pair (list vs get, client vs job vs material, etc.), and even similar resources like client contacts and job contacts are clearly differentiated in descriptions. search and search_by_type are also distinct enough from the list tools.

Naming Consistency5/5

The naming follows a consistent list_<plural_resource> / get_<singular_resource> convention with snake_case throughout, and search/search_by_type use the same verb-first style. There are no mixed casing or varying verb patterns.

Tool Count2/5

At 28 tools, the set exceeds the 25+ threshold and feels heavy, especially since most are mechanical list/get pairs for the same entity types. The broad read-only scope explains the count, but it is more than an agent typically needs for a single server.

Completeness2/5

The server covers read operations for many ServiceM8 entities, but there are no create/update/delete tools at all, so any workflow that needs to modify a job, client, contact, or payment dead-ends. Some resources also have incomplete get/list coverage (e.g., staff has get but no list; attachments list only).

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
com.syncrosecure
Connect any AI assistant to Syncro: manage tickets, invoices, customers, assets, and more.
Customer Support Payments & Billing CRM
1
mcpOAuth
com.formester
Give AI agents access to form submissions — read, search, update, and process file attachments.
App Automation Databases Customer Data Platforms
2
Command+KOAuth
com.commandplusk
Set up and run an in-product AI assistant: widgets, knowledge, MCP connections, usage.
Developer Tools Workplace & Productivity
2
mcp-serverOAuth
com.make
Give your AI agents the tools to build, manage, and run automation workflows.
App Automation Developer Tools Workplace & Productivity
2

Related MCP Servers

backcrew-mcp-commusoft
jayson-svg
A
license
A
quality
B
maintenance
Enables AI assistants to interact with Commusoft CRM for tasks like customer lookups, supplier management, and more, with read-only access by default and optional write permissions.
Updated 2 months ago (2026-07-22 15:32 UTC)
7
MIT
RepairDesk MCP Server
Customer Support E-commerce & Retail
codeyoc
A
license
B
quality
B
maintenance
Provides MCP-compatible AI assistants with read/write access to RepairDesk shop data, enabling natural language queries and operations on tickets, customers, invoices, inventory, employees, and reference info, with safety confirmations for status changes.
Updated a month ago (2026-08-26 04:40 UTC)
7
MIT
Jobber MCP Server
CRM Finance Project Management
adeocode
A
license
Not graded
quality
C
maintenance
Enables AI assistants like Claude, ChatGPT, and Copilot to query live Jobber data—clients, jobs, quotes, invoices, revenue, and schedule—using natural language, with read-only access and careful API budget management.
Updated 24 days ago (2026-08-27 16:01 UTC)
1
MIT
MCP Server for Odoo
otomatercom-cloud
F
license
Not graded
quality
C
maintenance
Enables AI assistants to securely access and interact with Odoo data through natural language, supporting full CRUD operations, OAuth 2.1 and API key authentication, and granular per-model permissions.
Updated 11 days ago (2026-09-10 07:10 UTC)
-

BackCrew ServiceM8 MCP Server

Contents

What this actually does

Why use an independent MCP server instead of ServiceM8's official one?

Also from BackCrew

Some words you'll see, explained

How this keeps you safe by default

What it can look up (always safe)

⚠️ What it can change (off by default)

How to set it up

Step 1: Make a folder for this on your computer

Step 2: Get your ServiceM8 API key

Step 3: Install it

Connecting it to Claude

Claude Desktop / Claude Code

Things you can try asking

Testing it safely

For developers

Tool reference

Why this repo uses a CRUD factory instead of hand-written tools per resource

The tier/profile system

Project layout

Notes on the ServiceM8 API

Scope

What's next

Built by BackCrew

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers