ServiceTitan MCP

accounting_invoices_list

Read-onlyIdempotent

Retrieve filtered customer invoice headers by customer, job, date, amount, balance, review status, or assignee. Use this to find invoices matching specific criteria without estimates or line items.

Instructions

List one requested page of customer invoice headers using customer, job, business-unit, invoice, date, amount, balance, review, and assignment filters. Use this for filtered invoice search; use estimates or invoice-item tools when the required grain is an estimate or individual line item.

Input Schema

TableJSON Schema

Name	Required	Description
`ids`	No	Comma-delimited invoice IDs
`page`	No	Page number (starts at 1)
`sort`	No	Sort: Field (default), +Field (asc), or -Field (desc). Fields: Id, ModifiedOn, CreatedOn, Number, InvoicedOn, DueDate, Total, Balance
`jobId`	No	Job ID
`number`	No	Invoice number
`batchId`	No	Batch ID
`orderBy`	No	Order by field
`pageSize`	No	Records per page (default 50)
`statuses`	No	Invoice statuses
`jobNumber`	No	Job number
`totalLess`	No	Maximum invoice total
`customerId`	No	Customer ID
`batchNumber`	No	Batch number
`includeTotal`	No	Include total count in response
`totalGreater`	No	Minimum invoice total
`assignedToIds`	No	Assignee user IDs
`createdBefore`	No
`dueDateBefore`	No	Due date before RFC3339 date-time
`adjustmentToId`	No	Adjusted invoice ID
`businessUnitId`	No	Business unit ID
`modifiedBefore`	No
`reviewStatuses`	No	Review statuses
`createdOnOrAfter`	No
`dueDateOnOrAfter`	No	Due date on or after RFC3339 date-time
`invoicedOnBefore`	No	Invoiced on or before RFC3339 date-time
`orderByDirection`	No	Order direction: asc\|desc
`customFieldFields`	No	Custom field name/value filters
`invoicedOnOrAfter`	No	Invoiced on or after RFC3339 date-time
`modifiedOnOrAfter`	No
`customFieldOperator`	No	Operator for custom field filters
`balanceFilterBalance`	No	Balance filter value
`balanceFilterComparer`	No	Balance comparison operator

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv3.0.0Sep 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {},
+  "type": "object"
+}

First observedv2.5.1Apr 18, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description only needs to add behavioral context beyond that. It does so by clarifying the response grain (invoice headers), the one-page nature of the call, and the range of filtering dimensions. It does not discuss pagination defaults or sorting behavior, but the schema and output schema cover those.

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

Conciseness5/5

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

Two sentences contain the essential purpose, scope, and routing guidance with no fluff. The key verb and resource are front-loaded, and the usage caveat is placed immediately after the main definition.

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

Completeness5/5

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

Given the rich input schema, output schema, and annotations, this description provides enough context for an agent to select and invoke the tool correctly. It states what the tool returns at a high level, the main usage scenario, and the main alternative paths, while the schema handles the 32-parameter details.

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

Parameters3/5

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

Schema description coverage is 88% and each parameter already has a meaningful description, so the baseline is 3. The description adds only a high-level grouping of filter categories without explaining any individual parameter format or relationship beyond what the schema provides.

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

Purpose5/5

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

The description states a specific verb ('List'), a clear resource ('customer invoice headers'), and a concrete scope ('one requested page'), then enumerates the filter dimensions. It also differentiates this tool from estimates and invoice-item tools, making its purpose distinguishable from a large sibling list.

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

Usage Guidelines5/5

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

It explicitly says to use this tool for filtered invoice search and tells the agent to use estimates or invoice-item tools when the required grain differs. This gives clear when-to-use and when-not-to-use guidance, effectively routing the agent among alternatives without requiring it to inspect many siblings.

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

Deploy Server