- Brand
- Contractors Cloud
- Category
- Sales & CRM
- Primary Subcategory
- ERP & Operations Resource Tools
Integration details
Description
Contractors Cloud is a CRM and business management platform for construction contractors. This app connects ChatGPT to your Contractors Cloud account so you can work with your live business data in plain conversation, with your own permissions and your own company's data only. What you can do: - Customers and contacts: search, create, and update customer accounts and contacts. - Projects: search projects, create them with the right company, lead source, and workflow, read and add activity notes, and search or add project files and photos. - Tasks and appointments: find, create, and update tasks and appointments, and see what is on your schedule. - Estimates, work orders, and material orders: look up, create, and update them, including estimate line items, labor items, and material order scheduling. - Contracts and billing: look up, create, and update contracts, invoices, credit memos, and payments, and approve contracts or lock payouts when your role allows it. - Messages: search your inbox or a project's inbox, and start or reply to Jet Stream threads with teammates. - Reports: find and run saved reports for totals and trends, or have ChatGPT build a custom private report from your data and delete it when done. - Team lookup: find teammates and teams so work is assigned to the right person. - Product help: search Contractors Cloud's official help articles to answer how-do-I questions. The app acts as you. You sign in with your Contractors Cloud account and approve the connection once; it can only see and change what your account can, and it cannot access another company's data. Recording a payment only records it in Contractors Cloud; the app never charges a card or moves money. It does not email or text customers from chat (appointment invitations are the one exception, sent only when requested), though your company's own workflow automations still run as usual when records change. When you ask, it can delete estimates, draft work orders, material orders, contracts, invoices, credit memos, payments, and your own private reports, but only where Contractors Cloud's own rules allow it. It cannot delete projects, customers, contacts, files, or tasks. Available to standard Contractors Cloud users.
- Integration type
- Plugin
- Verification status
- Not applicable
- Platform
- ChatGPT
- Primary Subcategory
- ERP & Operations Resource Tools
- Secondary Subcategories
- None listed
- Brand
- Contractors Cloud
- Access
- Account required
- First tracked
- 2026-11-21
- Tool count
- 45
- Market
- US
The Primary Subcategory used for this profile’s headline score.
Other Subcategories where the Integration is listed.
Not discoverable in ChatGPT yet
ChatGPT now suggests Plugins on its own when they match a user's request, but not every Plugin is being surfaced yet.We haven’t seen Contractors Cloud suggested yet. Sign up and we’ll track it, and your Discoverability Score will appear here once ChatGPT starts surfacing it.
What discovery looks like

Get alerts for Contractors Cloud
Get updates when Contractors Cloud’s Discoverability Score or category rank changes.
Competing in ChatGPT ERP & Operations Resource Tools
View Category45 tools agents can invoke
Create a new customer account or update an existing one. Set `action` to `create` or `update`; each is described below. - `action: create` — creates a new account. Requires `type`, `name`, `address_street`, `address_city`, `address_state`, and `address_zip`; all other fields are optional. - `action: update` — partially updates an existing account. Requires `id`; only the fields you pass are changed. `type` is `0` for a person or `1` for a business. `name` should be the business name for a business account, or "Last, First" for a person account. `address_state`/`shipping_address_state` must be a two-letter US state abbreviation. `rep_id` must be an existing user in the same tenant. Returns the curated account as `{ data: ... }`. Sibling tool: use `account_search` to find an existing account's id before updating it (pass `filter.id` to fetch one by id — there is no separate "get" tool).
account_write
Create a new project (a job/opportunity at a customer's property), or update an existing one. Set `action` to `create` or `update`; each is described below. - `action: create` — see below for the account/contact/company-conditional requirements. - `action: update` — requires `id`. Accepts the same flat project fields as `create` (address, status, name, primary rep, financials, etc.) EXCEPT the account/contact-creation blocks and `company_custom_fields` — `new_account`, `contact_ids`, `new_contacts`, `company_custom_fields`, and `company_id` are `create`-only and are loudly rejected if present on `update` (use `account_id` to re-point an existing project at a different account; contacts and custom fields cannot be changed via this tool). Conversely, `cancellation_id`/`reason_canceled` are `update`-only and are loudly rejected on `create` — a project cannot be created directly into a cancelled status. A `status_id` change starts new status-duration tracking and fires a webhook/domain event automatically, the same thing changing status in the web app does. Setting `status_id` to 8 (Cancelled) requires `cancellation_id` (valid ids come from `project_create_options` — no arguments needed — under `cancel_reasons`); it records the cancellation (date, acting user, reason, and optional `reason_canceled` comment), writes a "Project was canceled" note, cancels pending/active workflow milestones, and holds the project's tasks. Moving a project out of Cancelled clears the cancellation fields and reverses those effects. Changing `rep_primary_id` also fills the company's Direct Responsibility Role slot on the project team (the role the tenant may call 'Sales Rep', 'Primary Rep', etc.), refreshes the stored rep name, writes a project note and re-tests the workflow — exactly like assigning the rep in the web app's Project Team. Changing `account_id` refreshes the project's `account_name` from the new account, writes a project note, and rebuilds the project's search text. Changing the project's name, address or number also rebuilds its search text; other `update` fields trigger no workflow re-test or search reindex. A project always belongs to one company (`company_id`) and one account (the customer), and has at least one contact. Before calling this tool, discover valid ids with `project_create_options {company_id}` — it lists that company's active events, active lead sources, workflows, site types, and custom-field definitions, plus which fields the company requires. Call `project_create_options` with no arguments first if you don't know which company to use. **Account** — pass exactly one of: - `account_id` — an existing account's id (find one with `account_search`). - `new_account` — an object with the same fields as `account_write {action: create}` (`type`, `name`, `address_street`, `address_city`, `address_state`, `address_zip` required; `address_latitude`/`address_longitude`/`shipping_address_*`/`rep_id`/`notes` optional) to create the account inline as part of this call. Passing both, or neither, is rejected. **Contacts** — pass `contact_ids` (existing contacts, found with `contact_search`), `new_contacts` (an array of objects shaped like `contact_write {action: create}`: `first_name`/`last_name` required, `email`/`phone_cell`/`phone_home`/`phone_work`/`address_*`/`status` optional), or both combined. At least one contact (existing or new) is required in total. Every contact — existing or newly created — is linked to both the new project and its account. **Company-conditional fields** — whether `name` and `workflow_id` are required depends on that company's settings (`is_project_name_required`/`is_project_workflow_required`, both visible via `project_create_options`). `company_custom_fields` (an array of `{id, value}`) must include every one of the company's active *required* custom fields; the value's expected type (string/number/date/boolean/one of a fixed option list) depends on that field's `type`, also visible via `project_create_options`. **Trial accounts** have a project limit; when it is reached `create` fails with an error naming the limit. **Side effects of a successful create**: a system note is added to the project's activity log, the project's coordinates are geocoded from its address, the company's workflow team and milestones are imported onto the project, and a workflow test run is kicked off in the background — none of this needs to be triggered separately. Returns the project as `{ data: ... }` (created or updated), in the same shape `project_search`/`project_note_write` return. Sibling tools: `project_create_options` (discover valid ids before calling this), `account_search`/`contact_search` (find existing account/contact ids), `user_search` (resolve a user's name to the id `new_account.rep_id` takes), `project_search` (find a project's id before updating it, or inspect one after creation), `project_note_write` (log activity on it afterward).
project_write
Add a note to a project's activity log, or update an existing note's visibility/type. Set `action` to `create` or `update`; each is described below. Notes are how activity gets recorded on a project: log a call, record a decision, leave a status update for the team. - `action: create` — adds a new note to a project. Requires `project_id` and `body`. Creating a note automatically updates the project's `last_note_created_at` timestamp. The note is always recorded as written by the authenticated user (there is no way to post a note as an automated/system actor via this tool). - `action: update` — changes an existing note's `is_visible_on_customer_portal` and/or `type_id`. Requires `note_id` and `project_id` (the note's parent project). The note's `body` can NOT be changed once created — pass a new `body` and the call is rejected; if you need different text, create a new note instead. Setting `is_visible_on_customer_portal` to true makes the note visible to the customer in their portal; nothing is emailed or pushed to them. There is deliberately no delete action — notes are an append-only record of what happened on a project. Returns the curated note as `{ data: ... }`. Sibling tools: use `project_search` to find a project's id before adding a note to it, and `project_note_search` to find a `note_id` to update.
project_note_write
Create a saved report over one reportable entity, or edit an existing one — its metadata, its columns, or its filter conditions. Set `action` to `create`, `update`, `add_column`, `update_column`, `remove_column`, `add_filter_condition`, `update_filter_condition`, or `remove_filter_condition`; each is listed below. This tool never returns report data: build/edit here, then run the report with `report_run` (use its `aggregates` mode for totals/averages/counts). **Discover keys first.** Every `entity`, column key, and filter subject/field/comparison/value key this tool accepts comes from `report_build_options` — call it before guessing. The normal workflow is: `report_build_options` (entities → categories → columns → filter_subjects → filter_fields → filter_comparisons → filter_values) → `report_write {action: create}` with the full definition inline → `report_run` → refine with the diff-edit actions below. **Every report you create here is always private to you** — forced server-side, not a default you can override. `is_private`, `shared_with`, and `cards` are locked on every action: visibility and sharing are managed in the web app, where the owner can see who the audience actually is. Passing any of those three is an error, not a silent no-op. KPI cards are likewise derived automatically at creation from whatever aggregate columns the report is born with (they show up on `report_search` results) and are managed in the web app from then on. **Out-of-the-box reports cannot be edited here at all.** Every action except `create` refuses a report with a non-null `out_of_the_box_key` (visible on `report_search` results). To tailor one, duplicate it in the web app, or create a new report with the columns/filters you want. Actions: - `create` — requires `entity` and `report_category_id`. Optional `name` (defaults to "{Entity} Report" — pass a real one), `description`, `sort_key` + `sort_direction` (required together; `sort_key` must be a sortable column on the entity), `page_size` (1-1000). Optionally pass the WHOLE definition inline: `columns` as an ordered array of `{key, aggregates?}` (left-to-right display order, at most 100; `aggregates` is a subset of that column's `supported_aggregates`), and `filters` as an array of `{subject_key, field_key, comparison_key, value_key, value_data?, operator?}` (at most 50; two conditions may share the same four keys only if their `value_data` differs). When `columns` is omitted the entity's default column set is attached for you; when `columns` IS provided nothing is auto-attached, so list every column you want. An invalid column or filter spec rejects the whole call and creates nothing. - `update` — requires `id`. Metadata only: `name`, `description`, `report_category_id`, `sort_key`, `sort_direction`, `page_size`. Only the fields you pass are changed. A report's `entity` is immutable (it would orphan every column and filter) — create a new report instead. - `add_column` — requires `id` and `column_key` (`{entity}_{column}` format, from `report_build_options`). Optional `aggregates` and `position` (1-indexed; appended when omitted). - `update_column` — requires `id` and `column_id` (the column's UUID, from this tool's readback or `report_search` with `with_columns`). Pass `aggregates` (replaces the whole set; `[]` clears it) and/or `position`. A column's `key` cannot be changed — remove it and add the other one. - `remove_column` — requires `id` and `column_id`. If it was the report's `sort_key`, the sort is cleared automatically. - `add_filter_condition` — requires `id`, `subject_key`, `field_key`, `comparison_key`, `value_key`. `value_data` is the value payload as an array of strings, and its expected shape depends on the value type (`custom_date` takes one `["YYYY-MM-DD"]`, `custom_date_range` exactly two `["YYYY-MM-DD", "YYYY-MM-DD"]`, an `is_in`-style selection takes a list of ids/values, `this_month`-style rolling values take none — `report_build_options {level: filter_values}` documents each). `operator` (`AND` default, or `OR`) joins this condition to the previous one. For `is_empty`/`is_not_empty`, `value_key` is filled in for you. - `update_filter_condition` — requires `id` and `condition_id`. Any of `subject_key`/`field_key`/`comparison_key`/`value_key`/`operator` you omit keeps the condition's current value, so a one-field change is a one-field call. `value_data` follows the same rule with one caveat: it is only carried forward while `value_key` stays the same. Change `value_key` without supplying a `value_data` and the old payload is cleared rather than stranded on a value type it does not fit (`custom_date` → `today`), and passing `value_data: []` explicitly always clears it. - `remove_filter_condition` — requires `id` and `condition_id`. Every successful action returns the report's full state so you can verify it and target the next edit without a second read: `{ report: {id, entity, name, description, report_category_id, is_private, page_size, sort_key, sort_direction}, columns: [{id, key, position, name, description, is_sortable, supported_aggregates, reference, selected_aggregates}], conditions: [{id, position, operator, subject_key, field_key, comparison_key, value_key, value_data}] }`. (Naming note: create's `filters` input array and the `conditions` readback key describe the same records — `filters` on the way in, `conditions` with persistent `id`s on the way out; `report_search`'s `with_filters` uses the same `conditions` shape.) A column whose underlying definition was renamed or removed in a later release comes back as a short row — `id`, `key`, `position`, and `selected_aggregates` only, with no `name`/`supported_aggregates` — which means the report is showing a column that no longer exists; drop it with `remove_column`. Sibling tools: `report_build_options` (discover every key this tool takes), `report_search` (find an existing report's id), `report_run` (get its rows or aggregates), `report_delete` (clean up a scratch report you built just to answer one question — but consider offering to keep a report the user may want again).
report_write
Create a new task or update an existing one. Set `action` to `create` or `update`; each is described below. - `action: create` — creates a new task and assigns it. Requires `subject`, `due_at`, `assignee_type`, and `assignee_id`; all other fields are optional. Creating a task auto-generates an activity note on the task (and on its project, if attached), and — when `notifies_on_create` is true — sends the assignee a "new task assigned" notification. These are automatic side effects of the underlying model observer, not something you trigger separately. - `action: update` — partially updates an existing task. Requires `id`; only the fields you pass are changed. **To complete a task, use `action: update` with `is_complete: true` — there is no dedicated "complete" action.** Doing so automatically sets `completed_at`/`completed_by` and, when `notifies_on_complete` is true, notifies the task's creator. Any update also auto-generates an activity note describing what changed, and — for a task attached to a project — queues a re-evaluation of that project's workflow. Task writes are never silent field edits; expect these side effects. `assignee_type` is `user` or `team`; `assignee_id` must be an existing user or team (matching `assignee_type`) in the same tenant. `project_id`, `project_milestone_id`, and `project_milestone_task_id` (if passed) must also exist in the same tenant. **Resolving `assignee_id` from a name:** an end user will say "assign it to Mike Kampa" or "assign it to the install crew", not give you an id. For `assignee_type: user`, call `user_search` with `filter.search` (add `filter.employed: true` so a departed employee can't win the match). For `assignee_type: team`, call `team_search` with `filter.search` (add `filter.is_active: true` so a disbanded team can't win the match). Use the returned `id`. Never ask the end user for an internal numeric id. If more than one person or team plausibly matches, ask which one they meant rather than guessing. There is no delete action on this tool — task deletion is a hard delete with cascading side effects (it removes the task's notes and logs a project note) and is deliberately not exposed to agents. Returns the curated task as `{ data: ... }`. Sibling tool: use `task_search` to find an existing task's id before updating it (pass `filter.id` to fetch one by id — there is no separate "get" tool).
task_write
Create a new contact, update an existing one, or link an existing contact to an account, project, or user. Set `action` to `create`, `update`, or `link`; each is described below. - `action: create` — creates a new contact. Requires `first_name` and `last_name`; all other fields are optional. - `action: update` — partially updates an existing contact. Requires `id`; only the fields you pass are changed. - `action: link` — attaches an existing contact to an existing account, project, or user, forming a relationship such as "this person is the point of contact for this account". Requires `contact_id`, `model_type` (`accounts`, `projects`, or `users`), and `model_id`. A contact can be linked to multiple entities, and an entity can have multiple linked contacts. `position` controls ordering among an entity's linked contacts (1-indexed; defaults to the end of the list for a new link). Linking a pair that's already linked is idempotent: called again with no `position`, it simply returns the existing linked-contact record unchanged; called again with an explicit `position`, it moves the existing link to that position instead. Returns the curated contact (`create`/`update`) or linked-contact record (`link`) as `{ data: ... }`. Sibling tool: use `contact_search` to find an existing contact's id before updating or linking it (pass `filter.id` to fetch one by id — there is no separate "get" tool).
contact_write
Delete an invoice, credit memo, or payment — pick which with `entity`. Each one soft-deletes: the record is flagged deleted rather than physically removed, and it is recoverable only by an administrator, never by a tool on this server. `entity: invoice` also soft-deletes the invoice's own lines. Deletion is blocked while a non-deleted payment or a non-deleted credit memo is still applied to it — the error lists every blocking reason found at once, not just the first; unapply or delete those first, then retry. `entity: credit_memo` also soft-deletes the credit memo's own lines and permanently removes its invoice application records — nothing blocks a credit memo delete, but it additionally requires the delete-credit-memos permission. `entity: payment` also soft-deletes the payment's own applied lines and un-links (without deleting) any credit memo that was refunded through it — nothing blocks a payment delete either. Every deletion additionally requires project finances to be visible to the caller. On success, the affected project's financials and payouts are recomputed and a note is added to its activity log (a payment's note is added to the account instead, since a payment carries no project of its own). This tool stays registered while ANY of invoice, credit memo, or payment writes are enabled on this server, so each entity's own deletion additionally requires THAT entity's writes to be enabled here — deleting an invoice while invoice writes are off fails with "Invoice writes are not enabled on this server.", even while credit memo or payment writes remain on, and likewise for the other two entities. Find ids with `billing_search`.
billing_delete
Permanently delete a contract. This is a hard delete and cannot be undone. Deletion is blocked while the contract still has any of the following attached: invoices, payment lines, payouts, expenses, work orders, material orders, permits, or vendor services. When blocked, the error lists every blocking reason found at once, not just the first — remove or reassign those first, then retry. On a successful delete, the removal is logged, a project note is added, the project's contract dates are refreshed, its financials are recomputed to reflect the contract's removal, and its workflow is re-tested in the background. Find a contract's id with `contract_search` first.
contract_delete
Delete an estimate. Nothing blocks this — an estimate has no deletion guard, so it always succeeds for an estimate you can reach. This is a soft delete: the estimate is flagged deleted rather than physically removed, and its line items, comments, and financial items are left untouched behind it. There is no restore action on this server, and a deleted estimate can no longer be found by `estimate_search` or changed by `estimate_write`, so treat it as permanent. On a successful delete, an "Estimate ... was deleted." note is added to the project's activity log, the project's estimate totals are rolled up, and the revenue of any proposal referencing the estimate is recomputed without it. Unlike a contract delete, no workflow re-test is triggered. Find an estimate's id with `estimate_search` first. To remove a single line from an estimate rather than the whole estimate, use `estimate_write` with `action: remove_line_item`.
estimate_delete
Permanently delete a material order. This is a hard delete and cannot be undone. Deletion is blocked while the material order still has a supplier assigned. Unassign the supplier first with `material_order_write` (`action: update`, `supplier_id: null` — this also recomputes the work order's cost totals and the project's estimated expenses), then retry. On a successful delete, the order's line items and any attached supplier-level bill expenses (and those expenses' local QuickBooks link records) are removed first (each removed expense adds a "was DELETED" note to its bill and the project's activity log, the bills' balances and the contracts' expense totals are recalculated, and payouts are recalculated unless the contract's payouts are locked, and the recalculation can re-test the project's workflow in the background), the parent work order's labor item quantities are recomputed to reflect the removed order's items, and a "was deleted" note naming the order's PO# is added to the project's activity log. Find a material order's id with `material_order_search` first.
material_order_delete
Permanently delete a report you created — the cleanup step of the scratch-report workflow: when a data question can't be answered by an entity's `_search` tool, build a private one-off report (`report_build_options` to discover options, `report_write action:create` to build it), run it with `report_run` to get the answer, then delete it here once you're done. This cannot be undone. Deletion is a choice, not an obligation — if the report might be useful again (a recurring question, something the user may want to revisit or refine), leave it in place, or ask the user whether they'd like to keep it, instead of deleting automatically. Eligibility is strict: you may only delete private, unshared reports you created — not one of the tenant's out-of-the-box reports, not a tenant-public report, and not a private report you've shared with specific users/teams (someone else may be relying on it). A report that fails any of those checks — including one that simply does not exist, one owned by someone else, a tenant-public report, a report you've shared, or your own out-of-the-box report — all read back as the exact same "does not exist" error, so this tool can never be used to confirm whether some other report exists. Find a report's id with `report_search` first.
report_delete
Permanently delete a work order. This is a hard delete and cannot be undone. Deletion is only allowed while the work order's status is Draft — any other status blocks the delete with an error naming the reason. On a successful delete, the work order's custom field values, comments, labor items, material order line items, its Material Orders (regardless of their own state), their installer- and supplier-level bill expenses (along with those expenses' local QuickBooks link records; each removed expense adds a "was DELETED" note to its bill and the project's activity log, the bills' balances and the contracts' expense totals are recalculated, and payouts are recalculated unless the contract's payouts are locked, and the recalculation can re-test the project's workflow in the background), and this server's own status-history records are all removed in the same transaction as the work order itself. Find a work order's id with `work_order_search` first.
work_order_delete
Call this before `contract_write`, `estimate_write`, `work_order_write`, `material_order_write`, `invoice_write`, `credit_memo_write`, or `payment_write` to discover the valid ids their lookup fields accept — pick which with `entity`. Every returned id is guaranteed to pass that write tool's own validation for that field. - `entity: contract` — `contract_type_id` (flagged `requires_insurance_jobs`; types 1/3 are omitted when a resolved company has insurance jobs disabled, all 4 returned otherwise), `financial_class_id` (company-scoped). - `entity: estimate` — `trade_id`, `estimate_type_id`, `event_trade_parameter_id`, `event_tax_item_id`, `estimate_category_id` (company-scoped). Materials are not listed (the catalog is too large) — pass `material_search` (partial code/name match, up to 25 results) to look one up as `material_id`, or pass a known `material_id` to get that material's own `material_color_id`/`material_size_id` options. - `entity: work_order` — `trade_id`, `work_order_type_id`, `work_order_status_id` (statuses 8/9/10 are omitted: they are derived from the work order's progress and can never be set), `crew_id`. For labor items (`add_labor_item`/`update_labor_item`), look up materials exactly as for `estimate`: `material_search` returns `material_id` matches (with their `unit`), and a known `material_id` returns its `material_color_id`/`material_size_id` options. - `entity: material_order` — `trade_id`, `type_id`, `supplier_id` (tenant-scoped, active only), `delivery_time_id`/`delivery_place_id` (global lookups, not tenant-scoped). For line items (`add_line_item`/`update_line_item`), look up materials exactly as for `estimate`: `material_search` returns `material_id` matches (with their `unit`), and a known `material_id` returns its `material_color_id`/`material_size_id` options. - `entity: invoice` — `tenant_term_id`, `financial_class_id` (company-scoped), `invoice_item_id` (company-scoped), `contract_invoice_status_id`, `event_tax_item_id` (company-scoped, active tax codes; `rate` is a fraction, so 0.0825 = 8.25%). `invoice_write` also accepts `0` for no tax. - `entity: credit_memo` — `financial_class_id` (company-scoped), `invoice_item_id` (company-scoped), `contract_invoice_status_id`. - `entity: payment` — `contract_payment_method_id`, `contract_payment_status_id` (flagged `counts_as_paid` for the statuses that count toward an invoice's paid amount), `contract_payment_type_id`, `financial_account_id` (company-scoped), `mortgage_company_id`. `trade_id` returns YOUR tenant's own configured trades, not the full global trade catalog — small and relevant, and every id it returns is a valid `trade_id`. A company-scoped field (see above) is only included when a company is resolved: pass `project_id` (any project you can access — its tenant/company supply every company-scoped list) or `company_id` (must be a company you belong to; list yours with `project_create_options`, no arguments). `project_id` wins when both are given. Without either, company-scoped fields are omitted with a note instead of erroring. For `rep_id`, `contact_id`, or `account_id` on any of these write tools, use `user_search`/`contact_search`/`account_search` instead — this tool only covers lookup tables those don't already resolve. Returns `{ entity, company_id, fields: { <field name>: [...] }, notes: {...} }` — `fields` keys are the exact argument names the write tools accept.
financial_write_options
Call this before `project_write {action: create}` to discover the valid ids and requirements for creating a project, before `appointment_write {action: create}` to find a `company_appointment_type_id`, or before `project_write {action: update}` cancels one, to discover a valid `cancellation_id`. Drill down in two steps: - No parameters: lists the companies you belong to (id, name), plus each company's project-creation defaults (`default_site_type_id`, `default_lead_id`, `default_event_id`, `default_workflow_id`) and requirement flags (`is_project_name_required`, `is_project_workflow_required`). Also returns `cancel_reasons` (id, reason) — the global list `cancellation_id` accepts, not company-scoped, so no `company_id` is needed to get it. Pick a company id and pass it as `company_id` next if you're creating a project. - `company_id`: returns that company's active events, active lead sources, workflows, the global list of site types, and active custom-field definitions (id, name, type, options, is_required) — the exact option sets `project_write`'s `event_id`/`lead_id`/`workflow_id`/`site_type_id`/`company_custom_fields[].id` accept. Also returns `appointment_types` (id, name, duration in minutes, is_default): the appointment types the web app offers for that company (the tenant's shared types plus the company's own), which are the ids `appointment_write`'s `company_appointment_type_id` accepts. Also echoes the company's defaults, requirement flags, and `cancel_reasons` again for convenience. For account/contact ids, use `account_search`/`contact_search` instead, and for user ids (e.g. `new_account.rep_id`) use `user_search` — this tool only covers the company-scoped and global reference data `project_write` needs. Returns small, unpaginated option lists (never more than a company's own configured lists) as `{ level, data, cancel_reasons }` (and `company_id` when drilled into a company).
project_create_options
Fetch the full plain-text content of one help article by its number. Find the number with `help_article_search` first — there is no lookup by name here. When you use this article's content to answer the user, cite the returned article `url` so they can open the full article (with any screenshots) themselves — this tool's `text` is plain text only, so step-by-step screenshots and other images referenced in the article are not included and some UI click-path detail may be missing.
help_article_get
Discover the building blocks needed to author or edit a custom report: reportable entities, their columns, the tenant's report categories, and the full subject -> field -> comparison -> value filter-condition hierarchy. This is a stateless, read-only drill-down tool — no report has to exist yet. Call it once per `level` as you assemble a definition, then hand the discovered keys straight to `report_write`. Levels (pass one via `level`): - `entities` — every reportable entity: `{key, name, description}`. Pick one as `entity` for every other level. - `columns` — requires `entity`. Every column available on it: `{key, name, description, is_sortable, supported_aggregates, reference}`. Column keys feed `report_write action:create`'s inline `columns` array (`{key, aggregates?}`) directly, and the same key feeds `report_write action:add_column`'s `column_key` to attach a column to an existing report. Some entities expose dozens of columns, so this is paginated (default 50/page, max 100) via `page.size`/`page.number`. - `categories` — the tenant's report categories (the 5 shared system categories plus this tenant's own custom ones): `{id, name, description, is_system}`. `report_write action:create` REQUIRES a `report_category_id` with no default, so call this level first to find a valid one. - `filter_subjects` — requires `entity`. The filter subjects compatible with that entity — the top of the 4-level condition hierarchy. - `filter_fields` — requires `entity` + `subject_key`. That subject's fields. - `filter_comparisons` — requires `entity` + `subject_key` + `field_key`. That field's comparisons (e.g. `is`, `is_not`, `is_in`, `between`, `is_empty`) — each flags `requires_value` (false only for the valueless `is_empty`/`is_not_empty` pair). - `filter_values` — requires `entity` + `subject_key` + `field_key` + `comparison_key`. The value type(s) available, each carrying `value_data_rules` (the exact Laravel validation rules `report_write` enforces on `value_data`) and, for a small enumerated set, `allowed_values` to pick from directly. An entry here is sometimes a complete selectable value in itself and sometimes a value-TYPE wrapper — its `value_data_rules` tell you which: empty rules mean the entry's key alone (as `value_key`) is the whole selection, while rules mean the key picks the type and the actual payload goes in `value_data`. Date-like fields also expose ROLLING value types (`today`, `this_week`, `this_month`, `this_quarter`, `this_year`, ...) that take NO `value_data` and automatically track the current period — ideal for recurring reports, so a "this month" report never needs manual date edits. Rolling values live under the `is` comparison, NOT `is_between` (which only offers fixed `custom_date_range` payloads) — check `is` before concluding a field only supports fixed dates. A value type that instead resolves against a large, searchable reference table (users, teams, contacts, vendors, ...) skips a static option list and instead carries a `note` telling you to resolve the specific record's id first with the matching lookup tool (`user_search`, `team_search`, `contact_search`, `account_search`, `project_search`, etc. — whichever matches what the field represents) and pass the resolved id(s) as `value_data`. Every response echoes `level` plus whichever of `entity`/`subject_key`/`field_key`/`comparison_key` you supplied, alongside `data`/`meta` (the same slim `{total, per_page, current_page, last_page}` shape every list tool here uses) — never a raw paginator envelope. An unknown `entity`/`subject_key`/`field_key`/`comparison_key` returns a clean error naming the valid options instead of a stack trace. Workflow: discover entities/columns/categories/filter options here -> build the report in one call with `report_write action:create` (pass the full definition inline: `columns`, `filters`, `report_category_id`) -> iterate with further `report_write` calls (`add_column`/`update_column`/`remove_column`/`add_filter_condition`/`update_filter_condition`/`remove_filter_condition`) -> execute it with `report_run` (rows or aggregates) -> delete a throwaway/scratch report afterward with `report_delete`, or keep it if the user wants to reuse it.
report_build_options
Execute a SAVED report exactly as it's configured — its persisted columns and filter conditions are applied as-is; only pagination and sort can be overridden per call. There is no way to run an ad-hoc/unsaved report through this tool. Find a report's id (and, optionally, its column shape) with `report_search` first. `mode: rows` (default) returns a page of formatted rows, each keyed by the report's column keys (see `report_search` with `with_columns=true` to preview those keys/names beforehand). **Row responses do not include a total row count** — `meta` is `{ current_page, per_page, from, to, has_more }`, deliberately without `total`/`last_page` (the underlying query uses simple/cursor-style pagination for performance, not a count query). Call `mode: aggregates` to get the total row count plus any configured column aggregates (sum/avg/min/max/count) — call it once up front and again only when you need an updated total, not on every page. When the user wants a total, average, count, minimum, or maximum ("what's our total sold amount", "how many projects", "average job size") rather than individual records, prefer `mode: aggregates` over paging through `mode: rows` and summing values yourself — it runs one query over the report's entire filtered result set (every saved filter condition applied, not just the current page) and returns everything in a single call: `{ total: <matching row count>, aggregates: { <column_key>: { <aggregate>: <value>, ... }, ... } }`. A column only appears under `aggregates` if it already has that aggregate selected in the report's own configuration (see `report_search` with `with_columns=true`'s `selected_aggregates`) — if the metric you need isn't there yet, add it to the column with `report_write`'s `update_column`/`add_column` action rather than falling back to paging rows and summing them client-side. `page_size` is optional and only used in `mode: rows`; when omitted, the report's own saved page size applies (commonly 10). When provided it's clamped to at most 50. `sort_key`/`sort_direction` (rows mode only) override the report's saved sort for this call — `sort_key` must reference a sortable column on the report's entity, and the two must be passed together. Rate-limited per tenant, shared in spirit with the web app's own report-running budget (default 30 runs/minute across the whole tenant, not per user) — a busy tenant can exhaust this from either surface.
report_run
Search and list appointments (scheduled visits/meetings, optionally tied to a project) for the authenticated user's tenant. **Key example — "are there any appointments for me today?"**: pass `filter.related_to: "me"` plus `filter.starts_after`/`filter.starts_before` both set to today's date, e.g. `{ "related_to": "me", "starts_after": "2026-07-23", "starts_before": "2026-07-23" }`. A bare date is treated as the start/end of that day, so this combination means "today". Use this to find an existing appointment before updating it, or to fetch a single one by id (pass `filter.id` — there is no separate "get appointment" tool). Results are paginated; prefer narrowing with `filter` over paging through the entire list. Key parameters: `filter.related_to` accepts either a numeric user id or the literal string `"me"` — matches an appointment where that user is one of the (up to four) attendees, directly analogous to `task_search`'s `assigned_to`. `filter.project_id`, `filter.company_appointment_type_id`, `filter.appointment_result_id` are exact matches. `filter.slot_type` is `confirmed` (a real, scheduled appointment) or `placeholder` (a tentative hold with no attendees/type required yet). `filter.starts_after`/`filter.starts_before` narrow by start time — each accepts a bare date (`2026-07-23`) or a full datetime (`2026-07-23 15:00:00`); combine both for a range. `filter.search` is a full-text search across the title, description, location, creator name, and attendee list. `filter.id` fetches one exact appointment. `sort` accepts one of `starts_at`, `ends_at`, `created_at`, `updated_at`, optionally prefixed with `-` for descending (e.g. `-starts_at`). **When `sort` is omitted, results default to `starts_at` ascending (soonest first)** — `AppointmentQuery` itself has no built-in default order, so this tool applies the agent-correct one. `include` eager-loads related objects onto each result — a comma-separated combination of `project`, `type`, `company_type`, `result`, `category`, `creator` (e.g. `project,result`). Attendees are handled specially, NOT via `include`: a `filter.id` fetch always inlines the full attendee roster as `attendees: [{id, name, email, model_type, model_id, is_optional, response}]`; every other (list) result omits attendees entirely to keep the response small — fetch a specific appointment by id to see its roster. Returns `{ data: Appointment[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: use `appointment_write` (action `create`/`update`) to schedule a new appointment or update an existing one.
appointment_search
Search and list accounts-receivable billing records for the authenticated user's tenant, across six related entities selected via the required `entity` argument. Soft-deleted records are never returned, regardless of entity. - **`invoice`** — a billed document on a project's contract (number, PO, dates, status, financial figures). Filters: `id`, `project_id`, `contract_id`, `tenant_term_id`, `financial_class_id`, `rep_id`, `contact_id`. Includes: `project`, `contract`, `term`, `rep`, `contact`, `financial_class`. Sorts: `number`, `updated_at` (default `-updated_at`). **Requires at least one of `filter.id`, `filter.project_id`, or `filter.contract_id`** — those are the anchors this tool accepts; every other filter only narrows within them. - **`invoice_line`** — a single line item on an invoice (quantity, rate, amount, tax, status). Filters: `id`, `invoice_id`, `project_id`, `contract_id`. Includes: `company`, `project`, `invoice`, `invoice_item`, `contract_invoice_status`, `rep`. Sorts: `position`, `updated_at` (default: line position ascending). **Requires at least one of `filter.id`, `filter.invoice_id`, or `filter.project_id`.** Invoice lines and credit memo lines are stored in the same underlying table but NEVER mix — this entity only ever returns invoice-typed lines, even if an id collides with a credit memo line's own id. - **`credit_memo`** — a credit issued against a project's contract, optionally tied to an invoice or account (number, PO, total, remaining balance). Filters: `id`, `company_id`, `account_id`, `project_id`, `contract_id`, `invoice_id`, `rep_id`. Includes: `company`, `account`, `project`, `contract`, `invoice`, `rep`, `financial_class`. Sorts: `number`, `updated_at` (default `-updated_at`; note `created_at` on this entity really means the credit memo's own date, not a row-creation timestamp). **Requires at least one of `filter.id`, `filter.project_id`, `filter.contract_id`, `filter.account_id`, or `filter.invoice_id`** (a wider anchor set than `invoice`'s, since this table is small). - **`credit_memo_line`** — a single line item on a credit memo. Filters: `id`, `credit_memo_id`, `project_id`, `contract_id`. Includes: `company`, `project`, `credit_memo`, `invoice_item`, `contract_invoice_status`, `rep`. Sorts: `position`, `updated_at` (default: line position ascending). **Requires at least one of `filter.id`, `filter.credit_memo_id`, or `filter.project_id`.** Same shared-table split as `invoice_line`, inverted — only ever returns credit-memo-typed lines. - **`payment`** — a top-level payment or refund record, NOT nested under a project (a payment's project context, if any, comes only from its applied lines). Filters: `id`, `company_id`, `account_id`, `type` (`1` = payment, `-1` = refund), `contract_payment_status_id`. Includes: `company`, `account`, `creator`, `financial_class`, `contract_payment_method`, `contract_payment_status`, `financial_account`, `mortgage_company` (the last four resolve the payment's own bare lookup-table ids — e.g. `contract_payment_method_id` — into their names). Sorts: `created_at`, `updated_at` (default `-updated_at`). **Requires at least one of `filter.id`, `filter.account_id`, or `filter.company_id`** — `company_id` is the natural anchor for "this company's recent payments"; `type`/`contract_payment_status_id` only narrow within one of those. - **`payment_line`** — a single applied line on a payment, INCLUDING refund applications (the `type` field on each result tells you which). Visibility follows the line's own project, independent of whether the caller can see the parent payment — so a `payment` include can resolve to `null` even when the line itself is visible. Filters: `id`, `payment_id`, `project_id`, `contract_id`, `invoice_id`, `account_id`, `contract_payment_type_id`. Includes: `account`, `payment`, `project`, `contract`, `invoice`, `contract_payment_type`. **Does not support `sort` at all** — results come back ordered by internal id, stably but arbitrarily. **Requires at least one of `filter.id`, `filter.payment_id`, `filter.project_id`, or `filter.invoice_id`.** Money-valued fields (the `financials_*`/`amount`/`total_amount`/etc. groups, depending on entity) — including `description` (it embeds totals) on `invoice`/`credit_memo`/`payment`, and `status` (paid state) on `invoice`/`payment` (`payment` also hides `contract_payment_status_id` and the `contract_payment_status` include) — are silently omitted, per row, for a caller whose permissions hide project finances — exactly like the REST API; a hidden field is never an error. Returns `{ data: [...], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) across all six entities. Sibling tools: `invoice_write`, `credit_memo_write`, `payment_write` and `billing_delete` are available when invoice, credit memo, or payment writes are enabled on this server (each entity needs its own flag).
billing_search
Search and list contacts (people associated with accounts, projects, or users — e.g. a homeowner, a property manager, a vendor's point of contact) for the authenticated user's tenant. Use this to find an existing contact before creating a new one, to look up a contact by name/email, or to fetch a single contact by id (pass `filter.id` — there is no separate "get contact" tool). Results are paginated; prefer narrowing with `filter` over paging through the entire list. Key parameters: `filter.search` is typo-tolerant and relevance-ranked across last/first name, street address/zip, email, and phone (home/cell/work) when the search service is active; otherwise it falls back to a plain substring match on first name, last name, and email only. `filter.first_name`/`filter.last_name` do partial (substring) matches; `filter.email` is an EXACT match against the contact's primary or alternate email address (not a partial match — use `search` for that); `filter.phone` is an EXACT match against any of the contact's phone numbers (home, work, cell, fax) and accepts any format — `+13334445555`, `(333) 444-5555`, `333.444.5555`, and `3334445555` all match the same contact — making it the reliable way to check whether a contact with a given number already exists; `filter.status` and `filter.has_email` are exact boolean matches; `filter.id` fetches a specific contact. `sort` accepts one of the listed fields, optionally prefixed with `-` for descending (e.g. `-created_at`). `include=owner` eager-loads the contact's owning user. Returns `{ data: Contact[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Sibling tools: use `contact_write` (action `create`/`update`/`link`) to create or update a contact, or to link an existing contact to an account/project/user.
contact_search
Search and list contracts (the sold job's financial document on a project — contract type, name, sold/financial figures, approval state, payout lock, rep, and financial class, optionally tied to an insurance claim) for the authenticated user's tenant. REST has no tenant-wide contract list — contracts nest under `projects/{project}/contracts` — so this tool exists to make a tenant-wide search possible at all, subject to the required-filter rule below. **At least one of `filter.id`, `filter.project_id`, or `filter.claim_id` is required** — a tenant-wide scan across every contract is not supported. Use `filter.project_id` for "contracts on this project", `filter.claim_id` for "contracts tied to this insurance claim", or `filter.id` to fetch one exact contract (there is no separate "get" tool). `filter.company_id`, `filter.contract_type_id`, `filter.rep_id`, `filter.financial_class_id` narrow further. `include` eager-loads `company`, `project`, `claim`, `rep`, `contract_type`, and/or `financial_class` (comma-separated) — include `claim` for insurance context (policy number, claim number, date of loss, deductible). There is no `sort` parameter — `ContractQuery` defines no sortable fields, so results come back in whatever order the database returns them, exactly like the REST endpoint. Because nothing orders the query, row order is not guaranteed to stay stable across pages; prefer narrowing with filters over paging when you need a complete set. `is_approved`/`approved_at` report the contract's approval state, and `is_payouts_locked`/`payouts_locked_at` its payout-lock state. Financial figures (the `financials_*`/`expenses_*` groups, `payouts_amount`, `overhead_amount`) are hidden per-field based on the caller's permissions, exactly like the REST API — a hidden field is silently omitted, never an error. Returns `{ data: Contract[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Sibling tools: `contract_write` (create/update via an `action` enum) and `contract_delete` are available when contract writes are enabled on this server.
contract_search
Search and list customer accounts (a person or business Contractors Cloud does work for) for the authenticated user's tenant. Use this to find an existing account before creating a new one, to look up an account by name, or to fetch a single account by id (pass `filter.id` — there is no separate "get account" tool). Results are paginated; prefer narrowing with `filter` over paging through the entire list. Key parameters: `filter.search` does a multi-word substring match (not typo-tolerant — this entity has no relevance-ranked search service) against the account's name, address, zip, and the names, phone numbers and emails of its contacts; periods are ignored, and phone numbers match formatted or digits-only. Coverage of zip, emails and secondary/tertiary contacts may lag for accounts last saved in the web app. For an exact phone lookup use `filter.phone` instead. `filter.name` does a partial (substring) match against the account name specifically; `filter.email` is an EXACT match against the account's primary, secondary, or tertiary email address; `filter.phone` is an EXACT match against any of the account's phone numbers (home/work/cell/fax across the primary/secondary/tertiary contact slots) and accepts any format — `+13334445555`, `(333) 444-5555`, `333.444.5555`, and `3334445555` all match the same account — making it the reliable way to check whether an account with a given number already exists; `filter.id`, `filter.rep_id`, and `filter.type` (`0` = person, `1` = business) are exact matches. `sort` accepts one of the listed fields, optionally prefixed with `-` for descending (e.g. `-created_at`); results default to newest first. `include` eager-loads `rep` and/or `creator` (comma-separated for both); requested includes are returned in both slim and detailed modes. By default (`detailed=false`) each result is a slim projection — id, type, name, address, rep_id, and the primary contact's name/phone/email — because the full account resource carries ~40+ fields including three full contact triads (primary/secondary/tertiary) that are rarely needed for a list. Pass `detailed=true` to get every field. Returns `{ data: Account[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Sibling tool: use `account_write` (action `create`/`update`) to create or update an account.
account_search
Search and list estimates (a priced scope of work on a project — materials, labor, and markup — often tied to an insurance claim) for the authenticated user's tenant. This is the read side for supplement/insurance-estimate analysis: comparing an estimate's totals against a claim's policy/deductible, or reviewing a project's estimate history. **At least one of `filter.id`, `filter.project_id`, or `filter.claim_id` is required** — a tenant-wide scan across every estimate is not supported. Use `filter.project_id` for "estimates on this project", `filter.claim_id` for "estimates tied to this insurance claim", or `filter.id` to fetch one exact estimate (there is no separate "get" tool). `filter.trade_id`, `filter.estimate_category_id`, `filter.is_active`, `filter.created_by` narrow further. `sort` accepts `created_at`/`updated_at`, optionally prefixed with `-` for descending; omitted, results default to newest-first (`EstimateQuery::defaultSorts()`). `include` eager-loads `project`, `trade`, `estimate_type`, `category`, `claim`, and/or `creator` (comma-separated) — include `claim` for insurance context (policy number, claim number, date of loss, deductible). Pass `with_line_items=true` (REQUIRES `filter.id`) to inline that one estimate's line items under a `line_items` key — `{id, position, name, description, quantity, unit, base_cost, labor_cost, percentage_markup, total_cost, material_class_code}` each, in position order (`percentage_markup` is omitted for users whose role hides project finances). **`material_class_code` is `0` for a material line and `1` for a labor line.** On a component-priced estimate (`labor_mode` 2 with `is_priced_from_assembly_components` on) `base_cost` and `total_cost` are derived from the line's assembly components. Capped at 250 line items; `meta.line_items_truncated` is `true` when an estimate has more than that. Returns `{ data: Estimate[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tools: `estimate_write` (create/update via an `action` enum) and `estimate_delete` are available when estimate writes are enabled on this server.
estimate_search
Search Contractors Cloud's official help documentation/knowledge base. Use when the user asks how to do something in Contractors Cloud or how a feature works. Returns candidate articles (title, preview, category, article number) — never full article content. Follow up with `help_article_get` on the most relevant number(s) for full content before answering the user. Results are capped at 10 per page — refine the query rather than paging deeply.
help_article_search
Search and list mail (email) in an inbox. Every user and every project has its own inbox with its own email address — mail sent to a project's address (or forwarded there) shows up here, and — by default — any incoming attachments are automatically saved into that project's "File Cabinet" (see `project_file_search`/`project_file_write` to browse or re-upload those files; a saved attachment's `url` from this tool's `filter.id` mode is directly downloadable if you need to re-fetch or re-route it yourself). Choose exactly one inbox to search: pass `filter.project_id` to search a project's inbox, `filter.inbox_id` to search a specific inbox by id, or pass neither to search your OWN inbox (the default). Access is intentionally narrower than the REST API: you may only search your own inbox, or the inbox of a project you can access — never another user's inbox or a calendar's inbox. An `inbox_id` naming anything else fails with the same "does not exist" error as a made-up id, so it can't be used to discover what other mailboxes exist. `filter.id` fetches one exact mail message and returns its FULL body plus its attachments (`{id, name, ext, size, url}` each) — use this before acting on a specific message. Every other call returns list mode: each result is a short preview (`body_preview`, the first ~300 characters) plus an `attachments_count` — NOT the full body/attachment list — to keep the response small. `filter.unread` (boolean), `filter.type` (`incoming`/`outgoing`), `filter.search` (full-text) and `filter.received_after`/`filter.received_before` (a bare date or full datetime, combinable into a range — same UX as `task_search`'s `due_before`/`due_after`) narrow the list. Archived mail is excluded unless you fetch it by `filter.id`. Returns `{ data: InboxMail[], meta: { total, per_page, current_page, last_page, inbox } }` — never the raw Laravel paginator envelope. `meta.inbox` is `{id, email_address}` for the inbox that was searched: `email_address` is the inbox's own address — the one to hand out when someone needs to send or forward mail INTO this inbox (e.g. a project's intake address) — and `id` can be passed back as `filter.inbox_id` on later calls. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database and search index from a runaway agent loop.
inbox_mail_search
Search and list Jet Streams (directed, notifying message threads — see `jet_stream_write`'s description for what makes them different from a plain project note) for the authenticated user's tenant. Use this to find an existing jet stream before replying to it (`jet_stream_write`, action `reply`), or to fetch a single one by id (pass `filter.id` — there is no separate "get" tool). Results are paginated; prefer narrowing with `filter` over paging through the entire list. `filter.scope` controls WHO the results include, and defaults to `mine` when omitted: `mine` matches streams the authenticated user created or is a recipient of — the "My Jet Streams" view. `created` narrows to just the ones they started. `tenant` widens to every jet stream in the tenant regardless of participation — this is policy-allowed (view access is tenant-wide, not participant-restricted), but a much broader net than the default, so use it only for a deliberate tenant-wide search; combined with `filter.search` it is measurably expensive on very large tenants (~2s measured at 182k streams), so use that combination deliberately rather than as a default habit. `filter.search` is a substring (not fuzzy) match against the stream's title AND its AI-generated topic summary — the AI topic is generated asynchronously and may still be blank on a freshly created stream. `filter.unread` narrows to streams the user has not viewed since their last activity. `filter.project_id` is an exact match. When `sort` is omitted, results default to `-updated_at` (most recently active tenant/thread first — a reply bumps a stream's `updated_at`, so this closely approximates most-recent-activity order at a fraction of the cost of the alternative). `sort=latest_reply`/`-latest_reply` is also available for reply-precise ordering, but it is a correlated subquery and measurably expensive on large tenants (measured ~11x slower than the default on a 182k-stream tenant) — prefer the default unless you specifically need reply-exact ordering. `include` eager-loads related objects onto each result — a comma-separated combination of `from`, `latest_reply`, `task`, `project`. A `filter.id` fetch additionally inlines the full participant roster as `participants: [{id, user_id, name, email, type}]` (`type` is `c` for the creator, `r` for a recipient) — every other (list) result omits it, carrying only the always-present `user_count`/`reply_count` totals instead. Returns `{ data: JetStream[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: use `jet_stream_write` (action `create`/`reply`) to start a new jet stream or reply to one found here.
jet_stream_search
Search and list material orders (an order for materials placed with a supplier, tied to a project and optionally a work order) for the authenticated user's tenant. **Key example — matching a supplier invoice**: a supplier's invoice usually carries their own PO/reference number and the supplier's identity, not a Contractors Cloud project id. Pass `filter.reference_number` (an exact match against the order's PO number) combined with `filter.supplier_id` to find the specific material order an invoice belongs to, then compare its `estimate_cost_amount` against the invoice's actual cost. `estimate_cost_amount` is the PRE-TAX sum of each line's quantity × cost — a supplier invoice usually includes tax, so expect the tax amount itself to show up as variance. Use `filter.id` to fetch one exact material order (there is no separate "get" tool) — no filter is otherwise required, since `filter.reference_number`/`filter.supplier_id` searches are inherently cross-project. `filter.project_id`, `filter.work_order_id`, `filter.contract_id`, `filter.status_id`, `filter.type_id` are exact matches. `filter.delivery_after`/`filter.delivery_before` narrow by delivery date at DAY GRANULARITY ONLY — pass a bare date (`2026-07-10`); if you pass a full datetime, only its date part is used and the time is silently ignored. Combine both for a range. `sort` accepts `submitted_at`/`created_at`, optionally prefixed with `-` for descending (e.g. `-created_at`); omitted, results default to newest-created-first (`MaterialOrderQuery::defaultSorts()`). `include` eager-loads `project`, `trade`, `contract`, `status`, `supplier`, `type`, `work_order`, `delivery_time`, and/or `delivery_place` (comma-separated). Pass `with_line_items=true` (REQUIRES `filter.id`) to inline that one order's line items under a `line_items` key — `{id, position, material_id, name, material_color_id, color, material_size_id, size, quantity, unit, cost_amount, total_amount}` each, in position order (`cost_amount` and `total_amount` are omitted for users whose role hides project finances). Capped at 250 line items; `meta.line_items_truncated` is `true` when an order has more than that. Returns `{ data: MaterialOrder[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tools: `material_order_write` (create/update via an `action` enum) and `material_order_delete` are available when material order writes are enabled on this server.
material_order_search
Search and list a single project's "File Cabinet" — the files and photos attached to a project. Requires `filter.project_id`; there is no tenant-wide file search (use `project_search` first to find the project's id). To count how many photos or files a project has ("how many photos are on this project?"), pass `filter.kind` (and any other narrowing filters) with `page.size: 1` and read `meta.total` from the response — don't page through the full list just to count it. Every result includes direct `url`/`url_thumbnail` download links (`url_thumbnail` is only populated for photos). Note that incoming email attachments sent to a project's inbox address are automatically saved as project files — a recently emailed document or photo will show up here without anyone manually uploading it. Key parameters: `filter.id` fetches a specific file by id. `filter.kind` is `photos` or `files` — `photos` returns only image uploads (stored in the fixed "Project Photo" folder), `files` returns everything else; omit it to return both. `filter.file_type_id` narrows to one folder (see `project_file_write`'s `file_type_id` schema description for the full fixed folder list). `filter.file_description_id` narrows to one company-defined file description/tag. `filter.search` does a partial match across the file's name, caption, and description. `filter.work_order_id` narrows to files linked to a specific work order id (or a comma-separated list of ids). `sort` accepts `size` or `updated_at`, optionally prefixed with `-` for descending (e.g. `-size`); defaults to newest-updated-first (`-updated_at`) when omitted. `include` eager-loads `file_type`, `file_description`, and/or `creator` (comma-separated). Returns `{ data: ProjectFile[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: use `project_file_write` (action `create`/`update`) to upload a new file/photo or reclassify (rename, move to a folder, tag, link to a record) an existing one.
project_file_search
Search and list a single project's notes — its activity log. Use it to read what has happened on a job (calls, emails, appointments, work orders, system activity) or what was told to a customer. Requires `filter.project_id`; there is no tenant-wide note search (use `project_search` first to find the project's id). To count a project's notes ("how many notes does this project have?"), pass any narrowing filters with `page.size: 1` and read `meta.total` from the response — don't page through the full list just to count it. Key parameters: `filter.id` fetches a specific note by id. `filter.search` matches words in the note body (every word must appear). `filter.type_id` narrows to one note type. `filter.created_by` narrows to notes written by one user id (see `user_search`). `filter.is_user_generated` separates notes people wrote (`true`) from automatic system activity (`false`). `filter.created_after`/`filter.created_before` and `filter.updated_after`/`filter.updated_before` narrow by when a note was created or last updated — each accepts a bare date (`2026-07-23`) or a full datetime in `YYYY-MM-DD HH:MM:SS` form (`2026-07-23 15:00:00`, space-separated; a `T`-form ISO value is treated as a bare date); combine both for a range. For "what happened on this job last week?" pass `created_after: <date a week ago>`. `sort` accepts `created_at` or `updated_at`, optionally prefixed with `-` for descending; defaults to newest first (`-created_at`) when omitted. `include` eager-loads `type` and/or `creator` (comma-separated). For users whose project finances are hidden, payment, bill, payout and invoice notes are left out and dollar amounts in other notes show as `$[hidden]`. Returns `{ data: ProjectNote[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: use `project_note_write` (action `create`/`update`) to add a new note or change an existing one's type or visibility.
project_note_search
Search and list projects (a job/opportunity at a customer's property) for the authenticated user's tenant. Use this to find an existing project before acting on it, to look up a project by name/address, or to fetch a single project by id (pass `filter.id` — there is no separate "get project" tool). Results are paginated; prefer narrowing with `filter` over paging through the entire list. Results default to newest first (`sort=-created_at`) when `sort` is omitted and `filter.search` is not used; when `filter.search` is used, omitting `sort` instead leaves results in the search's own relevance order (see `filter.search` below) — pass an explicit `sort` to override either default. Key parameters: `filter.search` matches against project name, number, addresses, account/customer name, and contact names — typo-tolerant and relevance-ranked when the search service is active, otherwise a plain substring match; `filter.name` does a partial (substring) match; `filter.id`, `filter.account_id`, `filter.status_id`, and `filter.company_id` are exact matches; `filter.favorite`/`filter.recent` scope to the current user's favorited/recently-viewed projects; `filter.has_work_orders`/`filter.has_unscheduled_work_orders` are boolean presence checks. `filter.custom_filter_id` applies a saved whiteboard filter's full condition set by an id you already have (e.g. from the web app) — there is no tool to look one up or create one right now. `sort` accepts one of the listed fields, optionally prefixed with `-` for descending (e.g. `-created_at`). `include` eager-loads `status`, `account`, `company`, `site_type`, `rep_primary`, `workflow`, and/or `current_project_milestone` (comma-separated combination) — use `workflow` for "what workflow is this project on" and `current_project_milestone` for "what milestone/status is this project currently at" without a separate call; requested includes are returned in both slim and detailed modes. By default (`detailed=false`) each result is a slim projection — id, hash, number, name, account id/name, status_id, address, primary rep id/name, percent_completed, created_at, updated_at — because the full project resource carries ~50 base fields plus a large block of financial fields. Pass `detailed=true` to get every field; financial fields (amounts, payouts, expenses) only appear when the calling user's permissions allow seeing project finances — they are silently omitted otherwise, exactly like the REST API. For a question this tool's filters can't express — a complex combination of criteria, or an aggregate/rollup across many projects ("combined total expenses", "sum/average/count of X by Y") — build a private custom report instead of trying to force it through `filter`/`sort`: discover entities/columns/filter options with `report_build_options`, create the report with `report_write`, run it with `report_run` (its `aggregates` mode for totals/averages/counts), and clean up a one-off report afterward with `report_delete`. Don't reach for this fallback for anything the `filter`/`sort`/`include` options above already cover. Returns `{ data: Project[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope.
project_search
Search and list saved reports — user-created or out-of-the-box, configured analytics definitions over one of 23 reportable entities (project, invoice, estimate, task, appointment, bill, claim, contract, credit_memo, expense, invoice_line, labor_item, material_order, material_order_item, milestone, payment, payment_line, permit, project_custom_field, session_activity, user, vendor_service, work_order). This tool never executes a report — it only finds/describes one. Use `report_run` to actually get rows or aggregates once you have a report id. Note: an out-of-the-box report looks like a normal private report on every other field (`is_private: true`, a real `created_by`) — a non-null `out_of_the_box_key` is THE signal that `report_write` and `report_delete` will refuse it; do not infer editability from `is_private`/`created_by`. To build or edit a report, use `report_build_options` to discover entities/columns/filter subjects/fields/comparisons/values, then `report_write` to create it (optionally with a full inline definition) or to update its metadata, columns, and filter conditions. A report an agent creates via `report_write` is always private to the caller — visibility and sharing are managed in the web app, not here. Delete a scratch report you no longer need with `report_delete`. Use `filter.id` to fetch one report by id (there is no separate "get" tool). `filter.entity` narrows to reports over one entity type. `filter.name` is a partial (substring) match. `filter.is_private`/`filter.favorite`/`filter.created_by` narrow further. Results default to the report's manual `position` order (drag-and-drop order in the web app) when `sort` is omitted; every result carries `is_favorited` for the current user at no extra cost. Pass `with_columns=true` (ideally combined with `filter.id`) to inline each report's ordered column definitions — `{id, key, name, description, is_sortable, supported_aggregates, reference, position, selected_aggregates}` — under a `columns` key on the result. `reference` is `null` for most columns, or `{resource_type}` (one of `project`, `invoice`, `credit_memo`, `payment`, `expense`, `bill`, `work_order`, `material_order`, `estimate`, `claim`, `permit`) when the column's display value points at an underlying resource; it only identifies which columns point at a resource — per-row resource ids are not currently exposed through `report_run` (that resolution is a REST-only `with_links` feature). Do this before calling `report_run` to understand what a report's rows will look like (rows come back keyed by each column's `key`), or before calling `report_write`'s `update_column`/`remove_column` actions (which target a column by its `id`). A column whose key no longer maps to a registered reportable column (a renamed/removed definition) still appears, as a degraded `{id, key, position, selected_aggregates}` row rather than being silently dropped. Omit it (the default) for a lighter listing call. Pass `with_filters=true` (ideally combined with `filter.id`) to inline each report's filter conditions — `{id, position, operator, subject_key, field_key, comparison_key, value_key, value_data}` — under a `conditions` key. Use this to see a report's current filter logic, or before calling `report_write`'s `update_filter_condition`/`remove_filter_condition` actions (which target a condition by its `id`). Omit it (the default) for a lighter listing call. Combined with a listing — `with_columns` and/or `with_filters` true while `filter.id` is not set — page size is capped at 10 regardless of the requested `page.size`, to keep a multi-report response from inlining an unbounded number of column/condition objects; fetch one report by `filter.id` for full-size responses. Returns `{ data: Report[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope.
report_search
Search and list tasks (to-dos assigned to a user or a team, optionally tied to a project) for the authenticated user's tenant. Good for "what's due", "what's overdue", or "what's on my plate" style queries. Use this to find an existing task before updating/completing it, or to fetch a single task by id (pass `filter.id` — there is no separate "get task" tool). Results are paginated; prefer narrowing with `filter` over paging through the entire list. Key parameters: `filter.assigned_to` accepts either a numeric user id or the literal string `"me"` — pass `"me"` to answer "what's on my plate", which matches tasks assigned directly to the current user AND tasks assigned to any active team they actively belong to. `filter.project_id`, `filter.created_by` are exact matches. `filter.is_complete`/`filter.is_high_priority` are exact boolean matches. `filter.id` fetches a specific task. Held tasks (parked from a cancelled project rather than deleted) are excluded by default; pass `filter.is_on_hold: true` to see only held tasks, or `false` to be explicit about excluding them. `filter.is_overdue` (boolean) answers "what's overdue" directly — `true` matches open tasks whose due date has already passed (a task with no due date is never overdue); `false` matches everything else (complete, or not yet due). `filter.due_before`/`filter.due_after` narrow by due date — each accepts a bare date (`2026-07-10`) or a full datetime (`2026-07-10 15:00:00`); combine both for a range, e.g. "what's due this week" → `due_after=<monday>` `due_before=<sunday>`. `filter.due_within` is a named-range shortcut for the same axis — one of `today`, `yesterday`, `before_today`, `after_today`, `this_week`, `last_week`, `next_week`, `next_two_weeks`, `this_month`, `last_month`, `this_quarter`, `last_quarter`, `this_year`, `last_year`, `last_hour`, `last_three_hours` — pass this instead of computing `due_before`/`due_after` boundaries yourself for "what's due this week" style queries. `filter.task_type` narrows by how the task originated: `workflow` (materialized by a project workflow), `non_workflow`, `project` (attached to a project), or `non_project`. `filter.search` is a free-text term matched (plain substring, no typo tolerance) against the task subject and its project's number/customer name. `sort` accepts one of the listed fields, optionally prefixed with `-` for descending (e.g. `-due_at`). `include` eager-loads related objects onto each result — a comma-separated combination of `project`, `assignee`, `creator`, `completer`, `account` (e.g. `project,assignee`). When `sort` is omitted, results default to high-priority tasks first, then — within the same priority tier — the task with the furthest-out due date first (mirrors `TaskQuery::defaultSorts()`, i.e. descending on both). This is NOT soonest-due-first; pass `sort=due_at` explicitly for an ascending, soonest-due-first ordering. Returns `{ data: Task[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: use `task_write` (action `create`/`update`) to create a task or update one — including completing it (`action: update` with `is_complete: true`; there is no dedicated "complete" action).
task_search
Search and list teams (named groups of users within the authenticated user's tenant — install crews, sales teams, office staff, and the like). **Use this to turn a team's name into the internal team id other tools require** — most importantly `task_write`'s `assignee_id` when `assignee_type: team` ("assign it to the install crew"). Call this tool with `filter.search` to resolve the name first, then pass the returned `id`. Never ask the end user to supply a numeric team id — look it up here instead. Key parameters: `filter.search` is the main entry point — a partial, case-insensitive match on the team's name; multiple words are AND-ed. `filter.is_active` (boolean) narrows to active vs disbanded/retired teams — pass `filter.is_active: true` when resolving a team to assign work to, so a disbanded team with a similar name can't win the match. `filter.id` fetches one specific team. `filter.leader_id` narrows to teams led by a specific user (resolve the person with `user_search` first — useful for "Mike's team"). `filter.company_id` narrows to teams attached to a given company. `sort` accepts `name` or `-name`; when omitted, results default to active teams first, then name A→Z. `include` eager-loads related objects onto each result — currently just `leader` (the team leader's user object). If `filter.search` returns more than one plausible team, ask the end user which one they meant rather than guessing — assigning work to the wrong team is not silently recoverable. Returns `{ data: Team[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: `user_search` resolves individual users the same way (for `task_write`'s `assignee_type: user`, `jet_stream_write`'s recipients, and rep fields). There is no team write or delete tool.
team_search
Search and list users (employees/teammates within the authenticated user's tenant — never customers; use `contact_search` for those). **Use this to turn a person's name into the internal user id other tools require.** An end user will refer to a teammate by name ("assign it to Mike Kampa"), never by id — call this tool with `filter.search` to resolve that name first, then pass the returned `id` to whichever tool needs it: `task_write` (`assignee_id`, with `assignee_type: user`), `jet_stream_write` (`user_ids`), `account_write` (`rep_id`), `project_write` (`new_account.rep_id`), or `contact_write` (`model_id`, with `model_type: users`). Never ask the end user to supply a numeric user id — look it up here instead. Key parameters: `filter.search` is the main entry point, but its behavior and field coverage depend on whether the search service is active. When active, it's a typo-tolerant, relevance-ranked search across last name, first name, username, email, title, and phone number (home, cell, direct — matched in any format, formatted or digits-only), capped at the top 100 matches by relevance. When inactive, it falls back to a plain, case-insensitive substring match across username, first name, last name, email, and the raw phone columns (home, cell, direct) exactly as stored — no typo tolerance, no title, and a phone number only matches when typed in the same format it's stored in. Either way, `"Mike Kampa"` matches a user whose first name is Mike and last name is Kampa. `filter.is_active` (boolean) narrows to enabled/disabled logins and `filter.employed` (boolean) narrows to currently-employed vs terminated staff — pass `filter.employed: true` when resolving someone to assign work to, so a departed employee with a similar name can't win the match. `filter.email` is an exact match. `filter.id` fetches one specific user — a numeric id, or the literal string `"me"` for the authenticated user themselves ("who am I", "my profile"). `filter.company_id` narrows to members of a given company (useful in a multi-company tenant where two people share a name). `sort` accepts one of the listed fields, optionally prefixed with `-` for descending (e.g. `-last_name`); ordering is not guaranteed when it is omitted. `include` eager-loads related objects onto each result — a comma-separated combination of `user_level` and `default_company`. If `filter.search` returns more than one plausible person, ask the end user which one they meant rather than guessing — assigning work to the wrong teammate is not silently recoverable. Returns `{ data: User[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. When `filter.search` is active and the search service is running, `meta.total` (and the results themselves) never exceed the top 100 relevance-ranked matches — a real match ranked below that cutoff will not appear, so narrow with `filter.employed`/`filter.company_id`/etc. rather than paging deeper if the person you expect isn't in the first 100. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tool: `team_search` resolves teams (for `task_write`'s `assignee_type: team`) the same way this tool resolves users. There is no user write or delete tool (deleting a user is never allowed — `App\Policies\UserPolicy::delete()` always denies it).
user_search
Search and list work orders (a crew's scoped piece of installation work on a project — trade, crew, schedule/install dates, status, PO/reference number, and an optional contract link) for the authenticated user's tenant. No filter is required — `App\Query\Scopes\WorkOrderAccessScope` already bounds every search to your own accessible projects, so a bare call with no filters searches every work order you can see. Use `filter.project_id` for "work orders on this project" (resolved through your own access; a nonexistent or inaccessible project id fails with a clean "does not exist" error rather than an empty list) or `filter.id` to fetch one exact work order (there is no separate "get" tool). `filter.contract_id`, `filter.company_id`, `filter.trade_id`, `filter.work_order_status_id`, `filter.work_order_type_id`, `filter.crew_id`, `filter.created_by`, `filter.managed_by` are exact matches. `filter.has_crew` (boolean) narrows to work orders with or without a crew assigned. `filter.is_scheduled` (boolean) narrows to work orders that have BOTH an install start and an install end date set (`true`) or are missing either (`false`). `filter.search` matches against the work order's own name/PO number OR its project's number, name, or address (street/city/state/zip). `filter.install_after`/`filter.install_before` narrow to work orders whose install window (`install_starts_at` through `install_ends_at`) overlaps the given range, at DAY GRANULARITY ONLY — pass a bare date (`2026-07-10`); if you pass a full datetime, only its date part is used and the time is silently ignored. Combine both for a range. Work orders with no install dates set at all are always excluded. `sort` accepts `created_at`, `install_starts_at`, `install_ends_at`, `priority`, `number`, `name`, or `status`, optionally prefixed with `-` for descending (e.g. `-install_starts_at`). When omitted, results default to the work order's position within its project (`order`), ascending — mirrors the REST endpoint's default. `include` eager-loads `project`, `company`, `trade`, `crew`, `contract`, `manager`, `work_order_status`, `work_order_type`, and/or `work_order_on_hold` (comma-separated). Pass `with_labor_items=true` (REQUIRES `filter.id`) to inline that one work order's labor items under a `labor_items` key — `{id, position, material_id, name, material_color_id, color, material_size_id, size, quantity, unit, cost_amount, total_amount}` each, in position order (`cost_amount` and `total_amount` are omitted for users whose role hides project finances). Capped at 250 labor items; `meta.labor_items_truncated` is `true` when a work order has more than that. Use the item `id` as `labor_item_id` in `work_order_write`. Returns `{ data: WorkOrder[], meta: { total, per_page, current_page, last_page } }` — never the raw Laravel paginator envelope. Rate-limited per authenticated user (default 60 calls/minute) to protect the tenant's database from a runaway agent loop. Sibling tools: `work_order_write` is always listed; creating and the labor item actions require work order writes to be enabled on this server (work order `update` does not). `work_order_delete` is listed only when work order writes are enabled on this server.
work_order_search
Create a new appointment or update an existing one. Set `action` to `create` or `update`; each is described below. - `action: create` — schedules a new appointment. Requires `company_id`, `starts_at`, `ends_at`; a `confirmed` appointment (the default `slot_type`) ALSO requires `company_appointment_type_id` (get it from `project_create_options` with the same `company_id`: its `appointment_types`), `title`, and at least one attendee — a `placeholder` (a tentative hold) does not. `company_id` must be a company you belong to; `project_id` (optional) must be a project you can access AND must belong to `company_id`. Each entry in `attendees` needs exactly one of `email` OR (`model_type` — `contact` or `user` — plus `model_id`); emails must be distinct (case-insensitive). **`notify` defaults to `false`. Setting it `true` sends a REAL ICS calendar invite email to every attendee — including contacts/customers, not just tenant users — so opt in deliberately.** - `action: update` — requires `id`. Behavior depends on whether the appointment has already started: if it HAS started, only `appointment_result_id` may be changed (everything else is rejected with a clear message; `notify` is accepted but has no effect there). If it has NOT started, you may change `title`, `description`, `starts_at`, `ends_at`, `is_all_day`, the `address_*` fields, and `notify` — as with `create`, `notify: true` emails an updated ICS invite to every existing attendee. A not-started `placeholder`'s `starts_at` must still be in the future and before `ends_at` (REST parity); a `confirmed` appointment's `starts_at` may be moved into the past. `appointment_result_id` can ONLY be set once the appointment has started — recording a result early is not supported (REST parity). **Attendees, `slot_type`, `company_id`, `project_id`, and `company_appointment_type_id` cannot be changed via this tool** (see each field's schema description for why) — manage the roster or reschedule a placeholder's confirmation through the Contractors Cloud web app. Creating or updating a project-linked appointment auto-generates an activity note on the project and re-evaluates its workflow — an automatic side effect of the underlying model, not something you trigger separately. There is no `delete` action — deleting an appointment is a real, unrecoverable hard delete (optionally emailing every attendee a cancellation) and is deliberately not exposed to agents. Returns the curated appointment (with its attendee roster) as `{ data: ... }`. Sibling tool: use `appointment_search` to find an existing appointment's id (pass `filter.id` — its response also inlines the attendee roster) before updating it.
appointment_write
Create or update a contract (the sold job's financial document on a project), approve or unapprove one, or lock or unlock its payouts. Set `action` to `create`, `update`, `approve`, `unapprove`, `lock_payouts`, or `unlock_payouts`; each is described below. Contracts are read with `contract_search` and removed with `contract_delete`. Records only: it never charges a card, processes a refund, or moves money. **A contract's sold amount is never taken from an estimate — contracts and estimates are not linked.** It is computed entirely from the contract's own billable/approved invoices; to reflect the job's value on a contract, invoice it (`invoice_write`) rather than expecting an estimate's total to carry over. `action: create` — requires `project_id`, `contract_type_id`, `name`, and `created_at`. The contract's company, status, and insurance certificate-of-completion closing comment are all derived server-side from the project and cannot be set here. A Warranty (type 4) contract self-approves on create and stamps its own approval date; every other type starts unapproved. A `claim_id` is only kept on an Insurance Proceeds (type 3) contract — on any other type it is cleared automatically, because a claim only ever belongs to an insurance-proceeds contract. Creating requires that you are not flagged "cannot create contracts". Side effects of a successful create: a "Contract [name] was created." note is added to the project's activity log, the project's earliest contract/approval dates are rolled up, expenses are recomputed across every contract on the project and rolled onto the project, this contract's payouts/commissions are recomputed, the project's search data is rebuilt, the project's job number may be generated when the company is configured to issue it, and the project's workflow is re-tested in the background — none of this needs to be triggered separately. `action: update` — requires `id`; every other field is optional, so send only what you want changed. `project_id` is rejected: a contract cannot be moved to another project. Approval and payout-lock state are not settable here — use the four verb actions below. Changing the type to Subject To (1) or Warranty (4) is rejected once the contract has sales (a non-zero sold or all-paid amount); resending the contract's own current type is always fine. The same insurance-proceeds claim rule as `create` applies: if the resulting type is not 3, the contract's claim is cleared. Every update also re-stamps the contract's company from its project — where the two disagree that can change which users can see the contract, since contract visibility is company-based. Side effects of a successful update: a "MODIFIED" note listing each changed field is added to the project's activity log, plus the same contract-date rollup, project-wide expense recompute, payout/commission recompute, search rebuild, possible job-number generation, and background workflow re-test that `create` runs. `action: approve` — requires `id` and no other fields. Marks the contract approved, stamps its approval date, recomputes the project's first-contract-approval date and its financials, and writes a note on the project's activity log. When the company is configured to issue the job number on contract approval, the project's job number is also generated and a second note is written. Idempotent: approving an already-approved contract does nothing at all — no writes, no notes, no recompute. `action: unapprove` — requires `id` and no other fields. Clears the approval flag and date, zeroes the contract's sold amount (immediately recomputed from whatever billable invoices remain on it), recomputes the project's contract dates and financials, writes a note, and re-tests the project's workflow in the background. Idempotent in the same way. `action: lock_payouts` — requires `id` and no other fields. Locks the contract's commission payout records so they can no longer change, and writes a note; it pays nothing out. The lock date is stamped only the first time a contract is ever locked; a later lock/unlock cycle keeps the original date. `action: unlock_payouts` — requires `id` and no other fields. Unlocks those payout records and writes a note, deliberately leaving the existing lock date in place. Both lock actions are idempotent, and neither triggers a workflow re-test, payout reprocess, or financial recompute. **Permissions**: approving or unapproving requires either Executive Authority or the "can approve contracts" permission, AND the project's company must have contract-manager review enabled. Locking or unlocking payouts requires either Executive Authority or Payout Authority. Creating requires that you are not flagged "cannot create contracts". Every action returns the contract as `{ data: ... }`, in the same shape `contract_search` returns — including the per-permission hiding of financial, expense, and payout fields. Sibling tools: `contract_search` (find a contract's id, or read one back), `contract_delete` (permanently remove one), `project_search` (resolve a project's id), `user_search` (resolve a rep's name to the id `rep_id` takes).
contract_write
Create or update a credit memo (a credit issued against a contract, typically to offset an invoice), or add, change, or remove one of its lines. Set `action` to `create`, `update`, `add_line`, `update_line`, or `remove_line`; each is described below. Find ids with `billing_search` (entity `credit_memo` / `credit_memo_line`). `action: create` — requires `contract_id`. The credit memo's company and account are derived from the contract's project and cannot be set here. `number` is optional: when omitted, the company's next suggested number is used; either way the company's shared invoice/credit memo counter advances by one on every create. A client-supplied `number` is written as-is with no uniqueness check, so duplicates are possible. `invoice_id` optionally names the invoice this credit memo credits; setting it is the ONLY way a caller influences which invoice the memo applies against — there is no separate "apply" verb, the financial recompute below reconciles the application from this field on every save (skipped when QuickBooks already owns the credit memo's application record — see `App\Actions\CreditMemo\ReconcileCreditMemoApplications`). Creating requires the create-credit-memos permission. Side effects of a successful create: a "Credit Memo [number] was created." note is added to the project's activity log, the credit memo's own totals/remaining-balance/description are recomputed (reconciling the `invoice_id` application when set), the contract's payouts are recomputed, and the project's workflow is re-tested in the background. `action: update` — requires `id`; every other field is optional, so send only what you want changed, and an empty payload is an accepted no-op. `contract_id` is rejected: a credit memo cannot be moved to another contract. `invoice_id` IS mutable here — changing it re-points which invoice the credit memo credits, and the same reconcile pass above runs again (subject to the same QuickBooks carve-out). Side effects mirror `create`: an activity-log note (diffing every changed field), the same totals/description recompute, payout recompute, and background workflow re-test. `action: add_line` — requires `id` (the credit memo). `invoice_item_id`, `quantity` and `rate_amount` are required; every other line field is optional. `amount` defaults to `quantity` × `rate_amount` when omitted or sent as `null`. `position` is optional: omit it to append the line last, or supply it to place the line there — the other lines shift to make room and positions stay 1..n. A line always belongs to exactly the credit memo it was created on and can never move to a different one. Side effects: the credit memo's description and totals are recomputed, a project note is written, the contract's payouts are recomputed when the credit memo is on a contract, and the project's workflow is re-tested (queued). `action: update_line` — requires `line_id`; every field is optional, so send only what you want changed, and an empty payload is accepted. Every save re-derives the line's `tax_amount` from the credit memo's tax code, so even an empty payload writes (with the side effects of `add_line`) when the stored tax amount is stale. Side effects mirror `add_line`. `action: remove_line` — requires `line_id`. This is a HARD delete of the line — there is no deletion guard and it cannot be undone. Side effects: sibling lines are renumbered into a gapless order and the credit memo's description and totals are recomputed. **Every action requires that the caller's project finances are visible** — the same permission floor `billing_search` hides money fields behind. Computed money (`total_amount`, `tax_amount`, `total_to_credit_amount`, `remaining_balance_amount`, `description` on the header; `tax_amount`, `item_winner_name` on a line) is never a payload field on any action — it always reflects the latest recompute. A taxable line's `tax_amount` is computed by the server from the credit memo's tax code, which is set on create from the linked `invoice_id`'s tax code (or else the company's most recently used one) and cannot be changed here. A tax code of `0` means no tax: the credit memo's lines carry none. `create`/`update` return the credit memo as `{ data: ... }`, in the same shape `billing_search` returns for a credit memo. The three line actions return the line as `{ data: ... }` (just `{ id, deleted: true }` for `remove_line`) plus a `credit_memo` block carrying the parent's freshly recomputed fields, so a follow-up read is not needed to see the new totals. Sibling tools: `billing_search` (find a credit memo or line's id, or read one back), `contract_search` (resolve a contract's id), `billing_delete` (entity `credit_memo`).
credit_memo_write
Create or update an estimate (a priced scope of work on a project — materials, labor, and markup), or add, change, or remove one of its line items. Set `action` to `create`, `update`, `add_line_item`, `update_line_item`, or `remove_line_item`; each is described below. Estimates are read with `estimate_search` (pass `with_line_items=true` alongside `filter.id` to read one estimate's line items) and removed with `estimate_delete`. `action: create` — requires `project_id`, `trade_id`, `estimate_type_id`, `created_at`, `name`, and `reference_number`. The estimate is created with no line items and with every money column at zero; its tax mode and the whole print-settings group are defaulted from the project's company and cannot be set here. Side effects of a successful create: the company's default estimate comments are copied onto the new estimate, the project's estimate totals are rolled up, an "Estimate [name] was created." note is added to the project's activity log, and the project's workflow is re-tested in the background. `action: update` — requires `id`; every other field is optional, so send only what you want changed, and an empty payload is an accepted no-op. `project_id` is rejected: an estimate cannot be moved to another project. Side effects of a successful update: an "Estimate [name] was updated." note listing each changed field is added to the project's activity log, the project's estimate totals are rolled up, and any proposal that references this estimate has its revenue recomputed; changing `labor_mode` or `is_auto_sales_markup_enabled` additionally recomputes the estimate's own persisted totals from its line items, since both feed that calculation. Moving an estimate out of Assembly mode (`labor_mode` 2) also turns automatic expenses off and keeps the stored `expenses_total`. The project's workflow is re-tested in the background. `action: add_line_item` — requires `id` (the estimate). Every line-item field is optional, so an empty line can be added and filled in later. `position` defaults to the estimate's next item number. Side effects: sibling line items are renumbered into a gapless order, an "Estimate item [name] was created." note is added to the project's activity log, the estimate's own totals, the project's estimate rollup and then the revenue of any proposal referencing the estimate are recomputed, and — when a material is attached — that material's default comments are copied onto the line, and the project's workflow is re-tested in the background. **When the estimate is in Assembly labor mode (`labor_mode` 2) with `is_priced_from_assembly_components` on, a line's cost is derived from its assembly components: a `base_cost` that differs from that derived cost is refused with an error (a new line's derived cost is `0`), and reads return the cost derived from the components.** **`base_cost`/`labor_cost` are TRUE COST, never the customer's price.** The line's sale price is derived as `cost / (1 - percentage_markup)` (e.g. `percentage_markup: 0.25` on a $100 cost sells for $133.33) — and ONLY when the estimate's own `is_auto_sales_markup_enabled` is `true`; if it is `false` (the default on `create`), no markup is ever applied and the sale price simply equals cost regardless of `percentage_markup`. Putting the customer's intended sell price into `base_cost` with `percentage_markup: 0` makes the line's — and the estimate's — profit exactly $0, which is a common mistake. `percentage_markup` must be below `1` (a margin of 1 would be an infinite sale price); negative values are allowed and price the line below cost. To reflect a known sell price: enable `is_auto_sales_markup_enabled` on the estimate, enter the real cost in `base_cost`/`labor_cost`, and set `percentage_markup` to `1 - (cost / sell_price)`. `action: update_line_item` — requires `id` (the estimate) and `line_item_id`; the line item must belong to that estimate. Every other field is optional and an empty payload is an accepted no-op that still re-stamps who last touched the line. Side effects match `add_line_item`, except the note is an "Estimate Item [name] MODIFIED." diff and the material default-comment import does not run. `action: remove_line_item` — requires `id` (the estimate) and `line_item_id`. This is a hard delete of the line and, with it, that line's own item comments and assembly components; there is no deletion guard and it cannot be undone. Side effects: an "Estimate Item ... was deleted." note is added to the project's activity log and the estimate's totals, the project's estimate rollup and then the revenue of any proposal referencing the estimate are recomputed without the line, and the project's workflow is re-tested in the background. `create` and `update` return the estimate as `{ data: ... }`, in the same shape `estimate_search` returns. The three line-item actions return the line item as `{ data: ... }` (just `{ id, name, deleted: true }` for `remove_line_item`) plus an `estimate` block carrying the parent's freshly recomputed `total`, `total_tax`, `revenue_amount`, and `expenses_total`, so a follow-up read is not needed to see the new totals. Sibling tools: `estimate_search` (find an estimate's id, read one back, or list its line items), `estimate_delete` (remove an estimate), `project_search` (resolve a project's id).
estimate_write
Create or update an invoice (a contract's billing document), or add, change, or remove one of its lines. Set `action` to `create`, `update`, `add_line`, `update_line`, or `remove_line`; each is described below. Invoices and their lines are found with `billing_search` (entity `invoice` / `invoice_line`); an invoice is removed with `billing_delete`. `action: create` — requires `contract_id`; the invoice's project is derived from the contract, so no separate `project_id` is accepted or needed. When `number` is omitted, the company's next suggested number is used; either way the company's shared invoice/credit memo counter advances by one on every create. No uniqueness check is performed on `number` either way, so a duplicate is accepted silently. Leaving `date` unset makes the invoice a "sales order" rather than a dated invoice. **Leaving `due_at` unset makes the invoice show status "Overdue" as soon as it has any open balance — a legacy zero-date quirk, not a bug — so set `due_at` on create whenever the invoice should read as "Open" instead.** `is_closed` can only be set here — there is no way to change it after create. Side effects of a successful create: the invoice's description is recomputed, a "CREATED" note is added to the project's activity log, the project's financials are recomputed, the contract's expenses and payouts are recomputed, the company's default invoice comments are copied onto the new invoice, and the project's workflow is re-tested in the background. `action: update` — requires `id`; every other field is optional, so send only what changed, and an empty payload is an accepted no-op. `contract_id` and `is_closed` are rejected: an invoice cannot be moved to another contract, and `is_closed` has no update path in legacy. Side effects mirror `create` minus the default comments: description recompute, a "MODIFIED" note diffing each changed field, financials recompute, and contract expenses/payouts recompute. `action: add_line` — requires `id` (the invoice); the line is always created under that invoice, and a client-supplied `invoice_id` is rejected. `invoice_item_id`, `quantity` and `rate_amount` are required; every other line field is optional. `amount` defaults to `quantity` × `rate_amount` when omitted or sent as `null`. `position` is optional: omit it to append the line last, or supply it to place the line there — the other lines shift to make room and positions stay 1..n. When `contract_invoice_status_id` is omitted, it defaults to the invoice's company's default invoice line status, or Pending if the company has none — this status decides which invoice financial bucket (pending / approved / billable) the line counts in, so an unset status is never simply "uncounted". Side effects: the parent invoice's description, the project's financials, and — since the invoice is always contract-linked — the contract's payouts are all recomputed, and the project's workflow is re-tested (queued). `action: update_line` — requires `line_id`; every field is optional and an empty payload is accepted. Every save re-derives the line's `tax_amount` from the invoice's current tax code, so even an empty payload writes (with the side effects below) when the stored tax amount is stale. The line's parent invoice can never be changed here — there is no `invoice_id` field on this action. Side effects match `add_line`, plus a project note diffing each changed field. `action: remove_line` — requires `line_id`. This is a HARD delete with no guard and cannot be undone. Side effects: a project note is added, the invoice's remaining lines are renumbered into a gapless order, the invoice's last-updated timestamp is touched, and the project's financials are recomputed. `financials_balance_amount` is, in short, billable line total minus credit memos minus payments in a status flagged `counts_as_paid` by `financial_write_options` (a Pending payment does not reduce it), plus tax owed. Financial totals (every `financials_*` field), `status`, `description`, `type`, `tax_amount`, `item_winner_name`, and `is_sales_order` are all computed by the server after every write and can never be set directly on any action. A taxable line's `tax_amount` is computed by the server from the invoice's tax code (`event_tax_item_id`) rate × the line `amount`, and changing the invoice's tax code re-taxes its billable lines (pending/approved lines keep their tax until their next save). A tax code of `0` means no tax: its lines carry no tax, and switching an invoice to `0` zeroes its lines' existing tax. `create`/`update` return the invoice as `{ data: ... }`. The three line actions return the line as `{ data: ... }` (just `{ id, deleted: true }` for `remove_line`) plus an `invoice` block carrying the parent freshly re-read AFTER the write, so a follow-up read is not needed to see recomputed totals. Every response uses the same shape, and the same per-permission financial-field hiding, that `billing_search` returns. **Permissions**: every action requires that project finances are not hidden for you and that you have contract access; `action: create` additionally requires that you are not flagged "cannot create invoices". Find ids with `billing_search` (entity `invoice` / `invoice_line`).
invoice_write
Create a new Jet Stream (a directed, notifying message thread) or reply to an existing one. Set `action` to `create` or `reply`; each is described below. **A Jet Stream is NOT a quiet log entry.** Every user in `user_ids` gets a push/email/bell notification the moment the stream is created, and every reply notifies every OTHER participant. If the stream is attached to a project, creating it and every reply to it ALSO auto-appends a system note to that project's activity feed ("JET STREAM ADDED: ...", "JET STREAM REPLY TO: ..."). If what you actually want is a plain status update or PA-note on a project with NO notifications sent to anyone, use `project_note_write` instead — do not use this tool just to "leave a note". - `action: create` — starts a new jet stream. Requires `title` (this IS the initial message text — there is no separate body field) and `user_ids` (the recipients, min 1, each an existing user in the same tenant — every one of them is notified). `project_id` is optional; when given, the stream is tied to that project (must be a project you can access — an inaccessible or made-up project_id fails identically) and its activity feed gets the "JET STREAM ADDED" note. There is no way to create a jet stream silently. - `action: reply` — adds a reply to an existing jet stream. Requires `jet_stream_id` and `body`. Find an existing stream's id with `jet_stream_search` (e.g. `filter.scope: mine`, or `filter.search` by title/topic) — never guess or ask the end user for a numeric id. You can only reply to threads you participate in — the stream's original creator, or a recipient already on its roster; a same-tenant stream you don't participate in fails identically to an unknown id. Notifies every OTHER participant in the stream, and — for a project-attached stream — appends a "JET STREAM REPLY TO" project note. There is no `update`/`delete` action: updating a jet stream's title is restricted to its original creator with little agent-facing value, and deleting one is a permission-gated, unrecoverable hard delete of the whole thread — deliberately not exposed to agents. Use `task_write` (not this tool) if you want the jet stream's message to ALSO create a related task — pass the related task's details there once you have this tool's returned jet stream id. Rate-limited per authenticated user (default 30 calls/minute, shared across BOTH `create` and `reply`) — tighter than a typical read-only tool's budget, since every call here notifies other humans, not just the database. Returns the curated jet stream (`action: create`) or reply (`action: reply`) as `{ data: ... }`.
jet_stream_write
Create or update a material order (a supplier order of materials for a project, tied to a work order and optionally rolled up under a contract), or add, change, or remove one of its line items. Set `action` to `create`, `update`, `add_line_item`, `update_line_item`, or `remove_line_item`; each is described below. Material orders are read with `material_order_search` (pass `with_line_items=true` alongside `filter.id` to read one order's line items) and removed with `material_order_delete`. Line items (the shingles, underlayment, drip edge, etc. being ordered) are managed with `add_line_item`/`update_line_item`/`remove_line_item`. `action: create` — requires `project_id`, `work_order_id`, `trade_id`, and `type_id`; `description` is optional (at most 50 characters). The work order must belong to the SAME project and must itself allow material orders (its `is_material_orders_allowed` flag) — a work order that doesn't is rejected with a pointed error rather than a generic validation failure. Several fields are derived automatically and can never be set here: the order's PO/reference number is generated server-side (project-scoped, race-safe, e.g. `MO1234-3`), the status always starts at Draft, its cost status starts Pending, and its `contract_id` is copied from the parent work order's own contract — not accepted directly, even if you pass one for a contract that genuinely belongs to the project. Side effects of a successful create: a "Material Order [...] was created." note is added to the project's activity log, and the project's workflow is re-tested in the background — no queued alert exists for this event today. `action: update` — requires `id`; every other field is optional, so send only what you want changed, and an empty update is a genuine no-op. `project_id` is rejected: a material order cannot be moved to another project. Sending a NEW `work_order_id` reparents the order — the same "must belong to this project and allow material orders" rule as `create` applies — and `contract_id` is RE-DERIVED from the (possibly just-changed) parent work order on EVERY update, not only when `work_order_id` is sent, fixing a legacy drift bug where a reparented order kept rolling its money up to the stale contract. When the resolved parent work order can't be found at all (a dangling reference), the contract association is left exactly as it was rather than being wiped. `actual_cost_amount` (the manually-entered actual cost, at least 0) is update-only — it is never accepted on create, and is independent of `estimate_cost_amount`, which is always derived from the order's line items. Side effects: changing `work_order_id`, `trade_id`, `type_id`, or `description` (a "header" change) writes a diff-based "MODIFIED" project note listing each changed field and re-tests the project's workflow in the background; an update that only touches `actual_cost_amount` produces neither — UNLESS the order's `contract_id` has drifted from its work order's own current contract, in which case the every-update re-derivation above changes `contract_id` too, which counts as a header change and fires the note and workflow re-test anyway. Supplier/schedule fields (`supplier_id`, `submitted_at`, `back_ordered_at`, `delivery_at`, `delivery_time_id`, `delivery_place_id`, `delivery_comment`) are update-only, mirroring legacy — a material order is always created bare and scheduled afterward. Changing any of them writes a "scheduling MODIFIED" project note and re-tests the workflow, and ALSO auto-recomputes the order's `status_id`: Ordered once a supplier AND a submitted date are both set, Back-ordered once a back-order date is set with no delivery date yet, Delivered once a delivery date has passed, Draft when none of the three dates are set. If the company is configured to auto-create tracking bills and this order has no expenses yet, a $0 supplier bill is also created automatically. `status_id` itself can never be set directly — it is always this derived value. `action: add_line_item` — requires `id` (the material order). Every line-item field is optional. Pass `material_id` for a catalog material (find it with `financial_write_options`, entity `material_order`, `material_search`) and `material_color_id`/`material_size_id` from that material's options — the line's `name`, `unit`, `color`, and `size` text are filled from those lookups when you don't send them. `cost_amount` is the UNIT cost and is never filled for you, so send it or the line contributes $0. `quantity`/`cost_amount` default to 0; `position` defaults to after the last line. Side effects: lines are renumbered gaplessly, a "Material order item [...] was created." project note is written, the parent work order's labor quantities are recomputed, and the order's `estimate_cost_amount` (the PRE-TAX sum of quantity × cost_amount, negative for a return — a supplier invoice usually includes tax, so expect that to show up as variance when comparing), the work order's cost totals, and the project's estimated expenses are all recomputed. `action: update_line_item` — requires `id` and `line_item_id`; the line must belong to that material order (a line on another order is reported as not found). Every other field is optional and only what you send is changed. A line can never be moved to another material order. Side effects match `add_line_item`, except the note is a "MODIFIED" diff. `action: remove_line_item` — requires `id` and `line_item_id`. A permanent hard delete with no guard. Remaining lines are renumbered and the same cost/labor recomputes run; no project note is written. `create`/`update` return the material order as `{ data: ... }`, in the same shape `material_order_search` returns. The three line-item actions return the line as `{ data: ... }` (just `{ id, name, deleted: true }` for `remove_line_item`) plus a `material_order` block with the parent's recomputed `estimate_cost_amount` and `actual_cost_amount` (omitted for users whose role hides project finances). Sibling tools: `material_order_search` (find a material order's id, match a supplier invoice back to its order, or read one back), `material_order_delete` (permanently remove one), `project_search` (resolve a project's id).
material_order_write
Create or update a payment (money received from — or refunded to — a customer) header, or apply, change, or remove one of its invoice-application lines. Set `action` to `create`, `update`, `add_line`, `update_line`, or `remove_line`; each is described below. Payments are read with `billing_search` (entity `payment`/`payment_line`). Records only: it never charges a card, processes a refund, or moves money. `action: create` — requires `account_id`, `company_id`, and `amount`. `account_id`/`company_id`/`type` are fixed for the life of the payment — there is no "move this payment" operation. `type` is `1` for a payment or `-1` for a refund, defaulting to `1` when omitted. `contract_payment_status_id` cascades when omitted: the company's own default status, else Pending — but the payment's own totals recompute (see below) runs immediately afterward and can normalize whatever status lands. A payment is created with zero lines ("Unapplied"); apply invoices to it afterward with `add_line`. Side effects of a successful create: a project note is written IF the payment already resolves to a project through an applied line (never true on a bare create — only relevant once lines exist), an account note is always written, and the payment's own status/applied/overage/description/search-data are (re)computed from its lines. **Only a payment status flagged `counts_as_paid` in `financial_write_options` (currently ids 6/7, "Deposited") counts toward an invoice's paid amount and balance.** A new payment defaults to Pending, which does NOT count — applying a line to a Pending payment leaves the invoice's balance unchanged until the payment is moved (via `action: update`) to a counts-as-paid status. Confirm with the user before marking money as deposited/counted rather than assuming a payment or its lines immediately affect an invoice's balance. A Refund (`type: -1`) is the one exception: its status is ALWAYS forced to Deposited (6) server-side regardless of what `contract_payment_status_id` was sent, so a refund always counts. `action: update` — requires `id`; every other field is optional, so send only what you want changed, and an empty payload is an accepted no-op. A payment's `amount` cannot be lowered below the total already applied through its lines — that is refused with a clear error. `account_id`/`company_id`/`type` are rejected — see above. A posted `contract_payment_status_id` of `0` means "leave the status unchanged", NOT "clear it" — there is no way to unset the status once set. Side effects of a successful update: a "MODIFIED" note listing each changed field is written to both the resolvable project (if any) and the account, and the payment's totals are recomputed exactly like `create`. `action: add_line` — requires `id` (the payment) and `invoice_id`. Only available on a payment-type payment (`type: 1`) — a refund's lines cannot be managed through this API. `invoice_id` is only checked against the SAME tenant, not cross-checked against the payment's own account. `account_id`/`project_id`/`contract_id`/`type` are all derived server-side from the payment and the target invoice and can never be set. `contract_payment_type_id` defaults to `1` when omitted. A payment can have only one live line per invoice — if it already has one, the add is refused with that line's id; use `update_line` on it instead. A line that would push the payment's applied total above the payment amount is refused with a clear error. Side effects: the parent payment's applied/overage/status/description are recomputed, the account's transaction totals are refreshed, and for every project any of the payment's lines touch, that project's financials and payouts are recomputed and its workflow is re-tested in the background — not just this line's own project, since one payment's lines can span several projects. No note is written for a line change — notes are only written by header `create`/`update`. `action: update_line` — requires `line_id`; `invoice_id` is immutable — a line can never be moved to a different invoice, only removed and re-added. Every other field is optional. A new `amount` that would push the payment's applied total above the payment amount is refused (unless it does not raise an already over-applied total). Same side effects as `add_line`. `action: remove_line` — requires `line_id`. This is a HARD, unguarded delete — the application is gone permanently and cannot be undone. Same side effects as `add_line`/`update_line`. A payment's `applied_amount`, `overage_amount`, `status`, and `description` are ALWAYS server-computed from its current lines after every write in this tool — never trust a value you sent for one of these; re-read the payment in the response (or via `billing_search`) instead. Every action requires that finances are visible to you (denied for a user flagged "project finances hidden" or "no access to contracts"). `create`/`update` return the payment as `{ data: ... }`, in the same shape `billing_search` returns for a payment. The three line actions return the line as `{ data: ... }` (just `{ id, deleted: true }` for `remove_line`) plus a `payment` block carrying the freshly recomputed parent, in the same shape `billing_search` returns for a payment — read it instead of assuming the line write alone tells the whole story. Find ids with `billing_search` (entity `payment` / `payment_line`, invoices via entity `invoice`). Sibling tools: `billing_search` (entity `payment` / `payment_line`, invoices via `invoice`), `billing_delete` (entity `payment`).
payment_write
Upload a new file/photo to a project's "File Cabinet", or reclassify (rename, move to a folder, tag, link to a record) an existing one. Set `action` to `create` or `update`; each is described below. - `action: create` — uploads a new file or photo to a project. Requires `project_id` plus EXACTLY ONE of `url` (a publicly fetchable http/https URL pointing at a public, non-private/loopback destination — the server fetches it, capped at 117 MB) or `content_base64` (base64-encoded file bytes, capped at 25 MB decoded; use `url` instead for anything larger, up to 117 MB). `name` (the original filename WITH extension, e.g. `roof-damage.jpg`) is required when using `content_base64` — there's no other way to know the file's name/type. Image files are detected automatically by inspecting the actual bytes (not the filename/extension) and are stored as photos; everything else is stored as a file — there is no way to force an image to be treated as a plain file. A detected photo always persists in the fixed "Project Photo" folder — any `file_type_id` you pass is discarded in that case (see `file_type_id`'s description). All other fields are optional metadata. - `action: update` — reclassifies an existing file: move it into a folder (`file_type_id`), tag it with a company file description (`file_description_id`), link it to a record (`related_to_type`/`related_to_id` — a contract, material order, bill, payment, permit, work order, vendor service, RoofScope order, EagleView order, or Hover record), rename it, or change its caption/description/visibility/sensitivity. Requires `id`. `is_cover_photo` may only be set when the target file is a photo — setting it on a non-photo file is rejected. **Choosing `url` vs `content_base64`.** `url` is the primary upload path: the server fetches the bytes itself, nothing travels through the conversation, and the full 117 MB is usable. `content_base64` is only practical for SMALL content you can reproduce byte-for-byte — something you generated yourself, or a few KB you hold verbatim. The validator accepts up to 25 MB decoded, but a base64 tool argument passes through the model's context: long strings are very expensive and are frequently altered in transit, then rejected as invalid base64. Treat ~100 KB as the realistic ceiling and prefer `url` whenever one exists. **A file on the user's own computer — a folder on their desktop, a chat attachment — cannot be uploaded with this tool**, and attempting to base64-encode one wastes time and fails. That is a constraint of the MCP tool-call transport (file bytes would have to be regenerated through the conversation), not a limitation of Contractors Cloud: the REST API, web app, and mobile app all accept ordinary multipart uploads up to 117 MB. Accurate alternatives: upload from the Contractors Cloud web or mobile app, or supply any publicly reachable link and use `url`. There is no `delete` action — deleting a project file is a real, permission-gated, unrecoverable hard delete (no soft trash) and is deliberately not exposed to agents. `file_type_id` is the fixed folder list: `0` No Folder, `1` Contract, `2` Material Order, `3` Expense/Credit, `4` Payment, `5` Permit, `6` Project Photo, `7` Sketches, `8` Work Order, `9` Vendor, `10` Estimates/Proposals, `11` Material Order Returns, `69` Integrations - Signeato, `70` EagleView, `71` GalaxyForms. If a `file_description_id` you pass doesn't exist for the project's company (and folder, once known), the error lists every valid `id: description` option so you can retry in one round trip. Returns the curated file as `{ data: ... }`. Sibling tool: use `project_file_search` to find an existing file's id (pass `filter.id`), or `filter.file_description_id`/`filter.file_type_id` to see what's already in use on a project.
project_file_write
Create or update a work order (a crew's scoped piece of installation work on a project), or add, change, or remove one of its labor items. Set `action` to `create`, `update`, `add_labor_item`, `update_labor_item`, or `remove_labor_item`; each is described below. Work orders are read with `work_order_search` (pass `with_labor_items=true` alongside `filter.id` to read one work order's labor items) and removed with `work_order_delete`. Labor line items are managed with `add_labor_item`/`update_labor_item`/`remove_labor_item`. `action: create` — requires `project_id`, `contract_id` (must belong to the same project), `trade_id`, and `work_order_type_id`. **Only available when work order writes are enabled on this server** — when they are not, this returns an error before validating or authorizing anything else; check with `work_order_search` or ask an administrator if unsure. The work order's company, status (starts at Draft), cost status, and PO/reference number are all derived server-side and cannot be set here — the PO number is generated from the project's number and a per-project sequence, race-safe across concurrent creates. `is_material_orders_allowed` defaults to `true` when omitted. Side effects of a successful create: a "Work Order [name] was created." note is added to the project's activity log, status-interval tracking starts for the new Draft status, and the project's workflow is re-tested in the background. `action: update` — requires `id`; every other field is optional, so send only what you want changed. `project_id` is rejected: a work order cannot be moved to another project. `contract_id`/`trade_id`/`work_order_type_id`/`number`/`description` are HEADER fields, editable only while the work order's status is below 4 (Draft, Waiting for Approval, or Waiting for Info) OR the caller has Executive or Production Authority — otherwise the update is rejected with "This work order can no longer be edited in its current status." `number` additionally requires Executive or Production Authority regardless of status. `work_order_status_id` is accepted free-form (validated only against real status ids, no state-machine enforcement), except that In Progress (8), Complete (9) and Closed Pending (10) are derived by Contractors Cloud and refused unless they equal the current status; setting a status is not completing a work order, which happens in Contractors Cloud. Changing it always starts a new status-tracking interval, regardless of any other setting. `crew_id` is nullable (send `null` to unassign) and, when the company has the corresponding settings enabled, is checked against the crew being active, having non-expired insurance, and being on the work order's event's installer list (only when the crew changes; re-sending the current crew is always accepted). `install_starts_at`/`install_ends_at`/`rescheduled_comment`: changing any of them requires Production Authority (Executive Authority is not enough) and is otherwise refused with "Saving the schedule requires production authority."; re-sending the current values is not a change and is always accepted. For the dates, omitting both leaves the schedule untouched and is not validated; sending one validates it against the stored other (start before end); send both as `null` to clear the schedule. Beyond the status-tracking interval above, the remaining side effects — a project note plus a background workflow re-test, and for a schedule change, an automatic status recompute and possible zero-tracking bill creation (only when the work order has a crew) — only fire when update side effects are enabled on this server; `company_id` is re-derived from the project on every update regardless of that setting. `action: add_labor_item` / `update_labor_item` / `remove_labor_item` — manage the work order's labor line items (the materials/labor the crew is paid for). **Only available when work order writes are enabled on this server** — otherwise they return an error before anything else. `add_labor_item` requires `id` (the work order); every item field is optional: `name`, `material_id`/`material_color_id`/`material_size_id` (catalog ids; `name`, `unit`, `color` and `size` text is filled from them when not sent — on add when `material_id` is sent, on update only when `material_id` changes), `quantity` and `cost_amount` (the UNIT cost). `quantity` and `cost_amount` default to 0 and may be negative for back-charges. Cost is NOT auto-priced from the catalog: pass `cost_amount` or the line contributes $0. New items are appended at the end. `update_labor_item` requires `id` and `labor_item_id` (an item on another work order is reported as not found), changes only the fields you send, and accepts `position` to move the item (items are renumbered gaplessly). `remove_labor_item` requires `id` and `labor_item_id` and permanently deletes it. `work_order_id` and `total_amount` are rejected. Side effects: a project note is written on every add, update and remove, adding an item inserts the material's default work order comment, and the work order's cost totals and the project's estimated expenses are recomputed. A labor item tied to a material conversion has its quantity recomputed whenever this work order's material order items change, so a hand-set quantity there may be overwritten. Find `labor_item_id` with `work_order_search` (`with_labor_items`) and material/color/size ids with `financial_write_options` (entity `work_order`, `material_search`/`material_id`). `create`/`update` return the work order as `{ data: ... }`, in the same shape `work_order_search` returns. The three labor item actions return the item as `{ data: ... }` (just `{ id, name, deleted: true }` for `remove_labor_item`) plus a `work_order` block with the recomputed cost, revenue and profit totals (omitted for users whose role hides project finances; `cost_amount`/`total_amount` on the item are likewise hidden). Sibling tools: `work_order_search` (find a work order's id, read one back, or resolve a manager's name to the id its `filter.managed_by` takes), `work_order_delete` (permanently remove one, available when work order writes are enabled), `project_search` (resolve a project's id).
work_order_write
Contractors Cloud ChatGPT Plugin FAQ
How the directory, categories and Discoverability Score work.
Read the methodologyHow do I improve Contractors Cloud's ChatGPT Plugin discoverability?
The levers are the listing surface agents actually read: names, descriptions, keywords, tool metadata, and registry health. Which lever matters depends on where discovery breaks, which is what continuous measurement shows.
What are Contractors Cloud alternatives on ChatGPT?
As of 2026-11-21, Contractors Cloud competes with (주)한산테크 MES, 101, 1barn, 1XA ERP, ADI Admin, AeroPlan IQ Connect, Aginera, Agriax and 157 more in ChatGPT ERP & Operations Resource Tools, ranked by public Discoverability Score.
Where is this profile measured?
This profile uses the geography attached to the latest public registry snapshot: US. Locale tags are intentionally omitted.