Inputs and Tools

Inputs and tools make Actions useful in real business flows.

Together, they define what data an Action can receive and what external capabilities it can use.

Inputs

Inputs are data provided when an Action runs. These can come from API calls or other external sources.

Examples:

• files,
• invoice details,
• invoice image,
• metadata values,
• user-provided JSON.

Define input types carefully so Action Flows can validate required data before a run.

Input Design Principles

• Keep input names descriptive and stable.
• Use explicit required/optional semantics.
• Prefer predictable structures over free-form payloads.
• Test with realistic sample data, not idealized examples.

Well-defined inputs reduce runtime errors and make Actions easier to reuse.

Tools

Tools let steps call external capabilities, such as APIs or custom logic.

Use tools when an Action Flow needs information or operations outside the model itself.

Typical tool scenarios include:

• looking up reference data,
• sending or updating records in external systems,
• calling internal APIs,
• and enriching step outputs with trusted system data.

Mapping Inputs to Tools

Most production Action Flows map input values into tool requests. Keep this mapping explicit.

Example pattern:

1. Validate input values in early steps.
2. Transform values into the expected API format.
3. Call a tool with only required fields.
4. Handle tool failures with clear fallback or error behavior.

Output Filters (JSONPath-like)

Input and Tool responses are often larger than what an LLM step actually needs.

To reduce prompt size and noise, each Step Input assignment and Step Tool assignment supports an optional outputFilter field.

When set, the filter is applied to JSON responses before the data is added to step context/output.

In Action Studio, outputFilter is shown as a separate field, while being stored as part of the step assignment configuration JSON.

Why use output filters

• Reduce token usage by keeping only relevant fields.
• Improve model focus by removing unrelated response data.
• Make step outputs easier to inspect in logs.

Supported syntax

The filter uses a JSONPath-like subset (not full JSONPath):

• $.field
• $.field.nested
• $.arrayField.0
• $.arrayField[*]
• $.arrayField[*].{fieldA,fieldB} (projection extension)
• field.nested (without $)
• $ (keep full JSON as-is)

Examples:

• $.data.items -> returns the items node under data
• $.data.items.0.id -> returns the first item id
• $.phoneNumbers[*].{number,country} -> returns each phone number with only number and country
• result.total -> returns total under result

Projection example:

{
  "userId": "user789",
  "name": "Bob K.",
  "phoneNumbers": [
    { "type": "home", "number": "555-0201", "country": "+358" },
    { "type": "mobile", "number": "555-0202", "country": "+358" }
  ]
}

Filter:

$.phoneNumbers[*].{number,country}

Result:

[
  { "number": "555-0201", "country": "+358" },
  { "number": "555-0202", "country": "+358" }
]

Another projection example:

Behavior notes

• Filtering is applied only to JSON-like response payloads.
• Binary responses (for example PDFs/images) are not filtered.
• If outputFilter is empty, full response data is kept.
• If path does not match, the filtered result is null.
• If response is plain text/non-JSON, filtering is skipped and original data is kept.

Practical guidance

• Start with the smallest field that still gives the next step enough context.
• Prefer stable paths that do not depend on optional branches.
• Avoid filtering out fields needed by downstream prompt templates or tools.
• Validate filters using realistic response examples before production rollout.

Best Practices

• Keep input contracts stable and descriptive.
• Mark required inputs clearly.
• Use least-privilege credentials for tool connections.
• Handle tool errors gracefully and expose useful logs.

Common Pitfalls

• Passing large raw payloads between many steps without normalization.
• Making tool calls with ambiguous or unvalidated identifiers.
• Treating model output as trusted input for external writes without checks.

---