> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Guide

> Single-page operational reference for agents using SimpleFunctions — quick rules, do's and don'ts, tool selection.

This is the compact guide an agent should ingest before using SimpleFunctions.

## Start sequence

```bash theme={null}
sf describe --all --json
sf world --json
sf query "Fed rate cut" --json --limit 3
sf inspect KXRATECUT-26DEC31 --json
```

## Safety classes

| Class            | Meaning                              |
| ---------------- | ------------------------------------ |
| `safe_read`      | Public read-only call                |
| `account_read`   | Authenticated user-scoped read       |
| `local_runtime`  | Starts or stops local process        |
| `server_write`   | Mutates SimpleFunctions server state |
| `exchange_write` | Can place or cancel exchange orders  |

## Tool discovery

```bash theme={null}
sf describe --all --json
curl "https://simplefunctions.dev/api/contracts/tools"
curl "https://simplefunctions.dev/api/tools"
```

Use each catalog for its intended layer:

| Catalog                    | Meaning                                   |
| -------------------------- | ----------------------------------------- |
| `sf describe --all --json` | Local installed CLI command manifest.     |
| `/api/contracts/tools`     | Strict SDK/Agent canonical tool manifest. |
| `/api/tools`               | Broad hosted compatibility inventory.     |

SDK and Agent SDK code should use canonical dotted names from
`/api/contracts/tools`. Broad names such as `get_world_state` are not canonical
SDK/Agent tools.

## Preferred context strategy

| Situation        | Call                                                                    |
| ---------------- | ----------------------------------------------------------------------- |
| New session      | `sf world --json`                                                       |
| Polling loop     | `sf world --delta --json --since 1h`                                    |
| Topic search     | `sf query "<topic>" --json --limit 3`                                   |
| Market detail    | `sf inspect <ticker> --json`                                            |
| Account memory   | `sf me --json --detail --limit 10`                                      |
| Portfolio memory | `sf portfolio history --json --ticks 20 --trades 10 --since 2026-04-23` |

## Error handling

Use the JSON contract. Do not scrape human terminal output.

```bash theme={null}
sf query "Fed rate cut" --json
```

Errors should be structured and exit codes should classify the failure.