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

> Tool 블록 관리 — HTTP·인라인 런타임, 파라미터, 헤더, DB 검증.

Tool 이 Agent 가 런타임에 호출하는 것. `tools` 명령 그룹이 Tool 블록 생성·편집·설정. Tool 은 런타임 (HTTP 나 인라인), 타입 있는 파라미터, 옵션 HTTP 헤더 가짐.

## 명령

| 명령                               | 설명                          |
| -------------------------------- | --------------------------- |
| `tools create --name <n>`        | Tool 블록 추가.                 |
| `tools update <tool-id>`         | 필드 패치 (많은 `--set-*` 플래그).   |
| `tools edit <tool-id>`           | Tool JSON 을 `$EDITOR` 에 열기. |
| `tools delete <tool-id>`         | Tool 제거.                    |
| `tools verify-db <tool-id>`      | SQL 도구의 DB 연결 테스트.          |
| `tools params list <tool-id>`    | 선언된 파라미터 인쇄.                |
| `tools params add <tool-id>`     | 파라미터 추가.                    |
| `tools params update <tool-id>`  | 파라미터 패치.                    |
| `tools params remove <tool-id>`  | 파라미터 제거.                    |
| `tools params reorder <tool-id>` | 파라미터 재정렬.                   |
| `tools headers list <tool-id>`   | HTTP 헤더 인쇄.                 |
| `tools headers add <tool-id>`    | HTTP 헤더 추가.                 |
| `tools headers remove <tool-id>` | HTTP 헤더 제거.                 |

## `tools create`

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

플래그:

* `--name <n>` (필수) — Agent 가 참조하는 방법.
* `--description <d>` — 가장 중요한 단일 필드. Agent 가 이걸로 언제 도구 호출할지 결정. 명확히 쓰기.
* `--runtime <json>` — 런타임 스펙 (HTTP 또는 인라인).
* `--params <json>` — 파라미터 배열. 정확한 모양은 `nora schema show` 참고.
* `--x <n>`, `--y <n>` — 캔버스 위치.

런타임 모양 한눈에:

**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 };"
}
```

명령이 새 Tool 의 ID 인쇄.

## `tools update`

```bash theme={null}
nora tools update t_refund \
  --set-description "주문 환불 (부분이나 전체)" \
  --set-http-url "https://api.example.com/refunds/v2/{order_id}"
```

### Update 플래그 — 그룹핑

**정체성**

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

**동작**

* `--set-idempotent on|off` — 두 번 호출이 한 번 호출과 같나?
* `--set-required on|off` — Agent 가 실행당 최소 한 번 호출해야.
* `--set-approval on|off` — 각 호출 전 승인 요구.
* `--set-max-turns <n>` — Agent 가 한 실행에서 이걸 몇 번 호출할 수 있는지 캡.

**HTTP 런타임**

* `--set-runtime-kind http|inline` — 런타임 전환.
* `--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>` — `api_key` auth 용 헤더 이름. `bearer` 는 무시됨.
* `--set-http-auth-value <v>` — auth 값 (리터럴이나 `secrets://ref`).

**Inline 런타임**

* `--set-inline-lang <lang>` — `javascript` / `python` / `sql`.
* `--set-inline-code <text>` — 인라인 코드.
* `--set-inline-code-file <path>` — 파일에서 코드 (`--set-inline-code` 교체).
* `--set-inline-database-url <url>` — SQL 용: DB 연결 문자열. `secrets://ref` 수용.

**검증**

* `--verify` — SQL 도구용, DB 연결 테스트하고 성공 시 `connected=true` 표시.

**위치/크기**

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

**벌크**

* `--patch <json>` — 임의 JSON 병합.

런타임 `--set-*` 플래그가 기존 런타임 객체에 deep-merge, 그래서 전체 런타임 재지정 없이 한 필드만 바꿈.

## `tools edit`

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

Tool JSON 을 `$EDITOR` 에 열기. 저장으로 적용.

## `tools verify-db`

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

SQL Tool 용, 설정된 DB 에 연결하고 프로브 쿼리 실행. 성공 시 `runtime.connected=true` 표시해 앱에서 Tool 이 초록으로 표시.

실패가 정확한 에러 인쇄 (잘못된 URL, 누락 드라이버, auth 실패).

## `tools params` — 선언된 입력

파라미터가 Agent 가 값 고르는 타입 있는 입력. 각 파라미터가 이름, 타입, 소스 (Agent-선택이나 fixed), 위치, 설명 가짐.

### List

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

모든 파라미터를 JSON 으로 인쇄.

### Add

```bash theme={null}
nora tools params add t_refund \
  --name amount_cents \
  --type integer \
  --required \
  --location body \
  --source llm \
  --description "환불 금액 (센트)"
```

플래그:

* `--name <n>` (필수).
* `--type <t>` (필수) — `string` / `integer` / `number` / `float` / `boolean` / `array` / `object`.
* `--description <d>` — 값 고를 때 Agent 가 읽음.
* `--required` — 기본 없음; Agent 가 제공해야.
* `--location <loc>` — `url` / `query` / `body` / `header`. HTTP 요청에서 값 가는 곳.
* `--source <src>` — `llm` (Agent 선택) 또는 `fixed`.
* `--fixed-value <v>` — `source=fixed` 용.

### Update

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

패치. 넘긴 필드만 변경.

### 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` 는 전체 순열 필요 (모든 param 정확히 한 번).

## `tools headers` — HTTP 헤더

HTTP Tool 용, 헤더가 런타임에 저장.

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

시크릿 값: `secrets://<ref>` 넘김 (워크스페이스 시크릿 참조) 또는 평문 문자열 (인라인 저장).

인터랙티브 시크릿 입력:

```bash theme={null}
nora tools headers add t_refund --name Authorization --value ?
# CLI 가 프롬프트하고 입력 마스킹
```

모든 입력 모드는 [파이핑·시크릿](/ko/cli/piping-and-secrets) 참고.

## 레시피

### Tool 을 한 URL 에서 다른 URL 로 마이그레이션

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

별도 배포.

### 그것 쓰는 모든 Tool 에 API 키 로테이션

```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
  # 이전 헤더 제거, 새 것 추가
  nora tools headers remove $id --name Authorization 2>/dev/null
  nora tools headers add $id --name Authorization --value "$new_key"
done
```

장기적으로 더 나음: `secrets://api_key` 사용하고 하부 시크릿 한 번 로테이션.

### Tool 인자 얼림

Agent 선택 인자를 특정 롤아웃용으로 fixed 로 전환:

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

모든 미래 호출이 Agent 출력 관계없이 `"customer_requested"` 사용.