Variables in Agent Tool Calls

Variables let an agent reference interaction-scoped values in tool inputs. For example, an agent can send {{city}}, and Scout substitutes the value when the tool runs. Use variables for request-specific context such as a tenant, workspace, locale, or routing value.

What variables are

An interaction variable is a placeholder written in double curly braces that an agent can put in a tool input:

{
  "query": "latest weather in {{city}}"
}

When the agent calls the tool, Scout replaces {{city}} with the actual value before the tool receives it. The tool sees the resolved value, and the model never has to hold it. Interaction variables are values you supply when you start an interaction. Agents can reference them in runtime tool inputs during that interaction.

Why use variables

Interaction variables let your application provide request context without copying it into an agent’s prompt. Variables separate the two responsibilities:

Your application provides interaction values when it starts an interaction.
The tool input keeps a symbolic reference until execution.
Scout resolves the real value only when the tool executes.

An agent can use interaction variables to route a call to the correct tenant or workspace.

When values are resolved

Variables are resolved at tool execution time, the moment before a tool runs, not when the prompt is rendered. A placeholder stays symbolic throughout the agent’s reasoning and is substituted only as the tool is invoked.

Variables apply to tool inputs only. They are not interpolated into prompts, messages, or model context.

Syntax

Scout supports these interaction variable forms:

Syntax	Resolves from
`{{NAME}}`	A top-level interaction variable
`{{local.path.to.value}}`	An interaction variable at the specified path
`{{customer.email}}`	An interaction variable at the specified path

Resolution rules

For agent-authored runtime tool input:

{{NAME}} resolves from a top-level interaction variable.
{{local.*}} resolves only from interaction variables.
{{customer.email}}, a bare dotted path, resolves through interaction variables only.
Missing values resolve to an empty string.

Use interaction variables in agent-authored input for request-specific context such as tenant, workspace, locale, or routing metadata.

Type behavior

How a resolved value is typed depends on where the placeholder sits:

Whole-field placeholder: when a placeholder is the entire field value, the resolved value keeps its native type (object, array, number, boolean).
Embedded placeholder: when a placeholder sits inside a larger string, the resolved value is converted to a string.

For example, {{customer}} on its own can resolve to a full object, while "Bearer {{token}}" always resolves to a string.

Security model

Interpolation prevents Scout from placing a variable’s value directly in the model context before a tool call:

Values are resolved at tool execution time, not baked into the prompt.
The tool receives the resolved value only when it executes.

Interpolation is not a guarantee that a secret stays hidden. A tool can return, transform, or otherwise reveal its resolved input in model-visible output. Only interpolate secrets into tools and configuration surfaces whose input and output behavior you trust.

Examples

Interaction-scoped variable

Supply a variable when you start the interaction, then reference it by name in the message. The agent uses {{city}} in the search tool’s input, and Scout resolves it at execution time. Here $AGENT is your agent ID and $SECRET is a Scout API key.

curl --request POST \
  --url "https://api.scoutos.com/world/$AGENT/_interact" \
  --header "Authorization: Bearer $SECRET" \
  --header 'content-type: application/json' \
  --data '{
    "variables": {
      "city": "Charleston, SC"
    },
    "messages": [
      {
        "content": [
          "Search the web for latest weather in {{city}}. Only search once. Compact the results"
        ]
      }
    ]
  }'

Nested interaction variables

Variables can be objects, and you can reference nested values with a dotted path.

curl --request POST \
  --url "https://api.scoutos.com/world/$AGENT/_interact" \
  --header "Authorization: Bearer $SECRET" \
  --header 'content-type: application/json' \
  --data '{
    "variables": {
      "location": {
        "city": "Charleston",
        "state": "SC"
      }
    },
    "messages": [
      {
        "content": [
          "Search the web for latest weather in {{location.city}}, {{location.state}}. Only search once. Compact the results"
        ]
      }
    ]
  }'

What the agent emits versus what the tool receives

The agent emits tool input with placeholders still in place. Scout resolves them just before the tool runs, and the tool receives only the final values.

{
  "query": "latest weather in {{city}}",
  "headers": {
    "X-Tenant": "{{tenant.id}}"
  }
}

{
  "query": "latest weather in Charleston, SC",
  "headers": {
    "X-Tenant": "tenant_42"
  }
}

Native-type preservation

Because {{customer}} is the whole field, it resolves to the full object. Because {{customer.email}} is also a whole field, it resolves to the string at that path.

{
  "customer": "{{customer}}",
  "customer_email": "{{customer.email}}"
}

{
  "customer": {
    "email": "a@example.com",
    "name": "Scout Customer"
  },
  "customer_email": "a@example.com"
}

MCP per-call headers

MCP-backed tools accept a reserved headers input that lets an agent supply request headers for a single tool call. These headers are merged over the MCP connection’s base auth headers and are not forwarded as normal tool arguments. They only shape the outbound request. Configure credentials in the MCP connection or integration settings. This trusted configuration keeps standing authorization separate from agent-authored input. Use interaction variables in per-call headers only for non-sensitive, request-specific metadata such as tenant, workspace, locale, or routing values:

{
  "headers": {
    "X-Tenant": "{{tenant.id}}",
    "X-Workspace": "{{workspace_id}}"
  }
}

Here both values come from interaction variables and resolve when the tool executes. The MCP connection’s base headers provide authentication.

Do not use agent-authored per-call headers to carry credentials or secret references. An MCP tool can expose resolved header values through its output. Configure authentication on the trusted MCP connection instead.

Next steps

Agents Overview

See how agents pick tools and run the core agent loop.

MCP Server

Connect MCP-compatible tools and configure base transport headers.

Observability

Inspect tool inputs and outputs, with resolved values, in the Logs view.

Async Interactions

Start interactions programmatically and pass variables in the request.

Get Started

Agents

Workflows

Data & Storage

Integrations

Platform

Variables in agent tool inputs

What variables are

Why use variables

When values are resolved

Syntax

Resolution rules

Type behavior

Security model

Examples

Interaction-scoped variable

Nested interaction variables

What the agent emits versus what the tool receives

Native-type preservation

MCP per-call headers

Next steps

Agents Overview

MCP Server

Observability

Async Interactions

​What variables are

​Why use variables

​When values are resolved

​Syntax

​Resolution rules

​Type behavior

​Security model

​Examples

​Interaction-scoped variable

​Nested interaction variables

​What the agent emits versus what the tool receives

​Native-type preservation

​MCP per-call headers

​Next steps

Agents Overview

MCP Server

Observability

Async Interactions

What variables are

Why use variables

When values are resolved

Syntax

Resolution rules

Type behavior

Security model

Examples

Interaction-scoped variable

Nested interaction variables

What the agent emits versus what the tool receives

Native-type preservation

MCP per-call headers

Next steps