Skip to main content
Glama

홈택스 원천세 정기신고 상세 저장

hometax__tax__withholding__regular_report__detail_save
Destructive

먼저 호출할 도구: hometax__session__login (같은 account_link_id). 작성 중인 원천세 정기신고서에 소득 구분별 상세를 저장합니다. 호출마다 토큰 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": {
      "draft_id": "<draft_id>",
      "expected_state_version": "<expected_state_version>",
      "idempotency_key": "<idempotency_key>",
      "detail_document": "<detail_document>"
    },
    "name": "hometax__tax__withholding__regular_report__detail_save"
  }
}

Input Schema

NameRequiredDescriptionDefault
draft_idYesinit 결과의 draft_id 를 그대로 입력합니다. 어느 신고서를 작성 중인지 가리킵니다.
account_link_idNo연동 ID(UUID v4). 선택 입력입니다. 비워 두면 서버가 API 키로 연동을 찾아 씁니다. 같은 기관에 인증서를 여러 개 연동했을 때만 직접 입력해 주세요. 기관마다 ID 가 다릅니다.
detail_documentYes소득종류별 명세입니다. income_sections 가 필수이고, 그 키는 basic_save 에서 고른 소득종류와 정확히 같아야 합니다. 근로소득(employment)의 rows 에는 그 소득종류의 행 코드(code)를 정해진 순서대로 모두 입력합니다. 그 밖의 소득종류의 rows 에는 그 소득종류에서 쓸 수 있는 행 코드 가운데 신고할 행만 입력하고, 같은 코드를 두 번 입력하지 않습니다. 행마다 인원(inc_pymn_nfp_cnt), 총지급액(inc_pymn_tota_pymn_amt), 세액 칸을 채웁니다. previous_refund(이번 세액에서 먼저 빼는 환급세액, 0 이상 정수, 기본 0), annex_choices, succession_popup 은 선택입니다.
idempotency_keyYes같은 요청을 두 번 실행하지 않기 위한 키(8자 이상 128자 이하)입니다. 같은 초안의 다른 단계에는 새 값을 입력하고, 재시도에는 같은 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려줍니다.
expected_state_versionYes직전 단계 결과의 state_version 을 그대로 입력합니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 실행하지 않고 거절합니다.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / detail_document / description
      Previous value: -"Withholding detail document payload"New value: +"소득종류별 명세입니다. income_sections 가 필수이고, 그 키는 basic_save 에서 고른 소득종류와 정확히 같아야 합니다. 근로소득(employment)의 rows 에는 그 소득종류의 행 코드(code)를 정해진 순서대로 모두 입력합니다. 그 밖의 소득종류의 rows 에는 그 소득종류에서 쓸 수 있는 행 코드 가운데 신고할 행만 입력하고, 같은 코드를 두 번 입력하지 않습니다. 행마다 인원(inc_pymn_nfp_cnt), 총지급액(inc_pymn_tota_pymn_amt), 세액 칸을 채웁니다. previous_refund(이번 세액에서 먼저 빼는 환급세액, 0 이상 정수, 기본 0), annex_choices, succession_popup 은 선택입니다."
    • changedInput schema / properties / draft_id / description
      Previous value: -"Draft ID returned by init"New value: +"init 결과의 draft_id 를 그대로 입력합니다. 어느 신고서를 작성 중인지 가리킵니다."
    • changedInput schema / properties / expected_state_version / description
      Previous value: -"Expected draft state version"New value: +"직전 단계 결과의 state_version 을 그대로 입력합니다(1 이상). 그사이 신고서가 바뀌어 값이 다르면 실행하지 않고 거절합니다."
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Idempotency key for safe retry"New value: +"같은 요청을 두 번 실행하지 않기 위한 키(8자 이상 128자 이하)입니다. 같은 초안의 다른 단계에는 새 값을 입력하고, 재시도에는 같은 값을 입력합니다. 같은 키로 다시 요청하면 다시 실행하지 않고 처음 결과를 돌려줍니다."
  2. First observed

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description reinforces that with an explicit 'this call is not purely read-only' plus a per-call cost signal (1 token) and the fact that an XBOSS job is created and its result stored. The closing sentence about agency data changes following each tool's execution content and existing confirmation procedures is vague boilerplate. The most important destructive behavior, namely whether re-saving replaces or appends existing detail rows, is not stated.

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

Conciseness4/5

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

Short and front-loaded: the prerequisite login call comes first, then the action, then cost and safety notes. The final two sentences are generic caveats that could be trimmed without losing information.

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

Completeness3/5

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

For a destructive, token-costing save with a nested object parameter and no output schema, the definition covers prerequisites and cost but leaves an agent guessing about the return value, in particular whether a new state_version comes back for the next step. It also does not explain how this step relates to preview, review, and submit in the workflow. The schema fills the parameter gaps, but the outcome and workflow position remain thin.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already explains draft_id, account_link_id defaults, the 8-128 character idempotency key with replay semantics, and the optimistic-lock rejection on expected_state_version. The description adds no parameter-level detail at all and never mentions the nested detail_document contract. Baseline 3 is appropriate when the schema does all the work.

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

Purpose4/5

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

The description gives a specific verb and resource: it saves income-category details (소득 구분별 상세) into the in-progress regular withholding report (원천세 정기신고서). The word 정기 ('regular') and the tool name together distinguish it from the amendment_report and late_report detail_save siblings with the same shape. It does not explicitly say how it differs from basic_save, which is the sibling an agent would most likely confuse it with.

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

Usage Guidelines3/5

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

It gives one concrete prerequisite chain: call hometax__session__login first with the same account_link_id. It does not state that basic_save must already have been completed (the schema, not the description, carries the constraint that income_sections keys must match the income types chosen earlier), and it gives no when-not guidance versus the amendment or late variants beyond what the name implies.

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