Skip to main content

​
Why tool modes exist

A voice-agent token with scope:'all' previously gave the LLM access to ~283 tools simultaneously (155 from ElevenLabs alone). This degraded tool-selection accuracy and added latency. Meta mode solves this by giving the agent two gateway tools instead:
  • internal_search_tools — keyword-ranked search across all available tools (returns name + description)
  • internal_execute_tool — generic executor: the agent passes a tool name + arguments and the platform dispatches it
The agent now navigates a catalogue rather than holding 283 simultaneous function definitions.

​
Token types and their defaults

Voice agents default to meta to protect LLM context and tool accuracy. Partner-minted tokens (Cursor, Claude Desktop, Windsurf, automation scripts) still receive full tool access by default.

​
JWT claims for fine-grained control

When minting a token manually you can include two optional claims:

​
toolMode

Values: "full" | "meta". Omitting the claim defaults to "full" for partner-minted tokens.

​
apps (limit the token to chosen apps)

When present, the token can only use tools from the listed apps. Calls to any other app are refused. The older name allowedApps still works the same way; if you send both, apps wins. Leave both out to allow every app the token’s scope includes.

​
Mailbox access level

A token with access to all apps also includes the customer’s connected mailbox, if they have one. You can set how much it may do with the mailboxAccessLevel option: To keep a token away from email entirely, use apps and leave the mailbox out of the list.

​
Setting these options in the portal

The Create Token tab in the Partner Portal covers the most common case. Its Tool Scope menu offers All apps and tools, Specific apps (the same as apps), and Specific tools.
Tool Scope set to Specific apps, with a list of the customer's apps and how many tools each has

Tool Scope set to Specific apps in the MCP Token Manager

Meta mode (toolMode) and the mailbox access level can only be set when you create a token through the API. Tokens created in the portal use full mode, and the default read level for the mailbox.

​
How agents use meta mode

In meta mode the agent workflow changes:
  1. Discover — call internal_search_tools with a keyword (e.g., "social post") to get relevant tool names and descriptions.
  2. Execute — call internal_execute_tool with the tool name and parameters.
  3. Rate limits, credit charges, scope, and app-limit enforcement all apply inside internal_execute_tool exactly as they do for direct tool calls.

​
Revert to full mode for voice agents

Voice-agent tool mode is a platform-level default managed by Knotie. If you need your voice agents to receive the full tool list (e.g., for debugging a tool-selection issue), contact Knotie support to have the default changed for your account. The change applies to newly minted voice-agent tokens; in-flight tokens are unaffected until the call ends.

​
New agent-facing tools

The following tools are now available to agent tokens with appropriate scope: MEDIA_IMPORT_FROM_URL runs the URL through a safe-fetch validator (HTTPS-only, private/loopback IP rejection, ≤3 redirects) before downloading.