Tool Calling의 시그니처와 호출률에 관한 조사

서론

Tool Calling의 호출률은 Tool의 Description뿐만 아니라 시그니처 (Signature)에 의해서도 좌우됩니다. (시그니처는 메서드 이름, 인수 이름, 필수 지정, 스키마 구조, 반환값 등을 의미합니다.)

이번 조사는 Tool의 시그니처를 변경했을 때 Tool 호출률이 어떻게 변하는지 확인합니다.

시스템 프롬프트(System Prompt)와 Tool의 Description, 시나리오를 고정하고, Tool 시그니처를 변경하여 Tool 호출률에 어떤 변화가 일어나는지를 관측했습니다.

결론적으로, 이번 조건에서는 자연스러운 명칭의 시그니처가 가장 안정적이었습니다. 반면, 인수를 줄인 최소 인수 시그니처 조건은 순서 완전 일치율이 가장 낮았습니다. 스키마를 단순화한다고 해서 반드시 안정화되는 것은 아니었습니다.

검증 설계

Tool의 시그니처에 따른 영향을 보기 위해, 검증 축은 아래의 두 가지로 설정했습니다.

축	값
대상 4개 Tool 시그니처	표준명 시그니처 / 대체명 시그니처 / 모호한 인수명 시그니처 / 최소 인수 시그니처 / 구조화 인수 시그니처
대상 외 Tool 시그니처	범용 더미 시그니처 / 용도별 더미 시그니처

고정 조건은 다음과 같습니다.

축	값
시스템 프롬프트	고정
...

각 조합은 30회씩 실행했습니다.

3개 모델 × 5개 대상 Tool 시그니처 × 2개 대상 외 Tool 시그니처 × 3개 시나리오 × 30회 = 2700회 실행

대상 외 Tool 수는 TODO용 4개의 Tool을 제외한 더미(Dummy) Tool의 수입니다. 이번 구성에서는 TODO용 Tool 4개와 더미 Tool 60개를 합쳐 총 64개의 Tool을 에이전트(Agent)에 설정했습니다.

검증 환경

항목	값
.NET	10
...

검증 방법

이번에는 총 2700회의 실행을 1회의 실행 프로세스로 완수했습니다. 각 모델이나 각 시그니처 사이에서 LM Studio의 모델 언로드/로드(unload/load)는 수행하지 않았습니다.

집계 방법

각 비율은 집계 대상 내의 성공 수를 시행 횟수로 나누어 계산했습니다. 단순한 행 평균이 아닙니다.

각 셀은 30회 실행되었으므로, 개별 셀에서는 편차가 남을 가능성이 있습니다. 따라서 본문에서는 모델별, 시그니처별, 시나리오별 합산 결과를 중심으로 확인하고 있습니다.

본문에서의 표기	의미
필요 Tool 호출률	기대하는 Tool이 모두 1회 이상 호출된 비율
...

검증에 사용한 구체적인 예시

여기서는 실제로 모델에 전달한 시스템 프롬프트와 대상 Tool, 그리고 시나리오 프롬프트를 보여줍니다.

시스템 프롬프트 실례

TODO 조작에 특화되지 않고, 툴 호출 지시만을 기재하고 있습니다.

당신은 사용자의 의뢰에 일본어로 간결하게 답변하는 어시스턴트입니다. 이용 가능한 툴이 있는 경우, 필요하다고 판단될 때만 사용하십시오. 툴을 사용할지 여부는 사용자의 의뢰 내용과 이용 가능한 툴의 설명으로부터 판단하십시오.

대상 Tool 실례

TODO 조작용으로 아래의 4개를 준비했습니다.

조작	표준명 시그니처	대체명 시그니처
등록	`RegisterTodo`	`InsertTodo`
갱신	`UpdateTodo`	`ModifyTodo`
삭제	`DeleteTodo`	`RemoveTodo`
목록	`ListTodos`	`GetTodos`

※ 검증 패턴에 따라 Tool 이름을 표준명 시그니처 또는 대체명 시그니처로 전환하고 있습니다.

Description은 아래의 값으로 고정했습니다.

Tool	Description
등록 Tool	TODO를 등록합니다.
...

대상 4개 Tool의 시그니처는 아래의 5종류를 준비했습니다.

기사 내 표기	내부 키 (Internal Key)	의도
표준 명칭 시그니처 (Standard Name Signature)	canonical	표준 메서드 명칭과 의미가 명확한 플랫 인자 (Flat Argument)를 가진 기준 조건
대체 명칭 시그니처 (Alternative Name Signature)	alternative	`dueDate`를 `date`로, `category`를 `type`으로 변경한 조건
최소 인자 시그니처 (Minimal Argument Signature)	minimal	`dueDate`나 `category` 등의 판단 재료를 제외한 조건
구조화 인자 시그니처 (Structured Argument Signature)	complex	`request.todo`나 `request.patch`와 같이 중첩된 객체 (Nested Object)로 만든 조건

엄격한 시그니처는 다음과 같습니다.

시그니처	등록 (Register)	업데이트 (Update)	삭제 (Delete)	목록 (List)
표준 명칭 시그니처	`RegisterTodo(title,dueDate,category,details?)`	`UpdateTodo(todoId,title,dueDate,details,status)` ※	`DeleteTodo(todoId)`	`ListTodos(statusFilter?)`
대체 명칭 시그니처	`InsertTodo(taskTitle,deadline,category,memo?)`	`ModifyTodo(targetId,taskTitle?,deadline,memo,state)`	`RemoveTodo(targetId)`	`GetTodos(filter?)`
모호한 인자 명칭 시그니처	`RegisterTodo(title,date,type,note?)`	`UpdateTodo(todoId,date,note,state)`	`DeleteTodo(todoId)`	`ListTodos(type?)`
최소 인자 시그니처	`RegisterTodo(title,details?)`	`UpdateTodo(todoId,details?,status)`	`DeleteTodo(todoId)`	`ListTodos()`
구조화 인자 시그니처	`RegisterTodo(request.todo,request.schedule,clientRequestId?)`	`UpdateTodo(request.target,request.patch,reason?)`	`DeleteTodo(request.target,reason?)`	`ListTodos(request.filter?)`

더미 Tool (Dummy Tool) 실례

더미 Tool은 60개를 준비했습니다. 메서드 명칭과 설명 (Description)은 고정하고, 인자 (Argument)만 2가지 패턴으로 구성했습니다.

대상 외 Tool	내부 키 (Internal Key)	입력 (Input)
범용 더미 시그니처	previous-dummy	`query?: string, notes?: string`
용도별 더미 시그니처	function-dummy	각 더미 Tool의 용도에 맞는 인자

범용 더미 시그니처는 모든 더미 Tool에 동일한 범용 인자를 부여하는 조건입니다.
용도별 더미 시그니처는 더미 Tool마다 용도에 맞는 인자를 부여하는 조건입니다.

용도별 더미 시그니처의 모든 사례를 보여드립니다.

범용 더미 시그니처는 모든 Tool에서 query?: string, notes?: string을 사용하므로 생략합니다.

용도별 더미 시그니처의 모든 사례

Method	용도별 더미 시그네처
`SearchWorkspaceFiles`	`searchText?: string, rootPath?: string, filePattern?: string`
`ReadWorkspaceFile`	`path?: string`
`EditWorkspaceFile`	`path?: string, content?: string`
`ListGitChanges`	`repositoryPath?: string`
`ShowGitDiff`	`path?: string`
`CreateGitCommit`	`message?: string`
`RunUnitTests`	`testProject?: string`
`RunIntegrationTests`	`testProject?: string`
`RunLinter`	`targetPath?: string`
`FormatCode`	`targetPath?: string`
`SearchWeb`	`query?: string, maxResults?: integer`
`OpenUrl`	`url?: string`
`QueryGitHubIssues`	`repository?: string, query?: string`
`QueryGitHubPullRequests`	`repository?: string, query?: string`
`CreateGitHubIssue`	`repository?: string, title?: string, body?: string`
`CommentOnGitHubIssue`	`repository?: string, issueNumber?: integer, body?: string`
`ListPullRequestChecks`	`repository?: string, pullRequestNumber?: integer`
`DownloadBuildArtifact`	`runId?: string, artifactName?: string`
`InspectPackageVersions`	`projectPath?: string`
`UpdateDependency`	`projectPath?: string, packageName?: string, version?: string`
`QueryDatabase`	`sql?: string`
`ExplainDatabaseSchema`	`tableName?: string`
`RunDatabaseMigration`	`migrationName?: string`
`RollbackDatabaseMigration`	`migrationName?: string`
`ListCloudResources`	`resourceGroup?: string`
`ShowCloudResource`	`resourceId?: string`
`QueryCloudCosts`	`startDate?: string, endDate?: string`
`QueryApplicationLogs`	`query?: string, startTime?: string, endTime?: string`
`QueryMetrics`	`metricName?: string, startTime?: string, endTime?: string`
`RestartService`	`serviceName?: string`
`ScaleService`	`serviceName?: string, instanceCount?: integer`
`CreateFeatureFlag`	`flagName?: string, description?: string`
`ToggleFeatureFlag`	`flagName?: string, requestedChange?: string`
`QueryReleaseNotes`	`packageName?: string, version?: string`

시나리오 1: TODO 등록 + 목록 조회

새로운 TODO를 등록하고, 그 후에 목록을 가져오는 시나리오입니다.

프롬프트:

월별 청구 데이터 확인 TODO 추가. 마감일은 2026-06-05. 카테고리는 finance. 상세 내용은 '청구 데이터와 입금 예정 비교'. 추가한 후 현재 TODO 목록을 표시해 주세요.

기대하는 Tool 호출 순서:

Register -> List

시나리오 2: TODO 업데이트 + 목록 조회

미리 입력된 TODO를 업데이트하고, 그 후에 목록을 가져오는 시나리오입니다.

사전 상태:

todo-101: 월별 청구 데이터 확인 / 2026-06-03 / finance / 청구 데이터 차이점 확인 / not_started

프롬프트:

todo-101의 마감일을 2026-06-07로 변경해 주세요. 상세 내용은 '거래처별 미입금 목록을 확인'으로 업데이트해 주세요. 상태는 in_progress로 해 주세요. 업데이트 후 현재 TODO 목록을 표시해 주세요.

기대하는 Tool 호출 순서:

:? (이 부분은 원문에 내용이 없으므로 비워둡니다.)

Update -> List

시나리오 3: TODO 삭제 + 목록

불필요해진 TODO를 삭제하고, 그 후에 목록을 가져오는 시나리오입니다.

사전 상태:

todo-201: 구 형식의 청구서 확인하기 / 2026-06-01 / finance / 구 형식은 사용하지 않으므로 확인 불필요 / not_started
todo-202: 입금 예정표 업데이트하기 / 2026-06-06 / finance / 최신 입금 예정 반영하기 / not_started

프롬프트:

todo-201은 불필요해졌으므로 삭제해 주세요. 삭제한 후에 현재의 TODO 목록을 표시해 주세요.

기대하는 Tool 호출 순서:

Delete -> List

전체 결과

2700회 실행에 대한 전체 결과입니다.

실행 수	필요 Tool 호출률	순서 완전 일치율	불필요한 Tool 호출률	Tool 미호출률	평균 Tool 호출 수
2700	98.1%	88.1%	2.7%	0.8%	2.10

필요 Tool 호출률은 98.1%였습니다. 반면 순서 완전 일치율은 88.1%입니다. 필요한 Tool은 호출할 수 있어도 순서나 불필요한 호출로 인해 무너지는 경우가 있습니다.

모델별 결과

모델	실행 수	필요 Tool 호출률	순서 완전 일치율	불필요한 Tool 호출률	Tool 미호출률	평균 Tool 호출 수
Gemma-4-26b-a4b	900	100.0%	93.7%	0.0%	0.0%	2.06
...

Gemma-4-26b-a4b가 가장 안정적이었습니다. 필요 Tool 호출률은 100.0%였으며, 불필요한 Tool 호출률도 0.0%였습니다.

GPT-OSS:20b는 필요 Tool 호출률은 높았으나, 불필요한 Tool 호출률이 4.7%였습니다. 특히 최소 인자 시그니처 (Minimum Argument Signature) 조건에서 대상 외 Tool을 사이에 끼워 넣는 경우가 나타났습니다.

LFM2.5-8B-A1B는 Tool 미호출률이 2.2%였습니다. 구조화된 인자 시그니처 (Structured Argument Signature)나 표준 명칭 시그니처 (Standard Name Signature)의 일부 셀에서 Tool을 호출하지 않는 경우가 나타났습니다.

모델	순서 완전 일치율
Gemma-4-26b-a4b	93.7%
...

위 표는 순서 완전 일치율입니다.

시그니처별 결과

시그니처	실행 수	필요 Tool 호출률	순서 완전 일치율	불필요한 Tool 호출률	Tool 미호출률	평균 Tool 호출 수
대체 명칭 시그니처 (Alternative Name Signature)	540	99.1%	95.6%	0.0%	0.4%	2.02
...

가장 안정적이었던 것은 대체 명칭 시그니처입니다. 표준 명칭 시그니처에서 벗어나더라도 자연스러운 이름이라면 Tool Calling (도구 호출)이 크게 무너지지 않았습니다.

모호한 인자명 시그니처 (Ambiguous Argument Name Signature)도 안정적이었습니다. date나 type과 같은 모호한 인자명에서도 순서 완전 일치율은 93.5%였습니다. 메서드 이름과 설명 (Description)이 TODO 작업으로서 강력하게 작용했다고 보고 있습니다.

최소 인자 시그니처 (Minimum Argument Signature)는 순서 완전 일치율 75.6%로 가장 낮았습니다. 인자를 줄이면 스키마 (Schema)는 단순해지지만, Tool의 용도를 판단할 단서도 줄어드는 경향이 나타났습니다.

시그니처	순서 완전 일치율
대체 명칭 시그니처	95.6%
...

위 표는 순서 완전 일치율입니다.

더미 Tool 시그니처별 결과

대상 외 Tool	실행 수	필요 Tool 호출률	순서 완전 일치율	불필요한 Tool 호출률	Tool 미호출률	평균 Tool 호출 수
용도별 더미 시그니처	1350	98.7%	89.5%	2.1%	0.7%	2.10
범용 더미 시그니처	1350	97.4%	86.8%	3.3%	1.0%	2.10

용도별 더미 시그니처가 조금 더 안정적이었습니다. 대상 외 Tool의 인자를 용도에 맞추면, TODO 작업과의 차이점도 명확해집니다.

다만, 더미 Tool 시그니처 (Signature)의 영향은 대상 Tool 측의 시그니처 차이보다 작아 보입니다.

| 대상 외 Tool |
|---|---|
| 용도별 더미 시그니처 |
| 89.5% |
| 범용 더미 시그니처 |
| 86.8% |

위 표는 순서 완전 일치율입니다.

시나리오별 결과

| 시나리오 |
|---|---|
| 실행수 |
| 필요 Tool 호출률 |
| 순서 완전 일치율 |
| 불필요한 Tool 호출률 |
| Tool 미호출률 |
| 평균 Tool 호출 수 |
| TODO 등록+목록 |
| 900 |
| 98.8% |
| 96.0% |
| 2.0% |
| 0.9% |
| 2.03 |
| ... |

가장 크게 무너진 것은 TODO 업데이트+목록입니다. 필요 Tool 호출률은 95.7%이지만, 순서 완전 일치율은 75.1%까지 떨어집니다.

업데이트 시나리오에서는 Update -> List가 기대 순서입니다. 실행 로그에서는 List -> Update -> List와 같이 먼저 목록을 호출하는 케이스나 대상 외 Tool을 사이에 끼워 넣는 케이스가 관측되었습니다.

그중 List -> Update -> List는 엄격한 기대 순서와는 다르지만, 업데이트 대상의 현재 값을 확인 → 업데이트 → 마지막으로 목록을 확인하는 흐름으로서 실용상으로는 자연스럽습니다. 이에 따라 업데이트 시나리오에 대해서는 이 순서도 정상에 준하는 것으로 취급했을 경우의 값도 확인했습니다.

| 판정 |
|---|---|
| 건수 |
| 비율 |
| 업데이트 시나리오 전체 |
| 900 |
| 100.0% |
| 엄격하게 Update -> List |
| 676 |
| 75.1% |
| 엄격하게 List -> Update -> List |
| 64 |
| 7.1% |
| 위 2가지 패턴을 정상에 준하는 것으로 보았을 경우 |
| 740 |
| 82.2% |

이 보정 후에도 업데이트 시나리오는 등록이나 삭제보다 낮습니다. 다만, 순서 완전 일치율 75.1%의 하락분 중 일정 수는 먼저 목록을 취득하여 업데이트 대상을 확인하는 동작으로 설명할 수 있습니다. 이 패턴은 비완전 일치 224건 중 64건이었습니다. 비율은 28.6%입니다.

| 시나리오 |
|---|---|
| 순서 완전 일치율 |
| TODO 등록+목록 |
| 96.0% |
| ... |

위 표는 순서 완전 일치율입니다.

시그니처 × 시나리오 결과

| 시그니처 |
|---|---|
| 시나리오 |
| 실행수 |
| 필요 Tool 호출률 |
| 순서 완전 일치율 |
| 불필요한 Tool 호출률 |
| Tool 미호출률 |
| 대체명 시그니처 |
| 등록+목록 |
| 180 |
| 98.9% |
| 98.3% |
| 0.0% |
| 1.1% |
| ... |

업데이트 시나리오에 대해, List -> Update -> List를 정상에 준하는 것으로 취급했을 경우는 다음과 같습니다.

| 시그니처 |
|---|---|
| 실행수 |
| 엄격한 순서 완전 일치율 |
| List -> Update -> List를 정상에 준하는 일치율 |
| 대체명 시그니처 |
| 180 |
| 95.0% |
| 3.9% |
| 98.9% |
| 모호한 인자명 시그니처 |
| 180 |
| 89.4% |
| 4.4% |
| 93.9% |
| ... |

표준명 시그니처는 먼저 목록을 취득한 후 업데이트하는 케이스가 많아, 정상에 준하는 일치율은 80.0%까지 올라갑니다. 최소 인자 시그니처는 거의 올라가지 않습니다. 최소 인자 시그니처의 낮은 수치는 확인 순서만으로는 설명할 수 없습니다. 인자 정보의 부족함이나 불필요한 Tool 호출의 영향이 크다고 보고 있습니다.

가장 크게 무너진 것은 최소 인자 시그니처의 업데이트 시나리오입니다. 순서 완전 일치율은 42.8%였습니다. 최소 인자 시그니처에서는 dueDate나 category를 제외하고 있습니다. 그 때문에 업데이트 내용을 details에 몰아넣는 케이스나 먼저 목록을 호출하는 케이스가 발생했습니다.

표준명 시그니처의 업데이트 시나리오도 57.2%로 낮은 편입니다. 이번 표준명 시그니처에서는 UpdateTodo의 title을 필수 인자로 설정했습니다. 하지만 업데이트 시나리오의 사용자 문장에서는 title을 명시하지 않았습니다. 표준명 시그니처가 본질적으로 나쁘다기보다, 업데이트 Tool의 필수 인자 설계와 시나리오의 궁합이 좋지 않았다고 보고 있습니다.

고찰

자연스러운 대체명 시그니처는 나쁘지 않다

RegisterTodo를 InsertTodo로 바꾸어도 안정적이었습니다. ListTodos를 GetTodos로...

로 바꾸어도 크게 무너지지 않았습니다. 메서드 이름(Method name)과 인자 이름(Argument name)이 사용자의 요청에 자연스럽게 대응하는 것은 컨텍스트 (Context) 설계로서 중요해 보입니다.

인자를 줄인다고 해서 반드시 안정적인 것은 아니다

최소 인자 시그니처 (Minimum argument signature)는 스키마 (Schema)로서 단순하며 판단하기 쉽다고 생각했습니다. 하지만 측정해 본 결과, 순서 완전 일치율 (Order exact match rate)이 가장 낮게 나타났습니다. Tool Calling (도구 호출)에서는 인자 또한 Tool (도구)의 용도를 전달하는 중요한 단서가 되므로 엄격한 설계가 필요한 것으로 보입니다.

중첩된 객체는 반드시 나쁜 것이 아니다

구조화된 인자 시그니처 (Structured argument signature)는 순서 완전 일치율 93.3%를 기록했습니다. 중첩된 객체 (Nested object)를 사용하더라도 비교적 안정적입니다.

이번 구조화된 인자 시그니처는 request.todo나 request.patch와 같이 의미 있는 이름을 남겨두었습니다. 중첩의 유무 그 자체보다는 계층 내의 이름이 얼마나 자연스러운지가 중요한 것으로 보입니다.

업데이트 Tool의 필수 인자는 신중하게 설계해야 한다

업데이트 시나리오의 전체 순서 완전 일치율은 75.1%였습니다. 등록이나 삭제와 비교했을 때 명확히 낮습니다.

업데이트 Tool에서는 어떤 항목을 필수 인자 (Required argument)로 설정하느냐에 따라 동작이 달라집니다. 사용자가 매번 모든 항목을 지정할 것이라고 단정할 수 없습니다. 업데이트 Tool은 변경할 항목만 전달할 수 있는 형태로 맞추는 것이 좋아 보입니다. 예를 들어 기한만 변경하는 요청이라면, 기한만 전달할 수 있으면 충분합니다.

또한 시나리오 자체에 문제가 있을 가능성도 있습니다. 처음에 목록 Tool을 호출한 뒤 업데이트 Tool을 호출하는 케이스가 많이 관찰되었습니다. 업데이트 대상을 특정하기 위해 먼저 목록 Tool을 호출하는 것은 자연스러운 동작이라고도 할 수 있습니다. 따라서 이번 업데이트 시나리오가 업데이트 Tool의 순서 완전 일치율을 낮추고 있을 가능성이 있습니다.

실제로 List -> Update -> List를 정상적인 흐름으로 간주할 경우, 업데이트 시나리오의 일치율은 75.1%에서 82.2%로 상승합니다. 순서의 엄격성뿐만 아니라 자연스러운 확인 절차를 어떻게 평가할지도 설계해 두어야 합니다.

요약

이번 통계 검증에서는 Tool의 시그니처를 변경해가며 Tool 호출률을 측정했습니다.

확인된 내용은 다음과 같습니다.

자연스러운 대체 명칭 시그니처가 가장 안정적이었다.
인자를 줄인 최소 인자 시그니처는 순서 완전 일치율이 가장 낮았다.
모호한 인자 명칭 시그니처는 인자 이름이 모호하더라도 크게 무너지지 않았다.
구조화된 인자 시그니처는 중첩된 객체에서도 비교적 안정적이었다.
용도별 더미 시그니처 (Dummy signature)는 범용 더미 시그니처보다 약간 더 안정적이었다.

이 검증 결과로부터 Tool 설계 시 용도와 의도를 고려하여 엄격하게 시그니처를 정의할 필요가 있다는 것을 알 수 있었습니다.

Tool Calling의 시그니처와 호출률에 관한 조사

요약

핵심 포인트

서론

검증 설계

검증 환경

검증 방법

집계 방법

검증에 사용한 구체적인 예시

시스템 프롬프트 실례

대상 Tool 실례

더미 Tool (Dummy Tool) 실례

용도별 더미 시그니처의 모든 사례

용도별 더미 시그니처의 모든 사례

시나리오 1: TODO 등록 + 목록 조회

시나리오 2: TODO 업데이트 + 목록 조회

시나리오 3: TODO 삭제 + 목록

전체 결과

모델별 결과

시그니처별 결과

더미 Tool 시그니처별 결과

시나리오별 결과

시그니처 × 시나리오 결과

고찰

자연스러운 대체명 시그니처는 나쁘지 않다

인자를 줄인다고 해서 반드시 안정적인 것은 아니다

중첩된 객체는 반드시 나쁜 것이 아니다

업데이트 Tool의 필수 인자는 신중하게 설계해야 한다

요약

관련 기사

Discussion

댓글