Agentic Context Description Language (ACDL)

• ACDL is a domain-specific language for describing the structure and evolution of context in agentic systems, modeling roles, dynamic content, and explicit time indexing.
• It distinguishes between prompt engineering and context engineering by formally specifying how instructions, observations, and tool outputs are organized across steps.
• The language supports visual rendering and standardized documentation, enabling clear comparative analysis of prompt architectures in different agentic systems.

Searching arXiv for the primary paper and closely related prompt-description languages so the article can cite the relevant works directly. Agentic Context Description Language (ACDL) is a domain-specific language for describing the structure and temporal evolution of the context sent to LLMs in agentic systems. It was introduced to address the absence of a standard, precise, and readable way to specify how an LLM context is assembled from instructions, observations, history, tool outputs, summaries, retrieved memory, and internal state across turns and substeps. In contrast to informal prose, ad hoc diagrams, or code inspection, ACDL is intended to capture the full architecture of a prompt in an implementation-agnostic form, while also supporting visual rendering and whiteboard-level communication (Pelc et al., 3 May 2026).

1. Motivation and problem formulation

The central problem addressed by ACDL is that, in agentic LLM systems, the prompt is not a static string but a state-dependent, time-evolving context. The paper characterizes this as a problem of context engineering rather than prompt engineering: prompt engineering concerns wording and phrasing, whereas context engineering concerns what information is included, how it is organized into role messages, and how it evolves across steps (Pelc et al., 3 May 2026).

This distinction matters because many systems that appear similar at a high level differ materially in context construction. Two systems may both be described as ReAct agents, yet diverge in whether reasoning traces are retained, whether tool outputs precede or follow user messages, whether summaries are inserted, and whether some messages recur at every iteration. The paper argues that such differences can affect behavior but are difficult to express unambiguously through prose alone.

ACDL is therefore proposed as a shared descriptive layer for the macro-logic of context construction. Its intended function is not to replace implementation code or exact prompt wording, but to make context architecture explicit, comparable, and portable across systems. A plausible implication is that ACDL treats prompt construction as a first-class object of analysis in agent research, rather than as incidental implementation detail.

2. Representational model: roles, content types, and abstractions

ACDL models an LLM context as a sequence of role messages, each of which contains content elements derived from runtime state, reusable templates, or computed functions. The paper specifies five role labels (Pelc et al., 3 May 2026):

Role	Meaning
S	system
U	user
A	assistant
T	tool
N	none, for legacy completion-style prompts

The formal reference further associates these roles with characteristic content. S: is used for system instructions, persona, tool descriptions, and constraints; U: for external input, observations, and tool results; A: for prior model outputs, reasoning traces, and chosen actions; T: for structured tool call results; and N: for a single unstructured completion block. This role structure reflects chat-style APIs while preserving compatibility with completion-style prompting.

ACDL distinguishes several categories of dynamic content. Templates are ALL_CAPS placeholders such as INSTRUCTIONS, AVAILABLE_TOOLS, and TASK_DESCRIPTION. Context variables denote values from runtime state, for example env.user_input[@T] or sys.mem[@T]. Functions denote computed content such as retrieval, summarization, formatting, or generation of document lists. Fragments provide reusable substructures, and name definitions provide local aliases for long expressions. Together these mechanisms allow prompt architecture to be described without fixing exact natural-language wording.

A key semantic constraint is that ACDL describes how existing structured state is linearized into context, but does not define how that state is stored or updated. The language is thus descriptive with respect to context assembly rather than prescriptive with respect to runtime state management.

3. Temporal indexing, control flow, and prompt evolution

One of ACDL’s defining features is explicit time indexing. The notation @T denotes the current main time step, while lower-case @t is used when iterating over historical steps. Nested substeps are written as @T.I or @t.i. The appendix includes examples such as the following (Pelc et al., 3 May 2026):

@T // Current time step @T-1 // Previous time step @T.I // Current substep of current turn @t.i // Substep i of turn t (in loops)

This temporal apparatus allows the language to represent not merely a prompt at one instant, but the evolution of prompt content across turns and substeps. For example, history replay can be written with ForEach, as in:

ForEach(t: range(1, @T)) { env.observation[@t] }

ACDL also supports conditional structure through If, ElseIf, Else, and Switch. These constructs may appear inside a role block, controlling which content appears inside one message, or around role messages, controlling whether entire messages appear. The appendix provides a representative conditional:

If sys.tool[@t] == get_clarification { U: env.user_input[@i] } ElseIf sys.tool[@t] == search { A: env.search_results[@t] } Else { A: sys.tool_used[@t].tool_response }

Iteration is handled by ForEach, which is used to replay conversation history, iterate over tools, or traverse substeps. The paper emphasizes that one of the main uses of ACDL is unpacking history into context. This is especially relevant for ReAct-style systems, where a prompt may consist of initial instructions, a user query, and then a repeated pattern of assistant reasoning or tool request followed by tool response across steps.

A notable construct for dynamic prompt construction is PromptEndsHere when <condition>. This marks a point beyond which no additional content is appended for the current turn. The paper uses this to describe cases in which a prompt stops early, such as an initial substep or an abbreviated variant, and notes that different time levels may have different prompt endings. This suggests that ACDL is designed to represent prompt assembly policies that depend not only on current state but also on control-flow position within nested loops.

4. Formal syntax and semantics

The formal reference defines a specification as a prompt declaration with indexed parameters:

PromptName[idx1, idx2, ...]: { <prompt-blocks> }

Reusable fragment definitions may also appear:

StrFrag FragmentName[params]: { <content-elements> } RoleFrag FragmentName[params]: { <prompt-blocks> }

Role messages support both multiline braced form and single-line form (Pelc et al., 3 May 2026):

S: { INSTRUCTIONS AVAILABLE_TOOLS env.datetime[@t] }

U: env.user_question[@t] A: resp.answer[@t] S: INSTRUCTIONS

The paper states that control flow is not allowed in single-line role messages; loops or conditionals inside a message require braces. ACDL also enforces a two-level scope corresponding to chat APIs. At the top level, the specification may contain role messages, labels or marks, control flow, names, fragment invocations, comments, and fragment definitions. Inside a role block, one may include content elements, control flow, names, fragment invocations, marks, comments, and break or continue. Nested role messages inside role messages are invalid. For completion-style prompts using N:, only one N: block is permitted, and it cannot coexist with chat-role blocks.

Runtime state references are organized through namespaces: env for environment or external state, sys for system or internal state, and resp for previous model outputs. The appendix gives examples including env.user_question[@T], sys.agent_desc, sys.tool[@t].tool_response[@t], and env.bomb_location[@t, bomb]. Indices support time references such as @T, @T-1, and @t.i, named indices such as bomb, and arithmetic expressions such as @t+1, @t-1, and @t%25.

Templates may take arguments, and functions are treated semantically as pure; if a function depends on mutable state, that state should be passed as input. The examples include:

summarize(sys.history[@t]) get_dialog_history(sys.agent_name) range(1, @T, 2)

Name definitions use Name var_name := expression, as in:

Name docs := k_relevant_docs(env.user_input[@T])

The appendix also shows list comprehensions:

Name relevant_summaries := [sys.summary[@t] for t in range(@T, @T-900, 100)]

Comments use //, and Mark annotations are presentational rather than semantic:

ForEach(t: range(1, @T)) { env.observation[@t] }

0

These semantic choices reflect a deliberate separation between the logical structure of context construction and implementation-specific execution details.

5. Visualization, tooling, and documented systems

A major claim of the paper is that ACDL is simultaneously formal and visual. ACDL specifications may be handwritten on a whiteboard, written as text, or rendered into diagrams by tooling. The rendered diagrams depict role blocks, loops, and annotations in a way intended to make differences between systems immediately visible (Pelc et al., 3 May 2026).

The paper describes this visual layer as analogous in communicative purpose to box diagrams in deep learning or UML in software engineering. The diagrams are not presented as merely decorative: they are intended as a standardized medium for expressing prompt structure and prompt evolution. Tool support includes a parser, interactive renderer, VS Code extension, documentation, and an agentic skill; tooling, examples, and documentation are also stated to be available at www.acdlang.org.

The language is demonstrated on several documented systems. ReAct variants are used as a motivating example: the diagrams expose whether reasoning traces are preserved in history, whether tools appear first or last, and how assistant and tool messages are interleaved. OpenCode and OpenClaw are reverse-engineered from code and traces and then documented in ACDL. The paper highlights that both are multi-turn, multi-step ReAct-style systems; both use sub-agents as tools; both support multiple tool calls in one turn; and both compact history when it grows too large, yet they differ in prompt structure and summary strategy. OpenClaw is described as having a long system prompt that includes skills, tools, sub-agents, and memories, whereas OpenCode is more minimal and passes tool definitions through the tools API parameter. OpenCode distinguishes Plan-mode and Build-mode via reminders, while OpenClaw timestamps each user input, supports heartbeat-like non-user-initiated tasks, and may inject pending async messages.

The paper also documents the Gemini 2.5 “Pokémon Blue” agent. Its ACDL description captures the system prompt instructing Gemini that it is playing Pokémon Blue and should beat the game, as well as tool usage, summarized action history, periodic progress evaluation every 25 turns, goal tracking, exploration instructions, and specialized sub-agents such as the pathfinder and boulder puzzle strategist. In the DeepSeek-V4 example, ACDL is used to express that tool-calling scenarios preserve reasoning traces across rounds, while general conversational scenarios discard prior reasoning traces when a new user message arrives. The authors argue that the resemblance between a DeepSeek-V4 context-management figure and ACDL renderings is striking, but that ACDL adds a formal account of dynamic evolution through time steps, message separation, and explicit role assignment.

6. Empirical significance, comparison with alternatives, and limitations

The paper argues that context structure is empirically consequential rather than cosmetic, and supports this claim with an experiment on seven MINT context configurations (Pelc et al., 3 May 2026). These variants differ along two axes: how much tool-use history is retained, and how tool calls and responses are grouped into messages. In the reasoning tasks, the best configuration reaches 77.53%, while the worst reaches 72.78%. In code-generation tasks, the top result is 54.41%, and the worst is 48.53%. The original MINT formulation is stated to be not best in either category. Within the paper’s argument, these results function as evidence that relatively small structural changes in context serialization can alter performance.

The same section situates ACDL against several existing modes of description. Informal prose is characterized as flexible but ambiguous, often failing to specify exact message order, which messages repeat, what history is preserved, what content is conditional, and where roles change across steps. Ad hoc diagrams can help, but are not standardized and may not support precise comparison. Code inspection is precise but burdensome, implementation-specific, and poorly suited to high-level cross-system comparison. The paper also compares ACDL to PromptML, PDL, and POML, arguing that these are useful languages but do not focus on the temporal evolution of agent contexts across multiple steps.

Two limitations are explicitly identified. First, ACDL assumes an immutable-during-construction execution model: state may mutate between prompt constructions, but remains immutable during any single construction. Systems that mutate state while building the prompt are cumbersome to describe and would need to be transformed into an equivalent immutable-during-construction form. Second, ACDL currently lacks a clean way to describe multi-agent systems with separate clocks and shared mutable state that any agent can read and modify; the stated workaround is explicit clock synchronization, which the authors call inelegant.

These limitations clarify a common misconception. ACDL is not presented as an executable language for building agents. It is explicitly descriptive, not executable, and intentionally does not define all runtime behavior. Likewise, because it abstracts away exact wording, it does not replace prompt engineering; it complements prompt engineering by formalizing the higher-level organization and temporal evolution of context. The paper identifies future extensions including support for additional API fields beyond standard message lists, better support for shared-state multi-agent systems with unsynchronized clocks, and possible extension of ACDL’s scope to cover more prompt-serialization cases. Within that framing, ACDL is positioned as a candidate standard for communicating context engineering in day-to-day work and in research papers.