Field Service Business Platform by Doing Work

customers_audience

Pick a customer audience by filters (tags, last job dates, kind of work, open quotes, money owed, maintenance plans, city or postal code, has email or phone) and get the counts and a page of matching customers. Read only: it sends nothing and changes nothing. Owner or office only; money filters need see_prices.

Input Schema

Name	Required	Description
`kind`	No
`sort`	No	name (default), last_job_oldest (never served first), last_job_newest or created_newest.
`limit`	No
`cities`	No	A service property (not archived) or a job address (job not cancelled) in one of these cities; case is ignored.
`cursor`	No
`autopay`	No
`jobs_to`	No
`overdue`	No	Has an invoice past its due day with money owed. Needs see_prices.
`shop_id`	Yes
`has_jobs`	No	true: at least one job that is not cancelled. false: none.
`tags_all`	No	Customers with every one of these tags.
`tags_any`	No	Customers with at least one of these tags.
`has_email`	No	Has an email address on the customer or on a current contact. This is not consent to marketing email; Doing Work keeps no marketing consent yet.
`has_phone`	No
`job_kinds`	No	Has a job (not cancelled) of one of these kinds.
`jobs_from`	No	With job_kinds, job_tags_any or job_summary_contains: only jobs dated on or after this day count.
`tags_none`	No	Leave out customers with any of these tags.
`created_to`	No
`owes_money`	No	Has sent invoices with money still owed. Needs see_prices.
`last_job_to`	No	The most recent job is on or before this day. Use it for customers not served since a date; pair with has_jobs:false in a second call for those never served.
`plan_status`	No	Maintenance plans. active: has an active plan. cancelled: had plans, none active now. none: never had one. any: has or had one.
`created_from`	No	Customer added on or after this day (shop time zone).
`job_tags_any`	No	Has a job (not cancelled) with one of these tags, for example the service or trade.
`lead_sources`	No
`postal_codes`	No	A service property or job address in one of these postal codes. End a code with * to match a prefix, for example 838*.
`last_job_from`	No	The customer's most recent job (not cancelled) is on or after this day, shop time zone. Customers with no jobs are left out.
`has_open_quote`	No	A quote sent and not yet signed or declined.
`min_owed_minor`	No	Owes at least this much in total. Needs see_prices.
`max_spent_minor`	No	Lifetime invoiced at most this. Needs see_prices.
`min_spent_minor`	No	Lifetime invoiced (sent and later, not voided, tax included) at least this. Needs see_prices.
`include_archived`	No	Default false. Erased and merged customers are never included.
`plan_term_ends_to`	No
`plan_term_ends_from`	No	Has an active maintenance plan whose current term ends on or after this day (renewals).
`job_summary_contains`	No	Has a job (not cancelled) whose summary contains these words, for example 'furnace'.

Output Schema

Name	Required	Description
`data`	Yes
`sort`	Yes
`counts`	Yes
`shop_id`	Yes
`currency`	Yes
`time_zone`	Yes
`next_cursor`	Yes
`prices_hidden`	Yes	true when the caller lacks see_prices, so money columns are null.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 1, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations, the description carries the burden well: it explicitly says 'Read only: it sends nothing and changes nothing' and discloses the owner/office and see_prices permission requirements. It does not cover pagination limits or rate behavior, but the key safety and authorization traits are stated.

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 definition is three compact sentences, front-loads the tool purpose and output, then follows with read-only safety and permissions. Every sentence earns its place despite the large 34-parameter surface.

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 an output schema and 71% schema description coverage, the description provides enough context to understand the tool's purpose, output shape at a high level, safety profile, and permission gates. It could be slightly more complete by explicitly naming sibling alternatives or pagination expectations, but it is adequate for this complex read-only filter 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 description coverage is 71%, so many parameters are already documented in the schema. The description enumerates major filter categories (tags, last job dates, job kinds, open quotes, money owed, plans, city/postal code, email/phone) but does not add specifics for parameters like cursor, limit, sort, or date pairing behavior beyond what the schema provides.

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 a specific verb and resource: pick a customer audience by filters and get counts plus a page of matching customers. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools like customers_search or customers_list.

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?

Usage is implied as customer segmentation/filtering, and the description adds access constraints: owner or office only, and money filters require see_prices. It does not say when to use this instead of customers_search or customers_list, leaving alternative routing to inference.

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

All Field Service Business Platform by Doing Work tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?