Skip to main content
Glama
kgy0617

ECOS MCP Server

by kgy0617
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

통계 시계열 조회

search_statistics
Read-onlyIdempotent

Search Bank of Korea ECOS time series by statistic code, cycle, and date range. Filter items, compute YoY or period-over-period changes, and get compact, CSV, or JSON results.

Instructions

통계 시계열 데이터를 조건별로 조회합니다.

★ 스마트 날짜: start_date, end_date를 생략하면 일간(D)은 최근 3개월, 그 외 주기는 최근 2년이 자동 설정됩니다.
★ 최신 우선: 결과가 end_count를 넘으면 가장 최근 구간을 반환하고 truncated=true와 안내를 붙입니다.
★ 증감률: transform="yoy"(전년동기대비 %) 또는 "pop"(직전 관측치 대비 %)를 지정하면 계산 열이 추가됩니다.
★ 포맷: "compact"(기본값, 계열별 [시점, 값] 배열), "csv", "json"(ECOS 원본 행)

★ 주기(cycle) 및 날짜 포맷 규칙:
- 연간(A): YYYY (예: "2024")
- 반기(S): YYYYS1, YYYYS2 (예: "2023S1")
- 분기(Q): YYYYQ1 ~ YYYYQ4 (예: "2024Q3")
- 월간(M): YYYYMM (예: "202401")
- 반월(SM): YYYYMMS1, YYYYMMS2 (예: "202401S1")
- 일간(D): YYYYMMDD (예: "20240315")

Args:
    stat_code: 통계표코드 (필수). 예: "722Y001"(기준금리), "901Y009"(소비자물가)
    cycle: 주기 (필수). A(연), S(반기), Q(분기), M(월), SM(반월), D(일)
    start_date: 검색 시작일 (선택)
    end_date: 검색 종료일 (선택)
    item_code1~4: 통계항목코드 (선택. 미지정 시 전체 세부항목 조회 — 결과가 매우 커질 수 있음)
    output_format: "compact"(기본값), "csv", "json"
    transform: "yoy", "pop", "none"(기본값)
    changes_only: True면 값이 바뀐 시점만 반환 (금리처럼 드물게 변하는 일별 지표에 유용)
    prefer_latest: 결과가 잘릴 때 최신 구간을 우선 반환 (기본값 True)
    start_count: 조회 시작 순번 (기본값: 1)
    end_count: 조회 끝 순번 (기본값: 1000)
    language: 응답 언어 — "kr" 또는 "en"

Returns:
    시계열 데이터 (지정된 포맷)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cycleYes
end_dateNo
languageNokr
end_countNo
stat_codeYes
transformNo
item_code1No
item_code2No
item_code3No
item_code4No
start_dateNo
start_countNo
changes_onlyNo
output_formatNocompact
prefer_latestNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context beyond annotations: smart date auto-fill, truncated=true with guidance, transform calculations, format variations, changes_only behavior, prefer_latest default, and pagination via start_count/end_count. No contradiction with annotations.

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

Conciseness5/5

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

The description is long but well-structured with bullet points and sections. Key behaviors (smart dates, truncation, transform, formats) are front-loaded, then date format rules, then parameter details. Every sentence adds value; no fluff. Given 15 parameters, the length is appropriate and organized.

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

Completeness5/5

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

With no output schema, the description must explain return formats, and it does: 'compact' (array of [time, value] per series), 'csv', 'json'. It also covers pagination, truncation, transform options, date formats for all cycles, and the behavior of changes_only and prefer_latest. All necessary information for an agent to call the tool correctly is present.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries the full burden of parameter explanation. It does so excellently: each parameter is documented in the Args section with types, defaults, and examples (e.g., stat_code examples, cycle options with format rules, output_format options, transform options, and the warning about item_code1-4 returning huge results). This fully compensates for the missing schema descriptions.

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 clearly states it retrieves statistical time series data by conditions, with a specific verb and resource. It mentions stat_code and cycle as required, and the examples (기준금리, 소비자물가) distinguish it from sibling tools like get_statistic_meta or search_statistic_tables.

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?

The description explains when to use the tool (time series queries) and provides extensive usage details like smart date defaults, truncation behavior, and format options. However, it does not explicitly mention alternative tools or exclusions, leaving some inference to the agent. It is clear enough that this is the time series query tool among the siblings.

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

Deploy Server

Other Tools