Docs / AI Agent / Tool reference
Reference
Agent tool reference
The SemAgent agent gets work done through tools. This page lists all 50+ built-in tools: what each does, which tier it belongs to, and its approval behavior. You can add your own tools via MCP — they pass through the same policy engine.
On every request the agent builds a plan and calls the tools it needs, in order. No tool call runs directly — it first passes through the policy engine:
User request
↓
Planner → proposes a tool call
↓
Policy engine: capability gate → allow-list → risk class → approval threshold
↓ ↓
runs without approval (SAFE) waits for user approval (action)
↓
Tool runs → result returns to the plan → agent continues
This evaluation happens at the code level; it cannot be bypassed with a prompt ("ignore the rules"). More: Autonomy & approvals and Security architecture pages (soon).
Two tiers: T1 & T2
| Tier | Meaning | Approval |
|---|
| T1 · Preparation | Side-effect free: reading, searching, analysis, drafting/artifacts. No permanent change to the outside world. | Runs freely SAFE |
| T2 · Action | Writing / sending / deleting / changing external systems. May be hard to undo. | Approved by risk |
ℹ️
The risk labels in the tables below are indicative. A tool's actual approval behavior is determined by the policy engine based on the tenant's autonomy level (Supervised → Autonomous), tool configuration, and "never runs silently" rules. Read-only tools are inherently SAFE.
Knowledge & research T1
Tools that gather context and change nothing. The agent's "eyes".
| Tool | What it does | Risk |
|---|
kb_search | Hybrid search over the tenant's knowledge base (pgvector); the basis of grounding. Returns source chunks. | SAFE |
web_research | Researches the web and summarizes. Results pass through quarantine as "untrusted content". | SAFE |
url_fetch | Fetches the content of a specific URL (single page). | SAFE |
apify_run | Runs an Apify actor to pull data (social/scraping). May incur external cost. | LOW |
social_read | Reads posts/comments from connected social connectors. | SAFE |
reddit_read | Reads threads/comments from Reddit (PRAW). | SAFE |
Generation & artifacts T1
Produces files and content; generated files are stored in the tenant's artifact store (not sent out). Getting a generated file out is a separate action — saving it to Drive, for example, requires approval.
| Tool | What it does | Risk |
|---|
doc_generate | Generates a Word/document (report, proposal, draft contract). The result can be saved to Drive. | SAFE |
pptx_generate | Generates a PowerPoint deck. The result can be saved to Drive. | SAFE |
xlsx_generate | Generates an Excel spreadsheet (data, calc, lists). The result can be saved to Drive. | SAFE |
image_generate | Generates an image. | SAFE |
list_artifacts | Lists files produced in this task. | SAFE |
email_draft | Prepares an email draft — does not send. Sending is a separate approval via email_send. | SAFE |
Memory & context T1
| Tool | What it does | Risk |
|---|
recall_history | Retrieves episodic summaries of past conversations ("last week's work"). | SAFE |
memory_save | Saves a fact/preference to user memory (consent-based). | LOW |
memory_delete | Deletes a saved memory. | LOW |
data_aggregate | Combines/summarizes gathered data (calc, grouping). | SAFE |
Scheduling T1
| Tool | What it does | Risk |
|---|
schedule_task | Sets a recurring/one-off task in natural language ("every morning at 8…"). | LOW |
schedule_list | Lists configured scheduled tasks. | SAFE |
schedule_cancel | Cancels a scheduled task. | LOW |
Email & Gmail T2
| Tool | What it does | Risk |
|---|
gmail_read | Reads an email. | SAFE |
gmail_search | Searches the inbox. | SAFE |
email_send | Sends an email. Recipient domain is subject to an allow-list; a "never silent" action. | MED |
gmail_forward | Forwards an email. | MED |
gmail_delete | Deletes an email — irreversible. | HIGH |
gmail_attachments | Lists email attachments / pulls them into a safe quarantine (to upload to Drive). With extract_text=true it also reads the text inside the attachment — PDF, Word, Excel, CSV; OCR for scanned PDFs. Extracted text is treated as external content and passes through quarantine. | SAFE |
Calendar & Drive
| Tool | What it does | Risk |
|---|
calendar_list_events | Lists calendar events. | SAFE |
calendar_create_event | Creates a calendar event (can add guests). | MED |
calendar_delete_event | Deletes an event. | MED |
drive_read | Reads a file from Google Drive and extracts the text inside it — PDF, Word (docx), Excel (xlsx), CSV and plain text; OCR kicks in for scanned (image-based) PDFs. | SAFE |
drive_upload | Uploads a file to Drive. From two sources: an email attachment (the quarantined file) and a file the agent generated itself — the output of xlsx_generate / doc_generate / pptx_generate (the artifact source). Missing folders are created; nested paths are allowed. | LOW |
🔒
Drive scope — the one-click connection only sees its own files. The one-click Drive Upload connection runs on Google's drive.file scope: the agent can see only the files and folders it created itself. It cannot see a folder you created by hand, so it cannot write straight into it. Two ways around it: (a) let the agent create the target folder tree and keep using that one, or (b) put a Google identity with the full drive scope (your own OAuth refresh token / a service account) into the Vault.
Data & system T2
| Tool | What it does | Risk |
|---|
http_request | Makes an HTTP request to an external API/endpoint. Target is subject to an egress allow-list. | MED |
db_query | Runs a query on a connected database. Target and write access are limited by allow-list. | HIGH |
E-commerce (Shopify) T2
| Tool | What it does | Risk |
|---|
shopify_query | Reads live store data (product, stock, order, customer) — GraphQL query. | MED |
shopify_mutation | Makes a change in the store (stock, order, refund, etc.) — GraphQL mutation. | HIGH |
🛍️
Customer-facing e-commerce answers inside the widget also use read-only helpers like search_products, search_orders, get_order_detail, search_customers. More: Shopify & e-commerce (soon).
Messaging & channels T2
| Tool | What it does | Risk |
|---|
whatsapp_send | Sends a WhatsApp message (API). | HIGH |
whatsapp_qr_send | Sends from a QR-linked (Baileys) WhatsApp line. | HIGH |
sms_send | Sends an SMS. | HIGH |
call_make | Starts an automated voice call (Make/telephony integration). | HIGH |
Social publishing T2
| Tool | What it does | Risk |
|---|
social_channels | Lists connected publishing channels (Postiz). | LOW |
social_post | Publishes/schedules a social post (Postiz). A public action. | HIGH |
Orchestration T2
| Tool | What it does | Risk |
|---|
delegate_task | Splits a large job across sub-agent(s); returns progress messages on long tasks. | HIGH |
Your own tools (MCP)
If the built-in 50+ tools aren't enough, connect your own MCP server. The tools it exposes are auto-discovered and pass through the same policy engine — meaning they're also subject to the T1/T2 classification, allow-lists and approval thresholds. More: Adding tools via MCP (soon).
⚠️
Confabulation guard: If a tool returns empty or errors, the agent doesn't invent a reason; it reports the situation with a diagnostic note ("possible causes…"). This prevents false excuses like "out of tokens / access blocked".
SemAgent