T2A Protocol

Tools can be smart without embedding LLM calls.

T2A is the Tool-to-Agent Protocol for auditable reasoning handoffs.

For CLIs, APIs, SDKs, CI jobs, workflows, and MCP servers.

No tool-side LLM API key · No tool-side model billing · No tool-side local model required

The agent reasons.
The tool validates.
The workflow resumes.

With an agent, why does every tool want another model?

You already have an intelligent agent such as Codex, Claude Code, or Cursor.

Then you connect a tool that reaches a reasoning checkpoint. It may need to summarize evidence, classify risk, consolidate memory, or draft a plan.

Today, that tool usually asks you to provide intelligence all over again:

• bring your own LLM API key
• pay the tool's hosted model bill
• run a tool-side local model

This is backwards. The intelligence is already available through the host agent, but the user must provision another model before the tool can deliver value.

For users, that means another key, account, bill, provider configuration, or local runtime.

For tool authors, that friction is not just maintenance overhead. It is a direct adoption problem: every extra setup step is another chance for users to abandon the tool before they experience its value.

T2A takes a different approach:

When a tool needs intelligence, it borrows it from the agent that called it.

The tool emits a structured, auditable reasoning handoff. The host agent completes the reasoning with its existing model capability. The tool validates the structured result before changing state or resuming execution.

The agent reasons. The tool validates. The workflow resumes.

First proof: smart memory without a memory-tool model key

t2a-memory is the first proof, not the whole protocol.

Memory is the pain in miniature.

A useful memory tool needs reasoning: extraction, consolidation, conflict handling, and durable updates.

Most smart memory tools solve that by asking for a model key, model config, SaaS account, or local model.

t2a-memory does not.

It is a local memory tool that:

• does not ask for an OpenAI key
• does not ask for an Anthropic key
• does not ask for a Gemini key
• does not require model, base_url, or provider
• does not create tool-side model billing
• does not run a tool-side local model

Yet a host agent can use it to create, consolidate, validate, and commit memory.

User asks local agent:
  Remember that I prefer concise but structured technical advice.

t2a-memory:
  creates a T2A handoff

host agent:
  reads the capsule
  performs the reasoning
  writes structured output

t2a-memory:
  validates the output
  commits local memory

User:
  runs t2a-memory read
  sees the memory

Abbreviated result:

t2a-memory doctor

T2A Memory doctor

Tool-side model setup: none

✓ provider/model/base_url config: none
✓ API key required by memory tool: no
✓ direct LLM SDK dependency: none
✓ tool-side local model required: no
✓ network required by memory operations: no

Result: ok

t2a-memory read

Memory:
  - The user prefers concise but structured technical advice.

The memory workflow became smart without the memory tool becoming an LLM client.

What this proves:

• the memory tool did not own the model call
• the memory tool did not ask for model credentials
• the host agent performed the reasoning
• the tool validated structured output
• local memory was committed
• the workflow completed without the tool becoming an LLM client

That is the T2A boundary in action.

Choose your path

I want to...	Start here
Feel the proof without installing	First proof
Try it with my local agent	Copy-paste proof
Try it without a capable agent	Manual fallback
Build a smart tool without an embedded LLM call	For tool authors
Teach a host agent to complete T2A tasks	For host agents
Read the protocol	T2A capsule, Spec

Copy-paste proof: ask your local agent to run it

Have Codex, Claude Code, Cursor, or another shell-capable local agent? Copy this prompt. Works with macOS/Linux/WSL shells and Windows PowerShell; the agent should detect the OS and use the matching commands. The agent will install the packages, create the T2A handoff, complete the reasoning task, validate, commit, and read the memory.

The proof uses npm packages, so it needs Node.js 22+ and npm. Your local agent can check this first and, with your approval, install them if missing.

Copy this into your local agent:

You are my local host agent.

Prove that t2a-memory can give me local memory without the memory tool owning a model key.

Use a user-level tool home. Do not require global npm permissions.

First, check whether Node.js 22+ and npm are available.

If they are available, continue.

If they are missing, tell me what is missing and ask for approval before installing Node.js/npm. Use the least invasive standard method for my OS, such as Homebrew on macOS, winget on Windows, or the system package manager / nvm / fnm on Linux if already available. Do not install system packages without asking.

First, detect my OS and shell.

If I am on macOS, Linux, or WSL, use this setup:

TOOL_HOME="${T2A_TOOL_HOME:-$HOME/.t2a/tools}"
mkdir -p "$TOOL_HOME"
npm install --prefix "$TOOL_HOME" @t2a-protocol/t2a @t2a-protocol/t2a-memory
T2A="$TOOL_HOME/node_modules/.bin/t2a"
T2A_MEMORY="$TOOL_HOME/node_modules/.bin/t2a-memory"

If I am on Windows PowerShell, use this setup:

$ToolHome = if ($env:T2A_TOOL_HOME) { $env:T2A_TOOL_HOME } else { Join-Path $HOME ".t2a\tools" }
New-Item -ItemType Directory -Force -Path $ToolHome | Out-Null
npm install --prefix $ToolHome @t2a-protocol/t2a @t2a-protocol/t2a-memory
$T2A = Join-Path $ToolHome "node_modules\.bin\t2a.cmd"
$T2AMemory = Join-Path $ToolHome "node_modules\.bin\t2a-memory.cmd"

Then run the doctor check and show the result:

macOS/Linux/WSL:
"$T2A_MEMORY" doctor

Windows PowerShell:
& $T2AMemory doctor

Create a memory handoff for this fact:

"I prefer concise but structured technical advice."

Run the matching command:

macOS/Linux/WSL:
"$T2A_MEMORY" remember "I prefer concise but structured technical advice."

Windows PowerShell:
& $T2AMemory remember "I prefer concise but structured technical advice."

Parse the JSON output from `t2a-memory remember`.
Set `TASK_DIR` on macOS/Linux/WSL, or `$TaskDir` on Windows PowerShell, from the returned `local.task_dir`.
Use that exact task directory for validation and commit.

Complete the T2A handoff:

- read `task.json` first
- inspect `prompt.md`, `input.json`, permissions, and `output.schema.json`
- write only `output.json` in the task directory, matching the schema
- run core T2A validation
- run T2A Memory validation
- repair output if validation fails
- commit only after validation passes
- run `t2a-memory read` and show me the committed memory

Use the matching commands:

macOS/Linux/WSL:
"$T2A" validate "$TASK_DIR"
"$T2A_MEMORY" validate "$TASK_DIR"
"$T2A_MEMORY" commit "$TASK_DIR"
"$T2A_MEMORY" read

Windows PowerShell:
& $T2A validate $TaskDir
& $T2AMemory validate $TaskDir
& $T2AMemory commit $TaskDir
& $T2AMemory read

Safety constraints:

- Do not configure an LLM provider for t2a-memory.
- Do not add OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, model, base_url, or provider config for the memory tool.
- Do not read unrelated user files.
- Ask before destructive changes.
- For package installation, write only inside the T2A user-level tool home.
- During the handoff and memory workflow, write only inside T2A/t2a-memory task and memory locations.

When done, explain what happened in one paragraph:

the agent reasoned, the tool validated, and the workflow resumed.

What the agent should do internally

• Detect the OS and shell.
• Install packages into ~/.t2a/tools or another user-level tool home with npm install --prefix.
• Use .cmd binaries on Windows PowerShell.
• Run t2a-memory doctor.
• Run t2a-memory remember.
• Parse local.task_dir.
• Write output.json.
• Validate with t2a and t2a-memory.
• Commit with t2a-memory.
• Read with t2a-memory read.

Success means:

• t2a-memory doctor reports no tool-side model setup
• a T2A handoff was created
• the host agent wrote structured output
• validation passed
• memory was committed locally
• t2a-memory read shows the memory
• the memory tool still has no tool-side model key or model config

Optional: install reusable agent skills for future sessions.

(Not required for the proof above.)

TOOL_HOME="${T2A_TOOL_HOME:-$HOME/.t2a/tools}"
"$TOOL_HOME/node_modules/.bin/t2a-memory" install --agent auto

This may write T2A and T2A Memory skill files into local agent skill directories such as .agents or .claude.

No local agent? Inspect the protocol manually

This path is for users who do not have a local shell-capable agent, have an agent that cannot reliably edit files, or want to inspect the protocol manually.

On Windows PowerShell, use the .cmd binaries under node_modules\.bin and PowerShell variable syntax.

Install the packages:

TOOL_HOME="${T2A_TOOL_HOME:-$HOME/.t2a/tools}"
export T2A_TOOL_HOME="$TOOL_HOME"
npm install --prefix "$TOOL_HOME" @t2a-protocol/t2a @t2a-protocol/t2a-memory

Create a memory handoff:

"$TOOL_HOME/node_modules/.bin/t2a-memory" remember "I prefer concise but structured technical advice."

Copy local.task_dir from the JSON output:

TASK_DIR="<task directory printed by t2a-memory remember>"

Inspect the capsule:

cat "$TASK_DIR/task.json"
cat "$TASK_DIR/prompt.md"
cat "$TASK_DIR/input.json"
cat "$TASK_DIR/output.schema.json"

Create output.json manually, or ask a separate chat model to produce JSON matching output.schema.json. Use the real event_id from input.json:

{
  "event_id": "<event_id from input.json>",
  "decision": "commit",
  "operations": [
    {
      "op": "add",
      "topic": "communication-style",
      "statement": "I prefer concise but structured technical advice.",
      "source_event_ids": ["<event_id from input.json>"]
    }
  ],
  "rationale": "The user expressed a durable communication preference."
}

Then validate, commit, and read:

"$TOOL_HOME/node_modules/.bin/t2a" validate "$TASK_DIR"
"$TOOL_HOME/node_modules/.bin/t2a-memory" validate "$TASK_DIR"
"$TOOL_HOME/node_modules/.bin/t2a-memory" commit "$TASK_DIR"
"$TOOL_HOME/node_modules/.bin/t2a-memory" read

The manual path is not the main wow path. The main wow path is a local host agent completing the handoff.

What just happened?

A tool reached a reasoning checkpoint.

Instead of embedding an LLM client, it emitted a T2A Capsule.

The capsule contains:

• task metadata
• bounded inputs
• prompt
• output schema
• validation boundary

The host agent completed the reasoning and wrote structured output.

The tool validated that output before committing state or resuming deterministic execution.

The agent reasons. The tool validates. The workflow resumes.

Simple flow

flowchart LR
  Tool["Tool hits reasoning checkpoint"] --> Capsule["Emit T2A Capsule"]
  Capsule --> Agent["Host agent reasons"]
  Agent --> Output["Writes structured output"]
  Output --> Validate["Tool validates"]
  Validate --> Resume["Workflow resumes"]

Loading

Why the boundary matters

T2A is not about removing model use.

It is about putting model use at the right boundary.

The host agent already owns the reasoning capability the user chose.

The tool is where domain constraints live: file paths, source IDs, memory schemas, risk labels, commit rules, and validation logic.

When a tool embeds its own model call, those boundaries collapse.

The tool starts owning prompts, provider configuration, model choice, credentials, billing, and failure recovery.

When a tool emits a T2A handoff, the boundary stays visible:

• the tool declares the task
• the agent performs the reasoning
• the tool validates structured output
• the workflow resumes only after validation

The usual alternatives all add user friction and tool-author adoption risk.

1. Bring your own LLM API key

Now every tool wants your OpenAI, Anthropic, Gemini, Cohere, Voyage, or local-compatible API key.

You may not have one. You may only have an agent product subscription. You may not want to hand billing credentials to every tool you try. You may not know what prompts the tool sends or how much it will spend.

For tool authors, BYOK is not just an integration chore. Every provider has different models, payloads, errors, rate limits, base URLs, streaming behavior, auth formats, and billing assumptions. The moment your tool asks for api_key, model, base_url, or provider, setup friction becomes part of your product, and users who do not have a key, do not trust the billing path, or do not want another provider form may never reach the first successful run.

2. Pay the tool's hosted model bill

The tool can hide the model call behind its own cloud service.

That removes the API-key form, but creates a new account, a new bill, a new data boundary, and a new trust decision. The user already pays for an agent with reasoning power; now every smart tool wants to charge for another slice of intelligence.

For tool authors, hosted model calls mean pricing, metering, abuse prevention, privacy questions, latency, support burden, and model-cost risk. They also move the adoption problem into your funnel: users must create or trust another account, accept another data boundary, and believe your tool is worth another recurring intelligence bill.

3. Run a tool-side local model

Local-first sounds good, but not every laptop can run a useful model. Local models consume CPU, GPU, RAM, disk, and battery. Small local models may be weaker than the host agent the user already has.

For tool authors, local model support means another setup path, another failure mode, and another quality problem. If the user's machine cannot run it well, or the local model gives weak results, the user experiences that as your tool failing.

Embedded LLM call vs T2A handoff

Embedded LLM call inside tool	T2A handoff
Tool asks for provider keys	Host agent uses its existing model capability
Tool handles model/provider differences	Host agent owns the model surface
Tool may receive billing credentials	Tool receives structured output
Hidden prompt/output	Auditable capsule and structured output
Tool owns model billing	Tool stays model-free
Tool trusts model output directly	Tool validates before commit/resume
Each tool reinvents provider config	One host agent can reason for many tools

T2A does not eliminate LLMs. It moves the model call out of the tool and into the host-agent boundary.

Protocol map

If you think in agent protocol maps, T2A fits like this:

Protocol	Direction	What it standardizes
MCP	Agent -> Tool	Agents call tools and access context
A2A	Agent <-> Agent	Agents coordinate with other agents
T2A	Tool -> Agent	Tools hand off reasoning checkpoints

T2A does not replace MCP or A2A. It completes a missing direction: after an agent calls a tool, the tool can hand a reasoning checkpoint back to the host agent.

But T2A is not only for MCP servers. The issuing tool can be a CLI, API, SDK, CI job, workflow, or MCP server.

T2A capsule

A T2A Capsule is a durable reasoning work order. In v0.1 it is local and file-based. Its entry document is task.json.

.t2a/tasks/<task-id>/
  task.json
  prompt.md
  inputs/            # generic capsule input directory
  input.json         # some tools, such as t2a-memory, may use a single input file
  output.schema.json
  output.json       # produced later by the host agent
  validation.json   # produced later by validation

At handoff time, task.json, prompt.md, declared inputs, and output.schema.json exist.

Some tools may use a single input.json; others may use an inputs/ directory.

The host agent writes output.json later.

validation.json is produced by validation.

T2A core validates the protocol envelope and output schema. The issuing tool validates domain semantics.

T2A handoff result

A T2A Handoff Result is the machine-readable signal a tool returns when reasoning is required. Agents should not need to guess when to use T2A.

Minimal local shape:

{
  "type": "t2a.handoff",
  "t2a_version": "0.1",
  "task_id": "memory-123",
  "local": {
    "task_dir": ".t2a/tasks/memory-123",
    "task_file": ".t2a/tasks/memory-123/task.json"
  }
}

Remote handoff patterns are documented, but v0.1 ships the local file-based flow first.

For tool authors

Your goal is not to adopt a framework.

Replace one embedded LLM call with one T2A handoff. Keep the rest of your tool unchanged.

Start here: T2A Tool Author Kit

Fast path:

1. Copy the Tool Author Kit setup prompt into Codex / Claude Code / Cursor.
2. Let it run t2a install tool-author-kit --agent auto.
3. Review its one-checkpoint migration plan.
4. Approve the smallest local T2A handoff.
5. Run t2a validate <task-dir>.

The kit includes:

• a coding-agent migration prompt
• a tool-author skill
• a runnable minimal CLI example
• a concrete local handoff template
• a compatibility checklist

Conceptually:

Before:
tool -> embedded LLM provider call -> parse result -> mutate state

After:
tool -> emit T2A Capsule
host agent -> write output.json
tool -> validate -> commit/resume

For host agents

Host agents complete T2A tasks by following the capsule, not by guessing.

1. Read task.json first.
2. Inspect declared inputs and permissions.
3. Follow prompt.md.
4. Produce output.json matching output.schema.json.
5. Run validation when available and safe.
6. Repair until validation passes.
7. Stop before resume unless explicitly asked.

Minimal host support:

• recognize type: "t2a.handoff"
• open local.task_file
• read declared inputs and prompt
• write the declared output path
• run validation when available
• do not resume automatically

The generic host-agent instruction file lives at skills/t2a/SKILL.md.

t2a-memory also ships installable skill templates:

• integrations/t2a-memory/templates/skills/t2a/SKILL.md
• integrations/t2a-memory/templates/skills/t2a-memory/SKILL.md

Validate, resume, continue

validate is deterministic checking.

resume belongs to the issuing tool.

continue means validate_then_resume.

In v0.1, the T2A CLI validates first and then prints resume/continue guidance. It does not execute arbitrary tool-owned commands.

Local-first v0.1

v0.1 is local-first, protocol-first, and intentionally small. It implements local file-based capsules first.

Remote APIs, SDKs, and MCP servers are documented as handoff patterns, but this repository does not include a hosted server, SDK, scheduler, daemon, or MCP bridge implementation yet.

Zero tool-side model setup

This repository must not add tool-side LLM API calls and must not require model, base_url, api_key, provider, or LLM SDK configuration.

The host agent may use its own model capability. The tool does not own the model call.

FAQ and not this

Q: Does T2A remove model use entirely?

A: No. It means no tool-side embedded LLM call. The host agent still performs reasoning.

Q: Is T2A a memory database?

A: No. t2a-memory is the first proof. T2A is a protocol for reasoning handoffs.

Q: Is T2A an MCP replacement?

A: No. T2A complements MCP and A2A.

Q: Is T2A limited to MCP servers?

A: No. T2A is for any tool that can emit a reasoning handoff: CLI, API, SDK, CI job, workflow, or MCP server. MCP Sampling is MCP-specific; T2A is a general tool-to-agent handoff pattern with capsule, validation, and commit/resume.

Q: Is T2A an agent framework?

A: No. T2A defines the handoff boundary.

Q: Why not just call OpenAI/Anthropic inside the tool?

A: Because the user may already have a trusted host agent with model access. Embedding another model call forces the tool to own provider configuration, credentials, billing, prompts, and recovery. T2A keeps reasoning with the host agent and makes the checkpoint auditable and validatable.

T2A in one sentence

T2A lets smart tools hand off reasoning to the host agent instead of embedding LLM calls.

T2A in one loop

Tool hits reasoning checkpoint
-> emits T2A Capsule
-> host agent reasons
-> tool validates
-> workflow resumes

If this boundary resonates, star the repo to follow the protocol, examples, and T2A-compatible tools.

Examples

• integrations/t2a-memory/: a memory tool records deterministic input, the host agent consolidates it, and the tool validates and commits local memory. Your agent gets memory. The memory tool gets no model key.
• examples/tool-author-minimal-cli/: a tiny runnable tool-author example that replaces one embedded model-call path with one local T2A handoff.
• examples/retrieval-brief/: a retrieval tool gathers bounded evidence, the host agent writes a grounded brief, and the issuing tool can validate source IDs.
• examples/change-risk-review/: a change tool records deterministic change inputs, the host agent classifies risk, and the issuing tool can validate resource IDs before continuing.

From source / development

Requires Node.js 22 or newer.

Core CLI source quickstart:

cd cli
npm install
npm run build
node dist/index.js inspect ../examples/retrieval-brief/.t2a/tasks/demo
node dist/index.js validate ../examples/retrieval-brief/.t2a/tasks/demo
node dist/index.js continue ../examples/retrieval-brief/.t2a/tasks/demo

Local package smoke test:

cd cli
npm install
cd ../integrations/t2a-memory
npm install
npm run dogfood:pack-smoke

The smoke test builds and packs both local packages, installs them into a temporary tool home, simulates the host-agent output step, validates, commits, reads memory, and checks path boundaries. See integrations/t2a-memory/README.md.

Repository layout

• spec/v0.1/: normative protocol documents.
• schemas/v0.1/: JSON Schema 2020-12 protocol schemas.
• cli/: TypeScript CLI for local capsule inspection, validation, and continue guidance.
• docs/: concepts, quickstart, capsule, handoff, validation, continue, security, and deferred/remote handoff notes.
• examples/: local capsule examples.
• skills/t2a/: host-agent skill for completing T2A capsules.
• skills/t2a-tool-author/: coding-agent skill for converting one tool reasoning checkpoint to T2A.
• prompts/: copy-paste prompts for host agents and coding agents.
• templates/: concrete T2A authoring templates.
• integrations/: integration templates and notes.
• integrations/t2a-memory/: user-level memory proof and package smoke flow.
• scripts/dogfood/: local package smoke tests.
• conformance/: validation fixtures for implementers.

License

Code and specification materials are licensed under the Apache License, Version 2.0.