Data Tools

Pure JSON/structure manipulation tools for operating on any value — maps, arrays, or scalars. Zero credits, no external calls, no LLM. All tools accept either inline payload or a cache_ref from _meta.datagrout.cache_ref of any previous tool response. All Data tools are available at data-grout@1/data.*@1.

data.get@1

Access a value at a path within a nested structure.

Parameters

Parameter Type Required Default Description
payload any conditionally – JSON value to access. Provide either payload or cache_ref
cache_ref string conditionally – Cache reference from a prior tool call
path array yes – Ordered list of keys (strings) and indices (integers)

Example

{
  "name": "data-grout@1/data.get@1",
  "arguments": {
    "cache_ref": "rc_abc123...",
    "path": ["QueryResponse", "Invoice", 0, "TotalAmt"]
  }
}

Response: {"value": 150.00, "found": true}

data.pick@1

Keep only the specified keys from a map. If payload is a list of maps, picks from each one.

Parameters

Parameter Type Required Default Description
payload object | array conditionally – Map or list of maps
cache_ref string conditionally – Cache reference
keys array yes – List of key names to keep

Example

{
  "name": "data-grout@1/data.pick@1",
  "arguments": {
    "payload": {"name": "Alice", "age": 30, "email": "a@b.com", "internal_id": "xyz"},
    "keys": ["name", "age"]
  }
}

Response: {"data": {"name": "Alice", "age": 30}}

data.omit@1

Remove the specified keys from a map. If payload is a list of maps, omits from each one.

Parameters

Parameter Type Required Default Description
payload object | array conditionally – Map or list of maps
cache_ref string conditionally – Cache reference
keys array yes – List of key names to remove

data.take@1

Return the first N items from an array. When operating on a cache_ref, creates a structural-sharing view instead of duplicating data.

Parameters

Parameter Type Required Default Description
payload array conditionally – Array to take from
cache_ref string conditionally – Cache reference
n integer yes – Number of items to take

Response: {"data": [...], "count": N}

data.drop@1

Skip the first N items from an array and return the rest. Creates a view ref when using cache_ref.

Parameters

Parameter Type Required Default Description
payload array conditionally – Array to drop from
cache_ref string conditionally – Cache reference
n integer yes – Number of items to skip

data.keys@1

Return the keys of a map or the indices (0..n-1) of an array.

Parameters

Parameter Type Required Default Description
payload any conditionally – Map or array
cache_ref string conditionally – Cache reference

Response: {"keys": ["name", "age", "email"], "count": 3}

data.count@1

Count items in an array, keys in a map, or characters in a string.

Parameters

Parameter Type Required Default Description
payload any conditionally – Value to count
cache_ref string conditionally – Cache reference

Response: {"count": 42}

data.flatten@1

Flatten a nested map into a single-level map with dot-path keys.

Parameters

Parameter Type Required Default Description
payload object | array conditionally – Nested map or array
cache_ref string conditionally – Cache reference
separator string no "." Path separator

Example

{
  "name": "data-grout@1/data.flatten@1",
  "arguments": {
    "payload": {"user": {"name": "Alice", "address": {"city": "SF"}}}
  }
}

Response: {"data": {"user.name": "Alice", "user.address.city": "SF"}}

data.merge@1

Merge two maps together. Target values override base for conflicting keys.

Parameters

Parameter Type Required Default Description
base object conditionally – Base map (inline)
base_cache_ref string conditionally – Cache reference for base
target object conditionally – Map to merge on top
target_cache_ref string conditionally – Cache reference for target
deep boolean no false Recursively merge nested maps

data.filter@1

Filter items in an array using declarative predicate conditions with path-based field access. Works on any array — record maps, nested objects, or flat values. When operating on a cache_ref, creates a structural-sharing view.

Parameters

Parameter Type Required Default Description
payload array conditionally – Array to filter
cache_ref string conditionally – Cache reference
where array yes – List of condition objects

Each condition in where:

Field Type Description
path array Path to the value to compare (list of keys/indices). [] compares the element itself
field string Shorthand for path: [field] — use for simple record maps
op string Operator: eq, neq, gt, gte, lt, lte, in, not_in, contains, starts_with, ends_with, is_null, not_null
value any Comparison value (not needed for is_null/not_null)

Example: filter nested objects

{
  "name": "data-grout@1/data.filter@1",
  "arguments": {
    "cache_ref": "rc_abc123...",
    "where": [
      {"path": ["address", "state"], "op": "eq", "value": "CA"},
      {"field": "active", "op": "eq", "value": true}
    ]
  }
}

Response: {"data": [...], "count": 15, "removed": 85}

Example: filter flat array

{
  "name": "data-grout@1/data.filter@1",
  "arguments": {
    "payload": [1, 5, 10, 15, 20, 25],
    "where": [{"path": [], "op": "gte", "value": 10}]
  }
}

Response: {"data": [10, 15, 20, 25], "count": 4, "removed": 2}

data.sort@1

Sort any array. For flat arrays, sorts by value directly. For arrays of maps, use by to specify sort keys.

Parameters

Parameter Type Required Default Description
payload array conditionally – Array to sort
cache_ref string conditionally – Cache reference
by string | array no – Field name or list of sort specs with field/path and dir
dir string no "asc" Default direction when by is omitted or a simple string

Example: multi-field sort

{
  "name": "data-grout@1/data.sort@1",
  "arguments": {
    "cache_ref": "rc_abc123...",
    "by": [
      {"field": "department", "dir": "asc"},
      {"field": "salary", "dir": "desc"}
    ]
  }
}

Example: sort flat array descending

{
  "name": "data-grout@1/data.sort@1",
  "arguments": {
    "payload": [3, 1, 4, 1, 5, 9],
    "dir": "desc"
  }
}

Response: {"data": [9, 5, 4, 3, 1, 1], "count": 6}

data.unique@1

Deduplicate an array, keeping the first occurrence of each value.

Parameters

Parameter Type Required Default Description
payload array conditionally – Array to deduplicate
cache_ref string conditionally – Cache reference
by string no – Field name to deduplicate on (for arrays of maps)
path array no – Path to the value to deduplicate on (takes precedence over by)

Example

{
  "name": "data-grout@1/data.unique@1",
  "arguments": {
    "cache_ref": "rc_abc123...",
    "by": "email"
  }
}

Response: {"data": [...], "count": 42, "duplicates_removed": 8}

Using cache_ref with data tools

Every tool call response includes _meta.datagrout.cache_ref. Use this ref in subsequent data tool calls to avoid re-transmitting payloads:

[
  {"tool": "salesforce@1/get-all-accounts@1", "args": {}, "output": "accounts"},
  {"tool": "data-grout@1/data.take@1", "args": {"cache_ref": "$accounts._meta.datagrout.cache_ref", "n": 5}},
  {"tool": "data-grout@1/data.pick@1", "args": {"cache_ref": "$accounts._meta.datagrout.cache_ref", "keys": ["Name", "Industry"]}}
]

Cache entries have a 5-minute touch-on-access TTL. All cached data is AES-256-GCM encrypted at rest. Entries are isolated per user.