Tools & Function Calling

Tools extend what an LLM can do during execution. When a template has tools assigned, PromptShuttle automatically manages the tool-calling loop: the LLM decides which tools to call, PromptShuttle executes them, feeds results back, and re-invokes the LLM until it produces a final answer.

How the tool loop works

1. Send prompt + tool definitions to LLM
2. LLM responds with tool_calls (or final text)
3. If tool_calls:
   a. Execute all tool calls in parallel
   b. Append results to conversation
   c. Go to step 1 (re-invoke LLM with results)
4. If final text: return response

The loop continues until the LLM stops calling tools or the maxToolCalls limit is reached.

Tool types

PromptShuttle supports five tool types, each suited to different use cases:

Type	What it does
External	Calls an HTTP endpoint with parameters from the LLM's tool call
Virtual	Enables provider-native capabilities (web search, code interpreter)
Agent	Invokes another flow as a sub-agent, enabling multi-agent orchestration
CritiqueLoop	Runs a producer/critic refinement loop to iteratively improve output
MCP	Calls a tool on an external Model Context Protocol server

External tools

External tools call HTTP endpoints. The LLM decides the arguments; PromptShuttle builds the request and returns the response.

Configuration

Field	Description
name	Tool name (shown to the LLM)
description	What the tool does (helps the LLM decide when to use it)
parameters	Parameter schema (name, type, description, required, enum values)
webUrl	Base HTTP endpoint URL. An absolute https://… names a fixed host; a relative path (/api/v1/search) makes the tool caller-hosted
webUrls	Environment-specific URL overrides ({ "production": "https://...", "staging": "https://..." })
headers	Custom HTTP headers (e.g. API keys)
callbackTokenHeader	Header carrying the caller's per-run token on caller-hosted calls (default X-Tool-Token)

How it works

1. The LLM returns a tool call with arguments (e.g. { "query": "weather in Berlin" })

2. PromptShuttle sends an HTTP GET to the configured URL with arguments as query parameters

3. The response body (up to 1MB) is returned to the LLM as the tool result

Parameter placeholders in URLs

External tool URLs support [[param]] placeholders that are substituted from the flow's request parameters:

https://api.example.com/v1/[[region]]/search

If the flow was called with "parameters": { "region": "eu" }, the URL becomes https://api.example.com/v1/eu/search.

Environment-specific URLs

Use webUrls to point to different endpoints per environment:

{
  "webUrl": "https://staging-api.example.com/search",
  "webUrls": {
    "production": "https://api.example.com/search",
    "staging": "https://staging-api.example.com/search"
  }
}

Tools your own app serves

If the endpoint lives in the same application that calls PromptShuttle, its address differs on every machine that application runs on — so it does not belong on the tool at all. Give the tool a relative path instead and let each request supply the host:

{ "webUrl": "/api/v1/tools/search?schema_id=[[schema_id]]" }

The origin then comes from the X-Shuttle-Callback-Url header per request. If a request omits it, the tool call fails rather than falling back to a stored URL.

See Caller-Hosted Tools.

Virtual tools (provider-native)

Virtual tools enable capabilities built into the LLM provider, such as web search. They are handled natively by the provider — PromptShuttle passes them through.

Portable tokens

Use search or web_search to request web search. Both tokens map to the serving provider's own search tool, whatever its wire name is. Matching is case-insensitive.

Token you send	OpenAI	Gemini	Anthropic	xAI
search	web_search_preview	google_search	web_search	web_search
web_search	web_search_preview	google_search	web_search	web_search
social_search	—	—	—	x_search
x_search	—	—	—	x_search
url_context	—	url_context	—	web_search (degrades to search)

A token the serving provider does not offer is skipped, not failed — the model answers without the tool, so a fallback candidate degrades instead of dying. The run then records a vendorToolUnavailable warning (see Run Health) naming the skipped token. Before this warning existed the skip was silent.

Using virtual tools

Virtual tools can be enabled in two ways:

1. On the template — Create a tool with type: Virtual and virtualToolId: "search", then assign it to the template

2. At request time — Pass vendorTools: ["search"] in the flow run request

Citations

Search-grounded responses carry their sources in citations on the response payload (url, title, domain). Sources are unified across providers: OpenAI url_citation annotations, Gemini grounding chunks, xAI inline citations plus its top-level source list.

Combining vendorTools with a responseSchema is safe: PromptShuttle runs the research schema-free, adds one structuring turn when needed, and carries the research turn's citations onto the final structured answer. Measured provider behavior for a single combined call (the passthrough /chat/completions path): OpenAI keeps annotations alongside a JSON-schema response (measured 6/6, two model families, 2026-08-20); Gemini returns grounding chunks only unreliably under a schema (4 of 12 runs came back with zero chunks even though searches ran — both AI Studio and Vertex, gemini-3-flash-preview).

Agent tools

Agent tools invoke another flow as a sub-agent. This is the foundation of multi-agent orchestration in PromptShuttle.

Configuration

Field	Description
agentTemplateId	The ID of the flow to invoke as a sub-agent
maxAgentDepth	Maximum nesting depth for this specific agent (overrides tenant default)

How it works

1. The LLM calls the agent tool with arguments

2. PromptShuttle creates a child request linked to the parent

3. The child flow executes with its own tool-calling loop

4. The child's text response is returned to the parent LLM as the tool result

5. Cost is tracked both per-agent (direct) and across the tree (cumulative)

Safety mechanisms

• Depth limits — Default max depth is 10. Configurable per tool, per tenant, or per request.

• Cycle detection — PromptShuttle tracks the ancestor chain and prevents an agent from calling itself (directly or indirectly).

• Cost limits — Per-request cost ceilings apply across the entire agent tree.

Context tools

When a template is running as a sub-agent, PromptShuttle automatically injects context tools:

Tool	Description	Injected at
get_context	Returns execution metadata: depth, agent path, cost used, budget remaining	sub-agents only
get_original_input	Returns the root request's original user messages	sub-agents only
get_state	Read from shared state (lexically scoped — child values shadow parent)	all requests with tools
set_state	Write to shared state (visible to child agents)	all requests with tools

These let agents be context-aware without hardcoding parent/child relationships.

A root request (the one you start) is only given the two state tools. The other two answer questions a root request can already see: get_original_input replays the root's own messages back to the model that is already reading them, and get_context reports a depth of 0 on a path of one. The state tools stay because a root write lands on the root's state, and every descendant reads it — that is the supported way to seed state for a whole agent tree before spawning.

All four remain callable by name at any depth, so a prompt that names one directly keeps working.

CritiqueLoop tools

CritiqueLoop tools implement an iterative refinement pattern: a "producer" flow generates output, then a "critic" flow evaluates it. If the critic rejects the output, the producer tries again with the critic's feedback.

Configuration

Field	Description
producerFlowId	Flow ID of the producer
criticFlowId	Flow ID of the critic
maxLoopIterations	Maximum refinement iterations (default 3)

How it works

for each iteration (up to maxLoopIterations):
    1. Run producer with original input + last critique feedback
    2. Run critic with (original input + producer output)
    3. Critic returns: { "approved": true/false, "feedback": "..." }
    4. If approved → return producer output
    5. If rejected → feed critique back to producer, continue

The critic always runs with temperature: 0 for consistent evaluation.

Critic response format

The critic flow must return JSON matching this schema:

{
  "approved": true,
  "feedback": "The response addresses all key points."
}

If approved is false, the feedback string is passed back to the producer for the next iteration.

MCP tools

MCP tools call tools on external Model Context Protocol servers. This lets you integrate with any MCP-compatible tool server.

See MCP Server Integration for setup details.

Managing tools via API

Method	Endpoint	Description
GET	/api/v1/tools	List all tools
GET	/api/v1/tools/{id}	Get a tool by ID
POST	/api/v1/tools	Create a new tool
PUT	/api/v1/tools/{id}	Update a tool
DELETE	/api/v1/tools/{id}	Delete a tool
GET	/api/v1/tools/{id}/usage	List flows that reference this tool

Tool parameter schema

Each tool defines its parameters with a list of properties:

{
  "name": "search_api",
  "description": "Search for products by keyword",
  "toolType": "External",
  "webUrl": "https://api.example.com/search",
  "parameters": {
    "type": "Object",
    "properties": [
      {
        "name": "query",
        "description": "Search query string",
        "type": "String",
        "required": true
      },
      {
        "name": "category",
        "description": "Product category to filter by",
        "type": "String",
        "required": false,
        "enum": ["electronics", "clothing", "books"]
      },
      {
        "name": "limit",
        "description": "Maximum number of results",
        "type": "Number",
        "required": false
      }
    ]
  }
}

Property types: String, Number. Use isList: true for array parameters. Use enum to constrain values.