Tools: Process many files or mails one by one

When many files or mails each have to be read and assessed (“Check all 50 invoices and list amount, IBAN and due date”), the assistant does not read them one after another itself. That would fill its context and hit the model’s output limit. Instead it uses the tool Process items one by one (process_items): every item is read in its own run with a fresh context, and the assistant gets a table with one row per item holding the fields you asked for. It continues with that table, for example by writing a file or answering your question.

When it kicks in

• From about three files or mails that each have to be read, the assistant decides on its own to use the tool. You do not have to ask for it.
• One call takes at most 100 items (default, configurable up to 200). If more files match the pattern, the call is refused, not cut short. Then narrow the file pattern or the folder, for example “only the PDFs in the folder 2026-10”. The same applies to a mail list that is too long.
• Each item returns at most 12 fields.

Three sources

Source	What gets processed	Requirement
Workspace	Files in the attached workspace, optionally with a file pattern (e.g. *.pdf) and a subfolder	Desktop, workspace attached → Tools: workspace & Git (desktop)
Folder tool	Files in the root folder of a folder tool set up by your administrators	Desktop, folder tool with read access, enabled for chat or agents → Set up a folder as a tool (desktop)
Mails	Mails of one mail account	Mail tools available → Tools: email

Depending on the file, an item is read with Read PDF document, Read Office document or Read file, a mail with Read email, and a folder tool’s file with that tool’s own read functions. A run uses only read tools the assistant itself has.

What you need to do

• In chat: attach the workspace, or make sure mail tools or a folder tool are available. Without a suitable read tool, the chat does not offer the tool at all.
• In an agent: in the Tools tab, tick Process items one by one plus the matching read tools (Read PDF document, Read Office document, Read file, Read email) or the folder tool. → Agents

What comes back

The assistant receives a table: one row per item with your fields, a status and, where needed, a reason. Every item appears, even one that could not be read. The status words are always German:

Status	Meaning
ok	Item read, fields filled.
fehlgeschlagen (failed)	The item could not be read or assessed, e.g. a scanned PDF without a text layer, or a timeout. The reason is in the row.
Ausgabelimit (output limit)	The answer was too long for the model, even after a second attempt.
abgebrochen (cancelled)	The item was not processed because the call’s time budget ran out.

The runs only read: they never write, send or change anything. Whatever follows from the table, such as a payments.csv, the assistant does afterwards with its usual tools.

Progress and stopping

While the items are processed, the chat shows a step process_items in the activity area, e.g. “Elemente 3/10 (1 fehlgeschlagen)” (items 3/10, 1 failed). It updates after each finished item and at least every 30 seconds. In agent runs the same progress appears in the run log. By default up to four items run at the same time.

If you stop the answer, processing is cancelled and the result so far is discarded.

Time limits

• Each item has 120 seconds. If the answer is cut off at the output limit, there is one more attempt.
• In chat, one call has about 15 minutes in total. In an agent run the tool also holds back time so the agent can still work with the table.
• Whatever is not finished when the budget runs out is listed as abgebrochen; the call still returns its table.

Personal data

With the PII shield on, the runs behave like reading in chat:

• PDF and Office content is checked. A run’s model sees personal data only as placeholders.
• Text files (e.g. .txt, .csv, .md) reach the model unchanged, as in chat. → Tools: workspace & Git (desktop)
• The field values leave the run in clear text, so that real IBANs, for example, can be written to a file. Before the assistant sees the table, it is pseudonymized again.
• For a folder tool, its PII-exempt setting applies.
• If an agent has “Do not check read content for personal data” switched on, that applies to its runs as well. → Agents

More: The PII shield — pseudonymisation & re-identification

Costs

Every run is a model call of its own. The costs count toward the chat answer or the agent run that called the tool. In chat, CompanyWizard checks before the start whether your usage limit still allows it.

Dry run and confirmation

• Directly in chat the tool always runs for real. The chat has no dry run.
• In an agent’s dry run the tool is suppressed like a writing tool, because it triggers paid model calls. The agent then gets no table. → Create an agent and test it in a dry run
• If the chat delegates to an agent that wants to process items one by one, the assistant asks for your approval first, as with write actions. → Agent delegation in chat

Adjusting the limits

Administrators can change the limits in the configuration section Chat:ProcessItems (as an environment variable e.g. Chat__ProcessItems__MaxItems). Values outside the range are set to the nearest limit. ToolTimeoutSeconds is the exception: it is taken as is. At 15 seconds or less, every call fails with a note saying so.

Key	Default	Range	Meaning
MaxItems	100	1–200	Maximum items per call
Parallelism	4	1–16	Runs at the same time
ItemTimeoutSeconds	120	1–3600	Time per item and attempt in seconds
ToolTimeoutSeconds	900	above 15	Total time of one call in seconds
MaxIterationsPerItem	4	1–20	Model steps per run

Web and desktop

• The workspace and folder tools exist only on desktop. → Two deployment modes — web vs. desktop
• Mails work in the web edition only if your administrators have enabled the mail tools for chat (Mail:ChatToolsEnabled). On a desktop paired with the server, a locally set up mail account is needed.

Tip for skill authors

If a skill needs many files, its SKILL.md can lay out the way, for example: “Read each invoice PDF in the workspace one by one with process_items (fields: recipient, IBAN, amount, reference), write the table as payments.csv, then call the script sepa_from_csv.” That way the data from many documents comes together without filling the context, and the script computes with the original values. How script skills work and what they require: Script skills: build, approve and use Python scripts in skills