Tools for agents: UTF-8 byte-budget JSON batching

Partition ordered JSON records into request-sized arrays with exact UTF-8 byte counts and copyable serialized bodies.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-json-batches/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call batch_json_by_bytes

records may contain any finite JSON values, including objects, arrays, scalars and null. Each output json field is a complete compact JSON array body, serialized with literal Unicode and no optional whitespace. utf8_bytes measures that string encoded as UTF-8, including array brackets and commas. It excludes HTTP headers, compression and the enclosing MCP response. Use the returned string verbatim when its exact budget matters: a client serializer can escape Unicode or format numbers differently. Batches preserve record order, never split a record, and greedily include the longest next contiguous prefix that fits. Source ranges are zero-based half-open [start_index,end_index). Empty input returns no batches. max_bytes is an integer of at least two; a record too large to fit alone fails the entire call with its index and required bytes. Nonfinite numbers and unpaired Unicode surrogates fail. Input lexical formatting and duplicate JSON object keys are not recoverable from parsed values. No request is sent and records are not persisted.

Input and output schemas
{
  "name": "batch_json_by_bytes",
  "title": "UTF-8 byte-budget JSON batching",
  "description": "Partition records into maximal consecutive compact JSON arrays within a UTF-8 byte budget; return exact serialized request bodies and source ranges.",
  "inputSchema": {
    "$defs": {
      "JsonValue": {}
    },
    "properties": {
      "records": {
        "items": {
          "$ref": "#/$defs/JsonValue"
        },
        "title": "Records",
        "type": "array"
      },
      "max_bytes": {
        "title": "Max Bytes",
        "type": "integer"
      }
    },
    "required": [
      "records",
      "max_bytes"
    ],
    "title": "batch_json_by_bytesArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "batch_json_by_bytesDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-json-batches/call
Content-Type: application/json

{
  "records": [
    {
      "id": 1,
      "text": "caf\u00e9"
    },
    {
      "id": 2,
      "text": "\u6771\u4eac"
    },
    null,
    {
      "id": 3,
      "text": "ready"
    }
  ],
  "max_bytes": 50
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

UTF-8 body budgets include structural bytes

Read the explanation

The source contract counts the exact UTF eight bytes of compact serialized array bodies. In the supplied example, the first object with id one and text cafe accented e takes twenty three bytes before array brackets. The second object containing Tokyo takes twenty four. Joining them needs one comma and two brackets, making fifty bytes. This is the complete body budget, excluding headers, compression and the enclosing response. With budget fifty, the first two objects fit exactly. Adding null costs its four letters and another comma, reaching fifty five, so the third record starts the next batch. Null and the final ready object occupy thirty bytes including their comma and brackets. The ranges are zero based and half open: first zero to two, then two to four. Records are never split and order is preserved. Lowering the limit to twenty four cannot fit even the first object plus brackets, which needs twenty five bytes. The contract rejects the whole call with the offending index and required bytes. Empty input returns no batches; nonfinite values and unpaired surrogates are invalid. Use the returned serialized body verbatim because another serializer can escape Unicode differently. These are source-contract examples: no backend or MCP request was made and local offline controls do not prove server execution.

UTF-8 Byte-Budget JSON Batching

How does batching JSON records by UTF-8 byte budget account for array syntax overhead and literal Unicode encoding?

The batch_json_by_bytes tool partitions an ordered sequence of arbitrary finite JSON records into contiguous JSON array batches without exceeding a designated byte threshold. Because each batch is serialized as an array, the computation adds overhead for outer square brackets (2 bytes) and value-separating commas (1 byte per boundary) while measuring characters in raw UTF-8 bytes rather than UTF-16 code units.

The algorithm is strictly greedy and contiguous: it does not reorder or bin-pack records to maximize capacity utilization. If any individual record wrapped in its own single-element array exceeds max_bytes, the entire operation fails with a validation error rather than truncating or splitting the record. The byte tally accounts strictly for the compact JSON string, omitting transport-level HTTP headers, TLS overhead, or content encodings like gzip.

Try a worked example

Clicking 'Run tool' with the default four records and max_bytes set to 50 evaluates records greedily. Record 0 ('café') compacts to 21 bytes and Record 1 ('東京') compacts to 26 bytes. Combined with outer brackets (2 bytes) and one comma separator (1 byte), batch 0 spans [0, 2) and consumes exactly 50 bytes (21 + 26 + 2 + 1 = 50). Because adding record 2 (null, 4 bytes + 1 comma separator = 5 bytes) would require 55 bytes and exceed 50 bytes, a new batch starts. Batch 1 spans [2, 4) with null (4 bytes) and Record 3 ('ready', 23 bytes) plus brackets and comma, totaling 30 bytes.

Array Framing and Separator Byte Accounting

In RFC 8259, an array consists of square brackets surrounding zero or more values separated by commas. The batching algorithm accounts for this structural framing by initializing batch overhead at 2 bytes ('[' and ']') and adding 1 byte for each value separator comma when more than one element is bundled. RFC 8259 - The JavaScript Object Notation (JSON) Data Interchange Format

UTF-8 Multi-Byte Character Measurement

RFC 8259 Section 8.1 requires JSON text exchanged between systems to be encoded in UTF-8. The tool outputs compact JSON strings with literal Unicode rather than ASCII escape sequences; multi-byte characters such as 'é' (2 bytes) and CJK ideographs like '東' and '京' (3 bytes each) are measured by their exact encoded byte size rather than string character length. RFC 8259 - The JavaScript Object Notation (JSON) Data Interchange Format

Sources and further reading