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 lock <tool-id>`	Freeze the block against MCP / CLI edits.
`tools unlock <tool-id>`	Unlock (sanctioned unlock ceremony).
`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.
--set-retry-safe on|off: the tool is safe to retry on transient failure (server retries automatically when on).
--set-dedupe-key-template <template>: per-call dedupe key template. Renders with {{param}} interpolation; two calls with the same rendered key coalesce into one execution. Use for idempotent side effects that carry no natural id.

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 / api_key / bearer.
--set-http-auth-header <name>: for api_key auth, the header name. Ignored for bearer.
--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 lock` / `tools unlock`

nora tools lock t_refund
nora tools unlock t_refund

Lock a tool to freeze it against MCP-driven agents or CLI patches. Update / delete / apply_flow calls that would modify it are rejected server-side. Unlock is the sanctioned single-field {"locked": false} ceremony. Same lock semantics apply across agents, tools, actions, and triggers.

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

CLI

SDK

Local App

Commands

`tools create`

`tools update`

Update flags: grouped

`tools edit`

`tools lock` / `tools unlock`

`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 lock / tools unlock

​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 lock` / `tools unlock`

`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