SimpleFunctions Developer Manual

Agents should call:

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

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.

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

CLI for humans and agents

Agent runtime

Portfolio

Tool Manifest

Manifest fields

Safety model

Planning model

Workflow namespaces

​Manifest fields

​Safety model

​Planning model

​Workflow namespaces

Manifest fields

Safety model

Planning model

Workflow namespaces