Skip to main content
Glama
gitbosung

open-ALIO-mcp

by gitbosung

open-ALIO-mcp — 공공기관 정보 MCP 서버

Open-source MCP server for Korean public institution information based on ALIO and ALIO Plus.

ALIO·ALIO Plus 기반 공공기관 경영공시정부·공공기관 관련 법령·지침·대국민서비스 정보를 AI 클라이언트(Cursor, Claude Desktop 등)가 조회·분석할 수 있도록 연결하는 MCP(Model Context Protocol) 서버입니다.

"한국전력공사의 최근 5년 정원·부채 추이를 보여줘" — 이 한 문장이면 됩니다.

왜 이 프로젝트인가 (Why this matters)

공공기관 정보는 ALIO에 이미 공개되어 있습니다. 그러나 일반 국민과 실무자가 원하는 질문 단위로 접근하기는 어렵습니다.

  • 특정 기관의 최근 5년 재무현황은? 유사 기관끼리 정원·부채·보수를 비교하면?

  • 이 기관은 어느 부처 소관이고, 채용·시설·서비스 정보는 어디서 확인하나?

  • ALIO 공시 수치와 최근 뉴스 보도가 일치하나?

open-ALIO-mcp는 이런 질문에 AI가 바로 답할 수 있도록 공공기관 정보를 MCP tool로 구조화한 공공데이터 접근성 개선 프로젝트입니다. Generic web search가 아니라 한국 공공기관 도메인에 특화된 MCP 서버로, 기관 식별·주무부처·정원/현원·재무지표· 대국민서비스·법령/지침·경영평가까지 공공기관 분석에 필요한 핵심 도메인 구조를 담고 있습니다.

이 프로젝트에서 가장 어려운 부분은 API 하나를 연결하는 것이 아니라, AI가 안전하게 조회·비교·설명할 수 있는 형태로 한국 공공기관 정보를 모델링하는 것이며, 그 기반은 이미 갖춰져 있습니다. 모든 응답이 출처·기준연도·단위·유의사항을 포함하는 source-aware 설계이므로, 출처 추적성이 중요한 공공부문 활용에 적합합니다.

Related MCP server: @opendata-kr/narajangteo-bid-mcp

이 MCP로 할 수 있는 것

영역

대표 기능

기관·경영공시

355개 ALIO 공시 단위(342개 독립 지정기관 + 13개 부설기관) 검색, 11종 지표 시계열·비교·스크리닝, 경영공시 항목 카탈로그

대국민서비스

채용공고·개방시설·국가사업 검색, 기관 지점 조회

분석·검증

기관 360° 브리핑, 뉴스↔지표 교차검증, 채용·뉴스 분포 집계

법령·지침

공공기관 맥락 법령·행정규칙 조회, 로컬 지침(HWPX/PDF) 조문 검색

경영평가

경영평가편람 지표·배점·본문 검색, 연도별 변경 추적

자연어 질문 하나로 AI가 위 도구를 조합해 출처·단위·유의사항과 함께 답합니다.

기대 효과

일반 국민

  • 공공기관 채용·개방시설·지원사업을 한곳에서 검색 — 기관명 별칭(한전·LH 등)만 알아도 조회 가능

  • "이 기관이 뭐 하는 곳인지" 설립목적·주요기능을 공식 공시 기반으로 확인

  • 기관 관련 최신 뉴스를 동음이의어·중복기사를 걸러 받아볼 수 있음

공공기관 종사자

  • 우리 기관과 동종 기관의 인력·보수·복지·재무 지표를 ALIO 공시 수치로 바로 비교

  • 정원 vs 현원을 구분한 인력현황 요약으로 "몇 명 재직?" 질의에 명확히 답변

  • 공시 주기·항목 분류를 카탈로그로 확인해 "언제·무엇이 공개되는지" 파악

유관 부서·공무원

  • 산하·동종 기관 다건 비교·스크리닝으로 국감·기능조정·정책 브리핑 초안 작성 시간 단축

  • 언론 이슈와 실제 공시 지표를 교차검증 — 보도와 수치의 괴리를 한 번에 확인

  • 공운법·경영지침·예산운용지침 등 공공기관 업무 맥락 법령·지침을 AI 대화 안에서 조회

  • 경영평가편람 지표·배점·세부평가내용 검색으로 평가 준비·변경 추적 지원

데이터·연구 활용

  • 모든 응답에 source(출처·기준연도)와 caveats(유의사항) 포함 — 추정 대신 결측 명시

  • 채용·지표 분포 집계로 수도권 편중, NCS 직무별 수요 등 거시 패턴 분석

  • ALIO 공시 페이지에서 수집·검증한 값까지 병합해 xlsx 미제공 항목으로 원천 데이터 확장 (수집 파이프라인은 별도 데이터 저장소에서 관리)

현재 상태 (Current status)

기능 구현 완료, 운영 전환 전 단계의 early-stage 프로토타입. MCP Tools 32개 · Prompts 2종 · Resources 5종.

  • 지금 바로 적합한 용도: 로컬 MCP 사용, 공공부문 AI 실험, 개인 분석

  • 공개 HTTP/SSE 배포 전 필요한 보강: 인증, rate limit, 감사로그, 데이터 갱신 자동화 등 운영 통제(operational hardening) — 자세한 내용은 SECURITY.mddocs/roadmap.md 참조

어려운 도메인 모델링(기관 식별·별칭, 공시 주기, 정원/현원 구분, 지표 단위, 출처 표기)은 대부분 프로젝트 안에 이미 구현되어 있고, 남은 과제는 주로 패키징·테스트·데이터 갱신·배포 통제 같은 운영 영역입니다. 이 저장소는 향후 **한국 공공부문 AI 지식 레이어(public-sector AI knowledge layer)**로 확장하기 위한 기반(foundation)으로 설계되었습니다.

데이터 소스

용도

NKOD OpenAPI 4종 (ALIO Plus)

기관·지점·채용·시설·국가사업

ALIO 항목별 공시 엑셀 11종

지표 시계열 (기관·연도는 카테고리별 — list_metric_categories 참조)

ALIO 공시 카탈로그·크롤링

경영공시 50개 항목(세부 92종) 메타 + HTML 표 수집

네이버 뉴스 API

기관별 뉴스·이슈 검색

국가법령정보센터 Open API

법령·행정규칙

로컬 지침·경영평가편람

HWPX/PDF 파싱 적재

기관 수 355개는 ALIO 공시 단위 기준이며 부설기관 13개를 포함합니다. 독립 지정 기관 수는 342개이고, MCP 응답의 is_subsidiary, parent_org_code, classification_org_type으로 구분합니다.

아키텍처 (Architecture)

데이터 흐름:

flowchart TD
    A[ALIO 공시 엑셀·크롤링] --> D[open-ALIO-mcp]
    B[ALIO Plus / NKOD OpenAPI] --> D
    C[법령·지침·경영평가편람] --> D
    N[네이버 뉴스 API] --> D
    D --> E[Claude Desktop]
    D --> F[Cursor]
    D --> G[기타 MCP 클라이언트]

질의 처리 구조:

flowchart TD
    U[사용자 자연어 질문] --> M[MCP 클라이언트 / AI]
    M --> T[MCP Tools 32종]
    T --> S[보안 래퍼 — 입력 검증·응답 제한]
    S --> L[데이터 레이어]
    L --> A1[로컬 스냅샷 — institutions·metrics·handbook·guidelines]
    L --> A2[온디맨드 API — ALIO Plus·뉴스·법령]
    T --> R["구조화 응답 (data + source + caveats)"]
    R --> M

상세 구조는 docs/architecture.md 참조.


MCP 기능 상세

Tools (32개)

1. 기관 검색·프로필

Tool

설명

search_institutions

기관 검색 — 별칭·부분일치 fallback(한전·심평 등), 관련도 정렬

get_institution_profile

기관 프로필 + 일반현황(설립목적·경영목표·기관장·주요기능 등)

get_institution_branches

기관 지점·사업소 목록

2. 경영공시·지표

Tool

설명

list_metric_categories

공시 지표 카테고리 11종 목록

list_metric_items

카테고리 내 지표 항목명 탐색

list_disclosure_items

ALIO 경영공시 항목 카탈로그 — 정기/수시·공시주기·ESG 분류 (50개·세부 92종)

get_institution_metrics

지표 시계열 조회 (정원·보수·부채·예산 등, 연도는 카테고리별)

get_institution_staff_summary

인력현황 요약 — 정원(authorized) vs 현원(actual) 구분, headcount 추정

compare_institutions

2~5개 기관 지표 나란히 비교

find_institutions_by_criteria

조건 스크리닝 — 지표 상·하위, 증감률 상위 (org_type·부처 필터)

지표 응답에는 공시 주기 주석이 자동 부착되며, 데이터가 비어 있으면 "공시 주기 미도래·미공시 가능성" 안내가 caveats에 추가됩니다.

3. 대국민서비스 (ALIO Plus)

Tool

설명

search_public_services

국가사업·대민 지원 서비스 검색

search_facilities

개방시설 검색 — 예약 링크·수용인원·운영시간, 통합 query·페이지네이션

get_facility_profile

개방시설 상세

search_recruitments

채용공고 검색 — 기관명 자동 해석, 마감임박·NCS·학력·우대조건·취소공고 제외

get_recruitment_profile

채용공고 상세 — 전형단계·모집요강·지원 링크

analyze_recruitments

진행중 채용 분포 집계 — 지역·직무·고용형태·학력·기관별 공고수/모집인원

4. 뉴스·통합 분석

Tool

설명

get_institution_news

기관별 뉴스 검색 — 공식명+별칭 OR 검색, 동음이의어 제외, 중복 제거, 기간 커버리지 진단

get_institution_briefing

360° 브리핑 — 프로필 + 핵심지표 추세 + 최근 뉴스 + 진행중 채용

cross_check_news_with_metrics

뉴스↔지표 교차검증 — 토픽(부채·정원·보수 등)을 지표로 매핑, 시계열+뉴스+공시주기

digest_institution_news

뉴스 테마 분류·집계 — 재무/채용/안전/감사/사업/정책/ESG + 타임라인

get_institution_news는 org_code 없이 query만으로도 동작합니다. sort='date'일 때 기간을 벗어나면 조기 종료해 API 호출을 줄이며, 보도량이 많아 기간을 다 못 덮으면 caveats로 알립니다.

5. 법령·행정규칙·지침

Tool

설명

search_laws / get_law_text

법령 검색·조문 조회 — 공운법 등 화이트리스트 가이드, 목차 모드 + 조문 지정

search_admin_rules / get_admin_rule_text

행정규칙(훈령·예규·고시·지침) 검색·본문 — 경영지침·혁신지침 등

search_guidelines / get_guideline_text

로컬 지침 조문 검색·조회 — law.go.kr 미등재 연도별 시달 지침(HWPX/PDF)

6. 경영평가편람

Tool

설명

search_evaluation_handbook

편람 본문 키워드 검색 — 중대재해·총인건비·안전관리등급 등, part·year 필터

list_evaluation_org_types

편람에 정의된 기관 유형(공기업 SOC·에너지, 준정부 기금관리형 등)

list_evaluation_indicators

유형별 평가지표·배점(계·비계량·계량) 표

get_evaluation_indicator_detail

지표명으로 세부평가내용·배점·지표정의 조회

compare_evaluation_handbook_years

두 연도 편람에서 동일 키워드 검색 — 변경 추적 보조

7. 운영

Tool

설명

get_server_status

서버·데이터 적재 상태 점검 (기관·지표·공시·채용스냅샷·편람·지침)

Prompts (2종)

Prompt

용도

summarize_disclosure

기관 1곳 공시 요약 — 개요·인력·보수·재무·출처 고정 양식

policy_brief

기관 비교 기반 1쪽 정책 브리핑 — 판단성 결론 금지 규칙 내장

Resources (5종)

Resource URI

내용

alio://disclosure-catalog

ALIO 경영공시 항목 카탈로그 (50개·세부 92종, 정기/수시·주기·metric 매핑)

alio://metric-categories

보유 지표 카테고리 인덱스

alio://related-laws

공공기관 핵심 법령·행정규칙 화이트리스트 (공운법 18종 + 기재부 지침 6종)

alio://handbook-index

경영평가편람 적재 목록

alio://guideline-index

로컬 적재 지침 목록

지표 카테고리 (data/metrics/)

아래 공시 기관 수·연도data/metrics/_index.json에 집계되어 있습니다. 최신 값은 MCP tool list_metric_categories 또는 get_server_status로 확인하세요.

category

내용

공시 기관 수

연도

단위

staff

임직원 정원·현원

355

2021–2026

salary

직원 평균보수·신입초임

355

2021–2026

천원

executive_pay

임원 연봉

343

2021–2026

천원

recruitment

신규채용·청년인턴

355

2021–2026

budget

수입·지출, 정부순지원수입

354

2021–2026

백만원

welfare

복리후생비

355

2021–2025

천원

welfare_etc

그 밖의 복리후생제도

305

2021–2025

천원

work_life

육아휴직·유연근무 등

355

2021–2025

tax

법인세

338

2021–2025

천원

head_expense

기관장 업무추진비

351

2021–2025

천원

finance

요약 재무상태표·손익

355

2021–2025

백만원

데이터 승격 주의: finance, budget, executive_pay는 엑셀 기반 metrics에 ALIO 공시 검증값을 병합합니다. 같은 기관·항목·연도에서 값이 충돌하는 그룹은 자동 선택하지 않고 기존 엑셀 값을 fallback으로 유지합니다. 이 저장소에는 병합이 끝난 런타임 데이터만 포함되며, 원천 수집·승격 파이프라인은 별도 데이터 저장소에서 관리합니다.


설치

Quick start with uvx

PyPI 배포판은 소스 체크아웃 없이 바로 실행할 수 있습니다.

uvx open-alio-mcp

첫 실행 때 로컬 data/ 디렉터리가 없으면 GitHub Release의 alio_snapshot.db를 사용자 데이터 디렉터리로 자동 다운로드합니다. 이 스냅샷만으로 기관 검색, 주요 공시 지표, 공시 항목 카탈로그, 지침·경영평가편람 검색을 사용할 수 있습니다.

API key setup

기본 스냅샷 조회에는 API 키가 없어도 됩니다. 다만 라이브 채용·시설·사업 조회, 뉴스 검색, 법령·행정규칙 조회를 쓰려면 아래 키를 설정하세요.

환경변수

필요한 기능

발급 위치

DATA_GO_KR_SERVICE_KEY

ALIO Plus 라이브 API: 채용·시설·사업·지점 등

data.go.kr

NAVER_CLIENT_ID, NAVER_CLIENT_SECRET

기관별 뉴스 검색·이슈 분석

developers.naver.com

LAW_API_OC

국가법령정보센터 법령·행정규칙 검색

open.law.go.kr

DATA_GO_KR_SERVICE_KEY는 공공데이터포털에서 "기획재정부_공공기관 정보 조회 서비스"를 활용 신청한 뒤 일반 인증키(Decoding) 값을 사용합니다.

LAW_API_OC는 국가법령정보센터 회원가입 후 "Open API 사용 신청"으로 발급받는 OC 값입니다. 보통 가입 이메일의 ID 부분입니다. 예를 들어 hong@example.com이면 hong 형태입니다.

NAVER_CLIENT_IDNAVER_CLIENT_SECRET은 네이버 개발자센터에서 애플리케이션을 등록하고 "검색" API 사용을 활성화해 발급받습니다.

Source checkout

Source checkout:

git clone https://github.com/gitbosung/open-ALIO-mcp.git open_alio_mcp
cd open_alio_mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e .
copy .env.example .env   # 발급받은 키 입력

.env (키 발급: data.go.kr → "공공기관 정보 조회서비스" 등 활용신청, Decoding 키 사용):

DATA_GO_KR_SERVICE_KEY=발급받은_일반인증키_Decoding값

# (선택) 기관별 뉴스 검색용 — developers.naver.com 앱 등록 후 '검색' API 키 발급
NAVER_CLIENT_ID=
NAVER_CLIENT_SECRET=

# (선택) 법령·행정규칙 조회용 — open.law.go.kr 회원가입 → 'Open API 사용 신청' → OC 발급
# OC는 가입 이메일의 ID 부분 (예: hong@gmail.com → hong)
LAW_API_OC=

Run

open-alio-mcp
python -m open_alio_mcp
uv run open-alio-mcp

Claude Desktop / MCP client package run after publishing. API 키가 필요 없으면 env 블록은 생략해도 됩니다.

{
  "mcpServers": {
    "open-alio": {
      "command": "uvx",
      "args": ["open-alio-mcp"],
      "env": {
        "DATA_GO_KR_SERVICE_KEY": "발급받은_일반인증키_Decoding값",
        "NAVER_CLIENT_ID": "",
        "NAVER_CLIENT_SECRET": "",
        "LAW_API_OC": ""
      }
    }
  }
}

Runtime data is loaded from data/ during source checkout development. Package installs can use OPEN_ALIO_DATA_DIR, OPEN_ALIO_SNAPSHOT_PATH, or the GitHub Release alio_snapshot.db downloaded by ensure_snapshot().

Claude Desktop 설정 파일 위치:

Windows

macOS

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json

~/Library/Application Support/Claude/claude_desktop_config.json

Cursor

프로젝트 .cursor/mcp.json 또는 전역 설정

프로젝트 .cursor/mcp.json 또는 전역 설정

Windsurf

프로젝트 .windsurf/mcp.json

프로젝트 .windsurf/mcp.json

Claude.ai 웹의 원격 Connector URL 방식은 이 저장소에서 아직 제공하지 않습니다. 현재 배포판은 로컬 stdio MCP 서버로 실행됩니다.

데이터를 직접 지정해야 하는 환경에서는 아래 변수를 사용합니다.

$env:OPEN_ALIO_SNAPSHOT_PATH="C:\path\to\alio_snapshot.db"
uvx open-alio-mcp

Troubleshooting:

  • uvx를 찾을 수 없으면 uv 설치 문서에 따라 uv를 설치한 뒤 새 터미널을 여세요.

  • DATA_GO_KR_SERVICE_KEY 오류가 나면 Encoding 키가 아니라 Decoding 일반 인증키를 넣었는지 확인하세요.

  • LAW_API_OC 오류가 나면 open.law.go.kr의 사용 신청 승인 여부와 OC 값을 확인하세요.

  • 스냅샷 다운로드가 실패하면 GitHub Release에서 alio_snapshot.dbalio_snapshot.db.sha256을 직접 내려받아 OPEN_ALIO_SNAPSHOT_PATH로 지정하세요.

Security Notes

  • API 키는 코드·README·테스트 파일에 직접 작성하지 말고 .env 또는 배포 환경변수로만 관리하세요.

  • API 키를 URL query parameter로 전달하지 마세요. 브라우저 기록, 프록시, 서버 로그에 남을 수 있습니다.

  • .env, .env.local, .env.*, 로그 파일은 .gitignore에 포함되어 있으며 커밋하지 않습니다.

  • 외부 API 오류 로그는 serviceKey, OC, NAVER_CLIENT_SECRET 등 민감값을 마스킹합니다.

  • MCP tool 입력값은 공통 보안 래퍼에서 길이·범위·허용값을 검증하고, 긴 응답은 MAX_RESPONSE_CHARSMAX_ITEMS_PER_TOOL 기준으로 제한됩니다.

  • 현재 open-alio-mcp / python -m open_alio_mcp 기본 실행은 stdio MCP입니다. HTTP/SSE로 공개 배포하는 경우에는 별도 reverse proxy 또는 앱 서버에서 rate limit, CORS allowlist, security headers를 반드시 적용하세요.

  • 운영·공개 배포에서 CORS_ORIGIN=*를 사용하지 말고 공식 서비스 도메인만 허용하세요.

  • 사내 내부망 도입 전에는 SSO/인증 연계, 사용자 식별 감사로그, 내부 데이터와 공개 데이터 tool 분리 정책을 확정하세요.

데이터 갱신·스냅샷 빌드

이 저장소는 병합이 끝난 런타임 데이터(data/)와 배포 패키지만 포함합니다. ALIO 공시 엑셀·크롤 수집·파싱·검증·승격으로 data/를 만들어내는 데이터 빌드 파이프라인은 별도 데이터 저장소에서 관리합니다. 새 공시 반영은 파이프라인 저장소에서 data/를 갱신한 뒤, 런타임 부분집합을 이 저장소로 동기화하고 아래로 배포 스냅샷을 빌드·릴리스합니다.

.venv\Scripts\python scripts\build_snapshot.py            # data/ → dist/alio_snapshot.db
.venv\Scripts\python tests\test_smoke.py                  # 오프라인 기능 스모크
.venv\Scripts\python scripts\security_smoke_test.py       # 입력 검증 스모크

빌드한 dist/alio_snapshot.dbdist/alio_snapshot.db.sha256을 GitHub Release에 올리면 uvx open-alio-mcp 사용자가 자동으로 내려받습니다.

법령·지침·경영평가편람

법령·행정규칙은 국가법령정보센터 Open API를 온디맨드로 검색합니다 (로컬 적재 없음). 공공기관 맥락 질의는 alio://related-laws 화이트리스트(공운법·계약사무규칙·경영지침 등)의 공식 명칭으로 검색해 정확도를 높입니다. get_law_text는 기본 목차 모드이며, article='11'처럼 조문을 지정해 본문을 받을 수 있습니다.

지침은 이원화합니다. 「경영에 관한 지침」 등 상시 지침은 law.go.kr 행정규칙으로 조회하고, 연도별 시달 지침(예산운용지침 등)은 파일을 파싱해 data/guidelines/에 적재합니다.

경영평가편람은 HWPX/PDF를 파싱해 data/handbook/에 적재합니다. alio://handbook-index로 보유 연도·part를 확인한 뒤 검색 도구를 사용하세요. 지침·편람의 원본 적재·파싱도 데이터 파이프라인 저장소에서 수행합니다.

Cursor / Claude Desktop 연결

프로젝트 루트에서 pip install -e . 후 콘솔 스크립트 또는 패키지 모듈을 stdio MCP로 실행합니다.

Cursor.cursor/mcp.json 또는 전역 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "open-ALIO-mcp": {
      "command": ".venv/Scripts/python.exe",
      "args": ["-m", "open_alio_mcp"],
      "cwd": "C:/path/to/open_alio_mcp"
    }
  }
}

macOS/Linux는 command.venv/bin/python으로, cwd를 실제 경로로 바꿉니다.

Claude Desktop — 배포 후에는 uvx 한 줄 구성을 권장합니다. 라이브 API 키가 필요하면 위 설치 섹션의 env 예시처럼 MCP 설정에 환경변수를 추가합니다.

{
  "mcpServers": {
    "open-alio": {
      "command": "uvx",
      "args": ["open-alio-mcp"]
    }
  }
}

로컬 체크아웃을 직접 연결할 때는 위 Cursor 예시와 같은 .venv Python 구성을 사용합니다.

연결 확인: AI에게 get_server_status 실행을 요청하거나, "ALIO 지표 카테고리 목록 보여줘"처럼 자연어로 질의합니다.


사용자별 활용법

아래 질문 예시는 AI가 적절한 tool을 자동 조합해 답변합니다.

일반 국민 — 채용·시설·기관 이해

질문 예시

활용 tool

기대 효과

"강남구에서 무료로 빌릴 수 있는 공공기관 회의실 알려줘"

search_facilities

예약 링크·수용인원까지 바로 확인

"이번 주 마감인 채용공고만 마감 빠른 순으로"

search_recruitments

놓치기 쉬운 마감임박 공고 우선 표시

"한전 채용 떴어?"

search_recruitments

'한전' → 한국전력공사 자동 해석

"청년이 신청할 수 있는 공공기관 지원 서비스"

search_public_services

대상·키워드별 국가사업 탐색

"한국토지주택공사는 뭐 하는 기관이야?"

get_institution_profile

설립목적·주요기능 공식 공시 기반 설명

"한전 요즘 무슨 이슈 있어?"

get_institution_news

별칭 확장·중복 제거된 뉴스 목록

공공기관 종사자 — 동종 비교·인력·공시 주기

질문 예시

활용 tool

기대 효과

"우리 기관이랑 비슷한 공기업들 평균보수 비교"

compare_institutions

2~5개 기관 수치 나란히 비교

"우리 기관 정원·현원 몇 명이야?"

get_institution_staff_summary

정원 vs 현원 구분 명확화

"동종 공기업 중 복리후생비 상위 기관은?"

find_institutions_by_criteria

조건 스크리닝으로 벤치마크 후보 추출

"직원 평균보수는 매년 언제 공시돼?"

list_disclosure_items

정기/수시·분기 주기 확인

"우리 기관 부채비율이 동종 대비 어느 수준이야?"

find_institutions_by_criteria + get_institution_metrics

상대 위치 + 추이 동시 파악

유관 부서·공무원 — 정책·국감·법령·평가

질문 예시

활용 tool

기대 효과

"산업부 산하 공기업 전체 정원 5년 추이"

search_institutions + get_institution_metrics

부처 필터 다건 집계

"부채 증가율 상위 공기업과 부채비율 추이"

find_institutions_by_criteria

스크리닝 후 심층 조회

"LH 한눈에 브리핑 (현황·재무·뉴스·채용)"

get_institution_briefing

360° 원샷 종합

"뉴스에서 LH 빚 많다는데 실제 부채비율은?"

cross_check_news_with_metrics

보도 vs 공시 수치 대조

"캠코 최근 이슈를 주제별로 정리"

digest_institution_news

재무/안전/ESG 등 테마별 타임라인

"○○공단 공시 한눈에 요약"

summarize_disclosure (prompt)

고정 양식 공시 요약

"기관 비교 1쪽 정책 브리핑 초안"

policy_brief (prompt)

판단성 결론 없는 브리핑 초안

"공운법상 경영공시 의무 조항 원문"

search_lawsget_law_text

조문 지정 조회로 컨텍스트 절약

"예산운용지침 총인건비 인상률 몇 %?"

search_guidelinesget_guideline_text

연도별 시달 지침 조문 검색

"2026 경영평가 안전관리 지표 배점은?"

get_evaluation_indicator_detail

편람 세부평가내용·배점 조회

"2025→2026 편람 총인건비 관련 변경"

compare_evaluation_handbook_years

연도별 키워드 검색 결과 대조

데이터·연구 — 교차 분석·출처 검증

질문 예시

활용 tool

기대 효과

"한국도로공사 5년 1인당 부채 계산"

get_institution_metrics (finance + staff)

지표 교차 파생 계산

"진행중 채용 NCS 직무별 공고·모집인원 집계"

analyze_recruitments

채용 시장 거시 패턴

"공공기관 채용 수도권 vs 지방 분포"

analyze_recruitments (region)

지역 편중 분석

"이 수치 어디서 나온 거야?"

(모든 tool 응답)

source·as_of_year·caveats 확인

"서버 데이터 적재 상태 확인"

get_server_status

데모·운영 전 점검

신뢰성 설계: 데이터가 없으면 추정하지 않고 결측으로 답하며, 공시 주기 기준으로 공백 사유를 안내합니다.


검증 현황 (Tool verification status)

핵심 도구는 tests/test_smoke.py(오프라인 기능·CI)와 scripts/security_smoke_test.py(입력 검증)로 스모크 테스트를 수행하며, 한국전력공사·LH·국립공원공단 등 대표 기관 시나리오를 포함합니다. 원천 데이터의 파싱·라이브 ALIO 대조 검증은 데이터 파이프라인 저장소에서 수행합니다.

도구 그룹

검증 수준

비고

기관 검색·프로필

자동 스모크 테스트

별칭·부설기관 케이스 포함

경영공시·지표 (시계열·비교·스크리닝)

자동 스모크 테스트

크롤 승격값은 교차검증 후 병합

대국민서비스 (채용·시설·사업)

자동 스모크 테스트

라이브 API — 키 필요, --offline 시 생략

법령·지침

자동 스모크 테스트

법령은 키 설정 시에만 실행

뉴스·통합 분석 (브리핑·교차검증)

수동 시나리오 검증

자동 테스트 보강 예정 — 결과 caveats 확인

경영평가편람

수동 시나리오 검증

자동 테스트 보강 예정 — 원문 대조 권장

도구별 상세 검증표·테스트 계획은 docs/testing.md 참조. fixture 기반 회귀 테스트와 CI 확대는 로드맵에 포함되어 있습니다.

폴더 구조

런타임 패키지 코드는 src/open_alio_mcp/ 아래에 있습니다.

경로

용도

src/open_alio_mcp/server.py

MCP 서버 진입점 (Tools 32 · Prompts 2 · Resources 5)

src/open_alio_mcp/alio_client.py

NKOD OpenAPI 4종 wrapper

src/open_alio_mcp/naver_client.py

네이버 뉴스 API wrapper

src/open_alio_mcp/law_client.py

국가법령정보센터 Open API wrapper

src/open_alio_mcp/guideline_store.py

로컬 지침 조문 검색·조회

src/open_alio_mcp/handbook_store.py

경영평가편람 검색·지표·연도 비교

src/open_alio_mcp/news_insights.py

뉴스 테마 분류·토픽↔지표 매핑

src/open_alio_mcp/metrics_store.py

지표 JSON 조회·스크리닝·인력 요약

src/open_alio_mcp/disclosure_store.py

ALIO 공시항목 카탈로그

src/open_alio_mcp/recruit_store.py

채용 스냅샷·분포 집계

scripts/

스냅샷 빌드(build_snapshot.py) + 스모크 테스트

tests/

오프라인 CI 스모크 테스트 (GitHub Actions에서 자동 실행)

docs/

아키텍처·데이터 출처·테스트·로드맵 문서

examples/

질의 예시·기대 동작

data/

런타임 데이터 — institutions, aliases, metrics/, snapshots/, reference/, guidelines/, handbook/

데이터 수집·빌드 파이프라인(크롤러·파서·빌드 스크립트·원본 rawdata)은 별도 데이터 저장소에서 관리합니다.

데이터 출처·한계

  • 모든 응답에 출처(source)와 유의사항(caveats)이 포함됩니다.

  • 원천: 재정경제부 NKOD OpenAPI(공공데이터포털·ALIO Plus) + ALIO 항목별 공시 엑셀 + ALIO 공시 페이지 크롤링 + 네이버 뉴스 검색 API + 국가법령정보센터 Open API(법제처) + 사용자 투입 지침·경영평가편람 파일.

  • 법령·행정규칙은 현행 기준 조회 결과이며 법률 자문이 아닙니다. 로컬 지침·편람은 파일 추출 텍스트라 표·서식이 손실될 수 있어 인용 시 원문 대조를 권장합니다.

  • 뉴스 결과는 언론 보도이며 기관의 공식 입장·공시 정보가 아닙니다.

  • 공시 수치 기준이며 기관 평가·정책 판단의 근거가 아닙니다.

  • 금액 단위는 카테고리별로 다릅니다(천원/백만원) — 응답 unit 필드 확인.

데이터 카테고리별 출처·갱신주기·갱신 방법은 docs/data_sources.md 참조.

로드맵 (Roadmap)

단계

목표

상태

Phase 1 — 로컬 MCP 프로토타입

ALIO/ALIO Plus 연결, 기관 검색·지표·비교, 출처 표기

완료

Phase 2 — 신뢰 가능한 오픈소스 MCP

테스트 자동화·CI, 데이터 갱신 스크립트, 문서·예시 정비

진행 중

Phase 3 — 공공부문 AI 지식 레이어

국회·나라장터·경영평가 결과 등 확장, 기관 지식카드, 데이터 거버넌스

계획

Phase 4 — 운영 배포

인증, rate limit, 감사로그, 모니터링, 정기 데이터 갱신, 공공기관 보안 검토

계획

상세 로드맵은 docs/roadmap.md 참조.

어려운 도메인 모델링 작업의 대부분은 이미 프로젝트에 구현되어 있으며, 남은 작업은 주로 패키징·테스트·데이터 갱신·배포 통제 같은 운영 보강입니다.

문서 (Documentation)

문서

내용

docs/architecture.md

모듈·데이터 레이어 구조

docs/data_sources.md

데이터 출처·기준일·갱신주기·갱신 절차

docs/testing.md

도구별 검증표·테스트 계획

docs/roadmap.md

단계별 로드맵

SECURITY.md

보안 정책 — 로컬 사용 기준과 공개 배포 전 점검 항목

examples/prompts.md

사용자 유형별 질의 예시 모음

examples/sample_outputs.md

대표 질의의 기대 동작·응답 형식

라이선스 (License)

MIT License

Available Tools

32 tools
analyze_recruitmentsA

[연구·정책용] 진행중 채용공고의 분포를 집계합니다.

dimension: region(지역)·ncs(직무)·hire_type(고용형태)·recruit_type(신입/경력)· education(학력)·org(기관). 차원별 '공고 수'와 '모집인원 합계'를 반환합니다. use_snapshot=True(기본)면 로컬 스냅샷 사용 — 없으면 라이브 전수 수집(API 다수 호출). region·ncs·hire_type·pref로 모집단을 좁힌 뒤 분포를 낼 수 있습니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
dimensionYes
ongoing_onlyNo
regionNo
ncsNo
hire_typeNo
prefNo
top_nNo
use_snapshotNo

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses the snapshot vs. live collection behavior and the associated API calls. It also clarifies that the tool returns aggregated counts and sums. While it does not cover rate limits or auth, the description provides reasonable transparency for a non-destructive tool.

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?

The description is relatively concise and uses line breaks to separate sections (purpose, dimensions, output, snapshot behavior, filtering). It front-loads the core functionality. However, it could be slightly more structured or formatted for easier scanning.

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?

With no output schema, the description explains the return values (counts and sums). It covers the key parameter effects and the snapshot mechanism. However, it does not mention error conditions, pagination behavior for top_n, or what happens if no data exists. Still, it provides sufficient context for basic use.

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?

Despite 0% schema description coverage, the description adds significant meaning by listing the dimension values and explaining the use_snapshot parameter's effect. It also mentions the filtering parameters (region, ncs, hire_type, pref) and the top_n parameter implicitly. This compensates well for the lack of 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 the tool aggregates distributions of ongoing recruitment postings, lists the dimensions (region, ncs, hire_type, etc.), and specifies that it returns 'number of postings' and 'sum of recruitment numbers' per dimension. This distinguishes it from sibling tools like search_recruitments, which focuses on individual postings.

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 indicates it is 'for research/policy use' and explains the behavior of use_snapshot (default true) and the ability to narrow the population with filters. However, it does not explicitly state when not to use this tool or provide direct comparisons with alternatives, though the purpose is clear enough.

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

compare_evaluation_handbook_yearsC

두 연도 편람(예: 2025 수정 vs 2026)에서 동일 키워드 검색 — 변경 추적 보조.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
year_aYes
year_bYes
limitNo

TDQS

C2.4/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It mentions searching and change tracking but does not disclose the output format, whether it returns diff or aggregated results, authentication needs, or any side effects.

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?

The description is a single sentence that is front-loaded and to the point. No wasted words, though additional details could be added without losing conciseness.

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

Completeness1/5

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

Given no output schema and no parameter descriptions, the description is highly incomplete. It fails to provide enough context for an agent to understand the input requirements and expected output, especially for a tool that compares data across years.

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

Parameters1/5

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

The description does not explain any parameter meaning. The input schema has 0% description coverage, and the description only provides the tool's high-level purpose. There is no clarification on 'query', 'year_a', 'year_b', or 'limit'.

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 clearly states it searches for the same keyword across handbooks from two years, with a hint of change tracking. It distinguishes itself from the sibling 'search_evaluation_handbook' which likely handles a single year. However, the purpose could be more explicit about the comparison output.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool vs. alternatives. The sibling tool 'search_evaluation_handbook' is not mentioned, and the description lacks context about usage scenarios beyond 'assist change tracking.'

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

compare_institutionsB

2~5개 기관을 동일 지표로 비교합니다. (설계서 §4-1 ③)

org_codes: search_institutions로 얻은 instCd 목록 (2~5개). item_query로 비교 항목을 좁히면 응답이 가벼워집니다. 예: '부채', '정원', '기본급'.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codesYes
categoryYes
item_queryNo
year_fromNo
year_toNo

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as read-only nature, response format, pagination, or rate limits. Only basic behavior is implied.

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?

Very concise, two sentences plus an example. Information is front-loaded with the purpose.

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

Completeness2/5

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

Given 5 parameters, no output schema, and no annotations, the description is insufficient. It misses explanation for year_from/year_to, category, and output structure. Also lacks guidance on when to use this vs similar tools like get_institution_metrics.

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 0%, so description must add meaning. It explains org_codes (list from search_institutions, 2~5 items) and item_query with examples. However, category, year_from, and year_to are not explained in detail.

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 clearly states it compares 2~5 institutions using the same indicator, with a reference to design document. It distinguishes from siblings implicitly as a comparison tool, but does not explicitly differentiate.

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 explains when to use (comparing 2~5 institutions) and provides a hint to use item_query to lighten response. However, it lacks explicit when-not-to-use or alternative tools.

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

cross_check_news_with_metricsA

뉴스 주장을 공시 지표로 교차검증합니다 — '뉴스에서 빚 많다는데 실제 부채는?'.

topic을 지표 카테고리로 매핑(부채/재무→finance, 정원/인력→staff, 보수→salary, 채용→recruitment, 복지→welfare, 예산→budget 등)해 해당 시계열과, topic 키워드로 필터한 관련 뉴스를 함께 반환합니다. org_code 또는 query로 기관을 지정하세요.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes
org_codeNo
queryNo
news_daysNo
metric_yearsNo
news_limitNo

TDQS

A3.9/5.0
Behavior3/5

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

No annotations provided. Description mentions returning time series and filtered news, but does not disclose whether tool is read-only, required permissions, rate limits, or error handling. Adequate but incomplete.

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?

Description is concise (4 sentences) with front-loaded purpose and example. Every sentence adds value; no wasted words.

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?

Tool has 6 parameters and no output schema. Description explains main function and parameter mapping but does not describe output structure, error handling, or edge cases. Adequate for basic use but leaves gaps.

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 0%. Description adds context for topic (mapping to categories) and institution specification (org_code or query), but does not explain parameter formats, constraints, or possible values for other params like news_days, metric_years, news_limit.

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?

Description clearly states the tool cross-checks news claims with public disclosure indicators, gives an example, explains topic-to-metric mapping, and specifies output (time series + filtered news). Distinct from siblings like get_institution_news and get_institution_metrics.

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?

Implies usage for verifying news with data, provides context with example and mapping. Lacks explicit when-not-to-use or alternative tool references, but context is clear enough from sibling list.

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

digest_institution_newsA

기관 뉴스를 테마별로 자동 분류·집계합니다 — 보도량 많은 기관의 이슈를 구조화.

평면적인 기사 목록 대신 테마(재무·실적/채용·인사/안전·재해/감사·비위/사업·협약/ 정책·국회/사회공헌·ESG/기타)별 건수와 대표 헤드라인, 날짜별 타임라인을 반환합니다. "캠코 한 달 이슈를 정리해줘"처럼 분포 파악에 사용하세요.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeNo
queryNo
daysNo
max_fetchNo
per_themeNo

TDQS

A3.7/5.0
Behavior4/5

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

Despite no annotations, the description reveals key behaviors: automatic classification into 8 themes, output includes counts, representative headlines, and a date timeline. It also implies a limitation (works best for institutions with high coverage via '보도량 많은 기관'). No destructive actions are mentioned, fitting a read-only tool.

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?

The description is well-structured: first sentence states the main action, second details the output, and third provides a use case. It is front-loaded with the core purpose. While slightly verbose with the listed themes, every part earns its place. Could be slightly more concise but overall effective.

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?

Given no output schema, the description explains return structure (theme counts, headlines, timeline) sufficiently. It also provides a use case. However, it lacks any explanation of the 5 input parameters, leaving a gap in completeness. The tool has moderate complexity, and the description misses parameter documentation.

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

Parameters1/5

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

The input schema has 5 parameters with 0% description coverage—no parameter descriptions are provided in the schema or the main description. The description only indirectly references 'days' via an example ('한 달'), but it does not explain org_code, query, max_fetch, or per_theme. With this low coverage, the description fails to add meaning to the schema.

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 the tool's function: it automatically classifies and aggregates institution news by theme, returning counts and timelines instead of a flat list. The verb 'digest' and resource 'institution news' are specific, and the description distinguishes it from a flat article list, implying differentiation from sibling tool get_institution_news.

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 contrasts with 'flat article list' and gives an example query ('summarize KAMCO's issues for the past month'), indicating when to use the tool for distribution insights. However, it does not explicitly name alternatives or when not to use it, though the contrast with a sibling tool provides implicit guidance.

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

find_institutions_by_criteriaA

조건 기반 기관 스크리닝 — 지표 상·하위, 증감률 상위 기관을 찾습니다. (설계서 §4-1 ④)

mode: top_n(최신값 상위)·bottom_n(하위)·growth_rate(기간 증감률 % 상위). item_query는 정렬 기준 항목 (예: category='staff', item_query='정원' 또는 '현원-전일제'). staff에서 item_query='정원'은 정원 기준, 실제 재직 인원 비교는 '현원-전일제' 사용. org_type·ministry로 대상 기관을 좁힐 수 있습니다 (예: org_type='공기업'). exclude_subsidiaries=True면 부설기관 공시 단위를 제외합니다. use_classification_org_type=True이고 org_type을 지정하면 부설기관은 모기관 유형으로 필터합니다. 결과는 단순 정렬이며 기관 평가·판단의 근거가 아닙니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryYes
item_queryYes
modeNotop_n
year_fromNo
year_toNo
org_typeNo
ministryNo
nNo
exclude_subsidiariesNo
use_classification_org_typeNo

TDQS

A4/5.0
Behavior4/5

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

In the absence of annotations, the description effectively discloses key behaviors: mode-dependent sorting, subsidiary handling (exclude_subsidiaries, use_classification_org_type), and a disclaimer that results are a simple sort not a basis for evaluation. However, it does not cover error handling or data freshness.

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?

The description is front-loaded with the purpose, followed by parameter explanations in a structured, bullet-like format. It is relatively efficient but slightly verbose with multiple sentences; overall well-organized.

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?

Given 10 parameters, no annotations, and no output schema, the description covers many aspects but has gaps: missing explanation of year_from/year_to behavior, no description of output format beyond 'simple sort', and no mention of error handling. Could be more complete.

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?

With 0% schema description coverage, the description compensates by explaining mode options, item_query examples, and filter parameters (org_type, ministry, exclude_subsidiaries, use_classification_org_type). It adds context for item_query values. Missing explanations for year_from, year_to, and n are partially mitigated by defaults.

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 the tool's purpose as condition-based institution screening for top/bottom indicators or growth rates. It specifies three modes (top_n, bottom_n, growth_rate) and distinguishes from sibling tools like search_institutions and get_institution_metrics which serve different purposes.

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?

The description provides details on parameter usage (mode, item_query, filters) but does not explicitly state when to use this tool versus alternatives like search_institutions. It implies usage for ranked screening but lacks direct guidance on exclusions or when not to use.

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

get_admin_rule_textA

행정규칙(훈령·예규·고시·지침)의 본문을 조회합니다 — search_admin_rules 결과의 'id' 필요.

ParametersJSON Schema
NameRequiredDescriptionDefault
rule_idYes

TDQS

A3.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states that it retrieves text (a read operation) but does not disclose any potential side effects, authentication requirements, rate limits, or what the response format is. Given no output schema, this is a significant gap.

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 extremely concise: one sentence that efficiently conveys the purpose, the resource, and the prerequisite. Every part is necessary and no words are wasted.

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?

Given low complexity (1 parameter, no output schema), the description covers the essential purpose and input. However, it lacks information about the return value (e.g., what format the text is returned in) and error handling for invalid IDs, making it somewhat incomplete.

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?

The single parameter 'rule_id' has 0% schema description coverage, so the description must compensate. It adds meaning by specifying that rule_id is the 'id' from search_admin_rules results, which is valuable context beyond just the parameter name.

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 the action (조회/retrieves) and resource (행정규칙 본문/admin rules text). It explicitly distinguishes from sibling tools like get_law_text and get_guideline_text by specifying the type of legal document. The prerequisite dependency on search_admin_rules is also clearly indicated.

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 explicitly states that the tool requires the 'id' from search_admin_rules results, providing clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

get_evaluation_indicator_detailC

평가지표명으로 세부평가내용·배점·지표정의를 조회합니다.

예: '안전 및 재난관리', '총인건비관리', '윤리경영'.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
yearNo

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description should disclose behavioral traits. It does not state it's a read-only operation, what happens on invalid input, or whether results are paginated. Only the basic query operation is hinted.

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 extremely concise—two sentences that immediately convey the tool's function with examples. No redundant text.

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

Completeness2/5

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

Given no output schema and low schema coverage, the description should provide more context such as return format, error handling, and the role of the year parameter. It is insufficient for an agent to reliably use this tool.

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

Parameters2/5

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

Schema description coverage is 0%. The description explains the query parameter (indicator name) with examples, but the year parameter is completely ignored, leaving its purpose and usage unclear.

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 clearly states it queries detailed evaluation content, scoring, and indicator definitions by indicator name. It gives concrete examples, making purpose evident. However, it does not explicitly differentiate from sibling tools like list_evaluation_indicators.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions.

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

get_facility_profileA

시설 일련번호(sn/fcltSn)로 상세정보와 첨부파일 메타를 조회합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
facility_snYes

TDQS

A3.7/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It states the tool retrieves data (read-only behavior is implied) but does not disclose any other behavioral traits like authentication requirements, rate limits, or side effects.

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 a single sentence that front-loads the purpose with a clear verb and resource. Every word is necessary, and no extraneous information is present.

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?

Given the tool's simplicity (1 parameter, no output schema, no nested objects), the description adequately covers the core functionality. However, it does not mention return format or any pagination, which is acceptable for a simple get-by-ID tool.

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?

The parameter 'facility_sn' has no description in the input schema (0% coverage). The description adds value by clarifying that it is a facility serial number (시설 일련번호) with alternative names sn/fcltSn, which helps the agent understand the parameter beyond 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 description clearly states the verb 'retrieve', the input (facility serial number), and the output (detailed information and attachment metadata). It distinguishes the tool from siblings like 'search_facilities' by specifying retrieval by a single ID, but does not explicitly contrast with other 'get_*' tools.

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?

The description implies usage when a facility serial number is known, but provides no explicit when-to-use or when-not-to-use guidance compared to sibling tools such as 'search_facilities' for searching or 'get_institution_profile' for institutions.

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

get_guideline_textA

적재된 지침의 조문을 조회합니다 — search_guidelines 결과의 'doc_id' 필요.

article 지정 시(예: '5', '5의2') 해당 조문 전문, 미지정 시 목차(조문 번호·제목)를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
doc_idYes
articleNo

TDQS

A4.2/5.0
Behavior3/5

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

No annotations provided, so description must cover behavioral traits. It mentions what is returned (provision text or table of contents), but does not explicitly confirm read-only nature, rate limits, or auth requirements. Basic behavior is covered.

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?

Two sentences: first states purpose and prerequisite, second explains conditional behavior. No unnecessary words, efficiently structured.

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?

No output schema, but description clarifies return content. Could mention that it is read-only, but overall adequate given the tool's simplicity and sibling context.

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 has 0% description coverage, but description adds meaning: doc_id source explained, article example given. Adds value beyond schema which only provides type and title.

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?

Description specifies retrieval of guideline provisions, distinguishing from siblings by requiring doc_id from search_guidelines and explaining output based on article parameter (full text vs. table of contents).

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?

Explicitly states prerequisite: doc_id from search_guidelines results. Explains behavior with and without article. Does not list when not to use or alternatives, but the sibling context makes it clear.

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

get_institution_branchesC

기관코드로 지점 목록을 조회합니다 (/brnch).

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeYes
limitNo

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral disclosure. It only says '조회합니다' (queries), implying a read operation, but does not state if it is read-only, whether it has side effects, or any other behavioral traits like rate limits or data freshness.

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 description is very concise—one sentence containing the main action and endpoint. However, it is too terse and misses critical information that could be included without bloating. Conciseness should not come at the expense of completeness.

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

Completeness2/5

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

Given the tool has two parameters, no output schema, and no annotations, the description is inadequate. It does not explain what constitutes a 'branch', the structure of the response, or any edge cases. The agent is left with many unknowns.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain any parameter. It does not clarify what 'org_code' represents or that 'limit' controls the number of branches returned. The schema provides minimal info (default and type), but the description adds no value.

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 clearly states the tool queries a list of branches by institution code, referencing the endpoint '/brnch'. The tool name matches, and it distinguishes from sibling tools like 'get_institution_profile' or 'get_institution_metrics'. However, the description is very brief and lacks any nuance.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as 'get_institution_profile' or 'find_institutions_by_criteria'. The description does not mention any prerequisites, exclusions, or context for use.

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

get_institution_briefingA

기관 360° 원샷 브리핑 — 프로필·핵심지표 추세·최근 뉴스·진행중 채용을 한 번에 종합합니다.

org_code 또는 query(기관명·별칭, 예 '한전')로 기관을 지정합니다. 프로필(설립목적·기관장·부처) + 정원/보수/부채비율 추세 + 최근 N일 뉴스 헤드라인 + 진행중 채용 건수를 묶어 반환합니다. "○○기관 한눈에 브리핑해줘"에 사용하세요.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeNo
queryNo
news_daysNo
metric_yearsNo
news_countNo

TDQS

A3.8/5.0
Behavior3/5

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

The description lists the components returned but does not explicitly state read-only behavior, rate limits, or any side effects. Since annotations are absent, the description should cover safety but falls short.

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?

Description is concise with a clear purpose statement followed by a structured list of returned components. No fluff, but could explicitly parameter mapping.

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?

The description lists return categories and identifies the institution via org_code or query, but fails to explain parameter defaults, behavior when both identifiers are missing, or the format of metrics trends. With no output schema and no annotations, more detail is needed.

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?

The description explains the use of org_code and query, and hints at news recency and count, but does not explicitly map to all five parameters (e.g., metric_years is omitted). With 0% schema coverage, the description should document all parameters.

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 aggregates profile, key metric trends, recent news, and recruitment into a one-shot briefing, and distinguishes it from sibling tools that provide individual pieces of information. Example usage is provided.

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 implies usage for a comprehensive overview, but does not explicitly contrast with siblings or provide when-not-to-use scenarios.

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

get_institution_metricsA

기관의 공시지표 시계열을 조회합니다. (설계서 §4-1 ②)

category: staff(임직원수)·salary(평균보수)·executive_pay(임원연봉)·recruitment(신규채용)· budget(수입지출)·welfare(복리후생비)·work_life(일가정양립)·welfare_etc·tax(법인세)· head_expense(기관장업무추진비)·finance(재무 — 결산은 전 기관, 반기 항목은 공기업 계열 한정). item_query로 항목을 좁힐 수 있습니다. 예: '정원', '현원', '부채', '기본급'. staff(인력) 조회 시: '임직원 총계'·'정원-계'는 정원, '현원-전일제'가 실제 재직 인원. 인력현황 요약은 get_institution_staff_summary 권장.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeYes
categoryYes
item_queryNo
year_fromNo
year_toNo

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool returns time series data, lists available categories, and describes item_query behavior with examples. It does not mention destructive actions, authentication, or rate limits, but since it is a read-only query tool, the description sufficiently conveys the non-destructive nature.

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?

The description is well-structured, front-loading the main purpose and using bullet points for categories. It is informative but slightly lengthy due to detailed examples and Korean text. Every sentence adds value, though some redundancy could be trimmed.

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?

Given the tool has 5 parameters and no output schema, the description covers the primary use case, explains categories and item_query, and provides an alternative for staff summary. It does not describe the output format or pagination, but for a metrics query tool, the essential context is present.

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 coverage is 0%, so the description must add meaning. It explains category values and item_query usage with concrete examples, but does not fully describe org_code, year_from, or year_to. The defaults for year_from and year_to (0) are not explained, leaving ambiguity about their meaning. The description partially compensates for the lack of schema descriptions but has gaps.

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 the main purpose: '기관의 공시지표 시계열을 조회합니다.' (query institution disclosure indicator time series). It lists specific categories and explains how item_query works, distinguishing it from the sibling tool get_institution_staff_summary by recommending the latter for a summary of personnel status.

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 provides explicit guidance on when to use this tool (time series of disclosure metrics) and recommends an alternative (get_institution_staff_summary) for staff summaries. It explains categories and item_query usage, but does not explicitly state when not to use it relative to other siblings like list_metric_categories or list_metric_items.

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

get_institution_newsA

공공기관 관련 최근 뉴스를 네이버 뉴스 API로 검색합니다.

org_code(instCd)를 주면 공식 기관명 + 안전한 별칭(한전·KEPCO 등)으로 OR 검색합니다. org_code 없이 query만 주면 별칭을 공식명으로 치환해 검색합니다 (예: '심평원'). days>0이면 최근 N일 기사만 반환 (네이버 API는 기간 파라미터가 없어 발행일 기준 필터). sort: 'date'(최신순, 기본)·'sim'(정확도순). max_fetch: 기간 필터 전 수집할 최대 기사 수(100~1000). 보도량 많은 기관의 '한 달 전체' 커버리지를 위해 페이지네이션으로 모읍니다. 클수록 호출 수 증가.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeNo
queryNo
daysNo
sortNodate
limitNo
max_fetchNo

TDQS

A4.1/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden. It fully discloses key behavioral traits: OR search with aliases, post-fetch date filtering due to API limitations (Naver API lacks date parameter), sorting options, and pagination behavior for max_fetch. Limitations are transparently 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?

The description is front-loaded with the main purpose in the first sentence, followed by parameter details in a structured, bullet-like format. Each sentence adds value, though some minor redundancy (e.g., repeating '네이버 API는 기간 파라미터가 없어' could be slightly more concise). Overall well-organized.

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?

Given 6 parameters, no annotations, and no output schema, the description provides sufficient context for behavior and limitations. It covers parameter interactions and API dependencies. However, it does not describe the structure of the returned data (e.g., fields like title, url, date), which would be helpful for an agent. Missing this detail reduces completeness slightly.

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 0%, so description must compensate. It explains 5 of 6 parameters (org_code, query, days, sort, max_fetch) in detail, describing their roles and special behaviors (e.g., alias substitution, date filter mechanism). The 'limit' parameter is not mentioned, but its purpose is standard. Overall, adds significant meaning beyond the schema.

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 the action ('검색합니다' - searches) and the resource ('공공기관 관련 최근 뉴스' - recent news about public institutions). It distinguishes itself from sibling tools like 'digest_institution_news' by focusing on raw news retrieval, with specific details on how it handles org_code and query for institution-specific searches.

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

Usage Guidelines2/5

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

The description provides parameter-level guidance (e.g., when to use org_code vs query alone) but does not address when to choose this tool over alternatives like 'digest_institution_news' or 'cross_check_news_with_metrics'. No explicit 'when not to use' or comparison to siblings is given.

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

get_institution_profileA

기관코드(instCd)로 기본 프로필을 조회합니다.

include_detail=True면 일반현황 상세(설립목적·주요기능·경영목표·기관장 등)를 포함합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeYes
include_detailNo

TDQS

A3.6/5.0
Behavior3/5

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

No annotations provided, so the description carries the full burden. It explains the optional detail inclusion but omits behavioral traits like idempotency or side effects. For a read operation, this is adequate but not exceptional.

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?

Two concise sentences, front-loaded with the main action. Every sentence adds value with no redundant information.

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 simple read tool with two parameters, the description covers the core function and optional behavior. The lack of output schema is mitigated by describing what the profile includes (basic info and optional details). Mostly complete.

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?

With 0% schema coverage, the description adds meaning by describing the include_detail parameter's effect. However, the org_code parameter is described using 'instCd' rather than the schema name, which may confuse the agent.

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 clearly states that the tool retrieves a basic profile by institution code, distinguishing it from siblings like get_institution_metrics or get_institution_news. However, it uses 'instCd' for the parameter while the schema uses 'org_code', causing minor ambiguity.

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?

The description implies usage (retrieve profile) but does not explicitly state when to use this tool over siblings or any prerequisites. The use case is implied by the name and description content.

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

get_institution_staff_summaryB

기관 인력현황 요약 — 정원(authorized) vs 현원(actual)을 구분해 반환합니다.

'○○기관 인력 몇 명?'·'정원 현원' 질의에 사용. 임직원 총계(A+B+C)는 정원이므로 headcount.estimated_total(정규 전일제+기간제)을 실제 재직 규모로 참고하세요.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeNo
queryNo
year_fromNo
year_toNo

TDQS

B3.4/5.0
Behavior3/5

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

No annotations present. Description discloses return of authorized vs actual categories and a specific field note, but lacks details on authentication, rate limits, or behavior with missing parameters. Some transparency but gaps remain.

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?

Two sentences with clear structure, front-loaded with key action. Second sentence adds value but could be more structured. No waste.

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

Completeness2/5

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

With 4 parameters and no output schema or annotations, description lacks parameter explanations, return format, and prerequisites. Usage examples help but incomplete for effective use.

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

Parameters1/5

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

Schema has 0% description coverage for 4 parameters. Description does not explain org_code, query, year_from, or year_to. No parameter semantics added beyond schema titles.

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?

Description clearly states it summarizes institution staff by distinguishing authorized (정원) vs actual (현원) and gives query examples, differentiating it from sibling tools like get_institution_metrics or get_institution_profile.

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?

Describes when to use (queries about staff count) and provides guidance on interpreting headcount.estimated_total. No explicit exclusion of alternatives, but context is clear.

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

get_law_textA

법령의 조문을 조회합니다 — search_laws 결과의 'mst'(법령일련번호) 필요.

article을 지정하면(예: '4', '4의2') 해당 조문 전문만 반환합니다. article 없이 호출하면 기본정보+조문 목차(번호·제목)만 반환하므로, 먼저 목차에서 필요한 조문을 찾아 article로 재조회하세요. 전 조문 전문이 꼭 필요할 때만 full_text=True를 쓰세요(대형 법령은 매우 깁니다).

ParametersJSON Schema
NameRequiredDescriptionDefault
mstYes
articleNo
full_textNo

TDQS

A4.3/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It describes the behavioral difference between calling with article (returns full text) and without (returns table of contents), and warns about full_text length. However, it does not specify response format, error handling, or what happens with invalid mst/article values.

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?

The description is relatively concise, with two paragraphs that front-load the purpose and prerequisite. Every sentence adds value, though the second paragraph is dense with multi-line instructions. Minor improvement could be breaking into bullet points.

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?

Given the absence of an output schema and no annotation, the description lacks details on the return structure (e.g., fields, format). It adequately covers usage patterns and parameter meanings, but the agent may need to infer response format or error behavior, leaving some incompleteness.

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%, but the description compensates by explaining mst (law serial number from search_laws), article (specific article number or empty for table of contents), and full_text (set true only if all articles needed). It adds meaning beyond the parameter names and defaults.

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 the tool retrieves law articles (법령의 조문) and explicitly links to search_laws via the mst parameter. It distinguishes itself from sibling tools like search_laws, get_admin_rule_text, and get_guideline_text by specifying its unique role in fetching article-level content.

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?

The description provides explicit step-by-step usage: first use search_laws to get mst, then call get_law_text without article to get the table of contents, then re-query with a specific article. It advises against using full_text=True unnecessarily, offering clear when-to and when-not-to guidance.

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

get_recruitment_profileA

채용공시 일련번호(sn/recrutPblntSn)로 상세·전형단계·첨부파일을 조회합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
recruitment_snYes

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It implies a read-only operation but does not explicitly state behavioral traits such as required permissions, rate limits, or side effects. For a simple lookup tool, this is adequate but not fully transparent.

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 a single, well-structured sentence that conveys the core functionality without unnecessary words. It is front-loaded with the key information.

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?

Given that this is a simple tool with one parameter and no output schema or annotations, the description covers the main purpose. However, it could mention that a valid serial number is required or hint at the return structure for completeness.

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 coverage is 0%, so the description must compensate. It explains that the parameter is a serial number (sn/recrutPblntSn) and that it is used to look up the recruitment profile, adding essential context beyond the schema.

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 the action (조회/retrieve) and the resource (채용공시/recruitment announcement), and specifies that it retrieves details, stages, and attachments. It distinguishes from sibling tools like search_recruitments which is for searching.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Sibling tools include search_recruitments for searching and other get tools, but the description does not provide any context for selection.

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

get_server_statusA

서버 상태 점검 — API 키·로컬 데이터 적재 현황. 데모 전 점검용.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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

Discloses what it checks (API key, local data loading) but no annotations exist. For a read-only status check, this is adequate but could mention it's non-destructive.

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?

Extremely concise, front-loaded with action, and includes context in second part. Every word earns its place.

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?

Sufficient for a simple status check with no parameters. Could mention expected output format but not critical given low complexity.

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?

No parameters, so schema coverage is 100%. Description adds no param info, baseline 4 applies.

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?

Clearly states it checks server status covering API key and local data loading, specifically for pre-demo use. Distinct from sibling tools that focus on data retrieval.

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?

Specifies usage context ('pre-demo check') but doesn't explicitly mention when not to use or alternatives.

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

list_disclosure_itemsA

ALIO 경영공시 50개 항목 카탈로그를 조회합니다 (정기/수시·공시주기·분류).

출처: alio.go.kr 경영공시 제도(공운법 제12조). "재무 공시는 언제 올라와?", "수시공시 항목만", "2분기 정기공시 목록" 같은 질문에 사용하세요.

disclosure_type: '정기' 또는 '수시'. schedule: 공시시기 부분일치 (예: '1분기', '매분기'). metric_category: 특정 지표(staff·finance 등)에 매핑된 공시항목만. only_with_metric=True면 본 MCP 지표로 조회 가능한 항목만 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
groupNo
disclosure_typeNo
scheduleNo
metric_categoryNo
only_with_metricNo
limitNo

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses the data source and that only_with_metric filters items, but does not mention read-only nature, response format, or pagination. Adequate but not comprehensive.

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?

The description is concise with a clear header, example queries, and parameter explanations. Every sentence adds value, though some parameter details could be more directly aligned.

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?

Given the 7 parameters and no output schema, the description covers the core functionality well. It provides source context and parameter semantics for the key filters, making it actionable for an AI agent.

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 coverage is 0%, so the description must compensate. It describes disclosure_type, schedule, metric_category, and only_with_metric with usage details, but omits query, group, and limit. Partial coverage.

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 ('조회합니다' = query) and resource ('경영공시 50개 항목 카탈로그'), clearly distinguishing it from sibling tools that focus on different aspects like institutions or metrics.

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?

Provides explicit example queries (e.g., '재무 공시는 언제 올라와?', '수시공시 항목만') that illustrate when to use this tool, though it does not explicitly state when not to use or mention alternatives.

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

list_evaluation_indicatorsA

유형별 평가지표·배점(계·비계량·계량) 표를 조회합니다.

org_class: '공기업'·'준정부기관' 등. org_subtype: 'SOC'·'에너지'·'기금관리형' 등. list_evaluation_org_types로 유형 목록을 먼저 확인할 수 있습니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_classNo
org_subtypeNo
yearNo

TDQS

A3.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as what happens with default parameter values, data freshness, or any limitations. Only mentions that it retrieves a table.

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?

The description is short and front-loaded with the purpose. It uses a line-break format for parameter examples, which aids readability. However, the structure could be more formalized.

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?

Given no output schema, no annotations, and three parameters, the description explains the main purpose and two parameters but omits behavior when parameters are empty, year ranges, and return format. It is moderately complete but has notable gaps.

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 coverage is 0%, and the description explains org_class and org_subtype with examples and a reference to the sibling tool. It does not explain the year parameter or provide value ranges, partially compensating 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 the verb '조회합니다' (retrieves) and resource '유형별 평가지표·배점 표' (evaluation indicators/scores table by type). It distinguishes from siblings such as list_evaluation_org_types and get_evaluation_indicator_detail.

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 suggests using list_evaluation_org_types to check types first, providing implicit usage guidance. However, it lacks explicit when-to-use vs. alternatives or when-not-to-use conditions.

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

list_evaluation_org_typesC

편람에 정의된 기관 유형(공기업 SOC·에너지, 준정부 기금관리형 등) 목록.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearNo

TDQS

C2.2/5.0
Behavior1/5

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

No annotations are provided, and the description fails to disclose behavioral traits such as data source details, output format, or any side effects. The tool's behavior is opaque.

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 description is very short and front-loaded, but it sacrifices completeness. While there is no waste, it lacks essential details about parameters and usage.

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

Completeness1/5

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

Given the tool's simplicity (1 param, no output schema, no annotations), the description is severely incomplete. It does not explain the year parameter, output format, or any constraints, leaving an agent underinformed.

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

Parameters1/5

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

The single parameter 'year' has no description in the schema (0% coverage), and the description does not mention or clarify its purpose. No value is added beyond the schema's minimal type information.

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 clearly states the tool lists institution types from a handbook, with examples. It identifies the action and resource, though lacks explicit differentiation from sibling tools, which are sufficiently distinct.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description only states what it does without providing context or exclusions.

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

list_metric_categoriesA

공시지표 카테고리 목록을 조회합니다 (staff·salary·finance·welfare 등 11종).

get_institution_metrics / compare_institutions의 category 파라미터로 사용합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are provided, but the description implies a read-only list operation. It does not explicitly state non-destructive behavior or return format, but for a zero-parameter list tool, the description adequately conveys functionality.

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 two sentences, concise and front-loaded. Every sentence provides essential information without redundancy.

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?

Given the simplicity (no parameters, no output schema), the description is largely complete. It could mention the output format (e.g., list of strings), but the usage context compensates.

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?

The tool has no parameters, and the input schema coverage is 100%. The description adds value by explaining that the output serves as category values for other tools, which is useful semantic context beyond the schema.

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 explicitly states the tool lists disclosure metric categories, provides examples (staff, salary, finance, welfare, 11 types), and distinguishes itself by noting it provides category parameters for sibling tools get_institution_metrics and compare_institutions.

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 clearly indicates the tool's output is used as the category parameter for two sibling tools, giving direct context for when to use it. It does not explicitly mention when not to use it, but the use case is straightforward and well-defined.

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

list_metric_itemsA

카테고리 내 지표 항목명을 조회합니다.

예: category='staff', item_query='정원' → 정원 관련 항목명 목록. org_code를 주면 해당 기관이 보유한 항목만 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryYes
item_queryNo
org_codeNo

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description fully bears the burden. It discloses that the tool returns item names and filters by org_code if given. However, it does not mention read-only nature, side effects, or other behavioral traits. Behavior is adequately described for a simple query tool.

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 three sentences: the first states the core purpose, the second provides a concrete example, and the third explains an optional parameter. It is front-loaded and efficient with no wasted words.

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?

Given the simple tool with 3 parameters and no output schema, the description covers the core functionality, explains all parameters, and gives an example. It does not specify return format, but that is acceptable given the lack of output schema. It is nearly complete for the tool's complexity.

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 0%, so the description must compensate. It explains 'category' with an example, 'item_query' as a search term, and 'org_code' as a filter for organization-specific items. This adds significant meaning beyond the bare schema, though it could specify the format of item_query (e.g., substring match).

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 the tool queries metric item names within a category, with an explicit example. It distinguishes from sibling tools like 'list_metric_categories' and 'get_institution_metrics' by focusing on items within a category.

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?

The description provides an example and explains the effect of org_code, implying usage context. However, it does not explicitly state when to use this tool versus alternatives like 'list_metric_categories' or 'get_institution_metrics', nor are there any when-not-to-use caveats.

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

search_admin_rulesA

행정규칙(훈령·예규·고시·지침)을 키워드로 검색합니다 — 국가법령정보센터.

「공기업·준정부기관의 경영에 관한 지침」 등 기재부 공공기관 지침류는 행정규칙으로 등재돼 있습니다(리소스 alio://related-laws의 admin_rules 참조). 여기서 0건이면 연도별 시달 지침(예산운용지침 등)일 수 있으니 search_guidelines(로컬 지침)를 확인하세요. 결과의 'id'를 get_admin_rule_text에 넘기면 본문을 조회합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
pageNo
displayNo
scopeNo

TDQS

A4.1/5.0
Behavior4/5

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

No annotations provided, so the description carries full burden. It explains what the tool searches, mentions edge cases (zero results may indicate annual guidelines), and references a resource. It implies read-only behavior but does not explicitly state it or mention auth/rate limits. Still, it provides adequate context for a search tool.

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?

The description is informative and front-loads the main purpose. Each sentence adds value, covering purpose, context, alternatives, and follow-up. It is slightly verbose but well-structured.

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?

No output schema exists, so the description should detail return values. It mentions results have an 'id' field and hints at the resource for admin rules, but lacks full parameter documentation and field details. Adequate but with gaps.

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

Parameters2/5

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

Schema description coverage is 0%, so description must compensate. It only implicitly clarifies 'query' as the search keyword. The other parameters (page, display, scope) are not explained, leaving ambiguity about their function and valid values.

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 the tool searches administrative rules by keyword, identifies the source (National Law Information Center), and distinguishes it from sibling tools like search_guidelines. It uses specific verbs and provides examples, making the purpose unambiguous.

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?

Provides explicit guidance on when to use this tool (for admin rules) and when to use an alternative (search_guidelines if zero results). Also instructs to pass the 'id' to get_admin_rule_text for full text, covering follow-up actions.

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

search_evaluation_handbookA

경영평가편람 본문을 키워드로 검색합니다.

예: '중대재해', '총인건비', '안전관리등급', '혁신가점'. part: '경영실적'·'기관장_경영계약'·'상임감사'·'기관별_별첨' 등으로 범위 축소. year: 2025·2026 등 — 미지정 시 적재된 모든 연도 검색.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
yearNo
partNo
limitNo

TDQS

A3.7/5.0
Behavior2/5

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

No annotations provided; description lacks disclosure of behavioral traits such as read-only nature, side effects, rate limits, or pagination behavior. Only describes the search function itself.

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?

Very concise, front-loaded with main purpose, uses examples and parameter details efficiently with no wasted sentences.

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?

Given 4 parameters and no output schema, description covers usage basics but omits return value format, pagination, or ordering, leaving some gaps for a search tool.

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 coverage is 0%, so description adds meaning for query, year, and part with examples. However, limit parameter is not explained beyond default value, and coverage is incomplete.

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?

Description clearly states it searches the evaluation handbook body by keyword, with examples and filtering options. Distinct from sibling search tools targeting different resources (laws, guidelines, etc.).

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?

Examples and parameter usage imply when to use (searching evaluation handbook) and how to narrow results with part/year, but no explicit comparison or when-not-to-use guidance against sibling search tools.

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

search_facilitiesA

공공기관이 개방·관리하는 시설을 검색합니다. org_code는 search_institutions 결과의 org_code(instCd)입니다.

query는 시설명·기관명·이용방법·주소를 통합 검색합니다 (예: '회의', '네이버 예약'). reservable_only=True면 예약 가능(rsvtPsbltyYn=Y) 시설만 반환합니다. 결과의 has_more=True면 page를 올려 다음 페이지를 조회하세요.

ParametersJSON Schema
NameRequiredDescriptionDefault
org_codeNo
regionNo
districtNo
facility_type_codeNo
free_onlyNo
reservable_onlyNo
queryNo
pageNo
limitNo

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden. It discloses the search behavior (unified query across fields), filtering by reservable_only, and pagination response field (has_more). These details add transparency beyond the parameter names, though it does not mention response format or error handling.

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 concise, using bullet points effectively. It front-loads the purpose and provides essential details in a few sentences without unnecessary fluff. Every sentence contributes meaning, making it easy to parse quickly.

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

Completeness2/5

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

Given 9 parameters, no output schema, and no annotations, the description is incomplete. It explains only a subset of filtering options (e.g., missing free_only, facility_type_code, region, district) and does not describe the return structure beyond has_more. The agent lacks critical details to fully leverage the tool's filtering capabilities.

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?

The description covers semantics for 4 out of 9 parameters (org_code, query, reservable_only, page implicitly). Parameters like region, district, facility_type_code, free_only, and limit are not explained. Since schema description coverage is 0%, the description adds value but leaves significant gaps for half the parameters.

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 the tool searches facilities managed by public institutions, specifies the use of org_code from search_institutions, and explains the query field's unified search across facility name, institution name, usage method, and address. It effectively distinguishes from sibling tools like search_institutions (institutions) and get_facility_profile (single facility).

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 provides explicit context by explaining that org_code comes from search_institutions, how filtering with reservable_only works, and pagination instructions via 'has_more'. However, it lacks explicit guidance on when not to use this tool versus alternatives like get_facility_profile for specific facilities.

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

search_guidelinesA

로컬에 적재된 지침(예산운용지침 등 law.go.kr 미등재 시달 지침)을 조문 단위로 검색합니다.

공백으로 구분한 여러 키워드는 AND 조건입니다 (예: '총인건비 인상률'). 연도별 지침은 year로 구분하세요. 적재 목록은 리소스 alio://guideline-index 참조. 상시 지침(경영지침·혁신지침 등)은 search_admin_rules(law.go.kr)가 우선입니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
yearNo
issuerNo
limitNo

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses that the tool searches local data, operates at clause level, supports AND queries, and references an external resource for the list of loaded items. It does not mention authentication or rate limits, but these are generally expected for a search tool.

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 concise with multiple sentences, each serving a purpose: scope, keyword behavior, year usage, reference resource, and sibling tool prioritization. No unnecessary information, and the core purpose is front-loaded.

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 search tool with 4 parameters and no output schema, the description provides sufficient context: what constitutes the data source, how keywords work, year separation, and a fallback to a sibling tool. It could mention the default behavior for optional parameters, but overall it is adequate.

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 0%, so the description must compensate. It adds meaning for `query` (AND condition with spaces) and `year` (separate guidelines by year), but does not explain `issuer` or `limit`. The partial coverage earns a moderate score.

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 explicitly states the tool searches locally loaded guidelines at the clause level, with a specific verb 'search' and clear resource scope. It distinguishes itself from the sibling tool `search_admin_rules` by noting that standing guidelines should use that tool instead.

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?

The description clearly states when to use this tool (for guidelines not on law.go.kr) and when not to (for standing guidelines, which should use `search_admin_rules`). It also explains query behavior (AND for multiple keywords) and year filtering.

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

search_institutionsB

공공기관을 이름·유형·주무부처로 검색합니다. org_code는 다른 도구의 진입점입니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
org_typeNo
ministryNo
limitNo

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the search capability and org_code role, failing to mention if it is read-only, pagination behavior, or any side effects. The minimal information does not sufficiently inform an AI agent about the tool's behavioral traits.

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?

Two concise sentences: first clearly states function and search dimensions, second adds critical context about org_code as entry point. No redundant information, efficient for an AI agent to parse.

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?

Given 4 optional parameters, no output schema, and no annotations, the description provides basic functionality and the role of org_code but lacks details on return format, error conditions, or pagination. It is minimally adequate for a simple search tool but leaves gaps.

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 0%, so the description must compensate. It maps the three search criteria (name, type, ministry) to likely parameters 'query', 'org_type', 'ministry', adding some meaning. However, it does not explain the 'limit' parameter or provide detailed semantics for each parameter. The contribution is moderate.

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?

Description clearly states the verb '검색합니다' (search) and resource '공공기관' (public institutions) with search dimensions (name, type, ministry). It also mentions org_code as entry point for other tools. However, it does not differentiate from sibling 'find_institutions_by_criteria', which may have overlapping functionality.

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?

Description implies usage context: search by name/type/ministry, and org_code is a key to other tools. But it lacks explicit guidance on when to use this tool versus alternatives like 'find_institutions_by_criteria' or other search tools. No exclusions or prerequisites are stated.

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

search_lawsA

법령(법률·대통령령·부령 등)을 키워드로 검색합니다 — 국가법령정보센터.

공공기관 관련 질의는 리소스 alio://related-laws의 화이트리스트(공운법 등 핵심 법령 공식 명칭)를 먼저 참조해 정확한 법령명으로 검색하세요. 복합 키워드는 0건이 나올 수 있으니 핵심 단어 하나로 검색 후 결과에서 고르세요. scope: 1=법령명 검색, 2=본문 검색. 결과의 'mst'(법령일련번호)를 get_law_text에 넘기면 조문을 조회합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
pageNo
displayNo
scopeNo

TDQS

A4.2/5.0
Behavior4/5

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

Discloses that complex keywords may yield zero results, explains scope parameter meanings (1=title search, 2=content search), and mentions the 'mst' field for chaining with get_law_text. Lacks disclosure on auth or rate limits but adequate given no annotations.

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?

Single paragraph with line breaks, front-loaded purpose. Each sentence provides useful guidance (searching, scope, chaining). Could be slightly more concise but no waste.

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?

No output schema, description partially compensates with behavioral details and parameter hints. Lacks return format description (except 'mst') and error handling. Adequate but not comprehensive.

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 has 0% description coverage. Description adds meaning for scope (1=title, 2=content) and implies query is keyword. Page and display not explained but have defaults. Adds moderate value beyond schema.

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?

Description clearly states '법령(법률·대통령령·부령 등)을 키워드로 검색합니다' with specific verb and resource, distinct from sibling tools like search_admin_rules and get_law_text.

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?

Explicit guidance on using alio://related-laws for public institution queries and advice to use single core keywords to avoid zero results, effectively steering usage.

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

search_public_servicesC

공공기관의 국가사업·대민 편의사업(서비스)을 검색합니다. org_code는 instCd입니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
org_codeNo
service_classNo
lifecycleNo
limitNo

TDQS

C2.5/5.0
Behavior2/5

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

No annotations are provided, and the description only mentions a parameter mapping. It fails to disclose significant behavioral traits such as pagination, authentication needs, or result format.

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 description is very short and to the point, but it could be expanded to include more useful information without being verbose.

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

Completeness1/5

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

Given 5 parameters, no output schema, and no annotations, the description is severely inadequate. It does not explain how to use the parameters effectively or what the tool returns.

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

Parameters2/5

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

With 0% schema description coverage, the description adds minimal value by clarifying that org_code is instCd. Other parameters (query, service_class, lifecycle, limit) lack any explanation beyond their names.

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 it searches for public services of public institutions, which is clear and distinct from sibling search tools like search_institutions and search_laws. However, it does not explicitly differentiate itself from siblings.

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

Usage Guidelines2/5

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

No guidance on when to use this tool over alternatives. It does not specify prerequisites, exclusions, or recommended scenarios.

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

search_recruitmentsB

공공기관 채용공고를 검색합니다. org_code는 pblntInstCd(instCd)입니다.

query에 기관명·별칭('한전')을 넣으면 자동으로 해당 기관 공고로 해석합니다. 필터: region(근무지역명, 예 '대구'), ncs(직무분류명, 예 '정보통신'), hire_type(고용형태명, 예 '청년인턴'), recruit_type('신입'·'경력' — '신입'은 신입+경력 포함), education(학력, 예 '고졸'·'학력무관'), pref(우대조건 키워드, 예 '지역인재'). closing_within_days>0이면 마감 N일 이내 공고만(D-day 기준). sort: 'latest'(기본)·'deadline'(마감임박순)·'headcount'(모집인원 많은순). 취소 표기 공고는 기본 제외(include_cancelled=True로 포함). use_snapshot=True면 로컬 스냅샷(data/snapshots)에서 조회 — API 한도·속도 회피.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
org_codeNo
ongoing_onlyNo
work_region_codeNo
regionNo
ncsNo
hire_typeNo
recruit_typeNo
educationNo
prefNo
closing_within_daysNo
sortNolatest
include_cancelledNo
use_snapshotNo
limitNo

TDQS

B3.4/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses that query with org name auto-interprets, cancelled notices are excluded by default (with include_cancelled), and use_snapshot reads from a local snapshot. However, it does not disclose if the tool is read-only, auth requirements, rate limits, or what happens with invalid inputs. Moderate transparency.

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?

The description is a single paragraph but well-structured with clear line breaks for filters and options. It is fairly concise given the number of parameters and conveys essential information without unnecessary verbosity.

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?

The description covers the main search functionality, filter details, sort options, and snapshot feature. However, it lacks descriptions for a few parameters (ongoing_only, work_region_code, limit) and does not explain the return format or output schema. Given the complexity (15 parameters, no output schema), it is somewhat incomplete.

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 0%, so the description must compensate. It explains many parameters (query, org_code, region, ncs, hire_type, recruit_type, education, pref, closing_within_days, sort, include_cancelled, use_snapshot). However, it does not explain ongoing_only, work_region_code, or limit. Partial coverage, but adds value beyond 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 description clearly states the tool searches public institution job announcements, and explains the main parameter org_code and query interpretation. It is specific about the resource (recruitments) and verb (search). However, it does not explicitly distinguish from sibling tools like analyze_recruitments, but the purpose is clear enough.

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?

The description provides usage context for many filters and sort options, and explains the use_snapshot parameter for API limit avoidance. However, it does not mention when to use this tool versus alternatives like analyze_recruitments, nor does it state exclusions or prerequisites.

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

TDQS

A3.6/5.0
Disambiguation5/5

Each tool targets a distinct function (searching, retrieving, analyzing, comparing) across different subdomains (institutions, metrics, news, recruitment, laws, facilities). Even overlapping areas like search_recruitments vs analyze_recruitments are clearly differentiated by purpose. Descriptions are detailed enough to avoid confusion.

Naming Consistency5/5

Tool names consistently use a verb_noun pattern (e.g., search_institutions, get_institution_profile, list_disclosure_items). Even longer names like cross_check_news_with_metrics follow a clear pattern. No mixing of conventions (all snake_case).

Tool Count4/5

32 tools is on the high end but justified by the broad domain of public institution data. Each tool serves a specific purpose across multiple areas (institutions, metrics, news, recruitment, facilities, laws, etc.). A few tools could potentially be merged (e.g., get_institution_staff_summary could be a param of get_institution_metrics), but the count is still reasonable.

Completeness5/5

The tool surface covers the full lifecycle of retrieving and analyzing public institution information: searching, profiling, metrics, news, recruitment, facilities, laws, guidelines, evaluation handbooks, and comparative analysis. There are no obvious gaps for the stated purpose of providing comprehensive public institution data.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    B
    maintenance
    This MCP server helps users prepare for Korean public institution jobs by integrating job postings, job descriptions, NCS competencies, and institutional analysis from various sources like ALIO and 클린아이.
  • A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Korean government power/energy statutory plans. Enables AI agents to search and retrieve public power plan documents.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gitbosung/open-ALIO-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server