Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-servicefusion Show me today's scheduled 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.
A Model Context Protocol (MCP) server exposing the Service Fusion REST API to AI agents. Enables AI-assisted field service management: job lookup, customer management, dispatch, invoicing, equipment tracking, and more.
Disclaimer: This is an unofficial, community-built integration. Not affiliated with or endorsed by Service Fusion.
Read tools:
get_todays_jobs — today's scheduled jobs with assigned techs
search_jobs — flexible search with filters (status, customer, date range, etc.)
get_job_details — full job record with expanded relations
get_customer_jobs — all jobs for a given customer
search_customers — by name, phone, email, or address
get_equipment — customer equipment with custom fields
get_open_invoices — outstanding invoices
get_techs — technician list
get_job_statuses, get_job_categories, get_sources — reference data
get_me — current authenticated user
Create tools:
create_job, create_customer, create_estimate
API documentation:
get_api_docs — look up the Service Fusion API reference directly from the MCP connection. Sections: index, jobs, customers, estimates, invoices, techs, data-types, authentication, known-issues, full
Related MCP server: Fergus MCP Server
Node.js ≥ 18
Service Fusion API credentials (My Office → Developer Settings → API Credentials)
git clone https://github.com/commair-tools/mcp-servicefusion-public.git mcp-servicefusion
cd mcp-servicefusion
npm install
npm run build
cp .env.example .env
# Edit .env and add SF_CLIENT_ID and SF_CLIENT_SECRETAdd to your claude_desktop_config.json (see claude_desktop_config.example.json):
{
"mcpServers": {
"service-fusion": {
"command": "node",
"args": ["/absolute/path/to/mcp-servicefusion/build/index.js"],
"env": {
"SF_CLIENT_ID": "your_client_id_here",
"SF_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}claude mcp add service-fusion node /absolute/path/to/mcp-servicefusion/build/index.js \
-e SF_CLIENT_ID=your_client_id -e SF_CLIENT_SECRET=your_client_secretThe server also supports Streamable HTTP transport for hosted deployments (Railway, Fly.io, Cloud Run, etc.) with OAuth 2.1 authentication.
Variable | Required | Description |
| Yes | Service Fusion OAuth client ID |
| Yes | Service Fusion OAuth client secret |
| Yes (for HTTP) | Set to |
| No | HTTP port (default: |
| Yes (for HTTP) | Public URL of your server, e.g. |
| Recommended | PIN for browser-based OAuth approval (required by Claude.ai web) |
| Optional | Static Bearer token for non-OAuth clients (e.g., Claude Code CLI) |
| No | Defaults to |
| No | Defaults to |
Fork or import this repo on Railway
Set the environment variables listed above
Railway auto-builds via railway.toml and exposes a public URL
Use that URL as your BASE_URL
Claude.ai web (OAuth flow): add the server URL (without trailing slash, e.g., https://mcp.example.com/mcp) as a remote MCP connector in Settings. Leave OAuth client ID/secret fields blank — the server advertises discovery metadata so Claude.ai handles the full OAuth handshake automatically. On first connect, you'll be redirected to a browser page to enter your MCP_OAUTH_PIN. After that, tokens auto-refresh for 30 days.
Claude Code / CLI clients: use the static token via the Authorization: Bearer <MCP_AUTH_TOKEN> header.
No authentication: if neither MCP_OAUTH_PIN nor MCP_AUTH_TOKEN is set, the server runs unauthenticated (not recommended for public-facing deployments).
The repo includes a complete Service Fusion API reference in service-fusion-api-reference.md, auto-generated from the official RAML spec at docs.servicefusion.com. Agents can access it through the get_api_docs tool at runtime.
To regenerate it after Service Fusion updates their spec:
node scripts/update-api-docs.mjs/jobs endpoint hangs without sort parameterAs of 2026-04-09, Service Fusion's /jobs list endpoint hangs indefinitely when queried without a sort parameter. This server works around it by defaulting all /jobs list queries to sort=-start_date in src/client.ts. If you see hangs on other endpoints in the future, check whether they require a sort param too.
There is no top-level /equipment endpoint. Equipment must be fetched via GET /customers/{customer-id}/equipment. The get_equipment tool handles this by resolving customer_name to customer_id internally.
Confirmed by Service Fusion support:
No PUT, PATCH, or DELETE on any endpoint (read and create only)
No native webhook/callback support
No sandbox/test environment
Rate limit: 60 requests/minute (server enforces backoff automatically)
TypeScript + Node.js
@modelcontextprotocol/sdk for MCP protocol
Express for HTTP transport
OAuth 2.1 with PKCE, Dynamic Client Registration, and resource indicators
Business Source License 1.1 — see LICENSE
TL;DR: Free to use, modify, and redistribute (including internally at HVAC businesses to manage your own operations). You may not resell it or offer it as a paid hosted service to third parties. On April 10, 2036 it automatically converts to the Apache License 2.0 (fully permissive).
Create a new customer record in Service Fusion. Note: This endpoint may require elevated API permissions. If you get a 403 error, customer creation must be done through the Service Fusion web UI instead.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | Yes | Customer or company name. | |
| first_name | No | Primary contact first name. | |
| last_name | No | Primary contact last name. | |
| No | Primary contact email address. | ||
| phone | No | Primary phone number. | |
| mobile_phone | No | Mobile phone number. | |
| street_1 | No | Street address line 1. | |
| street_2 | No | Street address line 2 (suite, unit, etc.). | |
| city | No | City. | |
| state_prov | No | State or province (2-letter code, e.g., 'TX'). | |
| postal_code | No | ZIP or postal code. | |
| source | No | Lead source. | |
| payment_type | No | Default payment type. | |
| notes | No | Customer notes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The permission note adds context beyond annotations, which already indicate readOnlyHint=false and destructiveHint=false. It does not contradict annotations and provides useful behavioral info about potential authorization failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences that deliver the core purpose and a critical caveat. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a create operation with 14 parameters and good schema coverage, but misses a note on the return value or response structure (no output schema provided). The permission guidance partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and brief descriptions. The description does not add additional parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Create a new customer record') and the resource ('in Service Fusion'). It directly conveys the tool's purpose with a specific verb and resource, distinguishing it from sibling tools like search_customers or create_estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on permissions ('may require elevated API permissions') and a fallback action if a 403 error occurs ('customer creation must be done through the Service Fusion web UI'). This helps the agent know when the tool is viable and what to do otherwise.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new estimate in Service Fusion. Requires an exact customer name (use search_customers to find it) and a category. Returns the created estimate record with its assigned number.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | Yes | Exact customer name as it appears in Service Fusion. Use search_customers to find the correct name. | |
| category | Yes | Estimate category — must be an exact match (e.g., 'Commercial Service', 'Residential Service', 'Commercial Install'). | |
| description | No | Estimate description / work to be quoted. | |
| start_date | No | Proposed start date/time (ISO 8601: YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD). | |
| end_date | No | Proposed end date/time (ISO 8601). | |
| source | No | Lead source (exact match). Use get_sources for valid values. | |
| contact_first_name | No | On-site contact first name (overrides customer default). | |
| contact_last_name | No | On-site contact last name (overrides customer default). | |
| street_1 | No | Site street address (overrides customer default). | |
| city | No | Site city (overrides customer default). | |
| state_prov | No | Site state/province (overrides customer default). | |
| postal_code | No | Site postal code (overrides customer default). | |
| tech_notes | No | Internal notes. | |
| note_to_customer | No | Notes visible to the customer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint: false). The description confirms by saying 'Creates' and 'Returns the created estimate record.' It adds value by explaining the prerequisite and return behavior, which goes beyond the annotations. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action. Every phrase is informative: system, action, prerequisites, and return value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters and no output schema, the description explains the return value ('Returns the created estimate record with its assigned number') and key prerequisites. It does not explain optional parameters, but the schema already covers them. Sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter has a description. The tool description reinforces the need for exact match on customer_name and category, referencing search_customers. This adds minimal extra value beyond the schema, fitting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new estimate in Service Fusion.' It specifies the verb (create), resource (estimate), and system. It also mentions what the tool returns and prerequisites, distinguishing it from siblings like create_job or create_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions requirements: 'Requires an exact customer name (use search_customers to find it) and a category.' This provides clear guidance on when to use the tool and points to a prerequisite tool. It does not explicitly state when not to use it versus alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new service job in Service Fusion. Requires an exact customer name (use search_customers to find it), a category (use get_job_categories or try 'Commercial Service', 'Residential Service', etc.), and a status (use get_job_statuses or try 'Scheduled', 'Confirmed', etc.). Returns the created job record with its assigned job number.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | Yes | Exact customer name as it appears in Service Fusion. Use search_customers to find the correct name. | |
| category | Yes | Job category — must be an exact match (e.g., 'Commercial Service', 'Residential Service', 'Commercial Install', 'Residential Install', 'Commercial Maintenance', 'Residential Maintenance'). | |
| status | Yes | Job status — must be an exact match (e.g., 'Scheduled', 'Confirmed', 'Unscheduled'). Use get_job_statuses for the full list. | |
| description | No | Job description / work to be performed. | |
| start_date | No | Scheduled start date/time (ISO 8601: YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD). | |
| end_date | No | Scheduled end date/time (ISO 8601). | |
| source | No | Lead source (exact match). Use get_sources for valid values. | |
| priority | No | Job priority (e.g., 'Normal', 'High', 'Emergency'). Default: 'Normal'. | |
| contact_first_name | No | On-site contact first name (overrides customer default). | |
| contact_last_name | No | On-site contact last name (overrides customer default). | |
| street_1 | No | Job site street address (overrides customer default). | |
| city | No | Job site city (overrides customer default). | |
| state_prov | No | Job site state/province (overrides customer default). | |
| postal_code | No | Job site postal code (overrides customer default). | |
| tech_notes | No | Internal notes visible to technicians. | |
| note_to_customer | No | Notes visible to the customer. | |
| po_number | No | Customer purchase order number. | |
| payment_type | No | Payment type (e.g., 'Check', 'Credit Card'). | |
| called_in_by | No | Name of person who called in the job. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions it is a creation operation (consistent with annotations) and specifies that it returns the job record with its assigned number. It adds context about required exact matches. Annotations already indicate non-readOnly and non-destructive, so description adds value. Could be improved by noting any side effects or permissions, but currently sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no fluff. The first sentence states the purpose, the second lists essential prerequisites, and the third describes the return value. Well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 19 parameters and full schema coverage, the description provides sufficient context for core functionality: required params, usage hints, and return value. It could mention error handling or validation, but remains complete for typical use. No output schema reduces the need to explain return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 extra guidance for required parameters (e.g., using search_customers for customer_name, listing common category and status values). This provides additional context beyond the schema definitions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new service job in Service Fusion and returns the created record with an assigned job number. It distinguishes itself from sibling tools like create_customer and create_estimate by specifying the domain (service job).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: requires exact customer name (referencing search_customers), category (referencing get_job_categories with examples), and status (referencing get_job_statuses with examples). This helps the agent select and invoke the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up Service Fusion REST API documentation. Call with section="index" to see all available sections, or pass a specific section like "jobs", "customers", "estimates", "data-types", "authentication", etc. Returns official endpoint docs including parameters, filters, field lists, request/response schemas, and examples.
| Name | Required | Description | Default |
|---|---|---|---|
| section | Yes | Section to retrieve. Use "index" for table of contents, or a section slug like "jobs", "customers", "estimates", "invoices", "techs", "data-types", "authentication", "known-issues". Use "full" for the complete reference (large). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds value by detailing what the output contains (endpoint docs, parameters, filters, etc.) without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and includes specific usage guidance without extraneous information. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description adequately explains the return content (parameters, filters, field lists, request/response schemas, examples). For a documentation retrieval tool, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'section' has 100% schema coverage, but the description adds significant meaning by explaining special values like 'index' and 'full', and providing examples of section slugs like 'jobs', 'customers', etc., which is beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves Service Fusion REST API documentation, differentiating it from sibling tools that focus on specific entities. It specifies the verb 'look up' and the resource 'Service Fusion REST API documentation'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on how to use the tool: call with section='index' for all sections, or a specific section like 'jobs'. It gives examples but does not explicitly mention when not to use it or alternatives, though the context implies it is for documentation retrieval only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all jobs for a customer by name. Returns the complete job history sorted by most recent first, including assigned technicians. Use search_customers first to find the exact customer name.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | Yes | The customer name to search for (partial match). Use search_customers first to find the exact name. | |
| status | No | Optionally filter by job status. Comma-separated for multiple (e.g., 'Open,Scheduled'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds value by detailing that results are sorted by most recent first and include assigned technicians.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two front-loaded sentences, no wasted words, and effectively communicates all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and richness of annotations/schema, the description sufficiently explains the output (complete job history sorted by date including techs), making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description does not add additional meaning beyond what the schema already provides for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'jobs for a customer', and specifies it returns complete history sorted by most recent with assigned technicians. It effectively distinguishes itself from sibling tools like search_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to 'Use search_customers first to find the exact customer name', providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get equipment records for a customer. Requires either customer_id or customer_name (resolved to ID automatically). Equipment includes type, make, model, serial number, location, warranty info, and custom fields (filter sizes, belt specs, etc.). Optionally fetch a single equipment record by equipment_id.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_name | No | Customer name to look up equipment for (partial match). Resolved to customer_id internally. Either this or customer_id is required. | |
| customer_id | No | Customer ID (skips name resolution). Either this or customer_name is required. | |
| equipment_id | No | Specific equipment ID to fetch a single record. | |
| page | No | Page number (default: 1). | |
| per_page | No | Results per page (default: 50, max: 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by explaining the automatic resolution of customer_name to customer_id and the inclusion of custom fields (filter sizes, belt specs). There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, then prerequisites, then field overview. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and annotations already covering safety, the description explains input constraints and the type of data returned (e.g., type, make, model). It does not describe the output structure explicitly, but the field listing gives a reasonable expectation. Pagination details are covered in parameter descriptions. Minor gap: no mention of response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical context: customer_name performs partial matching and is internally resolved to customer_id, customer_id skips resolution, and equipment_id fetches a single record. It also clarifies the mutual exclusivity between customer_name and customer_id for input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get equipment records for a customer', using a specific verb ('Get') and resource ('equipment records for a customer'). It lists the fields included (type, make, model, etc.) and mentions an optional single-record fetch by equipment_id. This distinguishes it from sibling tools like get_customer_jobs or search_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states input requirements: 'Requires either customer_id or customer_name (resolved to ID automatically)' and notes that equipment_id is optional for fetching a single record. It does not, however, provide guidance on when not to use this tool or suggest alternative tools for broader customer info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available job categories (e.g., 'Commercial Service', 'Residential Install'). Use these values when creating jobs or filtering by category. Results are cached for 30 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds important behavioral context: 'Results are cached for 30 minutes,' which is beyond annotation scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. It front-loads the core action and immediately follows with usage guidance and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description fully covers what it does, how the values are used, and caching behavior. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the baseline is 4. The description does not need to add parameter meaning, and it appropriately focuses on the tool's purpose and output use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all available job categories' using a specific verb-resource pair. It distinguishes itself from sibling tools as the only category-listing function, with examples like 'Commercial Service', 'Residential Install'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: 'Use these values when creating jobs or filtering by category.' This provides clear context, though it does not explicitly mention alternatives or exclusions, which is acceptable given the tool's uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete details for a single job by its internal ID or display number. Returns the full job record with all related data: assigned technicians, tasks, notes, equipment, products, services, charges, payments, invoices, and visit history. Provide either job_id (internal) or job_number (display).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Internal numeric job ID. Provide this OR job_number. | |
| job_number | No | Display job number as shown in Service Fusion (e.g., '76633'). Provide this OR job_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns the full job record with all related data, but lacks additional behavioral context (e.g., visibility of soft-deleted jobs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no extraneous words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return data. It could mention behavior when both parameters are provided or omitted, but overall meets the needs for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds that they are alternatives and provides an example for job_number, which is helpful but not extensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get complete details for a single job' using its internal ID or display number, clearly distinguishing it from siblings like search_jobs which search, and get_todays_jobs which list jobs by day.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that either job_id or job_number should be provided, but does not explicitly state when not to use this tool or mention alternatives (e.g., search_jobs for searching).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available job statuses. Returns status names grouped by category (OPEN, OPEN_ACTIVE, CLOSED). Useful for knowing valid status values when filtering jobs. Results are cached for 30 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description goes beyond by noting results are cached for 30 minutes, which is valuable behavioral info. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying essential information: what it does, output format, use case, and caching behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully covers all necessary context: purpose, output structure, usage, and caching. Nothing missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds meaning by specifying the output grouped by category, which is not evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available job statuses grouped by category (OPEN, OPEN_ACTIVE, CLOSED). It distinguishes itself from sibling tools that handle customers, estimates, or jobs directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is useful for knowing valid status values when filtering jobs, providing clear use context. It does not explicitly mention when not to use it or direct alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current authenticated user info. Useful for verifying API connectivity and credentials.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint as safe. Description adds context about returning authenticated user info and verification purpose, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core purpose. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with comprehensive annotations, the description fully covers purpose and usage. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies. Description doesn't need to add parameter info as schema coverage is 100% (empty schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get current authenticated user info', specifying the verb and resource. Distinguishes from sibling tools (e.g., get_customer_jobs, get_equipment) which focus on other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Useful for verifying API connectivity and credentials', providing clear guidance on when to use the tool without needing to describe alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search invoices, optionally filtered by payment status or customer name. Use this to find outstanding balances, track payments, or review billing history.
| Name | Required | Description | Default |
|---|---|---|---|
| payment_status | No | Filter by payment status (e.g., 'Outstanding', 'Partial', 'Paid'). Comma-separated for multiple. | |
| customer_name | No | Filter by customer name (partial match). | |
| page | No | Page number (default: 1). | |
| per_page | No | Results per page (default: 20, max: 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe, read-only operation. The description adds no further behavioral details (e.g., rate limits, pagination limits, or what happens with empty results). It does not contradict annotations, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the action and providing immediate use cases. No extraneous information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high schema coverage and informative annotations, the description covers purpose and typical use cases. It does not mention return format or pagination, but those are partially documented in the schema. The only gap is the name inconsistency, but overall it is sufficiently complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds generic filtering context ('optionally filtered by payment status or customer name') but does not extend beyond schema details. Baseline 3 is correct as the description complements but does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search invoices' which is clear, but the tool name is 'get_open_invoices', creating ambiguity about whether it returns only open invoices or all invoices. The use cases given are helpful, but the inconsistency between name and description reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using the tool for 'find outstanding balances, track payments, or review billing history', providing some context. However, it does not specify when to avoid using it or mention alternative tools from the sibling list, such as 'search_customers' or 'get_job_details'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available lead sources. Use these values when creating jobs, estimates, or customers. Results are cached for 30 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: 'Results are cached for 30 minutes,' which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence front-loads the purpose, and the second adds usage guidance and caching behavior. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and clear annotations, the description is complete. It covers purpose, usage, and behavior (caching). No output schema is needed as lead sources are self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100%. According to guidelines, this baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all available lead sources,' which clearly identifies the verb and resource. While it does not explicitly distinguish itself from sibling tools like get_equipment or get_job_categories, the resource name is unique enough to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use these values when creating jobs, estimates, or customers,' providing clear guidance on when to use the output. It does not, however, mention when not to use it or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all technicians. Returns tech names and details. Results are cached for 30 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by noting results are cached for 30 minutes, a behavioral trait not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences, 13 words. Front-loaded with the main purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and annotations covering safety, the description is fairly complete. It states what is returned (names and details) and adds caching info. Could specify what 'details' means, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description does not need to add parameter meaning since schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all technicians and returns names and details. It is specific about the resource and action, though it does not explicitly differentiate from sibling tools, but given no other technician tool, it's clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. The caching behavior is mentioned but not framed as a usage recommendation. Since there are no other tools listing technicians, the lack of guidance is less critical, but still missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all jobs scheduled for today. Returns jobs with start_date matching today's date, including assigned technicians. Use this for daily dispatch review, morning briefings, or checking the current day's workload.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by job status (e.g., 'Scheduled', 'Dispatched', 'In Progress'). Comma-separated for multiple statuses. Omit to get all statuses. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns jobs with start_date matching today's date, including assigned technicians, which is consistent and provides extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage context, and what data is returned. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional parameter 'status'. The description does not add any extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all jobs scheduled for today' with specific verb and resource, and distinguishes from sibling tools by focusing on today's jobs. It also mentions returning assigned technicians.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases: 'daily dispatch review, morning briefings, or checking the current day's workload.' It does not mention when not to use it or alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for customers by name, phone, email, or address. Returns matching customer records with contact details. Use this to look up customer information or find the exact customer name for use with get_customer_jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Search by customer/company name (partial match). | |
| phone | No | Search by phone number (partial match). | |
| No | Search by email address (exact match). | ||
| address | No | Search by street address (partial match). | |
| city | No | Filter by city (exact match). | |
| zip_code | No | Filter by zip/postal code (exact match). | |
| page | No | Page number (default: 1). | |
| per_page | No | Results per page (default: 20, max: 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only and idempotent. The description adds that it returns 'matching customer records with contact details' which is slightly more specific, but it does not detail match types or result structure beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences. First sentence states the core action and searchable fields. Second sentence provides usage context. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, return type, and usage scenario linking to a sibling tool. However, it does not describe the output structure (e.g., list of customers) or that pagination parameters exist, though the schema covers those. Given 8 optional parameters and no output schema, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions search by name, phone, email, or address but does not add significant meaning beyond what the parameter descriptions already state (e.g., partial vs exact match).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('customers'), lists searchable fields (name, phone, email, address), and distinguishes itself from siblings like 'get_customer_jobs' by stating it returns customer records with contact details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use: 'Use this to look up customer information or find the exact customer name for use with get_customer_jobs.' This provides clear guidance and references a sibling tool, though it could also 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.
Search for jobs with flexible filters. Supports filtering by status, customer name, date range, address, phone, email, category, and more. Returns paginated results sorted by most recent first by default.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by job status. Comma-separated for multiple (e.g., 'Open,Scheduled'). Common statuses: Open, Scheduled, Dispatched, In Progress, Completed, Cancelled. | |
| sub_status | No | Filter by sub-status (exact match). May not be supported by all accounts. | |
| customer_name | No | Filter by customer name (partial match). | |
| start_date_gte | No | Jobs starting on or after this date (YYYY-MM-DD). | |
| start_date_lte | No | Jobs starting on or before this date (YYYY-MM-DD). | |
| end_date_gte | No | Jobs ending on or after this date (YYYY-MM-DD). | |
| end_date_lte | No | Jobs ending on or before this date (YYYY-MM-DD). | |
| address | No | Filter by job address (partial match). | |
| city | No | Filter by city (exact match). | |
| zip_code | No | Filter by zip/postal code (exact match). | |
| phone | No | Filter by phone number (partial match). | |
| No | Filter by email address (exact match). | ||
| category | No | Filter by job category. Comma-separated for multiple. | |
| source | No | Filter by lead source. Comma-separated for multiple. | |
| number | No | Filter by job number (partial match). | |
| sort | No | Sort results. Prefix with '-' for descending. Examples: '-start_date', 'customer_name', '-created_at'. Default: '-start_date'. | |
| page | No | Page number (default: 1). | |
| per_page | No | Results per page (default: 20, max: 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read operation. The description adds behavioral context about pagination and default sort order, which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences effectively convey the purpose and key features. The information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers main functionality and pagination but does not describe the response structure or error handling. Given the number of parameters and lack of output schema, it could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description provides a high-level summary but does not add new meaning beyond grouping the filters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for jobs with flexible filters, listing specific filter fields. However, it does not explicitly differentiate from sibling tools like get_customer_jobs or get_todays_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. It does not mention scenarios where a sibling tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_customercreate_estimatecreate_jobget_api_docsget_customer_jobsget_equipmentget_job_categoriesget_job_detailsget_job_statusesget_meget_open_invoicesget_sourcesget_techsget_todays_jobssearch_customerssearch_jobsScored across 16 tools
Each tool targets a distinct resource or action (customer, job, estimate, invoice, equipment, tech, etc.) with no overlap in functionality. The create, get, and search prefixes clearly separate intents.
All tools follow a consistent verb_noun pattern (e.g., create_customer, get_job_details, search_customers). Naming is uniform and predictable across the entire set.
16 tools is appropriate for a field service management API covering customer, job, estimate, invoice, equipment, and lookup functions. Each tool serves a necessary purpose without bloat.
The tool set covers creation and retrieval for core entities but lacks update and delete operations for customers, jobs, estimates, and invoices. This is a notable gap for full lifecycle management.
Connect any AI assistant to Syncro: manage tickets, invoices, customers, assets, and more.
Manage jobs, customers, scheduling, estimates and invoices for a field service business.
Authenticated, read-only field-service workspace tools for FieldRobin businesses.
Search customers, manage quotes, work orders, action items, and calendar events for your business
