아파트 단지 검색·평형별 시세
realty_search_complexesRead-onlyIdempotent
아파트 단지를 이름·지역으로 검색하고 평형별 실거래 시세를 함께 돌려준다. "○○아파트 34평 얼마야"류 단지 질문의 1차 도구다. query·region 중 하나는 필수.
**이 축의 자리(시세 도구 3종 중)**: 단지가 특정되면 **이게 기본**이다. 지역 평균
도구들(realty_region_price_stats·realty_area_price_bands)은 단지 간 편차를 뭉개므로
단지 질문에 쓰지 마라 — 같은 동 같은 평형에서 단지 평균이 24% 벌어진 실측이 있다
(동 평균 3.96억으로 답했다가 대장 단지 호가와 1억 어긋난 사고). 반대로 지역 전체의
수준·추이 질문이면 저 둘로 가라.
prices_by_area가 평형별 시세다 — pyeong_exclusive(전용평)와 pyeong_supply_est(분양평
어림)를 병기하므로, 사용자가 말한 "34평"(보통 분양평)은 pyeong_supply_est로 맞춰 답하라.
단지 수준 avg_price는 전 평형이 섞인 평균이니 평수 질문에 쓰지 말 것.
층별(저층/고층/RR) 시세·프리미엄 질문은 realty_complex_pyeong_price로 —
거기 층 밴드별 집계(price_by_floor_band)가 있다(이 도구엔 층 축이 없다).
응답의 complex_key는 realty_complex_rent_by_pyeong·[유료] 단지 도구들에 그대로 넣는 키다.
**단지끼리 급을 견줄 때는 price_per_exclusive_m2(전용 ㎡당 실거래 단가)를 축으로 쓰라**
— 행마다 실리고, **sort='unit_price'로 그 순서대로 받을 수 있다**(백엔드에 없는 축이라
이 응답에 실린 행만 다시 세운 것이다 — sort_applied.scope 참조). 행의 scores
(composite·convenience)는 걸어서 닿는 **시설의 개수**이지 선호도가 아니다(직선거리만
세어 간선도로 횡단 같은 보행 장벽을 못 본다) — 그 점수로 단지에 줄을 세워 추천하지
마라. 입지 점수는 **미검증 참고값**이다(scores_meaning.status — transit 90점 이상 86.7%).
"역세권이야?"는 행의 nearest_station·subway_distance_m(직선 m)으로 답하라.
응답의 scores_meaning·unit_price_axis에 근거가 있다.
**견줄 때는 조건을 맞춰라 — 두 인자가 그 수단이다.** ㎡단가는 평형이 작을수록,
준공이 새로울수록 높다(⚠️ **전국 중앙값 이야기다** — 서울은 구축이 더 비싼 동이 28.0%다).
`area_band_m2=59`면 각 단지의 대표 단가가 **전용 59±3㎡ 행만으로** 다시 계산되고,
`construction_year_band=2018`이면 2013~2023년 준공 단지가 비교군으로 표시된다
(in_year_band). 연식이 더 지배적이다 — 법정동 안 ρ 중앙값이 연식 +0.7298 대
평형 +0.2245라, 연식이 섞인 ㎡단가 순위는 **사실상 신축 순**이 되기 쉽다. 두 인자 모두
**가격 계산·비교군 표시에만** 걸리고 단지 검색을 거르지 않는다(못 잰 단지는 목록에
남고 값이 null + 사유다). 몇 개를 쟀고 몇 개를 못 쟀는지는 응답의 coverage가 적는다.
**0.84.0부터 scores.composite는 school + convenience다**(transit을 뺐다 — 전국 실측에서
고유값의 86.8%가 90~100에 몰려 변별력이 없고, 합산에 넣으면 법정동 격자 ρ 중앙값이
0.0825→0.0654로 떨어졌다). 백엔드 원장의 옛 가중평균 값은 **composite_legacy로 병기**하니 이전 응답과
견줄 때 그쪽을 쓰라 — 두 값은 척도가 다르다(가중평균 대 단순합).
**세대수 조건은 min_households·max_households가 받는다**(2026-09-07 외부 신고
T-2026W34-351): "500세대 이상", "1,000세대 넘는 대단지", "300세대 이하 소규모"는
이 인자로 넣어라 — 종전엔 전달할 자리가 없어 그 질문이 통째로 실패했다. 행마다
households가 실린다. **households가 null인 단지는 세대수가 원장에 없는 것이지
작은 단지가 아니다** — 그래서 세대수 조건을 걸면 그 단지들은 크든 작든 제외되고,
몇 건이 그렇게 빠졌는지는 meta.households_scope가 적는다.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 0부터 시작하는 페이지 번호 | |
| sort | No | name=이름순(거래량 많은 순), price=평균가 **높은** 순(전 평형 혼합 평균이라 큰 평형이 많은 단지가 앞에 온다), year=준공연도 **최신순(내림차순 — 신축이 먼저)**, **unit_price=전용 ㎡당 실거래 단가 높은 순** — 단지 간 급·선호를 견주는 축이다(못 잰 단지는 맨 뒤). ⚠️ unit_price는 백엔드에 없는 축이라 **이 응답에 실린 행만** 다시 세운 것이다 — total이 이 페이지보다 크면 '이 지역 ㎡단가 상위 N'으로 인용하지 마라(sort_applied.scope='page_only'가 그 사실을 값으로 싣는다). ⚠️ **오래된 순 정렬은 이 도구에 없다** — '오래된 단지'·'재건축 후보'를 찾는 조회에 sort='year'를 쓰면 정확히 반대 결과가 온다(정비사업 축은 realty_reconstruction·realty_redevelopment) | name |
| limit | No | 단지 수 — 평형별 시세가 포함돼 응답이 무겁다. 최대 20이고 더 받으려면 limit을 올리지 말고 **page를 넘겨** 이어 받아라(응답의 total이 전체 건수다 — 다만 서버가 지역 토큰을 뒤에서 검증한 경로에서는 total이 null이고 meta.total_unavailable이 사유를 적는다. 그리고 **sort='unit_price'로 받은 응답이 잘렸으면 page로 이어받을 수 없다** — sort_applied.page_continuation이 그 사실을 값으로 싣는다). 요청분을 다 실으면 응답이 크기 상한을 넘는 경우 **실제 반환 수를 줄이고 meta.size_capped**에 총계·이어받는 호출을 값으로 싣는다 — 조용히 자르지 않는다 (허용 범위 1~20) | |
| query | No | 단지명 일부 (예: 래미안, 마포래미안푸르지오) | |
| region | No | 시군구명 (예: 마포구, 서울특별시 마포구). **법정동까지 넣어도 된다**(예: '강남구 대치동') — 백엔드는 동으로 거르고 나머지 토큰은 서버가 검증해 note에 적는다. 종전 설명이 시군구만 적어 **이 도구가 못 하는 일로 읽혔고**, 동 단위를 원한 모델이 비아파트 도구로 새던 자리다(2026-08-23 PlayMCP QA) | |
| area_band_m2 | No | **평형을 고정해 단지끼리 견줄 때** 넣는다(전용면적 ㎡ — 분양면적이 아니다). 예: '59㎡대로 맞춰서 비교' → 59. 전용 ±3.0㎡ 근사 매칭이고(원장 면적이 59.224·59.9처럼 단지마다 달라 정확 일치는 대부분 0건이다), 각 단지의 price_per_exclusive_m2가 **그 밴드 안 평형 행만으로 다시 계산된다**. ⚠️ 이 인자는 **가격 계산에만** 걸리고 단지 검색을 거르지 않는다 — 밴드에 거래가 없는 단지도 목록에 그대로 실리고 그 값은 null + 사유다. 밴드에 든 행에는 in_area_band=true가 붙는다 (허용 범위 0 초과~500) | |
| period_months | No | 가격 집계 기간(개월). 비우면 2024-01 이후 전체 (허용 범위 1~24) | |
| max_households | No | 세대수 상한 — '300세대 이하 소규모'처럼 위쪽을 자를 때. min_households와 함께 주면 구간이 된다 | |
| min_households | No | **세대수 하한** — '500세대 이상', '대단지'를 여기에 넣는다(예: 500). 세대수가 원장에 없는 단지는 이 조건에서 제외되고 그 건수를 meta.households_scope로 실토한다(미상 ≠ 소규모) | |
| construction_year_band | No | **연식을 맞춰 단지끼리 견줄 때** 넣는 기준 준공연도. 예: 2018 → 2013~2023년 준공(±5년, 폭 10년)이 비교군이 된다. **연식은 ㎡단가를 가장 강하게 끄는 축이다** — 법정동 안에서 준공연도와 ㎡단가의 순위상관 ρ 중앙값이 +0.7298로 평형(+0.2245)·입지점수(+0.0707)보다 지배적이라, 연식이 섞인 비교는 사실상 '신축 순'이 되기 쉽다(⚠️ 방향은 지역마다 반대일 수 있다 — **서울은 ρ +0.3833이고 구축이 더 비싼 동이 28.0%, 세종은 36.8%**다. 재건축 기대가 가격에 들어간 U자 구간이다). ⚠️ 이 인자도 검색을 거르지 않는다 — 밴드 밖 단지는 목록에 남고 행마다 in_year_band로 갈라 적힌다(준공연도가 원장에 없으면 null: **판정 불가이지 구식이 아니다**). area_band_m2와 함께 주면 둘 다 걸린다 (허용 범위 1900~2100) |