Skip to main content
When an agent calls a tool (MCP or page), the LLM generates the tool’s input parameters token by token. For small, creative inputs like “make a bar chart grouped by department” this works well. But when a tool needs a large structured payload, like a 10KB JSON data blob, an entire widget’s source code, or a full document, having the LLM reproduce that data is expensive, slow, and unreliable. The LLM will mangle JSON, truncate long strings, and burn tokens acting as a copy machine. Pass-through parameters solve this by splitting the tool call into two channels: the LLM generates the creative parts, and Mindset AI silently injects the data parts. The LLM never sees the data parameters in the tool schema, so it can’t try to generate them. The tool handler (whether it’s an MCP tool on the server or a page tool in the browser) receives the complete tool call as if the LLM had produced everything.

​
Why this matters

Consider a widget creation scenario. The user is viewing a dashboard with employee data. They ask the agent to “make a table showing this data.” The MCP tool create_widget needs two things:
  1. Instructions like “make a table with columns for name, department, and salary”. The LLM should generate this because it requires reasoning about what widget to build.
  2. The data payload (thousands of tokens of JSON). The LLM should not touch this because it adds zero value by copying it.
Without pass-through parameters, the LLM sees the data in its context, painstakingly reproduces it into the tool call (taking seconds and burning output tokens), and often gets it wrong (missing braces, truncated arrays, mangled escaping). With pass-through parameters, the data goes directly from the host page to the tool. The LLM focuses on what it’s good at: reasoning and creativity. The cost savings are significant. Output tokens (what the LLM generates) are typically 3-5x more expensive than input tokens. A 5,000-token JSON blob reproduced as output is pure waste. Pass-through eliminates it entirely.

​
When to use pass-through parameters

Use them when the host page already has data that a tool needs, and the LLM would only be copying it verbatim. Good candidates:
  • JSON data payloads from the host page’s API
  • Existing widget or document source code that needs editing
  • File references or URLs that the platform manages
  • Any structured data over a few hundred characters
Not the right fit when:
  • The LLM needs to generate or transform the data (that’s the LLM’s job)
  • The data originates from another tool’s output during the conversation (that’s LLM orchestration)
  • The LLM needs to reason about the data to give a good response (use situational awareness for that)
For data payloads, the best practice is to use both channels together. Situational awareness gives the LLM a summary to reason about, like “this is employee salary data with 50 records”, and pass-through parameters give the tool the exact JSON. Each channel does what it’s good at.

​
How pass-through compares to other data channels

Mindset AI has several channels for passing data from the host page to the agent system:
Pass-through parametersSituational awarenessPage tools
DirectionHost page to toolsHost page to agentAgent to host page
PurposeGive tools exact data without LLM involvementGive the agent context to reason aboutLet the agent take actions on the page
Who sees itThe MCP server onlyThe LLM (in its system prompt)Agent calls it; handler runs in browser
Data fidelityExact (byte-for-byte)Approximate (LLM interprets it)n/a (input flows the other way)
Token costZero LLM tokensUses prompt tokensZero LLM tokens for the call args (LLM still generates them)

​
Platform-managed parameters

Some parameters are managed entirely by Mindset AI as infrastructure-level transport mechanisms, so you don’t set them. The most important example is file uploads. When a user uploads an image in the chat UI, Mindset AI uploads it to cloud storage and generates a time-limited signed URL. That URL needs to reach MCP tools that can process images, but the LLM should never see it (it can’t fetch URLs, and it might hallucinate fake ones). Platform-managed parameters are always hidden from the LLM, regardless of whether a value exists. The host page doesn’t need to configure anything; Mindset AI handles the entire lifecycle. Current platform-managed parameters:
ParameterWhat it does
uploaded_file_urlsDelivers signed cloud storage URLs for user-uploaded files (images, PDFs) to any MCP tool that accepts them. The user uploads a file in the chat UI; Mindset AI handles storage, URL signing, and delivery to tools.

​
Setting pass-through parameters

Two ways to set pass-through values: an HTML attribute for static initial values, and a JavaScript method for dynamic updates.

​
HTML attribute

<mindset-agent
  agent-uid="your-agent-uid"
  passthrough-params='{
    "create_widget.data_payload": "{\"items\":[1,2,3]}",
    "edit_widget.current_mdx": "<Card>...</Card>"
  }'
></mindset-agent>
The passthrough-params attribute value is a JSON-encoded string. Write the JSON object inline (escaping quotes as needed by your HTML), with each key identifying a tool parameter and each value as the string to inject. The SDK parses the string on read. Both passthrough-params (kebab-case) and passthroughParams (camelCase) are accepted. For dynamic updates after the page loads, use the JavaScript method instead. It takes a real object, not a string.

​
JavaScript method

const agent = document.querySelector('mindset-agent');

agent.setPassthroughParams({
  'create_widget.data_payload': JSON.stringify(myData),
});
agent.setPassthroughParams() is sync. Call it once mindset.init() has completed and the element has fired mindset:agent-idle. See § When the element is ready to call. To clear all pass-through params, pass an empty object: 
agent.setPassthroughParams({});
The new values take effect on the next tool call.

​
Key formats

Two formats are supported for the keys in the pass-through params object.

​
Targeted: tool_name.parameter_name

Injects into exactly one tool’s parameter. Use when you know the specific tool and parameter. 
{
  "create_widget.data_payload": "{\"items\":[1,2,3]}",
  "edit_widget.current_mdx": "<Card>existing code</Card>"
}
In this example:
  • data_payload is stripped from create_widget’s schema only. Other tools that happen to have a data_payload parameter are unaffected.
  • current_mdx is stripped from edit_widget’s schema only.

​
Wildcard: parameter_name

Injects into any tool that has a parameter with that name. Use when the value should be available regardless of which tool the LLM decides to call. 
{
  "reference_image": "https://storage.googleapis.com/signed-url..."
}
If three tools all declare a reference_image parameter, all three have it stripped from their schemas and all three receive the injected value when called. A wildcard key injects into every tool that declares a parameter of that name. When you add new tools to the agent (MCP or page), review their schemas to make sure overlapping parameter names don’t introduce unintended injection. If you want a value scoped to one specific tool, use the targeted format (tool_name.parameter_name) instead. If both a targeted entry and a wildcard entry exist for the same parameter name, the targeted entry wins.

​
Combining with situational awareness

Pass-through parameters and situational awareness are complementary:
ChannelWhat it doesWho sees it
Situational awarenessPuts context in the LLM’s system prompt so it can reason about the dataLLM only
Pass-through parametersInjects exact data into tool calls without LLM mediationMCP server only
Typical pattern for a widget creation scenario: 
<mindset-agent
  agent-uid="your-agent-uid"
  situational-awareness='{"widget_data_summary": "50 employee records with name, department, salary"}'
  passthrough-params='{"create_widget.data_payload": "{\"items\":[...]}"}'
></mindset-agent>
The LLM reads SA to understand what kind of data it’s working with, so it can write good instructions like “make a bar chart with the items array”. The tool receives the exact JSON via pass-through, no token-by-token LLM reproduction.

​
For MCP tool authors

If you’re building MCP tools that should accept pass-through values from the host page or platform-managed parameters from the SDK, the following sections describe the contract.

​
Receiving uploaded files

If your tool should accept user-uploaded files, declare the parameter in your tool’s inputSchema: 
uploaded_file_urls: {
  type: 'string',
  description: 'JSON array of signed URLs for user-uploaded files.',
}
Mindset AI automatically hides this parameter from the LLM and populates it when files are available. Your tool receives a JSON array of time-limited HTTPS URLs you can fetch directly.

​
Receiving pass-through data from the host page

If your tool has a parameter that SDK embedders should supply via passthrough-params:
  1. Declare the parameter in your tool’s inputSchema as normal.
  2. Document the parameter name so embedders know to set it (e.g. create_widget.data_payload).
  3. The parameter is hidden from the LLM only when the embedder provides a value. If no value is set, the LLM sees the parameter as usual.

​
Requesting a platform-managed parameter

If your tool has a parameter that should always be hidden from the LLM (a platform transport mechanism, not a creative input), request that the parameter name be added to Mindset AI’s managed-params list. Mindset AI will handle stripping and injection automatically, regardless of whether a value exists.

​
For page tool authors

Pass-through works identically for page tools. When you register a page tool whose schema declares a parameter you want filled by the host page rather than the LLM:
  1. Declare the parameter in your setPageTools() schema as normal.
  2. Set the corresponding pass-through entry, either targeted (tool_name.parameter_name) or wildcard (parameter_name).
  3. The SDK strips the parameter from what the LLM sees and injects your value when the tool is invoked. Your handler receives args with the injected value already present, no extra plumbing.
agent.setPageTools([{
  name: 'submit_form',
  description: 'Submit the form the user is editing.',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Submitter name (LLM fills this)' },
      data_payload: { type: 'string', description: 'The form data JSON' },
    },
  },
  handler: async (args) => {
    // args.name came from the LLM; args.data_payload came from passthrough.
    return await myApp.forms.submit(args);
  },
}]);

agent.setPassthroughParams({
  'submit_form.data_payload': JSON.stringify(currentFormData),
});

​
Quick reference

ConceptDescription
passthrough-params attributeHTML attribute on <mindset-agent> to set initial pass-through values
agent.setPassthroughParams(obj)JavaScript method to set or update pass-through values dynamically
tool_name.parameter_nameTargeted format: injects into one specific tool
parameter_nameWildcard format: injects into any tool with that parameter
Platform-managedAlways-stripped parameters managed by Mindset AI (e.g. uploaded_file_urls)
Update timingTakes effect on the next tool call
PersistenceTransient per message, never saved to thread history
Clearingagent.setPassthroughParams({}) to remove all values

Situational awareness

Give the agent context to reason about the data.

Page tools

Let the agent take actions in the browser.

Data channels overview

How pass-through fits alongside the other channels.

Element methods

Full element method surface.