Skip to main content
response_mask is an optional field on API tool definitions that controls which fields from a tool’s HTTP response are forwarded to the AI model in subsequent conversation turns. Without a mask, the full response body is stored in conversation history and re-sent to the model on every turn. For APIs that return large objects — say, a 70+ key flow document — this accumulates quickly and increases both latency and cost. A response_mask lets you declare exactly which fields the model needs, discarding the rest before the response enters history.

​
Format

The mask is a plain JSON object. Each key corresponds to a field in the response body. The value is either:
  • true — keep the field’s value as-is (any type: scalar, array, nested object)
  • A nested mask object — recurse into the field, applying the inner mask
Keys absent from the mask are dropped. 
{
  "response_mask": {
    "_id": true,
    "last_action_number": true,
    "members": {
      "_id": true,
      "email": true
    },
    "blocks": {
      "block_id": true,
      "type": true,
      "service_item": {
        "title": true,
        "price_per_unit": true
      }
    }
  }
}

​
Array handling

Arrays are transparent to the mask. When a masked field contains an array, the mask is applied to each element individually. You don’t need to declare that a field is an array — the same nested mask works regardless. 
// Response
{ "blocks": [{ "block_id": "abc", "type": "service", "styles": {} }] }

// Mask
{ "blocks": { "block_id": true, "type": true } }

// Result stored in history
{ "blocks": [{ "block_id": "abc", "type": "service" }] }
For arrays of scalars (e.g. ["id1", "id2"]), use true — there’s nothing to recurse into: 
{ "applied_service_charges_ids": true }

​
Tip: preserve decision fields

Use masks to keep only the fields the model needs for the next decision, especially for large objects like flows or search results. Make sure the mask still includes the fields that distinguish meaningful states such as “found”, “not found”, and “failed”. For example, for a contact lookup, keep identifiers and user-facing fields like _id, full_name, and email. Avoid masking a response so aggressively that matched objects become {} or large responses get truncated before the model can tell what happened.

​
Behaviour

ScenarioResult
response_mask omittedNo filtering; full response stored in history
Field present in mask, present in responseField included in history
Field present in mask, absent in responseField silently omitted (no error)
Field absent from mask, present in responseField dropped from history
Response is not a JSON objectMask is skipped; full response stored
Nested mask on a scalar valueScalar returned as-is
Mixed-type arrays — for example, a blocks array containing both container blocks and service blocks — are handled naturally. Fields absent from a given element are simply omitted for that element.