Customers and companies

With these tools an assistant can find a customer, read their full profile and history, add a new customer or correct one, and look up companies with their contacts and recent tickets.

Source: _TOOLS in services/runtime/src/runtime/mcp/tools.py, handlers _search_customers, _get_customer, _create_customer, _update_customer, _list_companies and _get_company.

search_customers sends the client no read-only hint. It reads and only reads.

search_customers

• Inputs: q and limit (1 to 500, default 50), both optional.
• q is a case-insensitive part of the name, email or company. It does not match phone numbers, even though the helpdesk's own customer search does.
• Without q, it lists the directory.
• Returns query, total_matched and customers (the first limit matches). There is no offset; narrow q instead.
• This is one of the older tools. It does not wrap customer text.

Source: _search_customers in services/runtime/src/runtime/mcp/tools.py.

get_customer

• Input: customer_id.
• Returns the profile with recent tickets, conversations and survey responses.
• Text a customer wrote comes back wrapped: ticket subjects, survey comments, survey answers and the ticket subject on each survey response as {"untrusted_text": ...}, and the customer's metadata as {"untrusted_data": ...}.
• The answer is held to 64 KB. A long history is cut and flagged; see Limits.

Source: _get_customer and _customer_detail in services/runtime/src/runtime/mcp/tools.py.

create_customer

• Inputs: display_name (1 to 120 characters) is required. email (up to 240), phone (up to 32), company (up to 120) and country (up to 4) are optional.
• Refusal: an email another customer already has.
• Returns the new customer, with metadata wrapped as untrusted data.

update_customer

• Inputs: customer_id, plus any of display_name, email, phone, company, country and company_id. Only the fields you send change.
• Emptying a field takes clear. Name the fields to empty, from email, phone, company, country and company_id. Sending null does nothing, because a null argument is dropped before the tool sees it, and sending an empty string is refused.
• Refusals: a field both sent and named in clear; a call that sends nothing and clears nothing; a clear entry outside the list above.
• display_name cannot be cleared, and metadata cannot be changed through this tool at all.
• Returns the updated customer, with metadata wrapped as untrusted data.

Source: _customer_patch, _update_customer and _CUSTOMER_CLEARABLE in services/runtime/src/runtime/mcp/tools.py.

list_companies

• Inputs: q (part of a name or domain), limit (1 to 500, default 50) and offset, all optional.
• Returns query, total_matched, limit, offset, companies, truncated and next_offset.
• next_offset is where the next page starts, or null on the last page. If a page is too big to send, it is cut short, truncated is true, and next_offset points at the first company that was left out. Carry on from there.

Source: _list_companies and PagedRows in services/runtime/src/runtime/mcp/tools.py.

get_company

• Input: company_id.
• Returns the company's details, owner, SLA policy, contacts and recent tickets. Each ticket subject is wrapped as untrusted text.
• The answer is held to 64 KB; see Limits.

Source: _get_company and _company_detail in services/runtime/src/runtime/mcp/tools.py.