> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora tools

> Manage Tool blocks — HTTP, inline runtimes, parameters, headers, DB verification.

Tools are what Agents call at runtime. The `tools` command group creates, edits, and configures Tool blocks. A Tool has a runtime (HTTP or inline), typed parameters, and optional HTTP headers.

## Commands

| Command                          | Description                            |
| -------------------------------- | -------------------------------------- |
| `tools create --name <n>`        | Add a Tool block.                      |
| `tools update <tool-id>`         | Patch fields (many `--set-*` flags).   |
| `tools edit <tool-id>`           | Open Tool JSON in `$EDITOR`.           |
| `tools delete <tool-id>`         | Remove Tool.                           |
| `tools verify-db <tool-id>`      | Test the DB connection for a SQL tool. |
| `tools params list <tool-id>`    | Print declared parameters.             |
| `tools params add <tool-id>`     | Append a parameter.                    |
| `tools params update <tool-id>`  | Patch a parameter.                     |
| `tools params remove <tool-id>`  | Remove a parameter.                    |
| `tools params reorder <tool-id>` | Reorder parameters.                    |
| `tools headers list <tool-id>`   | Print HTTP headers.                    |
| `tools headers add <tool-id>`    | Add an HTTP header.                    |
| `tools headers remove <tool-id>` | Remove an HTTP header.                 |

## `tools create`

```bash theme={null}
nora tools create \
  --name refund_order \
  --description "Refund an order by order_id" \
  --runtime '{"kind":"http","method":"POST","url":"https://api.example.com/refunds/{order_id}"}' \
  --params '[{"name":"order_id","type":"string","required":true,"description":"Order ID","location":"url","source":"llm"}]'
```

Flags:

* `--name <n>` (required) — how the Agent refers to it.
* `--description <d>` — the single-most-important field. The Agent uses this to decide when to call the tool. Write clearly.
* `--runtime <json>` — the runtime spec (HTTP or inline).
* `--params <json>` — array of parameters. See `nora schema show` for the exact shape.
* `--x <n>`, `--y <n>` — canvas position.

Runtime shapes at a glance:

**HTTP**:

```json theme={null}
{
  "kind": "http",
  "method": "POST",
  "url": "https://api.example.com/refunds/{order_id}",
  "auth": {"kind": "bearer", "value": "secrets://api_key"}
}
```

**Inline** (JS/Python/SQL):

```json theme={null}
{
  "kind": "inline",
  "lang": "javascript",
  "code": "return { doubled: input * 2 };"
}
```

The command prints the new Tool's ID.

## `tools update`

```bash theme={null}
nora tools update t_refund \
  --set-description "Refund an order (partial or full)" \
  --set-http-url "https://api.example.com/refunds/v2/{order_id}"
```

### Update flags — grouped

**Identity**

* `--set-name <n>`
* `--set-description <d>`
* `--set-icon <name>`

**Behavior**

* `--set-idempotent on|off` — is calling twice the same as calling once?
* `--set-required on|off` — Agent must call this at least once per run.
* `--set-approval on|off` — require approval before each call.
* `--set-max-turns <n>` — cap how many times the Agent can call this in one run.

**HTTP runtime**

* `--set-runtime-kind http|inline` — switch runtime.
* `--set-http-method <m>` — `GET` / `POST` / `PATCH` / `PUT` / `DELETE`.
* `--set-http-url <url>`.
* `--set-http-auth-kind <k>` — `none` / `bearer` / `header` / `basic` / `secret`.
* `--set-http-auth-header <name>` — for `header` auth, header name.
* `--set-http-auth-value <v>` — auth value (literal or `secrets://ref`).

**Inline runtime**

* `--set-inline-lang <lang>` — `javascript` / `python` / `sql`.
* `--set-inline-code <text>` — inline code.
* `--set-inline-code-file <path>` — code from file (replaces `--set-inline-code`).
* `--set-inline-database-url <url>` — for SQL: database connection string. Accepts `secrets://ref`.

**Verification**

* `--verify` — for SQL tools, tests the DB connection and marks `connected=true` on success.

**Position/size**

* `--set-x <n>`, `--set-y <n>`, `--set-width <n>`.

**Bulk**

* `--patch <json>` — arbitrary JSON merge.

Runtime `--set-*` flags deep-merge into the existing runtime object, so you can change just one field without re-specifying the whole runtime.

## `tools edit`

```bash theme={null}
nora tools edit t_refund
```

Opens Tool JSON in `$EDITOR`. Save to apply.

## `tools verify-db`

```bash theme={null}
nora tools verify-db t_query_users
```

For SQL Tools, connects to the configured database and runs a probe query. On success, marks `runtime.connected=true` so the Tool shows as green in the app.

Failures print the exact error (bad URL, missing driver, auth failure).

## `tools params` — declared inputs

Parameters are the typed inputs the Agent picks values for. Each param has a name, type, source (Agent-picked or fixed), location, and description.

### List

```bash theme={null}
nora tools params list t_refund
```

Prints all parameters as JSON.

### Add

```bash theme={null}
nora tools params add t_refund \
  --name amount_cents \
  --type integer \
  --required \
  --location body \
  --source llm \
  --description "Amount to refund in cents"
```

Flags:

* `--name <n>` (required).
* `--type <t>` (required) — `string` / `integer` / `number` / `float` / `boolean` / `array` / `object`.
* `--description <d>` — read by the Agent to choose values.
* `--required` — no default; Agent must supply.
* `--location <loc>` — `url` / `query` / `body` / `header`. Where the value goes in the HTTP request.
* `--source <src>` — `llm` (Agent picks) or `fixed`.
* `--fixed-value <v>` — for `source=fixed`.

### Update

```bash theme={null}
nora tools params update t_refund \
  --name amount_cents \
  --set-required
```

Patch. Only fields passed change.

### Remove & reorder

```bash theme={null}
nora tools params remove t_refund --name unused_param
nora tools params reorder t_refund --names order_id,amount_cents,reason
```

`reorder` requires a full permutation (every param exactly once).

## `tools headers` — HTTP headers

For HTTP Tools, headers are stored on the runtime.

### List / add / remove

```bash theme={null}
nora tools headers list t_refund
nora tools headers add t_refund --name X-Api-Version --value "2026-07-01"
nora tools headers add t_refund --name Authorization --value 'secrets://refund_api_key'
nora tools headers remove t_refund --name X-Api-Version
```

Secret values: pass `secrets://<ref>` (references a workspace secret) or a plain string (stored inline).

For interactive secret entry:

```bash theme={null}
nora tools headers add t_refund --name Authorization --value ?
# CLI prompts and masks input
```

See [Piping & secrets](/cli/piping-and-secrets) for all input modes.

## Recipes

### Migrate a Tool from one URL to another

```bash theme={null}
nora tools update t_refund --set-http-url https://api-v2.example.com/refunds/{order_id}
```

Publish separately.

### Rotate an API key across all Tools using it

```bash theme={null}
new_key="Bearer $(cat new-key.txt)"
for id in $(nora flows get support | jq -r '.blocks[] | select(.kind=="tool").id'); do
  # Remove old header, add new
  nora tools headers remove $id --name Authorization 2>/dev/null
  nora tools headers add $id --name Authorization --value "$new_key"
done
```

Better long-term: use `secrets://api_key` and rotate the underlying secret once.

### Freeze a Tool's arguments

Turn Agent-picked args into fixed ones for a specific rollout:

```bash theme={null}
nora tools params update t_refund \
  --name reason \
  --set-source fixed \
  --set-fixed-value "customer_requested"
```

Every future call will use `"customer_requested"` regardless of Agent output.