Tools

allowedTools controls the optional tools available to an agent. It is an allowlist, but two groups have special defaults:

vault_get, vault_list, register_outcome, http_fetch, and http_download are always registered. Vault tools are kept for legacy agent-scoped secrets; use Connections for new external API keys and integrations.
If allowedTools is omitted or empty, Polpo also registers the baseline coding tools: read, write, edit, bash, glob, grep, and ls.
If allowedTools is non-empty, include every coding tool the agent still needs. Optional tool categories and custom tools are never enabled implicitly.

Built-in catalog

Category	Tools
Coding	`read`, `write`, `edit`, `bash`, `glob`, `grep`, `ls`
Core and HTTP	`vault_get`, `vault_list`, `register_outcome`, `http_fetch`, `http_download`
Browser	`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_type`, `browser_press`, `browser_screenshot`, `browser_get`, `browser_select`, `browser_hover`, `browser_scroll`, `browser_wait`, `browser_eval`, `browser_close`, `browser_back`, `browser_forward`, `browser_reload`, `browser_tabs`
Images	`image_generate`, `image_analyze`
Video	`video_generate`
Audio	`audio_transcribe`, `audio_speak`
Search	`search_web`, `search_find_similar`
Email	`email_send`, `email_draft`, `email_list`, `email_read`, `email_search`, `email_download_attachment`, `email_verify`, `email_count`
Spreadsheets	`excel_read`, `excel_write`, `excel_query`, `excel_info`
PDF	`pdf_read`, `pdf_create`, `pdf_merge`, `pdf_info`
Word	`docx_read`, `docx_create`
Memory	`memory_get`, `memory_save`, `memory_append`, `memory_update`

Connections add explicit GitHub, Slack, Google Drive, remote MCP, channel, and API-key-backed tools. Project custom tools are enabled by their exact snake-case name.

Wildcards

The runtime expands these category wildcards:

browser_*  image_*  video_*  audio_*  search_*
email_*    excel_*  pdf_*    docx_*   memory_*

Connection tools do not have a catalog wildcard. List them explicitly.

{
  "name": "researcher",
  "allowedTools": [
    "read",
    "write",
    "grep",
    "search_*",
    "browser_*",
    "memory_*",
    "drive_search_files"
  ]
}

A wildcard grants every current tool in that category and may include new tools added in a later release. Use exact names where the grant must remain fixed.

Tool loading

Configure how an agent exposes its effective runtime tool palette with toolLoading.mode:

Mode	Behavior
`auto`	Default. Uses direct loading through 16 runtime tools and 49,152 serialized schema bytes, then switches to progressive loading.
`direct`	Exposes every effective runtime tool schema immediately. Use it for small, stable palettes or flows that require predictable visibility.
`progressive`	Gives the model catalog controls and lets it load exact granted tools before calling them natively.

{
  "name": "researcher",
  "toolLoading": { "mode": "auto" }
}

With progressive loading, the model receives catalog controls plus any explicitly preloaded tools:

polpo_tool_list and polpo_tool_search discover available tools.
polpo_tool_load adds exact tool schemas to the active set for the next model step.
Loaded tools are then called directly with their native schemas.

allowedTools remains the source of truth. Progressive loading can only discover and execute tools already granted to the agent; it does not expand permissions or expose secrets. The loading decision runs after execution-mode, Loop step, request, Route, and trusted-grant policies have narrowed the palette. Client-side OpenAI-compatible tools and provider-native tools remain directly exposed and do not count toward the automatic runtime-tool threshold. The legacy self-hosted router uses tool_read and tool_call as an execution indirection. Self-hosted deployments can still configure it with POLPO_TOOL_ROUTER=auto|on|off, POLPO_TOOL_ROUTER_THRESHOLD, and POLPO_TOOL_ROUTER_DIRECT_TOOLS. The two strategies are mutually exclusive for one request.

Audio providers

Audio tools use the model configured on the agent. audio_transcribe reads transcribe_model; audio_speak reads tts_model. Both fields use the provider/model format.

Capability	Providers	Example
Transcription	OpenAI, Deepgram	`deepgram/nova-3`
Speech	OpenAI, Deepgram, ElevenLabs, local Edge TTS	`deepgram/aura-2-thalia-en`

OpenAI, Deepgram, and ElevenLabs audio models call the provider directly and require the matching provider credential. Prefer managed routing or Connections where available; legacy direct-provider paths can still use the agent vault. edge/edge-tts runs in the agent sandbox and does not require a key. Audio traffic does not currently use the managed Model Gateway. For US English, start with deepgram/nova-3 for transcription and deepgram/aura-2-thalia-en for speech. Add a deepgram provider credential once; both tools reuse it.

{
  "name": "voice-agent",
  "allowedTools": ["audio_transcribe", "audio_speak"],
  "transcribe_model": "deepgram/nova-3",
  "tts_model": "deepgram/aura-2-thalia-en"
}

Filesystem access

allowedPaths restricts filesystem tools to selected paths. Relative paths resolve from the agent working directory; in Polpo Cloud that directory is /home/daytona/project/workspace.

{
  "name": "frontend-dev",
  "allowedTools": ["read", "write", "edit", "bash", "glob", "grep"],
  "allowedPaths": ["src/client", "src/shared", "public"]
}

If allowedPaths is omitted, access defaults to the workspace. Paths do not grant tools: the agent still needs the corresponding entries in allowedTools.

Getting Started

Platform

Agents

Orchestration

Built-in catalog

Wildcards

Tool loading

Audio providers

Filesystem access

​Built-in catalog

​Wildcards

​Tool loading

​Audio providers

​Filesystem access

Built-in catalog

Wildcards

Tool loading

Audio providers

Filesystem access