원본 캡처

툴 콜링 / RAG 파이프라인 리서치 원본 — 2026-08-01

불변 캡처. 편집 금지.

조사 방법

검색어

  • "Anthropic Claude tool use best practices tool definition when to call agentic loop parallel tool calls"
  • "RAG pipeline best practices 2026 chunking embedding hybrid search reranking evaluation RAGAS"
  • "RAG 2026 human approval gate tool calling observability tracing LangSmith common bugs agentic retrieval"

WebFetch 로 실제 열어본 URL (7개)

  1. https://www.anthropic.com/engineering/writing-tools-for-agents — [first-party] 툴 정의 작성 원칙
  2. https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use (실제 제목 "Define tools") — [first-party] 툴 스키마·description·tool_choice
  3. https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls — [first-party] tool_result / is_error / 에이전틱 루프
  4. https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use — [first-party] 병렬 툴 호출
  5. https://platform.claude.com/docs/en/build-with-claude/search-results — [first-party] search_result 블록 / RAG 인용
  6. https://www.premai.io/blog/building-production-rag-architecture-chunking-evaluation-monitoring-2026-guide/ — [aggregator] 2026 프로덕션 RAG 기본값
  7. (검색 스니펫만) galileo.ai, getmaxim.ai, metacto.com — RAG 관측성/LangSmith

신뢰도 표기: Anthropic 공식(platform.claude.com, anthropic.com) = [HIGH]. 서드파티 블로그 = [MED aggregator].

확인된 사실 [신뢰도]

A. 툴 정의 (description) 작성

  • [HIGH] 툴 정의의 파라미터: name(regex ^[a-zA-Z0-9_-]{1,64}$), description(plaintext, "what the tool does, when it should be used, and how it behaves"), input_schema(JSON Schema), input_examples(선택). 출처: platform.claude.com/.../implement-tool-use
  • [HIGH] "Provide extremely detailed descriptions. This is by far the most important factor in tool performance." description 은 다음을 설명해야 한다: What the tool does / When it should be used (and when it shouldn't) / What each parameter means / important caveats or limitations. "Aim for at least 3–4 sentences for each tool description, more if the tool is complex." 출처: platform.claude.com
  • [HIGH] 좋은 description 예시 (get_stock_price): "...It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company." → 즉 언제 호출 + 무엇을 안 하는지까지 명시. 출처: platform.claude.com
  • [HIGH] input_examples = 스키마 검증된 예시 배열. 복잡·중첩·포맷 민감 입력에 유효. 잘못된 예시는 400. 서버툴에는 미지원. 토큰 비용 ~20–50(단순)/~100–200(복잡 중첩). 출처: platform.claude.com
  • [HIGH] "Consolidate related operations into fewer tools." create_pr/review_pr/merge_pr 대신 action 파라미터 하나로. "Fewer, more capable tools reduce selection ambiguity." 출처: platform.claude.com
  • [HIGH] "Use meaningful namespacing in tool names." 서비스 prefix (github_list_prs, slack_send_message). tool search 쓸 때 특히 중요. 출처: platform.claude.com
  • [HIGH] 응답 설계: "return only high-signal information." semantic·stable 식별자(slug/UUID) 반환, Claude 가 다음 스텝 추론에 필요한 필드만. bloated 응답은 컨텍스트 낭비. 출처: platform.claude.com
  • [HIGH, anthropic.com engineering] "Writing tools for agents": 툴 description 을 신규 팀원 안내처럼. implicit context 를 명시(특수 쿼리 포맷, 니치 용어 정의, 리소스 간 관계). 파라미터명은 user 보다 user_id 처럼 모호성 제거. 출처: anthropic.com/engineering/writing-tools-for-agents
  • [HIGH, anthropic.com] 저수준 식별자(uuid,256px_image_url,mime_type) 대신 semantic 대안(name,image_url,file_type). "arbitrary alphanumeric UUIDs to more semantically meaningful" 로 바꾸면 retrieval 환각 감소. 출처: anthropic.com
  • [HIGH, anthropic.com] 토큰 효율: pagination/range/filtering/truncation 를 sensible default 로. truncation 시 에이전트에 "many small and targeted searches instead of a single, broad search" 유도하는 지시. 에러 응답은 opaque code 대신 actionable guidance. 출처: anthropic.com
  • [HIGH, anthropic.com] "Even small refinements to tool descriptions can yield dramatic improvements" — Claude Sonnet 이 툴 description 개선 후 SWE-bench Verified SOTA. 평가 주도 반복이 핵심. 출처: anthropic.com

B. 에이전틱 루프 / 결과 반환

  • [HIGH] client tool 응답: stop_reason = tool_use, content 에 tool_use 블록들. 각 블록 = id(나중에 결과 매칭용) / name / input. 출처: handle-tool-calls
  • [HIGH] 결과 반환: role: "user" 메시지 + tool_result content 블록. 필드: tool_use_id(어느 호출의 결과인지), content(선택; string 또는 nested content blocks 또는 document blocks — text/image/document/search_result 타입 허용), is_error(선택, true=에러). 출처: handle-tool-calls
  • [HIGH] 포맷 규칙: tool_result 블록은 대응 tool_use 메시지 바로 다음에 와야 하고, 그 사이 다른 메시지 금지. user 메시지 안에서 tool_result 블록이 먼저(FIRST), 텍스트는 모든 tool_result 뒤에. 어기면 400. 출처: handle-tool-calls
  • [HIGH] 병렬 툴 호출 결과는 한 user 메시지에 전부 몰아서 반환. tool_use 블록 하나당 tool_result 하나, tool_use_id 로 매칭. 출처: parallel-tool-use, handle-tool-calls
  • [HIGH] 실행하지 않은 호출(예: 순차 실행 중 앞 호출 실패)도 tool_result 를 is_error: true + 짧은 설명으로 반환. 예: {"type":"tool_result","tool_use_id":"toolu_02","is_error":true,"content":"Not executed: the preceding write_file call failed."} 출처: parallel-tool-use
  • [HIGH] Tool Runner (SDK): 수동 tool_use 루프·결과 포맷·재시도를 SDK 가 자동 처리. "Use the Tool Runner for most applications." 수동 패턴은 커스텀 배칭/순서/에러 제어 필요할 때만. 출처: handle-tool-calls, parallel-tool-use
  • [HIGH] 모델 응답에서 tool_use 블록이 항상 첫 블록은 아님 — text 블록이 먼저 나올 수 있음(자연어 설명 후 tool_use). 코드는 iterate 해서 tool_use 를 찾아야. 특정 포맷에 의존 금지. 출처: implement-tool-use, search-results 예제

C. tool_choice / 병렬 제어

  • [HIGH] tool_choice 4가지: auto(기본, tools 있을 때), any(툴 중 하나 반드시), tool(특정 툴 강제), none(툴 금지, 기본값 when no tools). 출처: implement-tool-use
  • [HIGH] any/tool 사용 시 API 가 assistant 메시지를 prefill 해 툴 사용 강제 → tool_use 앞 자연어 설명 안 나옴. 자연어 원하면 auto + user 메시지에 명시적 지시. 출처: implement-tool-use
  • [HIGH] tool_choice: any + strict tool use(strict: true) 조합 = 툴 호출 보장 + 스키마 정확 준수. 출처: implement-tool-use
  • [HIGH] 병렬 끄기: disable_parallel_tool_use: true 를 tool_choice 객체 안에 넣음(top-level 파라미터 아님). auto+disable → 최대 1개 툴 호출(텍스트만도 가능). any/tool+disable → 정확히 1개. 출처: parallel-tool-use
  • [HIGH] Claude 4 이상은 기본적으로 병렬 툴 호출. 강화 시스템 프롬프트: "For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially." (강한 버전 <use_parallel_tool_calls> 블록도 문서에 제공). 출처: parallel-tool-use
  • [HIGH] 병렬이 안 되는 흔한 원인 #1 = tool_result 를 각각 별도 user 메시지로 보냄 → "이게 Claude 에게 병렬 안 하도록 가르친다". 반드시 한 user 메시지에 전부. 출처: parallel-tool-use (Troubleshooting)
  • [HIGH] 의존 호출이 같이 나오는 것 줄이려면 시스템 프롬프트에 "Only batch tool calls that are independent of each other." 출처: parallel-tool-use
  • [HIGH] 병렬 작동 측정: 평균 tools/메시지 > 1.0 이면 병렬 동작 중. 출처: parallel-tool-use

D. 에러 핸들링 (is_error)

  • [HIGH] 툴 실행 에러: content 에 에러 메시지 + "is_error": true. 예: "ConnectionError: the weather service API is not available (HTTP 500)". 출처: handle-tool-calls
  • [HIGH] "Write instructive error messages." "failed" 같은 generic 금지, 무엇이 틀렸고 다음에 뭘 시도할지 포함. 예: "Rate limit exceeded. Retry after 60 seconds." 출처: handle-tool-calls
  • [HIGH] 잘못된 툴 호출(필수 파라미터 누락 등): tool_result 에 에러 표시하면 Claude 가 채워서 재시도. "Claude will retry 2-3 times with corrections before apologizing." 근본 해결은 description 개선 또는 strict tool use. 출처: handle-tool-calls
  • [HIGH] 서버툴 에러(web search 등)는 Claude 가 투명하게 처리 — client 와 달리 is_error 직접 다룰 필요 없음. web search 에러 코드: too_many_requests invalid_input max_uses_exceeded query_too_long unavailable. 출처: handle-tool-calls

E. 보안 / 승인 게이트 / 관측성

  • [HIGH] 툴 결과는 신뢰 불가 데이터(웹페이지, 인바운드 이메일, 유저 업로드, 서드파티 API). indirect prompt injection 위험 → 신뢰 불가 콘텐츠는 system/plain user text 아니라 tool_result 블록 안에 유지. 출처: handle-tool-calls (Warning)
  • [MED aggregator] 사람 승인 게이트: read 툴(query DB, search KB, retrieve order)은 자동 실행 OK, write 툴(create record, send email, refund, delete)은 실행 전 사람 확인. "never execute irreversible actions without human confirmation." 출처: 검색 스니펫 claudereadiness.com
  • [MED aggregator] RAG/에이전트 관측성 도구: LangSmith(LangChain 팀, 트레이싱+prompt hub+dataset), Langfuse, Phoenix, TruLens. 실패 시 어떤 임베딩 모델·벡터검색 결과·청크 랭킹·조립된 프롬프트·LLM 출력을 드릴다운. gateway(Helicone/Portkey) + eval(Phoenix/TruLens) 조합이 흔함. 출처: galileo.ai, metacto.com 스니펫

F. RAG — search_result 블록 / grounding·인용 [HIGH, Anthropic]

  • [HIGH] search_result content 블록으로 자기 콘텐츠를 web search 결과처럼 인용. RAG 용. Claude Haiku 3 제외 모든 active 모델 지원. 베타 헤더 불필요(표준 Messages API). 출처: search-results
  • [HIGH] 제공 방식 2가지: (1) 커스텀 툴이 tool_result 로 search_result 반환(동적 RAG), (2) user 메시지에 top-level content 로 직접(사전 fetch/캐시). 둘 다 citations 켜면 Claude 자동 인용, 특별 프롬프팅 불필요. 출처: search-results
  • [HIGH] search_result 스키마: type:"search_result", source(필수, URL 또는 식별자), title(필수), content(필수, text 블록 배열 — text만, 이미지 불가), citations:{enabled:true}(선택, 기본 disabled — 켜려면 명시), cache_control(선택). 출처: search-results
  • [HIGH] "All search results in a request must use the same setting" (citations enabled 여부 통일). 출처: search-results
  • [HIGH] 툴 방식 예제: 툴이 SearchResultBlockParam(source=..., title=..., content=[TextBlockParam(...)], citations={"enabled":True}) 리스트 반환 → ToolResultBlockParam(tool_use_id=..., content=tool_result) 로 감싸 user 메시지에. 출처: search-results (Python 예제)

G. RAG 파이프라인 2026 기본값 [MED aggregator — premai.io 2026 guide]

  • [MED] 청킹 기본: recursive chunking 512 토큰 + 10–20% overlap 이 baseline. "There is no universal best chunking strategy." 문서 타입·쿼리 패턴 의존. 출처: premai.io
  • [MED] 벤치마크(2026-02): academic papers 에서 "recursive 512-token splitting at 69% accuracy, 15 percentage points above semantic chunking." → 의미기반 청킹이 항상 이기지 않음. 출처: premai.io
  • [MED] overlap 반론(2026-01 분석): SPLADE retrieval 사용 시 overlap 이 recall 에 측정 가능한 이득 없었고 저장·임베딩 비용만 증가. 출처: premai.io
  • [MED] 짧은 문서(FAQ, 티켓)는 청킹 스킵. 기술/법률 문서는 hierarchical parent-child(작은 청크로 정밀 매칭 + 생성 시 full context). 출처: premai.io
  • [MED] 임베딩 모델: premai 는 Voyage voyage-3-large 를 프로덕션 winner 로 제시 — "outperforms OpenAI's text-embedding-3-large by 9.74% and Cohere's embed-v3-english by 20.71%", $0.06/1M vs OpenAI $0.13, 32K 컨텍스트(경쟁 8K), 1024차원(OpenAI 3072). [벤치마크 수치는 벤더 대비 주장 — 규격서 §5 벤치 인용 금지 유의, 위키 본문엔 옮기지 말 것]. 출처: premai.io
  • [MED] 하이브리드 검색 = 프로덕션 표준("mandatory"). BM25(sparse)+dense. dense-only 는 정확매칭(제품코드, 법률 인용, named entity) 놓침. 출처: premai.io / StackAI / CallMissed 스니펫
  • [MED] RRF(Reciprocal Rank Fusion) 공식 1/(rank+k), k=60. 일반 QA 가중치 시작점 dense 0.6 / sparse 0.4. dense top-50 + BM25 top-50 → RRF fuse 파이프라인. 출처: premai.io, 검색 스니펫
  • [MED] 하이브리드가 dense-only 대비 recall 최대 17% 개선, 추가 지연 <6ms. 출처: 검색 스니펫(callmissed/stackai)
  • [MED] 리랭킹 = "single highest-ROI addition to a basic RAG pipeline." precision +10–30%, 지연 +50–100ms. cross-encoder 가 query+doc 를 함께 읽어 pair 로 스코어 → 정확하지만 수백만 문서엔 느림. 패턴: 20 후보 retrieve → top 5 로 rerank → LLM. 모델: self-host BAAI/bge-reranker-v2-m3(~30ms GPU), managed Cohere rerank-v3.5(~100ms). 출처: premai.io
  • [MED] 프롬프트 조립: 청크 순서 역순으로(가장 관련 높은 것을 끝에) — LLM recency bias, 끝/중간보다 끝이 attention 높음. 각 청크에 소스 메타 [Source: {document_id} | Section: {heading}]. 조립 컨텍스트는 대개 8K 토큰 이하로 유지(컨텍스트 길수록 성능 저하 관측). 출처: premai.io
  • [MED] 평가 RAGAS 4대 지표: faithfulness(retrieved context 로만 뒷받침되는가, 목표 ≥0.85), answer relevancy(≥0.8), context precision(retrieved 중 관련 비율, ≥0.75), context recall(필요 정보 다 있었나, ≥0.8). retrieval 지표 recall@k, MRR. golden set 50–100 라벨 쿼리(도메인 전문가 25–30 + 합성 + 프로덕션). 청킹/임베딩/retrieval/prompt 변경마다 CI 로 eval. 출처: premai.io, 검색 스니펫
  • [MED] 에이전틱 RAG: "complex queries requiring multiple sequential retrievals"(예: Q3 정책 vs 지난달 규제 변화 비교)에. single-pass 부족할 때. 단, LLM 호출 배수·지연 증가로 "for most queries, it's overkill." long-context 는 하이브리드+리랭크 스택을 대체하지 않음(스케일 시 여전히 필요). 출처: premai.io
  • [MED] 기타 2026 패턴: semantic caching(반복 쿼리 30–60% hit), streaming generation, zero-result alerting(>5% 무결과 = 커버리지 갭). 출처: premai.io
  • [MED aggregator, 일반 통념] "80% of RAG failures trace back to the ingestion and chunking layer, not the LLM." "chunk better, retrieve hybrid, rerank aggressively, and measure." 출처: 검색 스니펫(premai/callmissed)

엇갈리거나 미확인

  • 청크 512 vs semantic: premai 벤치는 academic papers 에서 recursive 512 가 semantic 을 15%p 이김. 다른 스니펫(nerdleveltech 등)은 semantic 이 fixed-size 대비 "최대 70% 정확도 개선" 주장 → 도메인·비교대상이 달라 직접 충돌 아님. semantic 은 fixed-size 를 이기고, recursive 512 는 semantic 을 이기는 케이스가 공존. 위키엔 "정답 없음, 도메인 의존" 으로.
  • overlap 이득: 통념은 10–20% overlap 권장이나 premai 인용 분석은 SPLADE 에서 이득 없음 → 리트리버 종류에 따라 다름. 미확정.
  • 임베딩 벤더 수치(voyage 9.74%/20.71% 등)는 premai 가 인용한 벤더 주장. 독립 검증 안 됨. 규격서 §5 벤치 인용 금지 대상 → 본문 반영 금지.
  • 하이브리드 recall +17%, <6ms / rerank +10–30%, 50–100ms: aggregator 블로그 수치. 대략 방향성만 신뢰, 정확값 [unverified].
  • RAGAS 임계값(0.85/0.8/0.75/0.8): premai 의 "권장" 값이지 표준 아님. 프로젝트별 조정 필요.
  • 사람 승인 게이트 2-tier(read auto / write confirm)는 서드파티(claudereadiness) 프레이밍 — Anthropic 공식 문서에서 직접 확인 못 함. 다만 anthropic.com 이 "never give write access unless necessary" 원칙은 검색 스니펫에 등장(원문 미확인, [MED]).
  • Tool Runner 의 정확한 API(@beta_tool, tool_runner)는 이 세션에서 열지 않음 — 규격서 §6 에 기재된 것 사용.

원문 발췌

tool description (implement-tool-use, [HIGH])

Provide extremely detailed descriptions. This is by far the most important factor in tool performance. Your descriptions should explain every detail about the tool, including: What the tool does / When it should be used (and when it shouldn't) / What each parameter means and how it affects the tool's behavior / Any important caveats or limitations... Aim for at least 3–4 sentences for each tool description, more if the tool is complex.

좋은 description 예 (implement-tool-use)

"Retrieves the current stock price for a given ticker symbol... It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company."

tool_result 포맷 규칙 (handle-tool-calls, [HIGH])

Tool result blocks must immediately follow their corresponding tool use blocks in the message history... In the user message containing tool results, the tool_result blocks must come FIRST in the content array. Any text must come AFTER all tool results.

병렬 결과 (parallel-tool-use, [HIGH])

return one tool_result for each tool_use block, all together in the next user message. Match each result to its call with tool_use_id, and put every tool_result block before any text content in that message.

병렬 트러블슈팅 (parallel-tool-use, [HIGH])

Wrong: a separate user message for each tool result. Correct: all tool results together in a single user message. [Wrong 는] "teaches" Claude to avoid parallel calls.

is_error 지침 (handle-tool-calls, [HIGH])

Write instructive error messages. Instead of generic errors like "failed", include what went wrong and what Claude should try next, e.g., "Rate limit exceeded. Retry after 60 seconds."

prompt injection 경고 (handle-tool-calls, [HIGH])

Tool results often carry content from sources outside your control... Treat that content as untrusted... Keep untrusted content inside tool_result blocks rather than system prompts or plain user text blocks.

search_result 스키마 (search-results, [HIGH])

{"type":"search_result","source":"...","title":"...","content":[{"type":"text","text":"..."}],"citations":{"enabled":true}} Citations are disabled by default... All search results in a request must use the same setting. Search results hold text only.

RAG 요지 (premai.io, [MED aggregator])

Recursive chunking at 512 tokens with 10-20% overlap is the baseline... Hybrid retrieval [is] the production standard... Reranking [is] the single highest-ROI addition to a basic RAG pipeline... typically improves precision by 10-30% at a cost of 50-100ms added latency... [RAGAS] Faithfulness target ≥0.85.