The AGENT.md Pattern: Teaching AI Agents to Use Your Tools

Agent: I'll use the dataspoc CLI to ingest data.
Agent: Running: dataspoc ingest --from postgres --to s3://bucket
Error: No such command 'ingest'

Agent: Let me try: dataspoc pipe create --source postgres
Error: No such command 'pipe'

Agent: Maybe: dataspoc-pipe --help
[reads 50 lines of help text, burns 2000 tokens]

Agent: OK, I think it's: dataspoc-pipe run my-pipeline
Error: Pipeline 'my-pipeline' not found. Run 'dataspoc-pipe add' first.

# AGENT.md — DataSpoc Platform

## Capabilities

| Action | Tool | Command |
|--------|------|---------|
| Ingest data | Pipe | `dataspoc-pipe run <pipeline>` |
| Add new source | Pipe | `dataspoc-pipe add <name> --source <type>` |
| Query data | Lens | `dataspoc-lens shell` then SQL |
| Ask questions | Lens | `dataspoc-lens ask "<question>"` |
| Train model | Lens | `dataspoc-lens ml train --table <t> --target <col>` |
| Predict | Lens | `dataspoc-lens ml predict --model <name> --input <table>` |

## Python SDK

```python
from dataspoc_pipe import PipeClient
from dataspoc_lens import LensClient

pipe = PipeClient(project_path="./my-project")
lens = LensClient(bucket_alias="company")

# Ingest
pipe.run("my-pipeline")

# Query
result = lens.sql("SELECT * FROM raw__postgres__orders LIMIT 10")

# AI Ask
answer = lens.ask("What is the total revenue this month?")

# Train
lens.ml_train(table="curated__sales__customers", target="churned", model_name="churn-v1")

## Why This Works

AI agents (Claude, GPT-4, Gemini, local models) all share one behavior: they read context and follow instructions. When they encounter AGENT.md, they:

1. **Scan the capabilities table** — know exactly what actions are possible
2. **Copy the Python SDK examples** — use correct syntax on the first try
3. **Follow the patterns** — execute multi-step workflows correctly
4. **Respect the constraints** — avoid common mistakes
5. **Use error recovery** — self-correct without trial and error

The result: one tool call instead of eight. Correct on the first attempt.

## Comparison: Three Approaches

### No Documentation

### README.md (Designed for Humans)

### AGENT.md (Designed for Machines)

## How to Write AGENT.md for Your Own Tools

### Step 1: Capabilities Table

List every action your tool can do. One row per action. Include the exact command or function call.

```markdown
## Capabilities

| Action | Command/Function |
|--------|-----------------|
| Create user | `api.create_user(email, name)` |
| List users | `api.list_users(filters={})` |
| Delete user | `api.delete_user(user_id)` |

## SDK

```python
from myservice import Client

client = Client(api_key=os.environ["MY_API_KEY"])

# Create
user = client.create_user(email="test@example.com", name="Test")

# Read
users = client.list_users(filters={"active": True})

# Update
client.update_user(user.id, name="New Name")

### Step 3: Patterns (Multi-step Workflows)

Agents need to know the order of operations. Show common workflows as numbered steps:

```markdown
## Patterns

### Onboard a New Customer
1. `client.create_org(name="Acme")`
2. `client.create_user(email="admin@acme.com", org_id=org.id, role="admin")`
3. `client.send_invite(user.id)`

### Generate Monthly Report
1. `data = client.get_metrics(period="last_month")`
2. `report = client.generate_report(data, format="pdf")`
3. `client.email_report(report, recipients=["cfo@company.com"])`

## Constraints

- Never delete production data without confirmation
- Always use pagination for list endpoints (max 100 per page)
- Rate limit: 60 requests per minute
- IDs are UUIDs, never integers
- Dates are always ISO 8601 with timezone

## Error Recovery

| Error | Fix |
|-------|-----|
| 401 Unauthorized | Re-check API_KEY env var |
| 404 Not Found | Verify resource ID with list endpoint |
| 429 Rate Limited | Wait 60 seconds, retry |
| 500 Server Error | Retry up to 3 times with backoff |

# AGENT.md — [Your Tool Name]

## Capabilities

| Action | Command/Function | Returns |
|--------|-----------------|---------|
| ... | ... | ... |

## Setup

```python
from your_tool import Client
client = Client()  # or however initialization works

# Operation 1
result = client.do_thing(param1, param2)

# Operation 2
items = client.list_things(filter="active")

## Where to Put AGENT.md

Place it where AI agents will find it:

- **Repository root** — agents exploring your codebase will find it immediately
- **Package directory** — agents using your installed package can locate it
- **Documentation site** — agents with web access can fetch it
- **System prompt** — if you control the agent, inject it directly

DataSpoc includes AGENT.md in the installed package:

```python
import importlib.resources
agent_instructions = importlib.resources.read_text("dataspoc_lens", "AGENT.md")

@server.resource("dataspoc://agent-instructions")
def get_agent_instructions():
    return read_file("AGENT.md")