<carta-plugin>carta-crm:1.14.2</carta-plugin>
Overview
Look up contacts in the Carta CRM. A request about one named person renders that person's card; a request for a set renders a table. Route on that distinction first — it decides every call below.
Step 1 — Determine intent: one person, or a set?
- Detail — the user named one person and wants the record: "full details on Jane Doe", "tell me about Ihar", "more on this contact", "who is Jane Doe". → Step 2.
- List — the user wants a set, or filtered or plural results: "people at Acme", "contacts in my pipeline", "list contacts". → Step 3.
- By ID — the user gave a contact ID → Step 2, skipping the resolve.
A named single person is a detail request even when the user says "search" or "find". If it's genuinely unclear, treat it as a list and ask what they want to narrow to.
Step 2 — Detail: resolve the name, then render the card
Resolve through crm_call_tool, never crm_view_tool. This step is for you, not the
user: a view call collapses every array in the response to a count, so the rows — and the
id you need — never reach you, and the user gets a list they did not ask for.
Then branch on how many candidates came back:
- Exactly one match → render its card and stop:
- Several matches → do NOT guess. Render the candidates as a view and ask which one:
Then ask: "Several contacts match — which one did you mean?" When they pick, call
fetch_contact_by_idfor it. Namesakes are common in a CRM, so opening the top hit unasked shows the wrong person with full confidence. - No match → say so; do not render an empty view.
When the user gives an ID outright, there is nothing to resolve — one call, one card.
Render at most one card per request. If the user named several people, ask which to open rather than stacking views.
Step 3 — List: search and render the table
If the user mentions a specific list or folder by name, resolve the name to a list ID
first, then pass list_id to narrow the search. This lookup has no view of its own, so
it goes through crm_call_tool:
Increase limit if the user asks to see more results. Use offset to paginate.
If the view is unavailable
CRM views are enabled per organisation, and single-record views behind a second flag on
top of that. So any crm_view_tool call above may answer with:
CRM tool 'search_contacts' has no view — call it with crm_call_tool instead.
That is a normal response, not a failure — this organisation does not have that view
enabled. Retry that one call verbatim through crm_call_tool and present the result as
text per Step 4. Do not retry crm_view_tool, and do not report the message to the
user.
A detail request whose card has no view still resolves the same way: keep the
crm_call_tool resolve from Step 2 and present the chosen record as text.
Step 4 — Present results
When a card rendered, the user sees the whole record. Do not restate its fields. Answer what they asked, or acknowledge in one line.
When a table rendered, the user already sees every row. Do NOT re-list, re-format, or
summarise them as text — that duplicates the table. Answer the question they actually
asked, or acknowledge in one line (e.g. "Found 23 contacts — the ID is in the first
column, for /update-contact.").
When you fell back to crm_call_tool, display all non-empty fields in a readable
summary — name, title, company, email, phone, and tags — and show the ID prominently,
since the user needs it to run /update-contact.
fetch_contact_by_id also returns related deals and notes. The view renders those, but
call them out in text if the user is asking for context on a specific person.
If no contacts are found:
"No contacts found matching your search. Try a different name, email, or keyword."
