SimpleFunctions Developer Manual

SimpleFunctions has several tool catalogs. They are not interchangeable.

Use GET /api/contracts/tools for strict SDK and Agent SDK contract truth.
Use sf describe --all --json for the installed local CLI command manifest.
Use GET /api/tools for the broad hosted HTTP compatibility inventory.
Use MCP only as an adapter for MCP-compatible hosts.

/api/tools is not the SDK/Agent contract manifest. It can include broad compatibility names such as get_world_state; SDK and Agent SDK code should use canonical dotted names such as world.read from /api/contracts/tools.

Strict contract manifest

GET /api/contracts/tools

This is the canonical SDK/Agent tool universe. See Contract tools for schema version, access.anonymousAllowed, sideEffect, costEffect, Agent callability, SDK mapping, and replay metadata.

Local CLI catalog

sf describe --all --json          # full installed command manifest
sf tools --json                   # HTTP catalog wrapped in CLI envelope
sf tools search "<task>" --json   # search by task / option / tag
sf tools plan "<task>" --json     # plan a command sequence
sf skills list --json             # discover skills locally

For agents running on a user machine, the CLI manifest is the canonical local command surface. It reflects the installed version, local auth, local-only commands, command policy metadata, and JSON capability flags. It is not the SDK/Agent package contract. See Tool manifest.

HTTP tool catalog

GET /api/tools

Auth: none. Returns the broad hosted HTTP tool catalog used by remote integrations. Two tiers — public (no auth required) and authenticated (sf_live_...):

curl "https://simplefunctions.dev/api/tools" | jq '.tools.public | length, .tools.authenticated | length'

Each tool record has name, description, endpoint (when there is a 1:1 HTTP route), parameters, auth, returns, and an example URL. This is not a byte-for-byte mirror of sf describe --all --json, and it is not the strict SDK/Agent manifest. Use /api/tools for the broad remote HTTP compatibility surface. Use sf describe --all --json for the installed CLI command catalog and its command-level policy metadata. Use MCP tools reference only for the MCP adapter inventory and input schemas.

# all public tool names
curl -s "https://simplefunctions.dev/api/tools" \
  | jq -r '.tools.public[] | "\(.name)\t\(.endpoint)"'

Skill catalog

GET /api/skills

Auth: none. Returns the bundled skill catalog. A skill is a reusable agent capability — a markdown bundle with a description, a trigger phrase, declared tools, and a prompt body. This endpoint is the network-side discovery view; user-authored skills live behind /api/skill*.

{
  "skills": [
    {
      "name": "fed-watch",
      "trigger": "watch the Fed",
      "description": "Daily Fed-day workflow — check FOMC calendar, inspect rate-cut markets, summarise edges.",
      "category": "macro",
      "tags": ["fed", "rates"],
      "toolsUsed": ["get_world_state", "inspect_ticker", "get_calendar"],
      "estimatedTime": "30s",
      "prompt": "..."
    }
  ]
}

User-owned skills (create / fork / publish / run) live under /api/skill — see Skills.

Prompt context

GET /api/prompt

Auth: required. Returns the SimpleFunctions prompt / runtime context for the current user — system prompt, active thesis hints, available tools, and recent activity, shaped for an agent that’s about to start a turn.

curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/prompt"

MCP adapter

GET  /api/mcp/{transport}
POST /api/mcp/{transport}

Auth: none for tool discovery and public tools. Bearer sf_live_... to access authenticated tools (thesis, intents, portfolio, …). The MCP transport exposes SimpleFunctions tools to MCP-compatible clients (Claude Code, Cursor, Cline, …). Treat it as an adapter over the CLI/API product surface. See MCP server for client wire-up and MCP tools reference for the adapter tool list and input schemas. One-line client setup:

claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp

Voice — text-to-speech (TTS)

POST /api/proxy/tts

Auth: required (Authorization: Bearer sf_live_...). Body (JSON):

Field	Type	Required	Default	Notes
`text`	string	yes	—	1 – 5000 chars.
`voiceId`	string	optional	professional news anchor voice	Cartesia voice id.
`speed`	number	optional	implementation default	Speech rate.
`language`	string	optional	en	BCP-47 language tag.

Response: audio/mpeg binary stream (MP3). Errors

Status	Body	Cause
`400`	`Invalid JSON body`	Body is not JSON.
`400`	`text required (string, min 1 char)`	Empty text.
`400`	`text too long (max 5000 chars)`	Over the limit.
`401`	unauthorized	No / invalid auth.
`503`	`TTS proxy not configured`	Server has no Cartesia key configured.

curl -X POST -H "Authorization: Bearer $SF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Fed cuts in December","speed":1.0}' \
  "https://simplefunctions.dev/api/proxy/tts" \
  --output out.mp3

Voice — speech-to-text (STT)

POST /api/proxy/stt

Auth: required. Body: multipart/form-data with field audio (or file). Max 10 MB. Response 200

{
  "text": "Fed cuts in December",
  "duration": 1.84,
  "words": [
    { "text": "Fed", "start": 0.10, "end": 0.32 },
    { "text": "cuts", "start": 0.34, "end": 0.62 }
  ]
}

Errors

Status	Body	Cause
`400`	`Expected multipart/form-data with "audio" field`	Missing form field.
`400`	`"audio" file field required`	Field empty or wrong type.
`400`	`Audio file too large (max 10MB)`	Over the size limit.
`401`	unauthorized	No / invalid auth.
`503`	`STT proxy not configured`	Server has no Cartesia key configured.

curl -X POST -H "Authorization: Bearer $SF_API_KEY" \
  -F "audio=@clip.wav" \
  "https://simplefunctions.dev/api/proxy/stt"

The sf agent voice mode uses these endpoints internally; you only need to call them directly when wiring SimpleFunctions tools into another voice agent.

Tool manifest

Local discovery via sf describe --all --json.

Skills

User-owned skill CRUD, fork, publish.

MCP server

Adapter for Claude Code, Cursor, Cline.

MCP tools reference

MCP adapter inventory and input schemas.

Start with the API

Public market APIs

Authenticated APIs

Tools and events

Tools, skills, voice

Strict contract manifest

Local CLI catalog

HTTP tool catalog

Skill catalog

Prompt context

MCP adapter

Voice — text-to-speech (TTS)

Voice — speech-to-text (STT)

See also

Tool manifest

Skills

MCP server

MCP tools reference

​Strict contract manifest

​Local CLI catalog

​HTTP tool catalog

​Skill catalog

​Prompt context

​MCP adapter

​Voice — text-to-speech (TTS)

​Voice — speech-to-text (STT)

​See also

Tool manifest

Skills

MCP server

MCP tools reference

Strict contract manifest

Local CLI catalog

HTTP tool catalog

Skill catalog

Prompt context

MCP adapter

Voice — text-to-speech (TTS)

Voice — speech-to-text (STT)

See also