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.

​
allowedApps

When present, the token can only invoke tools belonging to the listed apps. Attempts to call tools from unlisted apps are rejected. Both the legacy tool-list and tool-call endpoints (/api/mcp/tools/list, /api/mcp/tools/call) enforce this claim. Omitting allowedApps grants access to all apps the token’s scope allows.
Create Token modal in AI Agents → MCP Tokens

The Create Token modal in AI Agents → MCP Tokens. Modal exposes Customer, Token Name, Description, Tool Scope, Usage Limit, Expires In — no toolMode or allowedApps controls.

The Create Token modal in the Partner Portal UI does not expose toolMode or allowedApps controls. The modal fields are: Customer, Token Name, Description, Tool Scope (a disabled dropdown with only “All Tools” / “Specific Tools” — no meta/full selector, no allowedApps field), Usage Limit, Expires In. toolMode and allowedApps are JWT-claim-only — they are honored when present in a token’s payload, but cannot be set from this UI. Any partner token minted from the Create Token modal is always full mode with all apps allowed. To mint a meta-mode or app-restricted token, mint it directly via the API / MCP route with the JWT claims set explicitly.

​
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 allowedApps 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.