> ## 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.

# Tool Manifest

> Discover SimpleFunctions CLI commands programmatically.

Agents should call:

```bash theme={null}
sf describe --all --json
sf tools plan "first time setup and login" --json
sf tools search "portfolio history" --json
sf tools plan "explain why CPI residual moved" --json
sf tools plan "tell me if oil explains CPI residual and send it to telegram" --json
sf tools plan "get my current user state and find quality opportunities" --json
sf guide --agent --json
```

`sf describe --all --json` returns the machine-readable catalog of CLI tools. `sf tools search` ranks that catalog for a natural-language task. `sf tools plan` returns a conservative ordered sequence with command strings, auth requirements, side-effect levels, and reasons. `sf guide --agent --json` returns local playbooks built around the same command contract.

This page documents CLI command discovery only. It is not the SDK/Agent contract manifest.

Use these surfaces for the different tool universes:

| Surface                    | Purpose                                                        |
| -------------------------- | -------------------------------------------------------------- |
| `GET /api/contracts/tools` | Strict SDK/Agent contract manifest with canonical dotted names |
| `sf describe --all --json` | Local CLI command manifest                                     |
| `GET /api/tools`           | Broad hosted compatibility inventory                           |

## Manifest fields

```ts theme={null}
type CliToolManifestItem = {
  name: string
  namespace?: string
  command: string
  description: string
  authRequired: boolean
  authType: 'none' | 'sf_api_key' | 'exchange_key' | 'browser_session' | 'mixed'
  readOnly: boolean
  sideEffects: boolean
  longRunning: boolean
  jsonStable: boolean
  outputModes: ('human' | 'json' | 'markdown')[]
  dangerLevel: 'safe_read' | 'account_read' | 'local_runtime' | 'server_write' | 'exchange_write'
  requiredArgs: Array<{ name: string; description: string }>
  options: Array<{ name: string; type: string; default?: unknown; description: string }>
  examples: Array<{ command: string; purpose: string }>
  responseSchema?: unknown
  errorSchema?: unknown
}
```

## Safety model

| Danger level     | Meaning                              |
| ---------------- | ------------------------------------ |
| `safe_read`      | Public or local read-only data       |
| `account_read`   | Reads authenticated user data        |
| `local_runtime`  | Starts or stops a local process      |
| `server_write`   | Mutates SimpleFunctions server state |
| `exchange_write` | Can place/cancel exchange orders     |

Agents should prefer `safe_read` and `account_read` commands unless explicitly authorized to mutate state.

## Planning model

Agents should use the catalog before guessing commands.

```bash theme={null}
sf tools plan "watch this FRED release and alert me when related markets move" --json
sf tools plan "find quality opportunities for my agent loop" --json
sf tools plan "tell me if oil explains CPI residual and send it to telegram" --json
sf tools plan "tell me if oil explains CPI residual and send it to telegram" --allow-side-effects --json
sf workflow demo monitor --dry-run --json
```

The planner is local and manifest-backed. It should surface read-first steps such as `status`, `login`, `setup --check`, `doctor`, `guide`, `brief`, `discover`, `investigate`, `query`, `econ`, `policy`, `world`, `inspect`, `watchlist`, `alerts`, `webhooks`, and `monitor list`; write/runtime/trade commands remain marked with side-effect metadata so the caller can require explicit approval.

Discovery tasks route through `sf discover --quality --json`, which combines ideas, world opportunities, cross-venue gaps, fresh listings, and contagion signals into a ranked queue. Authenticated loop tasks route through `sf brief --agent --json`, which summarizes user/workflow/portfolio/world context without returning secrets or raw delivery payloads.

Onboarding tasks route through `sf status --json`, `sf login`, `sf setup --check`, `sf doctor --agent --json`, `sf guide --agent --json`, `sf brief --agent --json`, and `sf describe --all --json`. Monitoring and delivery tasks such as "tell me if X and send it to Telegram" route through read-first investigation and existing workflow reads, then gate `sf monitor create` and `sf monitor run` behind `--allow-side-effects`.

The workflow demo is also local and non-mutating. It emits the full watchlist, alert, webhook, and research-monitor chain as a dry run so an agent can show the user exactly what would happen before running authenticated writes.

## Workflow namespaces

The live manifest includes the workflow namespaces used by monitoring agents:

| Namespace   | Typical command                             | Danger model                                                             |
| ----------- | ------------------------------------------- | ------------------------------------------------------------------------ |
| `watchlist` | `sf watchlist list --json`                  | read plus authenticated server writes for add/remove/refresh             |
| `alerts`    | `sf alerts list --json`                     | read plus authenticated server writes for create/pause/test/delete       |
| `webhooks`  | `sf webhooks list --json`                   | read plus authenticated server writes for add/test/rotate/delete         |
| `monitor`   | `sf monitor list --json`                    | read plus authenticated server writes for create/run/pause/resume/delete |
| `poly`      | `sf poly search "query" --json`             | public/wallet-address Polymarket global reads                            |
| `polyus`    | `sf polyus markets --json`                  | public Polymarket US reads; auth boundary is explicit                    |
| `forum`     | `sf forum read --json`                      | authenticated reads and channel/message writes                           |
| `brief`     | `sf brief --agent --json`                   | authenticated read-only agent loop brief                                 |
| `discover`  | `sf discover --quality --json`              | public read-only quality discovery feed                                  |
| `guide`     | `sf guide --agent --json`                   | local read-only onboarding playbooks                                     |
| `workflow`  | `sf workflow demo monitor --dry-run --json` | local read-only dry-run plan                                             |
| `trace`     | `sf trace receipt trace.ndjson --json`      | local read-only trace audit                                              |