How the tools work
Inputs every tool takes, paging, dates, and how to get the most out of the tools.
Common inputs
Every tool takes these inputs as well as its own. Your AI tool fills them in, so you don't need to do anything.
| Field | Required | Description |
|---|---|---|
intent | Yes | The user's end goal in one sentence, not this call's. |
userSatisfactionEstimate | Yes | How the request is going so far: 5 on track, 4 minor detour, 3 empty results or a retry, 2 repeated empty or wrong results, 1 stuck or user frustrated. |
Distru logs intent and userSatisfactionEstimate with each call, to find where the tools fall short. A missing or invalid value doesn't fail the call.
When your connection reaches linked accounts, every tool also takes a required account, naming which account the call works in, and every result carries it.
Start with get-me
distru-get-me returns the signed-in user and the company setup: timezone, US state, compliance system, active modules and key inventory and sales settings. Call it once at the start of a session so dates are read in the right timezone and the assistant knows which compliance tools apply. Pass includePermissions to check what the user may do before a write.
Paging
Search tools take limit (10 by default, 100 at most) and cursor, and return:
{
"items": [],
"hasMore": true,
"nextCursor": "<opaque>",
"totalCount": 1240
}nextCursor is present only when hasMore is true, and totalCount only when the search reports one. A cursor works only with the exact filters and sort that produced it, so repeat the same arguments when you pass it. Rows written while you page can be skipped or repeated.
Report tools page differently: they return rows, meta and nextCursor, and take cursor and maxRowsLimit.
Sorting
Tools that sort take sortBy, an object of field and direction. Each tool lists the fields it can sort by.
Dates
Date filters take YYYY-MM-DD, read in the company's timezone (start of day for …After, end of day for …Before), or an ISO 8601 timestamp with a UTC offset. Both ends are inclusive.
Other date and time inputs need the full ISO 8601 timestamp with its offset, such as 2026-09-01T00:00:00-07:00. A timestamp with no offset is refused.
IDs
Distru's IDs have a prefix that says what they are, such as com_1 for a company or inv_4 for an invoice. Inputs also take the same ID with no prefix, such as one from the public API or a Distru URL, but a prefix for the wrong kind of record is refused. IDs from other systems, such as Metrc labels or QuickBooks IDs, have no prefix and stay as those systems wrote them.
Filters that take IDs say which tool resolves them, for example customerIds comes from distru-search-companies. Many search tools also take ids to fetch several known records in one call.
Create, update and delete
Most record types have one distru-mutate-<record> tool with a required action of CREATE, UPDATE or DELETE, rather than three tools. Each tool's description and schema is sent to the model on every request, so fewer tools means less context spent on the tool list.
An update changes only the fields you send, and a field sent as null is cleared. A list you leave out stays as it is, and a list you send replaces the whole list.