Claude가 쓸 MCP 도구 설명, 예시를 넣어야 할까?

Q: Claude가 쓸 MCP 도구 설명, 예시를 넣어야 할까?

관례 과제 16개에서 한 줄 설명은 5/16, 한 줄에 예시만 붙이면 10~12/16이었고, 3~4문장 설명과 스키마+규칙 한 문장은 세 번 모두 16/16이었다. 문장에 예시를 더해도 16/16 그대로였다(천장이라 셋 차이는 못 가림).

이번 시간에는 MCP 도구 설명을 한 줄, 한 줄+예시, 3~4문장, 3~4문장+예시, 스키마+규칙 다섯 가지로 바꿔 가며 Claude가 ID 형식이나 날짜 같은 인자 관례를 얼마나 지키는지를 claude -p로 측정하며 배워가는 시간입니다.

조건마다 같은 과제를 세 번씩 돌렸어요. 모델 출력은 비결정적이라 같은 명령을 다시 돌리면 숫자가 달라질 수 있습니다. --model opus가 가리키는 모델도 시간이 지나면 달라질 수 있어요.

인자 관례와 엇갈린 조언

예를 들어서 가짜 MCP 서버에 운영 티켓을 만드는 create_ticket 도구를 붙이고, "보고자는 사번 40417 김하늘, 라벨은 Payment Timeout과 Checkout, 가장 급한 일"이라고 시켰다고 해볼게요.

이 도구에는 스키마만 봐서는 알 수 없는 관례가 있어요. 관례는 서버가 정해 둔 인자 표기 규칙입니다. 여기서는 보고자 ID가 USR- + 다섯 자리, 라벨이 소문자 kebab-case(낱말을 하이픈으로 이은 소문자), 가장 급한 일이 critical이고, critical이면 escalation 객체를 함께 넣어야 해요.

그런데 이 선택에서 Anthropic 글들은 서로 다른 방향을 권해요.

예시를 넣으라: "Introducing advanced tool use"(2025-11-24)는 "In our own internal testing, tool use examples improved accuracy from 72% to 90% on complex parameter handling."이라고 씁니다. 다만 이 예시는 API의 input_examples 필드예요. MCP 사양 최신 개정(2026-07-28)의 도구 정의에는 name, title, description, icons, inputSchema, outputSchema, annotations만 있어서, 이 글은 예시를 설명 문장 안에 넣는 방식으로 대신했습니다.
설명을 자세히 쓰라: Define tools 문서는 "Aim for at least 3-4 sentences for each tool description"이라고 쓰고, "Prioritize descriptions, but consider using input_examples for complex tools."라고 순서를 둡니다.
예시 대신 도구 설계를 바꾸라: "The new rules of context engineering for Claude 5 generation models"(2026-07-24, 아래에서는 new rules 글)는 "With our newest models, we've found that giving examples actually constrains them to a certain exploration space."라고 쓰고 "Instead of using examples, think more about the design of your tools"를 권합니다.

예시를 넣는 방식은 API input_examples와 다르고 과제도 이 글이 만든 것이라, 72%→90%와 숫자를 직접 비교하지는 않아요.

실습 준비

이 글의 명령은 모두 실습 코드의 claude-tool-description-design/ 디렉터리에서 실행합니다.

mcpgen/: 설정 파일 하나로 가짜 도구 N개를 내는 MCP 서버(server.mjs), mcp.json 생성기(mkconfig.mjs)
catalog_c7.json: 도구 32개 카탈로그
tasks_c7.jsonl: 과제 50개
templates.mjs: 설명 다섯 가지의 description 템플릿과 질문 끝에 붙는 문장
make_configs.mjs: 조건별 생성기 설정(configs/), mcp.json, 이름 대응표(names/)를 만드는 스크립트
run.mjs: 실습별 호출을 하나씩 돌려 stream-json을 out/에 남기는 실행기
show.mjs: stream-json 한 파일에서 필요한 필드만 골라 찍는 스크립트
parse.mjs, grade.mjs, summary.mjs: 호출 하나 뽑기, 단계별 채점, 조건별 집계
schema.mjs: 채점에 쓰는 스키마 검사기

그 밖의 파일은 데이터·보조 스크립트입니다.

도구 32개와 설명 다섯 가지

MCP 서버는 설정 파일 하나로 가짜 도구 N개를 내는 stdio 서버이고, 도구를 부르면 받은 인자를 그대로 돌려줍니다({"ok":true,"tool":...,"args":...,"value":42}).

도구는 블로그(blog), 코스(course), 결제(billing), 운영(ops) 서비스마다 8개씩 32개이고, 그중 관례 도구는 8개(서비스마다 2개)예요: create_ticket, create_deploy, refund_payment, issue_coupon, schedule_post, update_series, schedule_live_session, enroll_students.

도구마다 한 줄 설명(desc_ko), 3~4문장 설명(long_ko), 규칙 한 문장(rule_ko), 예시 인자(examples, 관례 도구는 최소·일부·전체 3개, 나머지는 1개), 느슨한 스키마(parameters), 엄격한 스키마(parameters_strict)를 적었어요.

느슨한 스키마는 타입, 필수 필드, 중첩 구조까지만 있고, 속성 설명은 "보고자 ID"처럼 이름 수준이에요. 엄격한 스키마는 같은 구조에 pattern, enum, minimum, maximum과 형식을 적은 속성 설명을 더한 것입니다. 관례 종류는 여섯 가지로 나눴습니다.

id: ID·표기 형식(USR- 접두, pay_ + 열두 자리, v + semver, 소문자 kebab-case 라벨)
datetime: 날짜·시간(YYYY-MM-DD, 초까지 쓴 ISO 8601 + +09:00)
unit: 단위(원 단위 정수, 분 단위 정수, 퍼센트 정수)
enum: 정해진 값(critical, prod, defect, percent)
correlation: 선택 필드 상관(전액 환불이면 amount를 넣지 않음, 조교만 role: "ta")
nested: 중첩 객체(discount: {type, value}, series: {name, order})

설명 다섯 가지는 생성기 description 템플릿으로 만들어요. 모든 질문 끝에는 도구가 필요 없는 질문에도 맞는 같은 문장을 붙입니다. 템플릿 다섯 개와 그 문장("도구가 필요하면 써서 처리하고, 결과만 짧게 답해.")은 templates.mjs에 있어요.

S: 한 줄 설명. 관례 정보가 없습니다.
SE: 한 줄 + 예시. example_ko는 예시 인자를 JSON 한 줄씩 /로 이은 문자열입니다. 관례는 예시 값으로만 드러나요.
L: 3~4문장. 관례를 모두 말로 적었고 예시 값은 없습니다.
LE: 3~4문장 + 예시
I: 한 줄 + 규칙 한 문장(desc_i)에 엄격한 스키마. new rules 글의 "what parameters does Claude have and how can they be more expressive?"를 옮긴 조건이에요. 선택 필드 상관처럼 스키마로 못 적는 규칙 하나만 문장으로 둡니다(비슷한 도구는 짝과의 경계 문장 하나).

예시 값 복사를 가려내려고 예시에는 kestrel-queue, USR-90731처럼 과제에 없는 값만 썼습니다.

과제 50개

질문 하나에 정답 도구는 하나입니다. 관례 과제의 id는 C01~C16(홀수가 conv_in, 짝수가 conv_out)이에요.

conv_in 8개, conv_out 8개: 관례 도구마다 둘. conv_in은 정답 인자의 필드 묶음이 예시 하나와 같고, conv_out은 어느 예시와도 다릅니다(예: 예시에 없는 "보통 우선순위 + 라벨만" 티켓, 메모를 남기는 전액 환불).
나머지: 같은 서비스 안 비슷한 도구 고르기(near 14개), 서비스만 다른 같은 일 고르기(cross 12개), 도구가 필요 없는 질문(no_tool 8개)

호출, 채점, 집계

run.mjs는 모든 호출을 아무 파일도 없는 빈 디렉터리($TMPDIR/ctooldesc-run)에서 다음 옵션과 --model opus --effort high --no-session-persistence --output-format stream-json --verbose로 부르고, 호출마다 180초 제한을 겁니다.

--setting-sources project + 빈 디렉터리: 사용자 설정과 CLAUDE.md를 읽지 않습니다.
--strict-mcp-config: --mcp-config로 준 서버만 붙입니다. 계정에 연결한 claude.ai 커넥터가 따라 붙지 않아요.
--tools "": 내장 도구를 모두 빼고, 이때 ToolSearch도 빠져 tool search가 꺼집니다. 도구 32개의 정의가 첫 요청에 모두 실려요.
--allowedTools "mcp__lab": 서버 lab의 도구를 허가 요청 없이 부르게 합니다.
--max-turns 8: 2.1.296 --help에는 없지만 동작하고, 한도에 걸리면 결과가 error_max_turns입니다. 이번 실측에서는 0건이었어요.

make_configs.mjs는 조건마다 생성기 설정과 out/mcp/<조건>.mcp.json, 그리고 보이는 전체 이름을 카탈로그 이름으로 되돌리는 대응표(names/<조건>.json)를 만들어요. run.mjs s1은 설명 다섯 가지 × 과제 50개 × 3회, 750호출을 돌립니다.

node make_configs.mjs
node run.mjs s1

14 configs, 10 mcp.json for calls: exp1-S, exp1-SE, exp1-L, exp1-LE, exp1-I, exp2-NP, exp2-NS, exp2-NM, exp0-set1, exp0-set2
exp0 server names: warehouse_analytics_reporting_service_for_quarterly_planning (60), warehouse_analytics_reporting_service_for_quarter_planning (58)

출력의 exp2-*, exp0-* 설정은 이 글에서는 쓰지 않아요.

채점은 단계로 나누고, 마지막에 관례 단계를 더했어요. 첫 MCP 호출만 채점합니다.

call: MCP 도구를 불렀는가? no_tool 과제는 부르지 않아야 통과하고 여기서 끝납니다.
pick: 첫 MCP 호출이 정답 도구인가?
schema: 인자가 느슨한 스키마를 통과하는가? 모든 조건을 같은 스키마로 채점합니다.
value: 질문이 준 값이 형식과 무관하게 같은가? 40417과 USR-40417은 여기서 통과합니다.
convention: 과제의 관례가 정답과 글자 그대로 같고, 규칙상 들어가면 안 되는 필드(must_absent)가 없는가

통과와 따로 세는 지표는 셋이에요.

과포함: 정답에 없는 필드를 넣은 호출
예시 값 복사: 인자 안 문자열 가운데 그 도구 예시에 있고 질문과 정답에는 없는 값
다시 부름: 첫 호출 뒤 같은 도구를 인자를 바꿔 다시 부른 수. 도구가 받은 인자를 그대로 돌려주므로 모델이 결과를 보고 고칠 수 있어서 따로 셉니다.

summary.mjs는 parse.mjs(stream-json에서 첫 요청 입력 토큰, 도구 호출, ToolSearch 검색을 뽑음)와 grade.mjs로 조건별 숫자를 찍어요. 이 글의 집계 출력은 모두 node summary.mjs <명령>이 찍은 그대로입니다.

실습 1: 관례가 있는 인자

관례 과제 16개(conv_in 8 + conv_out 8)의 결과를 볼게요. 아래 출력은 과제 종류별로 세 번의 통과 수를 쉼표로 이은 것이고, 관례 과제 줄만 옮긴 발췌예요.

node summary.mjs acc s1 S SE L LE I

S   conv_in  pick 8,8,8, schema 8,8,8, value 8,8,8, convention 2,2,2 /8  misses convention 18
S   conv_out pick 7,7,8, schema 7,7,8, value 7,7,8, convention 3,3,3 /8  misses convention 13, same_service 2
    first call to another tool: C06->get_payment x2
SE  conv_in  pick 6,5,7, schema 6,5,7, value 6,5,7, convention 4,4,6 /8  misses convention 4, same_service 6
    first call to another tool: C03->get_deploy_history x2, C05->get_payment x3, C07->list_payments x1
SE  conv_out pick 6,8,7, schema 6,8,7, value 6,8,7, convention 6,6,6 /8  misses same_service 3, convention 3
    first call to another tool: C06->get_payment x2, C08->list_payments x1
L   conv_in  pick 8,8,8, schema 8,8,8, value 8,8,8, convention 8,8,8 /8
L   conv_out pick 8,8,8, schema 8,8,8, value 8,8,8, convention 8,8,8 /8
LE  conv_in  pick 8,8,8, schema 8,8,8, value 8,8,8, convention 8,8,8 /8
LE  conv_out pick 8,8,8, schema 8,8,8, value 8,8,8, convention 8,8,8 /8
I   conv_in  pick 8,8,8, schema 8,8,8, value 8,8,8, convention 8,8,8 /8
I   conv_out pick 8,8,8, schema 8,8,8, value 8,8,8, convention 8,8,8 /8

출력을 보면 convention까지 통과한 수는 S 5/16(세 번 모두), SE 10/16, 10/16, 12/16, L, LE, I는 세 번 모두 16/16이었어요.

여기서 눈여겨볼 건 S도 value까지는 15, 15, 16/16을 통과했다는 점이에요. 모델은 질문의 값은 알아들었고, 형식만 틀린 거죠.

value까지 통과한 호출에서 관례 하나하나를 세어 볼게요.

node summary.mjs kinds s1 S SE L LE I

S   id 0/31, datetime 18/18, unit 15/15, enum 7/22, correlation 40/49, nested 12/12  (value-passed calls 46/48)
    failed C01:reporter.id x3, C01:labels x3, C01:priority x2, C01:escalation x3, C02:reporter.id x3, C02:labels x3, C02:priority x3, C03:version x3, C03:env x3, C04:version x3, C04:env x3, C05:payment_id x3, C05:reason x3, C06:payment_id x1, C06:reason x1, C07:user_id x3, C08:user_id x3, C09:tags x3, C15:students x3, C16:students x3
SE  id 20/24, datetime 17/17, unit 10/10, enum 15/15, correlation 39/42, nested 10/10  (value-passed calls 39/48)
    failed C01:escalation x3, C06:payment_id x1, C07:user_id x1, C08:user_id x2
L   id 33/33, datetime 18/18, unit 15/15, enum 24/24, correlation 51/51, nested 12/12  (value-passed calls 48/48)
LE  id 33/33, datetime 18/18, unit 15/15, enum 24/24, correlation 51/51, nested 12/12  (value-passed calls 48/48)
I   id 33/33, datetime 18/18, unit 15/15, enum 24/24, correlation 51/51, nested 12/12  (value-passed calls 48/48)

한 줄 설명(S)에서도 맞힌 관례: 날짜·시간 18/18, 단위 15/15, 중첩 객체 12/12. 모델은 아무 말이 없어도 2026-11-20T09:00:00+09:00처럼 초까지 쓴 ISO 8601에 한국 시간 오프셋을 붙였고, "1시간 반"을 duration_min: 90으로 넣었어요. 중첩 구조는 느슨한 스키마에 이미 있었습니다.
S에서 놓친 관례: ID·표기 형식 0/31(40417, 2026-1012-0042, 2.14.3처럼 질문의 표기 그대로), enum 7/22(urgent, production, 상품 불량처럼 그럴듯한 값을 지어냄), 그리고 필드를 넣어야 하는 상관 규칙(critical이면 escalation, 수강생은 role을 빼기)이에요.
S의 실패는 정보가 없어서입니다. 같은 모델이 L, LE, I에서는 같은 관례를 모두 지켰어요.

예시만 준 SE는 ID·표기 형식과 enum을 대부분 맞혔지만, 두 가지에서 떨어졌어요.

상관 규칙: create_ticket의 escalation을 세 번 모두 빠뜨렸습니다. 예시 셋 가운데 critical인 예시에만 escalation이 있었는데, 모델은 그 둘을 잇지 않았어요.
질문의 표기에서 바꿔야 하는 ID: 58213 → u_58213, 2026-0930-1188 → pay_202609301188을 놓친 호출이 있었습니다. 예시는 바뀐 결과만 보여 주고, "하이픈을 빼고 붙인다" 같은 변환 규칙은 말하지 않아요.

정리하면 이 과제에서 관례 통과를 가른 건 관례를 말로 적었는지(L, LE), 스키마와 규칙으로 적었는지(I)였고, 문장 위에 더한 예시의 효과는 보이지 않았어요. 셋 다 천장에 닿아서, L, LE, I 사이의 차이는 이 과제로는 가릴 수 없습니다.

실습 2: 예시만 붙이면 다른 도구로 먼저 조회했다

new rules 글의 "constrains them"을 도구 호출에서 볼 수 있는 지표로 바꿔, 셋을 세어 봤어요.

예시와 필드 묶음이 다른 conv_out에서 떨어지는가: SE의 convention은 conv_in 4, 4, 6 / 8, conv_out 6, 6, 6 / 8로 conv_out이 낮지 않았습니다.
과포함(정답에 없는 필드를 넣음): 다섯 조건 240호출에서 0번이었습니다.
예시 값 복사: 0번이었어요. 예시의 kestrel-queue, USR-90731, 2025-12-31 같은 값이 인자에 들어간 호출은 없었습니다.

node summary.mjs side s1 SE

SE  over-inclusion calls 0/48 (in 0, out 0)
    example copies calls 0
    recalls (same tool, changed args) 0 in 0 calls; convention on first gold-tool call: in 5,6,6, out 7,6,6 (gold tool called 48/48)

이 과제에서는 예시의 부작용으로 생각한 세 지표가 보이지 않았어요. 대신 다른 게 보였습니다. SE는 관례 과제 48호출 가운데 9번, 정답 도구보다 다른 도구를 먼저 불렀어요(get_payment 5, list_payments 2, get_deploy_history 2). S는 2번, L, LE, I는 0번이었습니다.

결제 번호 2026-1012-0042를 부분 환불하라는 과제(C05)의 SE 첫 회차를 볼게요.

node show.mjs out/s1/SE/C05-r1.jsonl tools,result

{"type":"assistant","message":{"content":[{"type":"tool_use","name":"mcp__lab__get_payment","input":{"payment_id":"2026-1012-0042"}}]}}
{"type":"user","message":{"content":[{"type":"tool_result","content":[{"type":"text","text":"{\"ok\":true,\"tool\":\"get_payment\",\"args\":{\"payment_id\":\"2026-1012-0042\"},\"value\":42}"}]}]}}
{"type":"assistant","message":{"content":[{"type":"tool_use","name":"mcp__lab__refund_payment","input":{"payment_id":"2026-1012-0042","amount":35000,"reason":"defect"}}]}}
{"type":"user","message":{"content":[{"type":"tool_result","content":[{"type":"text","text":"{\"ok\":true,\"tool\":\"refund_payment\",\"args\":{\"payment_id\":\"2026-1012-0042\",\"amount\":35000,\"reason\":\"defect\"},\"value\":42}"}]}]}}
{"type":"result","subtype":"success","is_error":false,"num_turns":3,"duration_ms":6847,"total_cost_usd":0.0241964,"result":"결제 2026-1012-0042 건에서 35,000원을 상품 불량 사유로 부분 환불했고, 시스템에서 요청이 정상 처리됐다는 응답을 받았습니다.\n\n다만 결제 조회 결과에 원래 결제 금액과 상태 같은 상세 정보가 없었습니다. 그래서 환불 뒤 남은 금액은 확인하지 못했습니다.","usage":{"input_tokens":6,"cache_creation_input_tokens":1120,"cache_read_input_tokens":30162,"output_tokens":459},"modelUsage":{"claude-opus-5-5":{"contextWindow":1000000,"provider":"firstParty","costUSD":0.0241964}}}

예시의 pay_202508141920과 질문의 2026-1012-0042가 모양이 달라 결제를 먼저 조회한 것으로 보여요. 그리고 조회 결과에 단서가 없자 질문의 표기를 그대로 넣었습니다. 이 서버는 조회 결과로 인자만 돌려줘 형식 단서가 없었고, 실제 조회가 ID 형식을 알려 주면 결과가 다를 수 있어요.

첫 MCP 호출이 아니라 정답 도구를 처음 부른 호출로 채점해도, SE는 36/48로 L의 48/48에 못 미쳤어요(위 출력의 convention on first gold-tool call).

실습 3: 설명이 첫 요청에 싣는 토큰

첫 요청 입력 토큰은 모델에게 가는 첫 요청이 읽은 입력 크기예요. 첫 assistant 메시지 usage의 input_tokens, cache_creation_input_tokens, cache_read_input_tokens를 더한 값입니다. tool search를 끈 이 실습에서는 도구 32개의 정의가 모두 이 안에 들어가요. 아래는 OFF 다섯 줄만 옮긴 발췌입니다.

node summary.mjs tokens

OFF S  first request 7,895~7,975 median 7,910 (150 calls), description chars 499
OFF SE first request 10,168~10,248 median 10,183 (150 calls), description chars 3,718, vs S +2,273 (71.0/tool)
OFF L  first request 12,280~12,360 median 12,295 (150 calls), description chars 4,954, vs S +4,385 (137.0/tool)
OFF LE first request 14,553~14,633 median 14,568 (150 calls), description chars 8,173, vs S +6,658 (208.1/tool)
OFF I  first request 9,790~9,870 median 9,805 (150 calls), description chars 1,557, vs S +1,895 (59.2/tool)

같은 조건 안의 범위(80토큰)는 질문 길이 차이이고, 같은 질문은 세 번 모두 같은 값이었습니다.

도구 하나당 S보다 SE가 71토큰, L이 137토큰, LE가 208토큰 많았어요. 도구 32개면 LE의 첫 요청이 S보다 6,658토큰 큽니다.
I는 설명 글자 수가 S보다 1,058자 많을 뿐인데 토큰은 1,895 많았어요. 엄격한 스키마의 pattern, enum, 형식을 적은 속성 설명도 함께 실리기 때문입니다.
150호출 추정 비용은 S 1.73달러, SE 2.00달러, L 1.84달러, LE 1.98달러, I 1.60달러였어요(node summary.mjs cost s1 S SE L LE I). 같은 도구 목록을 되풀이해 캐시 읽기가 대부분이라, 토큰 차이만큼 벌어지지 않았습니다.

정리

범위: Claude Code 2.1.296 claude -p, Opus 5.5(claude-opus-5-5), --effort high, 가짜 MCP 서버 도구 32개, 한국어 과제 50개를 조건마다 3번.

스키마로 알 수 없는 관례를 아무 데도 적지 않으면(S) 관례 과제 16개 가운데 5개만 맞았고, ID·표기 형식은 0/31이었어요. 날짜, 단위, 중첩 구조는 말하지 않아도 맞혔으니, 설명에는 모델이 추측할 수 없는 ID 접두, 정해진 enum 값, 필드 사이 규칙을 먼저 적어 주세요.
같은 관례를 3~4문장으로 적은 L, 거기에 예시를 더한 LE, 스키마의 pattern·enum과 규칙 한 문장으로 준 I는 세 번 모두 16/16이었고, 예시만 준 SE는 10~12/16으로 critical의 escalation을 세 번 모두 빠뜨렸습니다. 형식을 보여 주는 예시만으로 끝내지 말고, 변환 규칙과 필드 사이 규칙은 문장이나 스키마로 적어 주세요.
예시를 넣은 조건에서 과포함과 예시 값 복사는 0번이었고, 예시와 필드 묶음이 다른 과제에서도 떨어지지 않았어요. 대신 예시만 준 SE는 관례 과제 48호출 가운데 9번 다른 도구로 먼저 조회했으니, 예시만 넣으셨다면 추가 조회 호출이 늘었는지 확인해 보세요.
tool search를 끄면 도구 하나당 첫 요청이 S보다 SE 71, L 137, LE 208, I 59토큰 늘었습니다.