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

# Use SimpleFunctions tools from an agent

> Direct one-shot agent tool calls with stream-json or NDJSON events.

`sf agent --tool <canonical.tool>` calls a contract-mapped tool directly. It does not require an LLM key.

This is direct CLI tool mode, not the Agent SDK. `@spfunctions/agent` is the embeddable TypeScript runtime for Cursor-style market agents; this page documents the CLI wrapper around the same strict canonical tool semantics.

```bash theme={null}
sf agent --tool world.read --stream-json
sf agent --tool markets.search --input '{"query":"Fed CPI","limit":5}' --stream-json
sf agent --tool market.inspect --input '{"ticker":"KXRECESSION-26DEC31"}' --ndjson
```

`--tool` accepts canonical dotted names only. The older `sf agent --stream-json --once <tool>` path remains as compatibility behavior, but `--once` by itself is prompt mode.

The event stream includes:

* `session.init`
* `tool.catalog.loaded`
* `run.started`
* `tool.call.started`
* `tool.call.completed` or `tool.call.failed`
* `agent.final`
* `trace.receipt` when `--record-trace` is used
* `run.completed` or `run.failed`

## Trace

```bash theme={null}
sf agent --tool markets.search --stream-json \
  --input '{"query":"Fed CPI","limit":5}' \
  --record-trace trace.ndjson
```

Trace output is local NDJSON. Tool traces store canonical tool names, full redacted replayable output, and compact `outputSummary` audit fields. They must not store API keys, bearer tokens, venue credentials, or trading secrets.

Replay is deterministic for direct tool mode:

```bash theme={null}
sf agent --tool markets.search --stream-json \
  --input '{"query":"Fed CPI","limit":5}' \
  --replay-trace trace.ndjson
```

If the trace does not contain a replayable entry for the same canonical tool and input, direct replay fails rather than silently calling the live API.

## Manifest

`sf.manifest.list()` and `sf.manifest.get("world.read")` use `/api/contracts/tools`, the strict SDK/Agent manifest. Broad `/api/tools` names like `get_world_state` are hosted compatibility names, not canonical SDK/Agent contract names.

## Policy

Public read/research tools use `read.public`, `market_data`, `research`, and `sideEffect: none`.

Authenticated reads use `read.user`, require `SF_API_KEY`, and are not part of unauthenticated hello-world examples.

Write, paper-trade, runtime, secret, and live-trade tools are not exposed by default in direct once-mode.