Tab: Tools

The Tools tab lists every tool registered with the engine and lets you toggle each one on or off for the current instance. Disabled tools are invisible to the assistant — the LLM does not see their schema, so it cannot call them.

Tool registration

Polyant ships with a built-in registry. Tools self-register at boot: each tool lives in its own *.tool.ts file under packages/engine/src/agents/tools/. Adding a tool is a one-file change; no central registry to update.

For the full schema of every tool (input/output shapes, required env vars, harness flag), see Tool catalog reference. For the architectural model behind tools (registry, dispatch, harness injection), see Tools concept.

Activity stream

When the activity-stream module is enabled, every tool invocation emits a live event on the SSE feed surfaced by the Activity screen (see Overview). The event carries the instance slug, tool name, input arguments (redacted for sensitive tools like slackPostMessage), and outcome. This is the recommended way to observe in-flight agent behavior without tailing engine logs.

spawnTask recursion guard

spawnTask is now guarded against infinite recursion: any transitive spawnTask call from inside a spawned task is rejected at dispatch time (the guard refuses all nested spawnTask calls, not just those past a depth threshold). This prevents runaway fan-out when an agent’s prompt accidentally recurses on its own delegation pattern. The previous behavior (silent fan-out until the LLM context ran out) is gone.

Categories

Tools are presented in groups. The grouping is informational — there is no functional difference between categories.

Channel I/O

• send_outbound_message — sends a message to a connected channel from inside the agent loop. Used for proactive notifications and Room cycles.
• slackPostMessage — posts a message to a Slack channel or DM via the instance’s Slack credentials. Resolves user IDs (U...) automatically by opening a DM. Works cross-channel: a conversation that came in on WhatsApp, web, or a webhook can still post to Slack — the inbound channel is irrelevant, only the outbound slack channel configuration on the instance matters. Optional slack_allowed_channels secret enforces an allowlist of destinations.
• send_whatsapp_template — sends a pre-approved WhatsApp template message via Twilio.

Memory

• saveMemory — explicitly persists a fact to long-term memory.
• searchMemory — hybrid (vector + FTS) search over the memory store.

Knowledge base

• searchKnowledge — search the per-instance knowledge files.
• getKnowledge — fetch a single knowledge file by path.
• writeKnowledge — create or update a knowledge file.

Web and HTTP

• webSearch — multi-provider web search (Tavily / SerpAPI / DuckDuckGo, selectable via search_provider). The corresponding tavily_api_key / serpapi_api_key lives in instance secrets when the provider needs one.
• httpRequest — generic HTTP request with SSRF protection and instance-scoped auth.
• curl — escape-hatch tool that mirrors the curl CLI.

HubSpot CRM

• hubspotContact — create, update, get, search contacts (with custom properties).
• hubspotGetCompany — companies.
• hubspotDeal — deals.
• hubspotTicket — tickets.
• hubspotMeeting — meetings.
• hubspotNote — notes.
• hubspotCreateTask — tasks.
• hubspotSendEmail — transactional email through HubSpot.

All HubSpot tools require an hubspot_api_key (lowercase) in instance secrets.

GitHub

• ghIssue — create, comment, close, assign issues.
• ghPR — list, comment, review pull requests.

Both require a github_token (lowercase) in instance secrets.

Files and shell

• readFile, writeFile, listDirectory — work inside the per-instance, per-conversation sandbox.
• gitCloneRepo — clone a Git repo into the sandbox (with secure credential handling).

Skills and automation

• readSkill — load a skill bundle into the conversation.
• scheduleTask — schedule a future agent invocation (cron / interval / one-shot).
• spawnTask — meta-tool that spawns an ad-hoc sub-agent for a single bounded task. Transitive spawnTask calls from inside a spawned task are rejected (no nested spawn at any depth).

Agent-to-agent

• ask_<target_slug> — synthesized at runtime for every instance whose agent channel is enabled. The supervisor calls them like any other tool to delegate a sub-task to a peer agent. See concepts/channels.md for details.

Room control (harness tools)

• send_message_to_human — send a message on the room’s outbound channel.
• mark_events_completed — mark one or more events from the backlog as handled.
• compact_room_history — explicitly compact the room’s conversation history.

These are harness tools (harness: true): injected only inside Room cycles (see Room tab) and never appear on the Tools tab toggle list.

Misc

• verifyDocument — multimodal validation of an uploaded image/PDF (e.g. utility bill).
• fileUpload — upload a file to the instance’s S3 bucket.
• updateSoul, updateUserProfile — runtime self-modifications to specific prompt sections.

Toggling

To enable or disable a tool, click the switch on the row and Save at the top. The change applies to new conversations immediately. In-flight conversations finish with the previous tool set.

When tools need credentials

Many tools need API keys (HubSpot, Twilio, Tavily, GitHub). Those credentials live not on the Tools tab but on the Skills tab — see Skills tab. The pattern is:

1. Enable the relevant skill (HubSpot, GitHub, Tavily, etc.).
2. Fill in the skill’s environment variables (encrypted at rest).
3. The tools that depend on those env vars become functional.

A tool that is enabled but missing credentials will return an error to the LLM, which the assistant will surface as “I cannot do that right now” rather than crashing.