Tool Catalog

This page lists every tool the OSS engine registers at boot. Tools self-register by calling registerTool(...) inside packages/engine/src/agents/tools/*.tool.ts¹. The registry is loaded by loadAllTools() and exposed at runtime via getToolRegistry(); the admin UI fetches the same data through GET /api/tools.

Conventions

name — exact identifier the LLM uses to call the tool. Most tools use camelCase; harness tools and a few generic core tools use snake_case to match OpenAI’s tool-name regex ([a-zA-Z0-9_-]).
category — free-form grouping used only by the admin UI to organise the toggle list. No runtime semantics.
requiredSecrets — per-instance secret keys (rows in instance_secrets) that must be present for the tool to operate. Surfaced as a “missing configuration” warning in the admin panel via GET /api/instances/:slug/tools/required-secrets.
harness — when true, the tool is hidden from the admin UI’s per-instance toggle list and is only injected by the supervisor when includeHarness matches its category (typically room, whatsapp, or conversation-trigger). Bypasses the instance_tools table.
metaTool — when true, the tool is built specially by the supervisor because it needs the rest of the built tool set as input (e.g. spawnTask).

Core memory tools

Name	Category	Required secrets	Notes
`saveMemory`	memory	—	Persist a fact to long-term memory. Embedded and deduplicated (cosine ≥ 0.90).
`searchMemory`	memory	—	Hybrid search across memories: pgvector + Postgres FTS merged via RRF.

Knowledge tools

All three knowledge tools are additionally gated by the per-instance knowledgeEnabled flag — when it is false they are stripped from the supervisor’s tool set regardless of whether they appear in instance_tools (see packages/engine/src/agents/supervisor/index.ts:224).

Name	Category	Required secrets	Notes
`searchKnowledge`	knowledge	—	Hybrid search over the instance’s knowledge documents.
`getKnowledge`	knowledge	—	Fetch a single knowledge doc by filename. Returns the full body.
`writeKnowledge`	knowledge	—	Create or overwrite a knowledge doc. Triggers re-embedding.

Prompt-section editors

These tools are generated via createPromptUpdaterTool() (packages/engine/src/agents/tools/shared/update-prompt-section.ts). Both run an LLM pass to integrate the change into the existing section content.

Name	Category	Required secrets	Notes
`updateSoul`	prompt	—	Edit the personality section (`02-soul`) — name, tone, style, behavior, values.
`updateUserProfile`	prompt	—	Edit the user identity section (`07-user-identity`) — stable user facts.

Research / web

Name	Category	Required secrets	Notes
`webSearch`	research	`search_provider` (select), plus a provider key	`search_provider` is a typed select with choices `tavily
`curl`	research	—	Fetch a URL with `curl` semantics. Read-only HTTP `GET` / `HEAD` with redirect following.

HTTP / integrations

Name	Category	Required secrets	Notes
`httpRequest`	integration	—	General-purpose HTTP client. Supports any method, headers, JSON / form / raw bodies. Strict-mode SSRF guard: blocks private CIDRs and link-local addresses.

CRM (HubSpot)

All HubSpot tools require hubspot_api_key (private app token). They share the helper modules hubspot-fetch.ts (rate-limit-aware client), hubspot-rich-text.ts (markdown→HubSpot rich text), and hubspot-portal.ts (portal URL builder for deep links).

Name	Category	Required secrets	Notes
`hubspotContact`	crm	`hubspot_api_key`	CRUD for contacts. Search supports `filters`, `returnProperties`, `limit`, `after` for pagination. Create/update accept `customProperties: Record<string, string>` for arbitrary HubSpot custom properties (the tool never hardcodes property names).
`hubspotGetCompany`	crm	`hubspot_api_key`	Search/fetch companies by name or domain.
`hubspotDeal`	crm	`hubspot_api_key`	CRUD for deals. Stage values are HubSpot pipeline stage IDs.
`hubspotMeeting`	crm	`hubspot_api_key`	CRUD for meeting engagements. Associates with contacts and deals via `contactId` / `dealId`.
`hubspotNote`	crm	`hubspot_api_key`	CRUD for notes. Body is markdown — converted to HubSpot rich text server-side.
`hubspotTicket`	crm	`hubspot_api_key`	CRUD for support tickets. Returns ticket category, priority, owner.
`hubspotCreateTask`	crm	`hubspot_api_key`	Create a task engagement (assigned to the contact owner). Priority, due date, body.
`hubspotSendEmail`	crm	`hubspot_api_key`	Send an email to a HubSpot contact via the marketing email API. Logs in the contact timeline.

Dev / code

Name	Category	Required secrets	Notes
`gitCloneRepo`	dev	`github_token`	Clone a GitHub repo to the per-instance workspace. Writes a token credential helper (`.git/polyant-token`, `.git/polyant-askpass.sh`) so subsequent `git` operations authenticate. Files are cleaned up on conversation end or by the 2h stale sweeper.
`ghIssue`	dev	`github_token`	Create / read / update / close / comment on GitHub issues. Supports labels, assignees, milestones.
`ghPR`	dev	`github_token`	Create / read / update / merge / comment on pull requests. Supports draft mode, reviewer assignment.
`readFile`	dev	—	Read a file from the per-instance workspace. Path sandbox: refuses anything outside `workspaces/<instanceId>/`.
`listDirectory`	dev	—	List a workspace directory. Same sandboxing as `readFile`. Returns entries with type (`file` / `directory`) and size for files.
`writeFile`	workspace	—	Write a file inside the per-instance workspace. Same sandboxing.

Messaging

Name	Category	Required secrets	Notes
`slackPostMessage`	messaging	`slack_allowed_channels` (optional)	Generic, framework-first. Accepts `channel` (`#channel`, `Cxxx`, or `Uxxx` user IDs — adapter opens a DM) and `message`. Uses the instance’s Slack channel credentials via `channelManager.sendOutbound`. Cross-channel by design: the inbound channel is irrelevant — the tool always routes through the instance’s configured Slack channel, so a conversation that started on WhatsApp, web, or a webhook trigger can still fan out to Slack. Requires the `slack` channel to be configured on the instance. The optional `slack_allowed_channels` secret (comma-separated allowlist of `#name` / `Cxxx` / `Uxxx`, case-insensitive exact match) acts as a guardrail — when set, the tool refuses any destination not in the list. The message body is never logged in audit (only length).
`send_whatsapp_template` *	whatsapp	—	Send a pre-approved WhatsApp template message via the configured Twilio WhatsApp channel. Harness tool — only available inside the room/proactive context.

* harness: true — injected only when the supervisor runs with includeHarness containing whatsapp.

Document handling

Name	Category	Required secrets	Notes
`verifyDocument`	document	—	LLM-driven verification of an uploaded document against a checklist. Uses the instance’s configured AI provider (tier `standard`).
`fileUpload`	storage	`aws_access_key_id`, `aws_secret_access_key`, `aws_region`, `s3_bucket_name`	Upload an attachment from the current message (or supplied base64) to S3. Returns a public-ish key that resolves via `GET /api/attachments/*key`.

Skills

Name	Category	Required secrets	Notes
`readSkill`	skills	—	Load the current version of a global skill by slug. Returns frontmatter metadata + markdown body.

Scheduling

Name	Category	Required secrets	Notes
`scheduleTask`	agent	—	CRUD for scheduled tasks (cron or one-shot). Supports relative `runAt` (`+20m`, `+1h`, `+2d`). Persisted in the `scheduled_tasks` table — managed by the same backing store as the Scheduled Tasks REST API.

Agent

Name	Category	Required secrets	Notes
`spawnTask`	agent	—	Meta-tool (`metaTool: true`). Delegates a task to an isolated sub-agent with a separate context. The sub-agent inherits the parent’s tool set but not its history.

Room (harness)

All room tools are harness: true — injected by the supervisor only when running under the room scheduler (the synthetic room channel), not equipped for regular conversational replies.

Name	Category	Required secrets	Notes
`send_message_to_human`	room	—	Send a proactive message to the configured outbound channel (Telegram / Slack / WhatsApp). Plain text only — no rich formatting.
`mark_events_completed`	room	—	Mark one or more backlog events as `completed`. Scoped by `instanceId`. Returns the count of rows updated.
`compact_room_history`	room	—	Trigger a compaction pass on the activity log (daily → weekly → monthly buckets). Idempotent.
`send_outbound_message`	conversation-trigger	—	Send a one-off outbound message that opens a new conversation (used by scheduled tasks and webhook triggers). Harness-only.

Synthetic `ask_{slug}` agent tools

The agent-to-agent channel (packages/engine/src/agents/tools/agent-invoke.helpers.ts) generates one tool per peer instance at supervisor build time. These do not live in any *.tool.ts file — they are constructed dynamically by buildAgentInvokeTool() and never appear in the tools DB table.

Synthetic name format	Description
`ask_<target_slug>` (hyphens → `_`)	Invoke the peer instance with a free-form natural-language prompt. Recursion bound: max depth 1. Per-call timeout: `AGENT_CALL_TIMEOUT_MS` (default 60s). Parent aborts propagate.

The full description includes the target instance’s name and description, e.g.: Call agent "ResearchHelper" with a free-form natural-language prompt. Use when: <target description>.

Not in OSS

A few tools sometimes referenced in external docs are not part of the OSS engine — they belong to managed-tier deployments and are intentionally excluded from this codebase:

claudeCode — sandboxed Claude Code agent runner.
createSkill, runSkillScript — operator-grade skill authoring tooling.
bookingSearchSlots — booking-system integration.
markdownToPdf — PDF rendering pipeline.
renderService — Render.com deployment automation.

If you see one of these in the wild, it is a non-OSS extension. The OSS surface is the catalog above.

The one exception is spawnTask, which is registered from packages/engine/src/agents/tools/task-tool.ts (no .tool.ts suffix) because it is a meta-tool built by the supervisor with the rest of the tool set as input. ↩