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

# Tools, skills, voice

> CLI-first tool discovery, HTTP tool catalog, skill catalog, prompt context, MCP adapter, and the speech-to-text / text-to-speech proxies for voice agents.

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

```http theme={null}
GET /api/contracts/tools
```

This is the canonical SDK/Agent tool universe. See [Contract tools](/api-reference/contract-tools)
for schema version, `access.anonymousAllowed`, `sideEffect`, `costEffect`,
Agent callability, SDK mapping, and replay metadata.

## Local CLI catalog

```bash theme={null}
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](/cli/tool-manifest).

## HTTP tool catalog

```http theme={null}
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_...`):

```bash theme={null}
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](/reference/mcp-tools) only for the MCP adapter inventory
and input schemas.

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

## Skill catalog

```http theme={null}
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*`](/build/skills).

```json theme={null}
{
  "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](/build/skills).

## Prompt context

```http theme={null}
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.

```bash theme={null}
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://simplefunctions.dev/api/prompt"
```

## MCP adapter

```http theme={null}
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](/cli/mcp-server) for client wire-up and [MCP tools reference](/reference/mcp-tools) for the adapter tool list and input schemas.

One-line client setup:

```bash theme={null}
claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp
```

## Voice — text-to-speech (TTS)

```http theme={null}
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. |

```bash theme={null}
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)

```http theme={null}
POST /api/proxy/stt
```

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

**Response 200**

```json theme={null}
{
  "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. |

```bash theme={null}
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.

## See also

<CardGroup cols={2}>
  <Card title="Tool manifest" href="/cli/tool-manifest">
    Local discovery via `sf describe --all --json`.
  </Card>

  <Card title="Skills" href="/build/skills">
    User-owned skill CRUD, fork, publish.
  </Card>

  <Card title="MCP server" href="/cli/mcp-server">
    Adapter for Claude Code, Cursor, Cline.
  </Card>

  <Card title="MCP tools reference" href="/reference/mcp-tools">
    MCP adapter inventory and input schemas.
  </Card>
</CardGroup>