Skip to main content
Glama

전자세금계산서 목록 조회

hometax__etax__invoice__search_list

먼저 호출할 도구: hometax__session__login (같은 account_link_id). 기간으로 전자세금계산서를 조회합니다. from_date/to_date 는 YYYYMMDD 또는 YYYY-MM-DD 형식입니다. prh_sls_cl_cd 는 '01' 이 발급한 것(매출), '02' 가 받은 것(매입)입니다. 기관은 긴 기간을 '6개월이상은 조회할 수 없습니다.' 로 거절하므로 6개월 미만으로 잡고, 더 긴 기간은 여러 번 나눠 호출합니다. 로그인한 호출이면 첫 요청 전에 request_idempotency_key 값을 만들어 저장하세요. 응답을 받지 못한 그 요청을 되찾을 때만 같은 인자와 함께 그 값을 다시 보내고, 새로 실행할 때는 새 값을 쓰세요. 이 값 없이 다시 부르면 새 요청이 됩니다. 계정 없이 맛보기로 부를 때는 이 선택 칸을 쓸 수 없습니다. 기관 업무에 따로 있는 idempotency_key 칸은 다른 칸이니 그대로 두세요. 호출마다 토큰 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": {
      "from_date": "<from_date>",
      "to_date": "<to_date>"
    },
    "name": "hometax__etax__invoice__search_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
to_dateYesEnd date YYYYMMDD or YYYY-MM-DD (e.g. 20260131)
page_numNoPage number (default 1)
from_dateYesStart date YYYYMMDD or YYYY-MM-DD (e.g. 20260101)
page_sizeNoPage size (default 10)
prh_sls_cl_cdNoInvoice direction: '01'=issued(매출), '02'=received(매입). Default '01'.
account_link_idNo연동 ID(UUID v4). 선택 입력입니다. 비워 두면 서버가 API 키로 연동을 찾아 씁니다. 같은 기관에 인증서를 여러 개 연동했을 때만 직접 입력해 주세요. 기관마다 ID 가 다릅니다.
request_idempotency_keyNo로그인한 호출에서 응답을 못 받은 같은 요청을 되찾을 때 쓰는 선택 값입니다. 쓰는 법은 도구 설명에 있습니다.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / request_idempotency_key / description
      Previous value: -"Optional same-request recovery key for authenticated calls; see the tool description."New value: +"로그인한 호출에서 응답을 못 받은 같은 요청을 되찾을 때 쓰는 선택 값입니다. 쓰는 법은 도구 설명에 있습니다."
  2. First observed

TDQS

A4.1/5.0
Behavior5/5

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

The description discloses behavior well beyond the annotations: the institution's 6-month period rejection, a 1-token cost per call, XBOSS task creation and result persistence per request, and the critical caveat that despite being a query this call is 'not purely read-only' – which correctly aligns with readOnlyHint=false. It also warns that the institution's own idempotency_key field is a different field to leave untouched, and that guest (no-account) calls cannot use the optional idempotency parameter.

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 login call is correctly front-loaded, which is the highest-value information. However, the block is dense and includes material already covered by the 100%-covered schema (date formats, the 01/02 direction codes) plus a vague trailing sentence about institution data changes following per-tool procedures, both of which dilute the signal.

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 7-parameter query tool with no output schema, the description covers prerequisites, period limits, cost, side effects, and idempotency well enough to call it correctly. What it omits is anything about the response shape or pagination behavior (page_num/page_size), which matters since no output schema exists to describe the returned list.

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 description coverage is 100%, so the baseline is 3; the description earns above that by fully explaining how request_idempotency_key is to be generated and reused (the schema itself defers to the tool description for this) and by disambiguating it from the institution's separate idempotency_key field. The date-format and prh_sls_cl_cd explanations merely restate the schema and add no new meaning.

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 states a specific verb and resource ('기간으로 전자세금계산서를 조회합니다' – look up e-tax invoices by period) plus the direction filter, so the agent knows this is a period-based list retrieval. It does not explicitly distinguish itself from the sibling tools search_detail / search_summary / search_statistics, so an agent must infer that this is the list-level variant from the name alone.

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

Usage Guidelines4/5

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

It gives unusually concrete usage context: call hometax__session__login first with the same account_link_id, keep the period under 6 months because the institution rejects longer spans, and split longer ranges into multiple calls. The idempotency-key workflow (create before first request, reuse only to recover an unanswered request, new value for new work) is spelled out. It lacks only explicit routing guidance among the sibling invoice search tools.

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