research

Tool 명세 작성법 — LLM이 잘 쓰는 System Prompt

Tool 명세 작성법 — LLM이 잘 쓰는 System Prompt

핵심 원칙

Tool 명세는 "주니어 개발자에게 API 문서 쓰듯" 쓴다. LLM은 그 문서를 읽고 판단하는 주니어 개발자다.

좋은 Tool 명세의 네 가지 요소

1. 언제 써야 하는가 (트리거 조건)

LLM이 가장 많이 실수하는 부분 — 이 tool을 써야 하는 상황 판단.

사용 시점:
  - 사용자가 RAG 파이프라인에 넣으려 할 때
  - 사용자가 Obsidian에 저장하려 할 때
사용하지 말 것:
  - 파일을 단순 저장만 할 때
  - 이미 .md 형식일 때

2. 입출력 타입과 의미 + Tool 연결

입력:
  - file_path (str): 변환할 파일의 절대 경로
    → download_file의 출력값을 그대로 사용
출력:
  - md_path (str): 생성된 .md 파일의 절대 경로
    → index_to_rag 또는 save_to_obsidian의 입력으로 사용 가능

"어떤 tool의 출력을 받아서 어떤 tool로 넘기는지" 명시 → Tool 연결 품질 향상

3. 에러 케이스와 대응

실패 케이스:
  - FileNotFoundError: file_path가 잘못됨
    → 이전 단계(download_file)를 다시 시도
  - UnsupportedFormatError: 변환 불가 형식
    → 사용자에게 형식 확인 요청

에러 케이스 없으면 LLM이 실패 시 루프에 빠지거나 엉뚱한 행동을 함.

4. 예시 (가장 효과적)

예시:
  입력: file_path="/tmp/paper.pdf"
  출력: md_path="/tmp/paper.md"

System Prompt 전체 구조

[시스템 역할 정의]
너는 사용자의 일정 관리를 돕는 AI agent다.
캘린더 이벤트가 트리거되면 사용자가 설정한 Skill을 실행한다.

[사용 가능한 Tool 목록]
## Tool: login
## Tool: search
## Tool: download_file
## Tool: convert_to_md
## Tool: index_to_rag
(각각 4가지 요소로 명세)

[사용자 Skill 정의]
## Skill: research_before_meeting
트리거: 회의 30분 전
단계:
  1. search(query=회의 제목 키워드)
  2. download_file(각 결과의 pdf_url)
  3. convert_to_md(각 pdf)
  4. index_to_rag(각 md)

[사용자 설정]
obsidian_path: /Users/lee/Obsidian/research
credentials_key: academic_db

[현재 맥락]
이벤트: "Transformer 논문 리뷰 회의"
시각: 30분 후 시작

LLM CoT 추론 예시

위 System prompt를 받았을 때:

이벤트 "Transformer 논문 리뷰 회의" 30분 후
→ research_before_meeting Skill 트리거

1단계: search
  키워드 추출: "transformer architecture"
  → results = [논문A, 논문B, 논문C]

2단계: download_file × 3
  → /tmp/a.pdf, /tmp/b.pdf, /tmp/c.pdf

3단계: convert_to_md × 3
  → /tmp/a.md, /tmp/b.md, /tmp/c.md

4단계: index_to_rag × 3
  → 사용자 Obsidian 경로에 인덱싱

완료. 요약 보고.

Tool 명세가 명확하면 LLM이 이 추론을 스스로 한다. 명세가 부실하면 중간에 판단이 흔들린다.

나쁜 vs 좋은 비교

나쁨: login: 로그인한다
좋음:
  ## Tool: login
  설명: 웹사이트에 인증하고 세션을 반환한다
  입력:
    - url (str): 로그인할 사이트 URL
    - credentials_key (str): 사용자 설정 인증 키
  출력:
    - session_id (str): 이후 tool 호출에 사용
  실패: AuthError → 사용자에게 알리고 중단
  사용 시점: 해당 사이트의 다른 tool 호출 전 반드시 먼저

관련 개념

← research 목록으로홈으로