realty_rental_yield[유료] 시군구별 월세 수익률·평균 매매가·평균 월세를 조회한다. 수익형 투자 스크리닝용.
기본 응답은 최신 완결월 1개월치를 수익률 내림차순으로 자른 것이다 — 전체 기간·전체
지역이 아니다(truncated 필드 확인). 특정 월은 year_month로 조회하라.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 반환 행 수 — 수익률 내림차순 상위 N (허용 범위 1~50) | |
| region | No | 시도(예: 서울특별시) 또는 시군구(예: 강남구). 세종은 시 단위로 나온다 | |
| year_month | No | YYYYMM (기본 최신 완결월) | |
| pyeong_supply | No | 분양평수(예: 25·34) — 서버가 ×0.745로 전용평으로 환산해 **전용평 구간**(S·M·L·XL·XXL)을 고른다(분양 25평→S, 34평→M) |
Changes observed during successful MCP inspections.
Input schema / properties / pyeong_supply / descriptionPrevious value: -"분양평수 20/25/34/40/50 중"New value: +"분양평수(예: 25·34) — 서버가 ×0.745로 전용평으로 환산해 **전용평 구간**(S·M·L·XL·XXL)을 고른다(분양 25평→S, 34평→M)"Output schema / (root)Previous value: -{
- "additionalProperties": true,
- "title": "realty_rental_yieldDictOutput",
- "type": "object"
-}New value: +nullInput schema / properties / limit / descriptionPrevious value: -"반환 행 수 — 수익률 내림차순 상위 N"New value: +"반환 행 수 — 수익률 내림차순 상위 N (허용 범위 1~50)"Input schema / properties / limitAdded value: +{
+ "default": 30,
+ "description": "반환 행 수 — 수익률 내림차순 상위 N",
+ "maximum": 50,
+ "minimum": 1,
+ "title": "Limit",
+ "type": "integer"
+}Input schema / properties / region / descriptionPrevious value: -"시도 단위 (예: 서울특별시) — 응답은 시군구별로 온다"New value: +"시도(예: 서울특별시) 또는 시군구(예: 강남구). 세종은 시 단위로 나온다"Input schema / properties / year_month / descriptionPrevious value: -"YYYYMM (기본 최신월)"New value: +"YYYYMM (기본 최신 완결월)"Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds the critical behavioral fact that the default response is truncated to the latest complete month, sorted by yield descending, and is NOT the full period or region — with the pointer to check the truncated field. That is exactly the kind of default-scope disclosure an agent needs to avoid misreading results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero padding; the core capability comes first, then the truncation caveat, then the override for a specific month. Front-loaded and every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still explains the shape of the default result (one latest complete month, yield-descending, truncated flag) so the agent can interpret returns. Minor gaps remain around non-default behavior and region coverage limits, keeping it from 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds value by tying year_month to the default (latest complete month) and explaining why the default result set is limited. Parameter-level detail (limit, region, pyeong_supply) is left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (조회) and concrete resource: 시군구별 월세 수익률, 평균 매매가, 평균 월세, plus the intended job (수익형 투자 스크리닝). It does not explicitly differentiate itself from nearby siblings such as realty_region_price_stats or realty_region_rankings, so it lands at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use ('수익형 투자 스크리닝용') and tells the agent how to widen scope ('특정 월은 year_month로 조회하라'). No named alternatives or explicit when-not guidance, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.