ATIP (Agent Tool Introspection Protocol)

A lightweight, CLI-first protocol that allows AI agents to safely introspect and cryptographically verify local tools via a simple --agent contract, without requiring MCP servers or additional infrastructure.

What is ATIP?

ATIP defines a simple convention for CLI tools to expose their capabilities to AI agents:

$ gh --agent
{
  "atip": {"version": "0.6"},
  "name": "gh",
  "description": "GitHub CLI",
  "commands": {
    "pr": {
      "list": {...},
      "create": {...}
    }
  },
  "effects": {
    "network": true,
    "destructive": false
  }
}

No servers. No JSON-RPC. No handshakes. Just a --agent flag that outputs structured JSON.

Why ATIP?

The Problem

AI agents need to know:

What tools are available? (discovery)
How do I use this tool? (parameters, types)
What are the side effects? (destructive? network? cost?)
Is it safe to retry? (idempotent? reversible?)
Can I trust this binary? (signatures, provenance, supply chain)

Current solutions fall short:

Parsing --help — Inconsistent, unreliable
Hardcoded knowledge — Doesn't scale to custom tools
MCP servers — Overkill for simple CLI tools that execute and exit

The Solution

ATIP separates introspection from execution—with cryptographic trust:

Concern	Solution
Discovery	`tool --agent` outputs metadata (ATIP)
Trust	Sigstore signatures + SLSA attestations
Execution	Direct subprocess invocation
Stateful tools	MCP (when genuinely needed)

For 95% of CLI tools (git, kubectl, terraform, gh), ATIP provides everything agents need—including enterprise-grade supply chain security—without infrastructure overhead.

Quick Start

For Tool Authors

Add ATIP support to your CLI tool in 30 minutes:

import json, sys

ATIP_METADATA = {
    "atip": {"version": "0.6"},
    "name": "mytool",
    "version": "1.0.0",
    "description": "Does something useful",
    "commands": {
        "run": {
            "description": "Execute main function",
            "options": [
                {
                    "name": "verbose",
                    "flags": ["-v", "--verbose"],
                    "type": "boolean",
                    "description": "Enable verbose output"
                }
            ],
            "effects": {
                "filesystem": {"write": true},
                "network": false,
                "idempotent": false
            }
        }
    }
}

if "--agent" in sys.argv:
    print(json.dumps(ATIP_METADATA))
    sys.exit(0)

# ... rest of your tool logic

See docs/adoption-guide.md for full details.

For Legacy Tools

For tools that don't natively support --agent, you can create shim files:

# ~/.local/share/agent-tools/shims/curl.json
{
  "atip": {"version": "0.6"},
  "name": "curl",
  "version": "8.4.0",
  "description": "Transfer data from or to a server",
  "commands": {
    "": {
      "description": "Make HTTP request",
      "options": [...],
      "effects": {"network": true, "idempotent": false}
    }
  }
}

Or use atip-gen to auto-generate metadata from --help output:

atip-gen curl -o shims/curl.json

For Agent Developers

Integrate ATIP into your AI agent:

from atip_bridge import discover_tools, compile_to_openai, execute_tool

# 1. Discovery
tools = discover_tools()  # Scans PATH and shims

# 2. Compile to provider format
openai_tools = [compile_to_openai(t) for t in tools]

# 3. Send to LLM
response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
    tools=openai_tools
)

# 4. Execute directly
for call in response.choices[0].message.tool_calls:
    result = execute_tool(call.function.name, call.function.arguments)

See docs/agent-integration.md for integration patterns.

Key Features

🎯 Zero Infrastructure

No servers, daemons, or sockets. Works on a fresh system with only the tool binary.

🔒 Safety Metadata

Tools declare effects (destructive, idempotent, reversible, cost) so agents can make informed decisions:

{
  "effects": {
    "destructive": true,
    "reversible": false,
    "cost": {"billable": true}
  }
}

🛡️ Trust & Supply Chain Security

Cryptographically verify tool binaries and control what capabilities agents can use—down to the parameter level:

{
  "trust": {
    "source": "native",
    "verified": true,
    "integrity": {
      "checksum": "sha256:e3b0c44298fc1c14...",
      "signature": {
        "type": "cosign",
        "identity": "https://github.com/cli/cli/.github/workflows/release.yml@refs/tags/v2.45.0",
        "issuer": "https://token.actions.githubusercontent.com"
      }
    },
    "provenance": {
      "url": "https://github.com/cli/cli/attestations/...",
      "format": "slsa-provenance-v1",
      "slsaLevel": 3
    }
  }
}

Enterprise-grade controls:

Binary verification — SHA-256 hash + Sigstore/Cosign signatures
Supply chain attestation — SLSA provenance verification
Trust levels — COMPROMISED → UNSIGNED → UNVERIFIED → VERIFIED
Policy enforcement — Allowlist signers, builders, minimum trust levels
Capability gating — Restrict destructive operations to verified tools only

📦 Partial Discovery

Large tools (kubectl, aws-cli) support filtered discovery to avoid context bloat:

$ kubectl --agent --commands=pods,deployments --depth=1

🔄 Interactive Tool Handling

Metadata includes stdin/TTY requirements so agents know when tools need special handling:

{
  "interactive": {
    "stdin": "required",
    "prompts": true,
    "tty": false
  }
}

🌐 Universal Translation

ATIP compiles to native function calling formats for OpenAI, Gemini, and Anthropic with safety information preserved.

🤝 MCP Compatible

ATIP complements MCP—use ATIP for discovery, MCP for stateful execution when needed.

Architecture

How ATIP tools work together to enable AI agents to safely use CLI tools:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           ATIP Toolchain                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────┐    ┌─────────────┐    ┌─────┐    ┌──────────────┐        │
│  │atip-discover │ →  │ atip-bridge │ →  │ LLM │ →  │ atip-execute │        │
│  │              │    │             │    │     │    │              │        │
│  │ Find tools   │    │ Compile to  │    │     │    │ Run safely   │        │
│  │ with --agent │    │ OpenAI/etc  │    │     │    │ with checks  │        │
│  └──────────────┘    └─────────────┘    └─────┘    └──────┬───────┘        │
│         ↑                                                  │               │
│         │            ┌──────────────┐                      ↓               │
│         │            │atip-registry │              ┌──────────────┐        │
│         └────────────│              │              │   CLI Tool   │        │
│                      │ Shim hosting │              │              │        │
│                      └──────────────┘              │ gh, kubectl, │        │
│                                                    │ terraform... │        │
│  Supporting: atip-validate, atip-gen,              └──────────────┘        │
│              atip-lint, atip-diff                                          │
└─────────────────────────────────────────────────────────────────────────────┘

See reference/README.md for detailed tool documentation.

Repository Structure

atip/
├── spec/rfc.md              # Full specification (v0.6.0)
├── schema/0.6.json          # JSON Schema for validation
├── examples/                # Example ATIP metadata
│   ├── gh.json              # Full example (GitHub CLI)
│   ├── minimal.json         # Minimal valid ATIP
│   └── tools/               # Example tools implementing --agent
│       ├── hello-atip       # Minimal bash example
│       └── atip-echo        # Effects metadata example
├── reference/               # Reference implementations
│   ├── atip-bridge/         # TypeScript compiler library
│   ├── atip-discover/       # Discovery CLI (TypeScript)
│   ├── atip-discover-go/    # Discovery CLI (Go)
│   ├── atip-validate/       # Schema validator
│   └── atip-gen/            # Auto-generate from --help
└── docs/                    # Additional documentation
    ├── adoption-guide.md
    ├── agent-integration.md
    └── why-not-mcp.md

Documentation

RFC Specification — Complete protocol specification
Adoption Guide — For tool authors
Agent Integration — For agent developers
Why Not MCP? — Positioning and comparison
Contributing — How to contribute

Reference Tools

atip-discover — Scan PATH for ATIP-compatible tools
atip-validate — Validate ATIP metadata against schema
atip-gen — Generate ATIP metadata from --help output
atip-bridge — TypeScript library for compiling ATIP to provider formats

Examples

Minimal ATIP

{
  "atip": {"version": "0.6"},
  "name": "hello",
  "version": "1.0.0",
  "description": "Print a greeting",
  "commands": {
    "": {
      "description": "Say hello",
      "arguments": [
        {"name": "name", "type": "string", "required": true}
      ],
      "effects": {"filesystem": {}, "network": false}
    }
  }
}

Full Example

See examples/gh.json for a complete GitHub CLI example with:

Nested subcommands
Authentication requirements
Effect declarations
Usage patterns

Example Tools

See examples/tools/ for working CLI tools that implement --agent:

hello-atip — Minimal bash example
atip-echo — Demonstrates various effects metadata

Comparison to MCP

Aspect	ATIP	MCP
Purpose	Tool introspection	Stateful execution
Infrastructure	None	Server process
Typical tools	gh, kubectl, terraform	Playwright, databases
Use together?	Yes — ATIP for discovery, MCP for execution

ATIP and MCP solve different problems. See docs/why-not-mcp.md for detailed comparison.

Status

Current Version: 0.6.0 (Draft)

This specification is open for community feedback and contributions.

Roadmap

v0.1.0 — Core protocol and schema
v0.2.0 — Partial discovery
v0.3.0 — Interactive effects
v0.4.0 — Trust and provenance
v0.5.0 — Cryptographic verification (SLSA/Sigstore)
v0.6.0 — Content-addressable registry
v1.0.0 — Stable release

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Proposing spec changes
Contributing shims
Reporting issues
Submitting implementations

License

This specification and reference implementations are released under the MIT License.

Links

Specification: spec/rfc.md
JSON Schema: schema/0.6.json
Issues: GitHub Issues
Discussions: GitHub Discussions

Built for the agent-native future.

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
.claude/agents		.claude/agents
docs		docs
examples		examples
reference		reference
schema		schema
spec		spec
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md

License

lenulus/atip

Folders and files

Latest commit

History

Repository files navigation

ATIP (Agent Tool Introspection Protocol)

A lightweight, CLI-first protocol that allows AI agents to safely introspect and cryptographically verify local tools via a simple --agent contract, without requiring MCP servers or additional infrastructure.

What is ATIP?

Why ATIP?

The Problem

The Solution

Quick Start

For Tool Authors

For Legacy Tools

For Agent Developers

Key Features

🎯 Zero Infrastructure

🔒 Safety Metadata

🛡️ Trust & Supply Chain Security

📦 Partial Discovery

🔄 Interactive Tool Handling

🌐 Universal Translation

🤝 MCP Compatible

Architecture

Repository Structure

Documentation

Reference Tools

Examples

Minimal ATIP

Full Example

Example Tools

Comparison to MCP

Status

Roadmap

Contributing

License

Links

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages