Tools reference
The Formule MCP server exposes 24 tools. Every one of them runs as
you: the server resolves your identity first and then queries the database under
row-level security, so a tool can only ever return what you could see by signing
into the app yourself. An agent asking search_leads gets their own leads; a
manager asking the same question gets the agency’s.
Read-only tools
Section titled “Read-only tools”These answer questions. They never modify anything.
whoami
Section titled “whoami”Who this call acts for: the person, their agency (or agencies), their agent profile if any, whether you can write (can_write) and whether this chat is linked. Call it first. If user is null, explain the linking steps in scoping and do nothing else.
Takes no parameters.
list_companies
Section titled “list_companies”The agencies this person belongs to (all agencies for a super admin), with how they belong (via) and which one is active. Use the slugs with select_company or company_slug.
Takes no parameters.
search_leads
Section titled “search_leads”Find leads by free text (name, surname, property, email, phone), status, or assignment. Returns the most recent first. Only leads this person may see in Formule.
| Parameter | Type | What it does |
|---|---|---|
query |
string | Text to match against name, surname, property, email; a phone number is matched exactly. |
status |
string | Filter by crm_status. |
unassigned_only |
boolean | — |
limit |
integer | Max results (default 20, max 100). |
get_lead
Section titled “get_lead”Full details for one lead, including comments, its open property matches (from the agency’s external listing catalogue, when connected) and open reminders.
Takes no parameters.
list_stale_leads
Section titled “list_stale_leads”Leads that still need attention (UNCLEAR / ATTEMPTED_NO_RESPONSE / NURTURE) with no comment in the last N days. The raw material for a follow-up digest.
Takes no parameters.
list_matches
Section titled “list_matches”Property matches between this person’s leads and the agency’s external listing catalogue, best score first. Default: open (‘new’) matches only. A catalogue: “none” answer means no catalogue is connected: relay that, never ‘no matches’.
| Parameter | Type | What it does |
|---|---|---|
status |
string | — |
since |
string | ISO timestamp; only matches created after this. |
limit |
integer | — |
search_listings
Section titled “search_listings”Search the agency’s external listing catalogue (active listings). A catalogue: “none” answer means this agency has no catalogue connected: say so.
| Parameter | Type | What it does |
|---|---|---|
locality |
string | Locality or region name (case-insensitive). |
max_price |
number | — |
min_bedrooms |
integer | — |
property_type |
string | e.g. Apartment, Penthouse, Villa |
sale_or_rent |
string | — |
limit |
integer | — |
list_agents
Section titled “list_agents”Active agents of the agency (names and contact details, as shown in the app).
Takes no parameters.
my_stats
Section titled “my_stats”This person’s numbers over the leads they may see: leads by status, new in the last 7 and 30 days, leads with no note yet, leads still open but quiet for 7+ days, last activity, open reminders. Admins see their agency-wide view.
Takes no parameters.
find_leads_for_listing
Section titled “find_leads_for_listing”Which of this person’s leads would want a given property. Pass a listing reference from the agency’s external listing catalogue, or describe the property (locality, price, bedrooms, property_type, sale_or_rent). Ranks on the leads’ stated preferences first, then on the free-text wishes written on each lead; returns the best few with the reason each fits.
| Parameter | Type | What it does |
|---|---|---|
ref |
string | Listing reference in the agency’s external catalogue. |
locality |
string | — |
price |
number | — |
bedrooms |
integer | — |
property_type |
string | e.g. Apartment, Penthouse, Villa |
sale_or_rent |
string | — |
limit |
integer | Default 10. |
list_due_followups
Section titled “list_due_followups”Open reminders due up to a point in time (default: end of today, UTC) plus any overdue ones, soonest first. Your own reminders; admins also see their agency’s.
| Parameter | Type | What it does |
|---|---|---|
until |
string | ISO 8601 timestamp; default end of the current UTC day. |
include_future |
boolean | Also list reminders due after until. |
limit |
integer | — |
get_lead_timeline
Section titled “get_lead_timeline”What the assistant remembers about one lead’s WhatsApp conversation: last contact, counts, listings already shared, warmth, and the latest messages (text kept 30 days). Only for leads whose agent enabled WhatsApp reading in Formule.
Takes no parameters.
list_nudges
Section titled “list_nudges”What the assistant should tell this person now: follow-ups due, leads gone quiet, new property matches, next steps after a conversation. Each has a ready-to-send draft. Pure read: call acknowledge_nudges after showing them.
| Parameter | Type | What it does |
|---|---|---|
include_delivered |
boolean | Also return nudges already shown (default true). |
limit |
integer | — |
Tools that change data
Section titled “Tools that change data”These write. Expect your client to confirm before running one.
add_lead_note
Section titled “add_lead_note”Append a dated note to a lead’s comments (the same log agents write in the CRM).
Takes no parameters.
schedule_followup
Section titled “schedule_followup”Remind this person about a lead at a given time (‘remind me to call Maria on Friday’). Reminders belong to the person asking; they can only be set in an agency they are a member of.
| Parameter | Type | What it does |
|---|---|---|
lead_key (required) |
string | — |
due_at (required) |
string | ISO 8601 timestamp, e.g. 2026-09-11T09:00:00+02:00. |
note |
string | What to do, in the person’s words. |
link_channel
Section titled “link_channel”Finish the one-time account link: the person got a 6-character code in Formule (Profile → Link your assistant) and sent it in this chat. Pass the code; the chat identity comes from the assistant runtime. From then on this chat acts as that person.
| Parameter | Type | What it does |
|---|---|---|
code (required) |
string | — |
chat_id |
string | The chat the code was sent from. Set by the assistant runtime; do not fill in by hand. |
platform |
string | Default telegram. |
select_company
Section titled “select_company”Switch the active agency for a person who belongs to several (see whoami). Pass the agency’s slug: map the agency name the person used to a slug yourself, never ask them for a slug. In a chat the choice sticks for later calls.
Takes no parameters.
update_lead_status
Section titled “update_lead_status”Set a lead’s crm_status.
Takes no parameters.
set_match_status
Section titled “set_match_status”Mark a property match as shown, sent (the listing was sent to the client) or dismissed.
Takes no parameters.
complete_followup
Section titled “complete_followup”Mark a reminder as done (optionally logging what happened as a note on the lead).
Takes no parameters.
acknowledge_nudges
Section titled “acknowledge_nudges”Mark nudges as delivered after showing them to the person (list_nudges is a pure read). Only pending nudges change.
Takes no parameters.
dismiss_nudge
Section titled “dismiss_nudge”The person does not want this nudge (e.g. already handled it elsewhere).
Takes no parameters.
snooze_nudge
Section titled “snooze_nudge”Bring this nudge back later (default 24 hours).
Takes no parameters.
send_whatsapp_message
Section titled “send_whatsapp_message”Send ONE message to a lead from the agent’s own WhatsApp number, only after the agent explicitly approved this exact text in this conversation. Logs it on the lead in the CRM, closes the nudge it answers, and sets the next reminder (default 3 days; 0 for none). Repeating a call with the same idempotency_key within 24 hours returns the first result and sends nothing. Never claim a message was sent unless sent is true.
| Parameter | Type | What it does |
|---|---|---|
lead_key (required) |
string | — |
text (required) |
string | The exact text the agent approved. |
idempotency_key (required) |
string | A value unique to this approval (e.g. the chat message id of the approval). Reuse it if you retry. |
nudge_id |
string | The nudge this send answers, if any. |
next_follow_up_days |
integer | Default 3. 0 = no reminder. |
This page is generated from the server source. If a tool here looks wrong, the
source is the truth — see supabase/functions/mcp/server.ts.