Skip to main content
Glama

APICK Business

개인 국세 통합조회 인증 요청

req_hometax_bundle

개인 국세 통합조회를 위한 본인 간편인증을 요청합니다. products 로 조회할 상품을 고르면 고른 상품만 승인 한 번으로 실행하고, 단가는 고른 상품 단가의 합입니다. 휴대폰 알림 발송과 접수 과금이 발생하므로 사용자 확인 후 호출하세요. transactionId와 status를 반환하면 휴대폰 승인을 안내하고, 승인 후 get_hometax_bundle에 transactionId를 전달하세요. 승인 대기 중 인증 요청을 반복하거나 자동 승인하지 마세요. [인증 발송 성공 시 20P]

Input Schema

NameRequiredDescriptionDefault
nameYes본인 이름
yearNo증명 귀속연도 4자리 (증명을 고를 때 사용)
phoneYes본인 명의 휴대전화 번호 (숫자만)
yearsNo신고·납부내역 조회 연수 (1~10, 생략 시 1)
formatNo증명 응답 형식 (생략 시 both)
engl_ynNo영문 증명 여부 (Y/N, 생략 시 N)
itrf_cdNo증명 발급 사유 코드 (서버 공통코드)
deliveryNo교부방법 (06 프린터·10 화면·04 팩스·12 전자문서지갑)
issuanceNo증명 발급 구분 (서버 공통코드)
productsYes조회할 상품 키 (1개 이상). personal_income·cash_receipt_deduction·income_by_payer·income_data_check·tax_return_history·tax_payment_history·income_amount_cert·pension_credit_cert·fact_cert
quantityNo발급 희망 수량 (1~5, 생략 시 1)
birthDateYes생년월일 8자리 (YYYYMMDD)
end_monthNo증명 조회 종료 월 (01~12)
submit_toNo제출처 코드 2자리 (증명을 고를 때 사용)
incomeYearsNo소득·현금영수증 조회 연수 (1~5, 생략 시 1)
start_monthNo증명 조회 시작 월 (01~12)
use_purposeNo사용용도 코드 2자리 (증명을 고를 때 사용)
authProviderYes휴대폰에서 승인할 간편인증 방식
resno_open_ynNo주민등록번호 공개 여부 (Y/N)
amount_open_ynNo소득금액증명 금액 공개 여부 (Y/N)
address_open_ynNo주소 공개 여부 (Y/N)
income_source_open_ynNo소득금액증명 소득발생처 공개 여부 (Y/N)
withholding_all_print_ynNo소득금액증명 원천징수의무자 전체 표시 (Y/N)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false and idempotentHint=false; the description goes well beyond that by disclosing that a real phone notification is sent, that billing/charging occurs (20P on successful send), that the call returns transactionId and status, and that retrying during pending approval is harmful. This is exactly the side-effect and cost context the annotations cannot convey.

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?

Purpose is front-loaded, followed by product/pricing semantics, the confirmation caution, the return-value-to-next-call flow, and the retry prohibition — each sentence carries distinct information. It is slightly cluttered by stating the charge twice (billing warning and the trailing [인증 발송 성공 시 20P] tag).

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 23-parameter, no-output-schema tool it covers the essentials: what it returns (transactionId, status), what happens on the user's phone, the cost, and the handoff to get_hometax_bundle. It does not explain that identity fields (name, birthDate, phone) must match the account owner or which optional certificate parameters are relevant per product, but the fully described schema fills most of that gap.

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 baseline is 3, but the description adds genuine meaning the schema lacks: products is a multi-select whose selection determines what actually runs, and the unit price is the sum of the selected products' prices. It does not clarify how the many certificate-specific optional parameters (year, format, delivery, *_open_yn) map to which products, leaving that to the schema.

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 first sentence gives a specific verb and resource (requesting simple self-authentication for personal national tax integrated lookup), and the description explicitly names the follow-up sibling get_hometax_bundle, so the agent can separate this 'auth request' step from the 'fetch results' step. It does not explain how it relates to the other req_* siblings, but the pattern is inferable.

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 states the precondition (get user confirmation first because a phone push and billing are triggered), the prohibition (do not repeat the auth request while approval is pending, do not auto-approve), and the exact next action (pass the returned transactionId to get_hometax_bundle). When-to-use, when-not-to-use, and the alternative step are all explicit.

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.