Built-in Agent Tools: Lead Capture and More

Built-in tools are actions that SiteTrellis provides, so your agent can do useful things without you building an API: save a lead, hand over to a person, send your team an email, remember a fact, show a link, or end the chat. Each can be switched on or off per agent. Together with custom HTTP tools they make up the agent's tool set.

Overview and defaults#

Tool (name)	What it does	Default
`capture_lead`	Saves the visitor's contact details as a lead.	On
`escalate`	Hands the conversation to a person.	On
`end_conversation`	Closes the chat after the AI says goodbye.	On
`send_email_to_team`	Emails a message to your team.	Off
`set_attribute`	Remembers a fact about the visitor.	On
`show_link`	Shows a clickable link button under the reply.	Off

These names are reserved: a custom HTTP tool cannot use them. When the agent's max tool iterations is set to 0, no tools of any kind are offered. The escalate tool is also only offered when escalation is enabled for the agent.

A note on names You may see the human handoff tool called "escalate to human" in places. Its tool name in the agent configuration and in this documentation is escalate.

capture_lead#

The AI is given your lead capture fields as the tool's inputs. When it has the required details and the visitor agreed to share them, it calls the tool. SiteTrellis validates the values (valid email, phone-like number, select option and so on); if something is wrong the AI is told what to ask the visitor to correct. On success a lead is saved, notification emails go to your configured addresses, and a lead.captured webhook event is sent. There is one lead per conversation; later calls update it.

Tips: write the "when to offer" guidance in the lead capture instructions field; keep the field list short; do not enable the tool if you do not want leads (for a pure support agent, turn it off).

escalate#

Lets the AI hand the chat to a person on its own judgment, for example when the visitor is frustrated or the question is beyond the agent. It takes a short reason, which is shown to your team. What happens next is governed by your escalation settings: the tool uses the action and message of your visitor request rule (live takeover by default), applies the out-of-hours rule if you are closed, and collects contact details first if your escalation form requires them. If a person already has the chat, the tool simply reports that. A handoff.requested webhook event is sent.

Tips: tell the AI in the prompt exactly when to use it. Keep a visitor request rule in your escalation settings so the tool has the behavior you expect.

end_conversation#

When the visitor clearly says they are finished, the AI says goodbye and calls this tool; the conversation is closed after its reply, your closing message applies, and a conversation.ended event is sent. The visitor can still start a new chat. You can also end chats automatically with end phrases and an idle timeout in the agent's conversation settings. See Build your agent.

Tip: if you use human takeover, consider turning this off so the AI does not close a chat that a person might want to continue, or tell it to end only after the visitor confirms they need nothing else.

send_email_to_team#

Lets the AI email a message to your team, for example "a customer wants a callback about X". It takes a subject and a message. The email goes to your escalation email recipients, or, if none are set, your lead notification addresses, or, failing that, the account's owners and admins, and contains a link to the conversation. It is off by default because you must decide who receives it. To prevent spam or prompt-injection abuse, at most 3 such emails can be sent per conversation, and subject and message lengths are capped.

Tips: prefer capture_lead when you simply need contact details, and webhooks for automation. In the playground the tool pretends to send but does not email anyone.

set_attribute#

Lets the AI remember a short fact about the visitor for the rest of the conversation, such as their company, plan or the product they are interested in. It takes a key (lowercase letters, digits and underscores, up to 40 characters) and a value. Saved attributes appear in the dashboard, can be used in custom tool templates as {{visitor.KEY}}, and are included in lead and handoff data. A conversation can hold up to 30 attributes; the names id and public_id are reserved.

Tips: because the AI chooses the attributes from what the visitor says, treat them as unverified. Do not use them to make access decisions.

show_link#

Shows a button-style link under the AI's reply, for example "Book a demo" or "View sizing guide". It takes a full http(s) url and a short label. At most 3 links can be shown per reply. The AI is told to use only URLs it found in your knowledge or in tool results, never to invent them.

Tips: put your key URLs (pricing, booking, returns policy, contact page) in the knowledge text with a short label, and tell the agent when to share each. The widget renders links as ordinary links; the AI is also free to write links in its text using light markdown.

Choosing which tools to enable#

Principle of least privilege: enable only the tools the agent needs. Every tool is something a clever visitor could try to trigger.
Support agent: escalate, end_conversation, set_attribute, optionally show_link and send_email_to_team; turn capture_lead off if you do not need it.
Sales agent: capture_lead, show_link (booking page), escalate.
After enabling, test in the playground. The AI only calls a tool when its description and your prompt make clear that it should. Remember that the playground does not create real leads or send real emails or webhooks, so also check once on the live widget.