Skip to main content
Glama

홈택스 원천세 전자파일 변환신고 원본 올리기

hometax__tax__withholding__file_conversion__upload
Destructive

REQUIRES prior hometax__session__login call with same account_link_id. init 의 job_id 를 source_job_id 로, snapshot_hash 를 expected_snapshot_hash 로 하여 미리 등록한 원천세 전자파일 원본을 기관에 올리고 곧바로 형식검증을 요청합니다. 원본 파일 내용은 이 도구로 보낼 수 없습니다. 먼저 REST POST /v1/hometax/withholding/file-conversion/{source_job_id}/original 로 원본을 등록하고 돌려받은 file(file_job_id, filename, sha256)을 그대로 넘기세요. 암호는 이 도구로 입력할 수 없습니다. 결과 state 가 password_required 면 암호가 걸린 파일이니 REST API 의 형식검증(format_validate) 요청에 encrypted_fields.password 로 암호를 입력해 이어서 진행하고, 아니면 status 로 형식검증 결과를 확인하세요. 이 도구는 기관의 기록을 바꿉니다. 첫 호출은 실행되지 않고, 전송할 내용의 미리보기와 1회용 confirmation_token 을 돌려줍니다(오류 WRITE_CONFIRMATION_REQUIRED). 그 미리보기를 사용자에게 그대로 보여 줍니다. 사용자가 동의한 뒤에만 같은 인자에 그 confirmation_token 을 더해 다시 호출합니다. 사용자의 동의 없이 토큰을 넣지 않습니다. 인자를 하나라도 바꾸면 토큰은 무효가 됩니다. 그때는 토큰 없이 호출해 새 미리보기를 받습니다. 호출마다 토큰 1소진 요청 처리 시 XBOSS 작업을 생성하고 처리 결과를 저장합니다. 기관 원본의 조회 여부와 별개로 이 호출은 순수 읽기 전용이 아닙니다. 기관 데이터 변경은 도구별 실행 내용과 기존 확인 절차를 따릅니다.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "source_job_id": "<source_job_id>",
      "expected_snapshot_hash": "<expected_snapshot_hash>",
      "file": "<file>"
    },
    "name": "hometax__tax__withholding__file_conversion__upload"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileYes올릴 원본 파일의 참조 객체입니다. 원본 등록 요청이 돌려준 file_job_id(job_ 으로 시작하는 작업 번호), sha256(소문자 16진수 64자리), filename(기관에 전달할 파일 이름)을 그대로 입력합니다. filename 은 1자 이상이고 UTF-8 로 100바이트 이하여야 하며 점 하나나 둘, 줄바꿈 같은 제어 문자, 슬래시와 역슬래시와 쌍점을 쓸 수 없습니다. 파일 내용은 요청에 담을 수 없고, 맞지 않으면 원본 참조가 필요하다는 입력 오류로 거절합니다. JSON 문자열이 아니라 객체로 입력하며 문자열이면 입력 오류로 거절합니다.
source_job_idYes이어서 진행할 이전 단계 작업의 job_id 를 그대로 입력합니다(job_ 으로 시작하는 작업 번호). 변환 초기화(init) 결과를 받습니다. 접수된 신고를 다시 올리는 재신고(restart_after_receipt_no)에는 그 기존 변환 작업의 결과를 받습니다. 같은 조직과 환경, 같은 기관 연결에서 성공한 원천세 파일변환 작업이어야 하고 아니면 진행하지 않고 거절합니다.
account_link_idNo연동 ID(UUID v4). 선택 입력입니다. 비워 두면 서버가 API 키로 연동을 찾아 씁니다. 같은 기관에 인증서를 여러 개 연동했을 때만 직접 입력해 주세요. 기관마다 ID 가 다릅니다.
confirmation_tokenNo첫 호출이 돌려준 1회용 확인 토큰입니다(오류 WRITE_CONFIRMATION_REQUIRED). 같은 인자에 이 값을 그대로 넣어 다시 호출하면 실행됩니다. 10분 뒤 만료되고 한 번만 쓸 수 있습니다.
expected_snapshot_hashYessource_job_id 작업 결과의 snapshot_hash 를 그대로 입력합니다(소문자 16진수 64자리). 그 작업의 내용과 맞지 않으면 진행하지 않고 작성 내용이 바뀌었다는 오류(409)로 거절합니다.
restart_after_receipt_noNo이미 접수된 정기신고(regular)를 새 파일로 다시 신고할 때 다시 신고할 기존 접수번호입니다. 숫자 10자리 이상 30자리 이하입니다. source_job_id 는 그 기존 변환 작업의 결과여야 하고, 변환이 끝난 상태이며 이 접수번호가 현재 기관의 변환 작업과 일치해야 합니다. 정기신고가 아니거나 상태나 접수번호가 맞지 않으면 409 로 거절합니다. 입력하지 않으면 기관에 진행 중인 변환 작업이 없을 때만 올릴 수 있고, 있으면 중복 업로드로 409 거절합니다.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / $defs / FileReference / properties / file_job_id / description
      Added value: +"원본 등록 요청이 돌려준 작업 번호입니다(job_ 으로 시작). 그대로 입력합니다."
    • addedInput schema / $defs / FileReference / properties / filename / description
      Added value: +"기관에 전달할 원본 파일 이름입니다. 1자 이상이고 UTF-8 로 100바이트 이하여야 하며, 점 하나나 둘, 줄바꿈 같은 제어 문자, 슬래시와 역슬래시와 쌍점을 쓸 수 없습니다. 맞지 않으면 입력 오류로 거절합니다."
    • addedInput schema / $defs / FileReference / properties / sha256 / description
      Added value: +"원본 등록 요청이 돌려준 파일 확인값입니다(소문자 16진수 64자리). 그대로 입력합니다."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint/readOnlyHint=false annotations, it discloses the two-step write-confirmation protocol: the first call never executes and returns a preview plus a one-time confirmation_token (WRITE_CONFIRMATION_REQUIRED), the user must consent, any argument change invalidates the token, and each successful call creates an XBOSS job. It also explains how to finish when the result state is password_required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The prerequisite and the token flow are front-loaded well, but the text is long and has redundancy: the trailing paragraph ('순수 읽기 전용이 아닙니다... 도구별 실행 내용과 기존 확인 절차를 따릅니다') restates the mutation warning already made earlier. One sentence about token consumption/XBOSS creation is garbled and hard to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, six-parameter mutation tool with no output schema, it covers prerequisites, the confirmation gate, error codes, and the encrypted-file branch, and it describes the returned preview/token and status outcomes. Minor gaps remain, such as what to do on a 409 snapshot mismatch or duplicate upload beyond re-calling, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents field constraints. The description still adds real meaning by mapping init's job_id to source_job_id and its snapshot_hash to expected_snapshot_hash, and by insisting the file reference must be the exact object returned by the REST registration call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it uploads an already-registered withholding-tax electronic file original to the institution and immediately requests format validation. It is clearly separated from sibling steps (init, preview, submit, content_validate) by naming source_job_id/expected_snapshot_hash from init and by saying file contents cannot be sent here.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit prerequisites (prior login with the same account_link_id), a mandatory REST pre-step (POST .../original), and a concrete alternative path for encrypted files (REST format_validate with encrypted_fields.password when state is password_required). It also tells the agent exactly what not to do: no file contents and no password through this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources