Tools

A tool gives an agent a capability beyond writing a model response. It can read live information, work with another application, execute code, create a file, or operate Siesta AI itself.

Siesta AI exposes two user-facing groups:

Tools
├── Connection Tools
│   ├── Shared Tools
│   └── Private Tools
└── Platform Tools
    ├── Search, scraping, code, tasks, and orchestration
    └── Platform Management for Siesta AI administration

Choose the Right Tool

The agent needs to	Use	Example
Read or change an external business application	Connection Tool	Gmail, Slack, Jira, HubSpot, Google Drive
Use a team or organization credential	Shared Tool	Shared support mailbox or service-account Jira
Act as the current user	Private Tool	Personal Gmail, calendar, or OneDrive
Use a capability provided by Siesta AI	Platform Tool	Code Interpreter, Task Management, Web Scraper
Create or update Siesta AI configuration	Platform Management	Create an agent, update a Skill, write a Memory page
Answer from maintained indexed knowledge	Data or Memory	Policies, manuals, approved knowledge collections
Call a custom interface	REST or MCP Connection Tool	Internal CRM API or MCP server

Connection Tools

Connection Tools work with external systems. Their functions come from configured Connections, REST APIs, or MCP servers. Examples include reading a Drive file, sending a Slack message, creating a Jira issue, or querying an analytics service.

• Shared Tools use Connections shared with the agent's audience and are suitable for team-owned or organization-owned accounts.
• Private Tools resolve the current conversation user's own Connection and are suitable when actions must run under that user's identity.

The difference is credential ownership and runtime identity, not the provider function itself. Connection functions can be disabled, enabled, or enabled with confirmation. Require confirmation for send, publish, create, update, delete, permission, financial, or production-impacting actions.

Platform Tools

Platform Tools are built-in capabilities assigned directly to an agent or Template. The backend constructs some functions directly; Google Search and Web Scraper use system-managed provider Connections but still appear to users as Platform Tools.

The key relationship is:

Platform Tools
├── Task Management
├── Grounding with Google Search
├── Web scraper
├── Code interpreter
├── SiestaAI Help
├── Orchestration
├── JavaScript executor
└── Platform Management

Platform Management is the privileged capability for administering Siesta AI. It belongs to the Platform Tools group.

How Platform Tools Reach an Agent

Siesta.AI.App loads the available Platform Tools and stores their selected IDs on the agent. It keeps Shared and Private Connection Tools in separate form sections. Templates can also include Platform Tool assignments.

Siesta.AI.Backend then creates the executable catalog. Platform Tools reach it in two ways:

• runtime builders construct Task Management, Code Interpreter, SiestaAI Help, Platform Management, Orchestration, and JavaScript Executor,
• system-owned Connections supply Google Search and Firecrawl functions implemented in Siesta.AI.Tools.

System-owned connection functions bypass ordinary user connection ownership lookup because their credential belongs to the system organization. Organization-level connection governance still applies.

Platform Management

Platform Management creates, reads, searches, or updates Siesta AI objects. The frontend hides this privileged capability from normal Users. The backend adds its functions only when the agent has Platform Management assigned and the current user has the Owner or Admin role.

Assignment alone is therefore not enough. An Owner/Admin role alone is also not enough. Both checks must pass for the Platform_* functions to enter the runtime catalog.

Platform Tool Overview

Platform Tool	Runtime surface	What it does	Important prerequisite
Task Management	Platform_CreateTask	Creates a task in the agent's configured task workspace.	Agent must have TaskWorkspaceId.
Grounding with Google Search	GoogleSearch.Search	Searches Google Custom Search and returns URLs, snippets, and limited scraped page context.	Assigned Platform Tool must reference the system GoogleSearch connection.
Web scraper	Firecrawl functions	Scrapes, crawls, maps, or searches web content through Firecrawl.	Assigned Platform Tool must reference the system Firecrawl connection.
Code interpreter	CodeInterpreterAgent	Delegates code, data, file, and artifact work to a hosted code interpreter agent.	System Code interpreter connection must contain project endpoint/name.
SiestaAI Help	siesta_help_resolve	Diagnoses missing connection/tool setup and returns guidance or action cards.	Assigned Platform Tool.
Platform Management	Platform_* functions	Creates, reads, searches, and updates Siesta platform objects.	Owner/Admin user context and assigned Platform Management.
Orchestration	run_function_batch	Sends many inputs to a named sub-agent function.	Agent must have sub-agents for useful calls.
JavaScript executor	JsExecutorAgent	Runs synchronous JavaScript with sub-agent, Excel, status, and artifact helpers.	Assigned Platform Tool.

Task Management

Task Management exposes one function: Platform_CreateTask.

Use it only when the user explicitly asks to create a task. The backend function description says: create a task only when the user explicitly asks and never call it proactively.

What It Does

Platform_CreateTask creates a TaskItem in the task workspace assigned to the current agent. It stores the current conversation and current agent as source references when the source conversation still exists. The created task receives an icon resolved from the requested icon, summary, and prompt.

If the workspace has auto-execution enabled, the backend immediately starts task execution using the explicitly assigned agent or the workspace default agent.

Inputs

Field	Required	Behavior
summary	Yes	Short task summary. Empty values fail.
prompt	No	Detailed task prompt. Defaults to an empty string.
icon	No	Requested icon filename. The backend resolves it through the task icon resolver.
status	No	Parsed as Todo, InProgress, Review, or Done; defaults to Todo.
assignedChatBotId	No	Optional UUID of the agent assigned to the task. Invalid UUID fails.
assignedChatBotName	No	Optional exact agent name. If multiple agents match, the backend asks for assignedChatBotId.

Output And Failure Modes

On success, the tool returns task ID, summary, status, and a button labeled Open task.

The call fails when:

• summary is missing,
• the agent has no task workspace,
• the workspace is inaccessible or the user cannot write to it,
• assignedChatBotId is invalid,
• assignedChatBotId and assignedChatBotName refer to different agents,
• assignedChatBotName is missing, ambiguous, or inaccessible.

Grounding With Google Search

Grounding with Google Search is implemented through the GoogleSearch tool connection. The Platform Tool links to a system-owned GoogleSearch connection, and the runtime adds its connection function to the agent.

Function

GoogleSearch.Search performs a Google Custom Search request and returns ranked results. The implementation also tries to fetch each result URL and extract a short text context from paragraphs, headings, and list items. It removes common non-content tags such as scripts, styles, navigation, headers, footers, iframes, SVGs, and noscript blocks.

Inputs

Field	Required	Behavior
query	Yes	Search query. It should be specific.
count	No	Number of results from 1 to 10. Values are clamped; default is 3.
country	No	Google gl country code, for example us, cz, or sk; default is cz.
timePeriod	No	Google dateRestrict, for example d1, w1, m1, or y1.

Output And Use

The model receives:

• result title,
• result URL,
• snippet,
• optional scraped page text, truncated to keep context small.

The user-facing result lists found URLs and can include a View on Google button.

Use this tool when the answer depends on current public information, search result ranking, or time-bounded research. Do not treat search results as verified internal truth; the assistant should compare and cite sources when accuracy matters.

Web Scraper

Web scraper is implemented through the Firecrawl tool connection. The Platform Tool links to the system Firecrawl connection. It is read-oriented: it fetches external content but does not write to the target website.

Functions

Function	Inputs	Backend behavior
ScrapePageAsync	url, onlyMainContent	Calls Firecrawl scrape, requests markdown, and returns the page title plus markdown.
CrawlSiteAsync	url, limit, includePaths, excludePaths	Starts a Firecrawl crawl, polls until completion or timeout, and combines page markdown with source URLs.
MapSiteAsync	url, search, limit	Calls Firecrawl map and returns discovered links, including title/description when available.
SearchWebAsync	query, limit	Calls Firecrawl search and returns markdown or descriptions from top web results.

Output And Use

Use Web scraper when the user gives a specific URL, asks to inspect a site, wants SEO/content review, wants a site map, or needs page content turned into structured context.

Important boundaries:

• It can fetch sensitive URLs if the agent is allowed to see them, so prompts should be clear about what may be scraped.
• It depends on the Firecrawl API key and configured API URL.
• Crawl jobs can fail, time out, or return no pages.
• External page content can be stale, misleading, copyrighted, or policy-restricted.

Code Interpreter

Code interpreter exposes CodeInterpreterAgent.

The function delegates the user request to a hosted code interpreter agent. The tool builder deliberately tells the model not to solve, plan, write code, choose file names, or define implementation details before delegation. The assistant should pass the user's intent directly or minimally reformatted.

What It Does

The backend:

1. Loads the system Code interpreter connection from the system organization.
2. Reads the configured project endpoint and project name.
3. Creates an Azure AI Project client and a hosted code interpreter agent using gpt-4.1.
4. Uploads current conversation attachments to the code interpreter sandbox when file bytes are available.
5. Appends available input filenames to the delegated prompt.
6. Runs the hosted agent.
7. Collects text output.
8. Downloads generated container files referenced by annotations.
9. Uploads generated files to Siesta AI artifacts.
10. Returns the text result and file metadata.

Inputs And Outputs

Field	Required	Behavior
prompt	Yes	Original user request for the coding specialist.

The output can include:

• plain text result,
• generated artifact file IDs,
• file names,
• file size,
• content type.

Use Code interpreter for programming, scripting, calculations, file transformation, data analysis, chart/file generation, and debugging tasks that benefit from executing code.

SiestaAI Help

SiestaAI Help exposes siesta_help_resolve.

It is a diagnostic and guidance tool for connection setup, tool assignment, and platform documentation questions. It does not create permissions by itself. It resolves what the user appears to need and can return either a normal help answer or an action card with setup buttons.

Enable it on the agent in Configuration -> Platform Tools by turning on SiestaAI Help in the Platform Tools list.

Inputs

Field	Required	Behavior
userRequest	Yes	Original user request that needs help or connection diagnostics.
capability	No	Best matching capability, such as email.send, calendar.create_event, drive.read_file, slack.send_message, jira.create_issue, connections.setup, or connections.assign.
targetService	No	Explicitly named service such as Gmail, Outlook, Google Calendar, Google Drive, Slack, Jira, or HubSpot. Do not infer Gmail/Outlook from generic "email".
targetServices	No	Explicitly named services when the user asks to set up or assign multiple connections.
targetServiceMentionedByUser	No	True only when the user explicitly named the service.
targetAgentId	No	Agent ID that should receive connection/tool setup. Prefer IDs returned by Platform Management.
targetAgentName	No	Agent name when no target ID is available.
targetAgentMentionedByUser	No	True when the user asked to configure a specific agent.
intent	No	Use connection_setup, connection_assignment, connection_diagnostics, or platform_docs.
topic	No	Canonical documentation topic such as workflows, connections, agents, or tools.

Output And Use

The result includes a title, message, state metadata, optional docs URL, and sometimes a primary button/action. If action labels are returned, the assistant should tell the user to use the shown buttons instead of explaining a long manual navigation path.

Use it when the user says an agent cannot use Gmail, Outlook, Drive, Slack, Jira, HubSpot, calendar, or another external service; when they ask how to connect a tool; or when they ask for platform documentation.

Platform Management Functions

Platform Management exposes privileged Platform_* functions for operating Siesta AI itself.

They are gated in two ways:

• the agent must have Platform Management assigned,
• the current user must be Owner or Admin in chat execution.

Platform Management is hidden from normal Users.

Internally, this capability is still stored as the system-tool record named Platform Tools. The documentation uses Platform Management to distinguish it from the complete Platform Tools group.

Agent Functions

Function	What it does	Important fields
Platform_CreateAgent	Creates a new agent. The new agent uses the current agent's model and connection unless overridden.	name, systemMessage, description, modelName, temperature, maxTokens, presencePenalty, frequencyPenalty, initialMessage, reasoningEffortLevel
Platform_CreateAgentFromTemplate	Creates an agent from a template exactly using the template configuration.	templateId
Platform_GetAgent	Reads a single agent. Omit ID or pass self for the current agent.	id
Platform_ListAgents	Searches organization agents by name.	search, limit
Platform_UpdateAgent	Updates an existing agent. Omit ID or pass self for current agent. Only provided fields are changed.	Agent fields plus skillIds, memoryCollectionIds, memoryPageIds, systemToolIds, subAgentIds
Platform_ListConversations	Lists recent private conversations for an agent. Hidden, shared, and public conversations are excluded.	agentId, search, limit
Platform_ListMessages	Lists recent messages from a private conversation. Hidden, shared, and public conversations are excluded.	conversationId, search, role, limit

Platform_UpdateAgent replaces full assignments for arrays that are provided. Passing skillIds, systemToolIds, or subAgentIds means "set the complete list", not "append". Passing memory collection/page arrays replaces all current memory page assignments.

Platform_GetAgent returns agent details including prompt, model settings, skills, memory collections/pages, assigned Platform Tools, and sub-agents.

Skill Functions

Function	What it does
Platform_CreateSkill	Creates a skill with name, instructions, and optional description.
Platform_GetSkill	Reads one skill, including full instructions.
Platform_ListSkills	Searches organization skills by name.
Platform_UpdateSkill	Updates name, instructions, or description. Only provided fields are changed.

Skills define reusable behavior for agents. Updating skill instructions can change behavior for every agent that uses the skill.

Template Functions

Function	What it does
Platform_GetTemplate	Reads one agent template including full configuration.
Platform_ListTemplates	Searches organization templates by name.

Templates can copy prompts, model settings, skills, memory assumptions, and Platform Tools into new agents. Review templates before using them to create privileged agents.

Memory Functions

Function	What it does	Important fields
Platform_CreateMemoryCollection	Creates a Memory collection in the current organization.	name
Platform_GetMemoryCollection	Reads a Memory collection.	id
Platform_ListMemoryCollections	Searches Memory collections.	search, limit
Platform_UpdateMemoryCollection	Updates collection name.	id, name
Platform_CreateMemoryPage	Creates a Memory page inside a collection.	collectionId, name, body, order, parentId
Platform_GetMemoryPage	Reads a Memory page.	id
Platform_UpdateMemoryPage	Updates page name, body, order, or parent.	id, name, body, order, parentId

Memory created through Platform Management becomes reusable context. Treat it as operational knowledge, not temporary chat output.

Orchestration

Orchestration exposes run_function_batch.

Inputs

Field	Required	Behavior
functionName	Yes	Name of the sub-agent function to execute for every input.
input	Yes	Array of input strings.

The backend creates a private conversation for the selected sub-agent for each input string, sends the input as a message, and combines the results. It runs in parallel with a maximum concurrency of 40.

Use it for repeatable batch work such as classification, summarization, scoring, extraction, or repeated specialist review. Do not use it when a single direct answer or one sub-agent call is enough.

JavaScript Executor

JavaScript executor exposes JsExecutorAgent.

It runs synchronous JavaScript in a Jint engine and returns log output plus the final expression result. Objects and arrays are converted through JSON.stringify for readable model output.

Available Helpers

Helper	Behavior
log(message)	Adds internal log output returned with the result.
logStatus(message)	Publishes a real-time status update visible to the user.
callAgent(name, prompt)	Synchronously creates a private conversation with a named sub-agent and returns its response.
callAgentsParallel(names, prompts)	Calls multiple sub-agents in parallel; names and prompts must have equal length.
readExcelFile(fileName, sheetName, maxRows?)	Reads rows from an attached Excel file.
listExcelSheets(fileName)	Lists sheet names in an attached Excel file.
writeExcelFile(fileName, sheetName, rows)	Writes rows to a new Excel file.
createExcelDocument(fileName, sheetName, rows)	Creates an Excel file and attaches it as a downloadable conversation artifact.
searchExcelRows(fileName, sheetName, columnName, searchValue)	Searches rows by case-insensitive column value match.
getExcelColumnStats(fileName, sheetName, columnName)	Returns numeric column stats: min, max, sum, average, count.
copyFileAsArtifact(sourceFileName, newFileName)	Copies a conversation attachment into artifacts and returns file metadata.
editArtifactFile(fileId, content)	Replaces content of an artifact previously created for editing.

Usage Rules

• All helper functions are synchronous.
• Do not use async, await, or Promises.
• Use logStatus() before significant work so the user sees progress.
• Use it when loops, branching, aggregation, spreadsheet processing, or controlled sub-agent orchestration are clearer in code than in natural language.
• Limit it to trusted/admin or power-user agents because it can call sub-agents, process files, and create artifacts.

Governance Notes

Enable Platform Tools intentionally.

• Task Management can create persistent work and may auto-execute tasks.
• Grounding with Google Search and Web scraper read public or reachable external content, which can be stale, misleading, sensitive, or policy-restricted.
• Code interpreter can execute code and create files; review outputs before operational use.
• SiestaAI Help guides setup but does not grant permissions.
• Platform Management can change agent behavior, Skills, Memory, sub-agents, and Platform Tool assignments.
• Orchestration can create many sub-agent conversations quickly.
• JavaScript executor can run scripted logic, call sub-agents, process Excel files, and create artifacts.

When Platform Tools are included in a Template, newly created agents can inherit them. Review Platform Tool assignments before publishing Templates broadly. Use Tool Executions to inspect arguments, results, status, errors, and approvals.

User-Safe Examples

Use web search to verify this, then cite what you found.
Do not rely only on memory.

Scrape this URL and summarize only facts visible on the page.

Create a task from this conversation with summary, prompt, and status Todo.

Check whether this agent has the right connection assigned. If not, show me the setup action.

Analyze this spreadsheet and create a downloadable cleaned version.

Use the JavaScript executor to read the attached Excel file, group rows by owner, and create a cleaned workbook.

Related Guides

• Tool Executions
• Users: Work with Agents
• Users: Use Chat Effectively
• Users: Use Tasks to Track Work
• Set Up Tools, APIs, and MCP Access
• Admins: Define Access Policies and Visibility Rules