nora tools

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`

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:

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

Inline (JS/Python/SQL):

{
  "kind": "inline",
  "lang": "javascript",
  "code": "return { doubled: input * 2 };"
}

The command prints the new Tool’s ID.

`tools update`

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`

nora tools edit t_refund

Opens Tool JSON in $EDITOR. Save to apply.

`tools verify-db`

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

nora tools params list t_refund

Prints all parameters as JSON.

Add

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

nora tools params update t_refund \
  --name amount_cents \
  --set-required

Patch. Only fields passed change.

Remove & reorder

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

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:

nora tools headers add t_refund --name Authorization --value ?
# CLI prompts and masks input

See Piping & secrets for all input modes.

Recipes

Migrate a Tool from one URL to another

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

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:

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.

Setup

Flows

Blocks

Data & knowledge

Reliability

Workspace

Reference

Commands

`tools create`

`tools update`

Update flags — grouped

`tools edit`

`tools verify-db`

`tools params` — declared inputs

List

Add

Update

Remove & reorder

`tools headers` — HTTP headers

List / add / remove

Recipes

Migrate a Tool from one URL to another

Rotate an API key across all Tools using it

Freeze a Tool’s arguments

​Commands

​tools create

​tools update

​Update flags — grouped

​tools edit

​tools verify-db

​tools params — declared inputs

​List

​Add

​Update

​Remove & reorder

​tools headers — HTTP headers

​List / add / remove

​Recipes

​Migrate a Tool from one URL to another

​Rotate an API key across all Tools using it

​Freeze a Tool’s arguments

Commands

`tools create`

`tools update`

Update flags — grouped

`tools edit`

`tools verify-db`

`tools params` — declared inputs

List

Add

Update

Remove & reorder

`tools headers` — HTTP headers

List / add / remove

Recipes

Migrate a Tool from one URL to another

Rotate an API key across all Tools using it

Freeze a Tool’s arguments