How FieldTask tools work

FieldTask's MCP tools run the same checks and return the same data as the REST API. This page explains what's different when an AI client is the caller.

You use names; the client uses IDs

Every tool argument that refers to a record is an ID, but you never need to supply one. Describe the customer, place or person, and the client resolves them with the list tools:

You mention	The client looks it up with
A customer	fieldtask_list_customers, by name or contact details
A site or address	fieldtask_list_customer_locations for that customer
A person to assign	fieldtask_list_members, by display name
A product or service	fieldtask_list_products
A job	fieldtask_list_jobs

FieldTask's instructions to the client are to:

• ask you to choose when a name matches more than one record, using details you can recognize rather than IDs;
• follow every page of results before deciding a record doesn't exist;
• never invent an ID, and never create a duplicate to avoid a lookup;
• explain a missing permission instead of treating it as "no results".

These are instructions, not guarantees. Check important changes in FieldTask, or ask the client to read the record back.

What the tools return

Each tool returns structured JSON (structuredContent) matching the schema shown on its page, and the same JSON as text for clients that only read text. Record names and descriptions come from your organization's data; FieldTask tells clients to treat that text as data, not as instructions.

Which fields appear depends on the connection's permissions. For example, a job's customer summary needs customers:read.

Creating records safely

Create tools never update or match existing records. To make retries safe, create tools take an operation_key: calling again with the same key and arguments returns the original result instead of creating a second record. See Idempotency and recovery.

If a create seems to fail or times out, ask the client to check, for example "check the operation for that job" or "list today's jobs for Example Property Services", before asking it to create the record again. Every create result includes an operation_id that fieldtask_get_operation can look up for seven days.

Errors

A failed tool call returns isError: true with an error object: code, message, fix, docs_url, request_id, and retry_after when the client should wait. The codes are the same as the REST API's, with missing_permission for a missing permission. See Errors.

One error is specific to MCP: response_too_large means a created record, such as a draft with many line items, is too large to return through MCP. Nothing is created. Create fewer items, or use the REST API.

Problems with the connection itself, such as an expired sign-in, come from the MCP protocol rather than a tool result. The client asks you to sign in again.

Limits

Tool calls count against the same per-minute, concurrency and daily limits as REST requests. See Rate limits and quotas.