> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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"`를 씀.