korea-realty

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds real behavioral context beyond that: the return is document-form text rather than structured data, and a court-name-less lookup degrades to a candidate list. Only the exact return content remains thinly described.

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?

The core purpose and id contract are front-loaded in the first three lines and the routing rule is clearly separated. The '이 축의 자리' framing adds some meta-verbosity that slightly dilutes an otherwise tight definition.

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 carries the return burden and does so adequately by declaring document-form text output and the candidate-list fallback. Combined with the rights-citation constraint, an agent has enough to call and interpret it correctly, though the exact response shape stays vague.

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 description coverage is 100% and the schema itself already documents the pipe-delimited format, court-name prefix, and case-number shape. The description largely restates this, adding only the firm constraint to pass the id through unchanged and the candidate-list consequence — baseline 3 is appropriate.

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 resource ('search가 돌려준 id로 경매 사건의 전체 내용을 가져온다') and explicitly positions itself against the two closest siblings, realty_get_auction_case and realty_auction_history, by input/response form. An agent can distinguish it without opening any schema.

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 explicit routing rules: use realty_get_auction_case when the user speaks the case number or structured fields are needed, and realty_auction_history for foreclosure history/discount schedules. It also states a bound on use — do not fabricate rights relationships if rights is absent.

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

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

Annotations only cover the safety profile (readOnly/idempotent/openWorld), and the description goes well beyond them: it discloses the outlier filter (excluding cancelled contracts and sub-50%-of-median direct trades), warns that this makes values differ from realty_region_price_stats' unfiltered mean, and notes the 3-sample minimum plus by_dong_hidden_cells disclosure. That is exactly the methodological context an agent needs to avoid misreporting numbers.

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?

Front-loaded with purpose and the routing rule, and each block (axis position, filter note, pyeong conversion) earns its place. Slightly dense with bold markers and stacked alternatives, but no filler sentences.

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?

No output schema exists, yet the description still covers return-shape essentials (band labels in exclusive pyeong, per-row one-line vs full footnotes, hidden-cell count) plus the unit-conversion table so the agent can translate to user-facing 분양평. Nothing needed to call it correctly is missing.

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 baseline is 3; the description adds real meaning on top by explaining that region can take a legal-dong string and that gu-level aggregation conflates new/old downtown, and by framing by_dong as the answer to a specific question with an observed 4x spread. It does not add much on period_months or include_footnotes beyond what the schema already says.

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+resource: retrieves sale price levels for a region bucketed into four exclusive-area bands, with the band definition (전용면적 기준) inline. It explicitly names what it is not for (specific complexes → realty_search_complexes), so it is separable from the 50+ siblings without opening a schema.

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 the exact question shape it answers ("○○구에서 무슨 평수대가 얼마쯤 해?") and then positions it against both relevant alternatives: trend questions → realty_region_price_stats, specific complex → realty_search_complexes, and 'which dong is cheap' → the by_dong parameter. It even states a precedence rule when the two price-level tools disagree.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine context beyond that: many failed bids signal rights/hazard problems, and results should be framed as candidates needing verification, not recommendations. It does not cover auth needs, rate limits, or result ordering.

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?

The first two sentences are near-duplicates ('유찰이 쌓여 최저입찰가가 크게 떨어진 경매 물건을 골라낸다' vs '유찰이 누적돼 최저입찰가가 크게 떨어진 물건을 찾는다'), which is redundant. The useful routing and caveat content is front-loaded but preceded by that repetition.

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?

For a 7-parameter, no-output-schema tool, the description covers purpose, caveats, regional narrowing, and the key sibling distinction. It is largely complete; only return-format nuances (which the schema does not provide) are absent.

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 schema carries the heavy parameter detail. The description still adds useful guidance by tying sido/sigungu to the region-narrowing use case, slightly above the structured fields.

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 resource: it selects auction properties whose minimum bid price has dropped sharply due to accumulated failed bids. It explicitly names the sibling realty_search_auctions and the axis distinguishing them, so an agent can separate them without opening schemas.

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 explicit when-to-use guidance ('조건 필터·목록이 목적이면 그쪽, 저감 큰 후보 발굴이면 이쪽') plus a concrete warning not to combine the two because items overlap. It also instructs how to narrow ('○○에서 유찰 많은 물건' → sido/sigungu).

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

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

Goes well beyond the read-only/idempotent annotations: it warns that photos exist only as collection-time preserved copies because court originals are destroyed after the hearing date, that null result rows are future hearings or undecoded court codes, that kind_note marks non-bid rows, that fail_count_note explains count mismatches, and that min_bid_source=item_list may be stale. These are exactly the non-obvious traits an agent needs.

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?

Purpose is front-loaded in the first sentence, and the dense remainder is operational caveats rather than filler. It is long and crowded with bolded warnings, which makes it harder to scan, but almost every clause carries actionable meaning.

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?

No output schema exists, so the description carries the full burden of return-value semantics — and it does, defining what fail_count, min_bid_10k, kind_note, fail_count_note, min_bid_source, and the tracking/price_events emptiness each mean and how they should be relayed. An agent would not misstate results after reading this.

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 description coverage is 100%, and the two parameters (case_no format rules, court_name uniqueness) are already fully documented in the schema. The description adds no independent parameter guidance, so the baseline 3 applies.

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?

The opening sentence gives a specific verb and resource set — retrieves a single auction case's failed-bid history, price-change timeline, and property photo URLs. The question-type framing ("몇 번 유찰됐어? 얼마나 떨어진 거야? 사진 있어?") pins down the intent precisely. It does not explicitly distinguish itself from the closest sibling realty_get_auction_case, so it stops short of a 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?

Clearly states the situations this tool owns (failed-bid counts, price-drop history, photos) and explains what to do when sub-sources are empty (tracking/price_events may be blank; court_schedule is authoritative). It gives no explicit when-not or named alternative such as realty_get_auction_case or realty_search_auctions, so it is context-rich but not routing-complete.

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

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

Annotations only say readOnly/idempotent/openWorld; the description adds everything an agent actually needs: the engine is deterministic (no LLM), court wording outranks engine verdicts with mismatches in `conflicts`, blank ledger cells mean 'not seen' rather than 'nothing assumed', and 유치권/법정지상권/분묘기지권/가처분 are deliberately not adjudicated but returned as an on_hold checklist. It also states the result is information, not legal advice, and recommends checking the source documents.

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?

Front-loaded with a one-line headline, then structured into usage and a numbered 경계 list, so it scans well. It is dense and long for a tool definition; some clauses (e.g. the parenthetical about 최우선변제 table basis) could be trimmed without losing decision value.

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 carries return semantics and does so well by naming the key output fields (conflicts, assumption.verdict, cross_check, on_hold, disclaimer). The overall shape of the rights timeline and per-tenant verdict output is only implied rather than described, which keeps it just under a 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, but the description adds real meaning: registry_entries must exclude names and 주민번호 (rejected keys surface as ignored_fields), and expected_bid_won yields a range rather than a single figure because enforcement costs and tax claims are invisible. The tenants guidance mostly restates the schema, keeping this short of a 5.

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 precise verb and resource in domain terms: judges, by rule, the rights a winning bidder takes on (말소기준권리, 인수/소멸, 임차인 대항력, 인수액). It explicitly distinguishes itself from the nearest sibling by noting that with only the court ledger it produces the same result as realty_get_auction_case(rights_analysis=true).

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 an explicit '사용법' block: if the user attached a registry document, read it into registry_entries in order; put tenants into tenants; if neither exists, run on the court ledger alone with the gap surfaced in on_hold. The fallback path and the sibling-equivalence case are both spelled out, leaving no ambiguity about when to use this versus realty_get_auction_case.

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

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

Annotations only cover the safety profile (readOnly/idempotent/openWorld/non-destructive); the description adds non-obvious behavior the agent could not infer: period-narrowing parameters are silently ignored by the backend (so none are exposed), '빌라' is silently remapped to '다세대' with the mapping disclosed in the response, and the '면적 미상' band is missing data rather than zero. These are exactly the quirks that prevent wrong conclusions.

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?

Core definition and formula are front-loaded, then exclusions, then caveats — a logical funnel with bold anchors for scanning. It runs long, and the 2026-10-17 measurement figures are illustrative evidence rather than instruction, but nearly every line carries actionable content.

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?

No output schema exists, so the description carries the return contract itself: sample_period (매각기일 min~max) for recency framing, by_fail_count distribution, by_area_band, and the include_footnotes toggle. Combined with the denominator warning against sibling tools, an agent has everything needed to call it and to interpret the numbers correctly.

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 description coverage is 100%, so the baseline is 3, but the description adds rationale the schema lacks — why area_band should '반드시' be used (78.8% national vs 75.7%/81.4% by band, 서울 82.4% vs 98.1%), why bid_count_max should match the subject's fail count, and why no period parameter exists. It does not, however, restate or extend sido/sigungu disambiguation beyond what their schema entries already say.

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?

The opening line states a specific verb and resource ('이 지역 이 물건은 보통 감정가의 몇 %에 낙찰되나'를 실제 매각결과로 답한다) and pins the metric with an explicit formula (낙찰가/감정가×100). It actively distinguishes itself from siblings with the same domain — realty_policy_rules, realty_auction_history, realty_compare_auction_vs_market — so an agent can route without opening any schema.

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?

Explicit when-not guidance is given ('감정가 12억에 최저가 7.68억이면 몇 번 유찰됐나'는 이 도구가 아니다) with the correct alternative named and even sub-arguments (realty_policy_rules topic='auction_rights', section='minimum_price_reduction'). The '경매 가격판단 3종 중' paragraph also states when to prefer realty_compare_auction_vs_market, including the reason (different denominator).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description layers on genuinely useful out-of-band caveats (무순위 ≠ 최종 미분양, 청약홈 밖 공급 미포함, co-construction full attribution, meta.match_rate, not a financial-soundness ruling). However, much of this is result-interpretation guidance rather than invocation behavior, and it discloses no auth/rate-limit/pagination traits, so it exceeds the annotation bar without being 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.

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

Front-loaded with the purpose sentence, then usage patterns, then disclosure caveats, then the exclusion — a sensible order for a 9-parameter tool. It is long and the disclosure block repeats material that also lives in parameter descriptions, but nearly every sentence carries non-redundant caveat value.

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 carries the return-value burden and does so: it describes the company row, the attached site list columns, the top-N ranking shape, and the per-row national baseline for comparison. Combined with the disclosure caveats, an agent has enough to call the tool and interpret its response.

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 description coverage is 100% and every parameter already carries a substantive inline description (aliases, partial matching, ranges, defaults), so the baseline is 3. The description adds the interaction rule for builder+developer and the effect of region, but that overlaps heavily with what the schema already says.

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 resource (시공사·시행사별 분양 성적) and enumerates the exact measures returned (공고 수·공급 세대·무순위 세대·비율·청약 1순위 배수·미달 세대). It explicitly distinguishes itself from a sibling by ruling out brand-name notice counting and routing that to realty_notice_facts(keyword).

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?

Enumerates the exact user-question shapes it answers ('○○건설 분양 성적', 'GS건설 현장 무순위 많이 나왔나', '대전 시공사별 분양'). It also states the argument-driven behaviors (builder/developer → company row + site list; no arg → top-N ranking; region → narrowed) and names the alternative tool for the excluded case.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description goes well beyond them: all inputs are declared (the server does not adjudicate holding-period start, home count, or regulated-area status), exemptions are explicitly out of scope, and the response is stated to carry traps, pending_legislation and disclaimer fields. That is the kind of boundary disclosure annotations cannot convey.

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?

Core capability is front-loaded in the first sentence, followed by scope and then boundaries. It runs long and dense across two paragraphs, but each block (capability, declared-input boundary, exemption boundary, routing) carries distinct information, so little is wasted.

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?

For a 17-parameter, no-output-schema tool this is thorough: it covers the declaration philosophy, the not_curated exemption gap, the escape hatch to realty_policy_rules, and the response fields (traps/pending_legislation/disclaimer). An agent has enough to both invoke it correctly and avoid over-promising on exemption cases.

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 description coverage is 100% and the 17 parameter descriptions are already unusually detailed (asset_type tax split, share_pct per-person taxation, asset2 holding-year recomputation). The description adds only the general 'everything is declared' framing rather than per-parameter meaning beyond the schema, so the baseline 3 is correct.

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?

Names a specific verb and resource — applying the capital gains tax rate table deterministically to declared transfer/acquisition/expense/holding values — and adds the multi-asset comparison scope (합산 vs 연도분산 vs 차손통산). It also distinguishes itself from siblings by naming realty_policy_rules as the statute source of truth rather than repeating it.

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?

Explicitly frames the two questions it answers ('지금 팔면 양도세 얼마?' / '두 채를 올해 같이 팔까 나눠 팔까?') and states what it does NOT do (1세대1주택 비과세, 12억 초과 안분, 감면 특례 = not_curated). It then routes the agent to a concrete alternative, realty_policy_rules(topic='one_home_exemption_map'), with a prescribed order of operations before falling back to 홈택스/세무사.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: default is today-or-later dates only, exact address/complex normalization, a 50–150% appraisal-value filter that excludes 지분경매/특수물건, the ±10% same-area baseline rule, null + '판정보류' fallback when area can't be matched, a warning about stale min_bid_source on failed auctions, and an explicit 2–4s latency disclosure.

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?

Core purpose is front-loaded and bold section headers organize the axis/alternative guidance well. However the two date-stamped repair notes (2026-08-08, 2026-08-16) read as changelog noise that a calling agent does not need, slightly bloating an otherwise tight description.

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?

There is no output schema, and the description compensates by explaining the returned signal values (주의/관심/보통/낮음/판정보류), the meaning of a null discount_vs_market_pct, the footnotes toggle, and the stale-min_bid caveat. Nothing needed to call or interpret the tool is missing.

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 description coverage is 100%, so the schema already documents all 8 parameters including the sido/sigungu/case_no/court_name relationships. The description reinforces the date-scoping and area-matching semantics but adds little parameter syntax beyond what the schema provides, so the baseline 3 is appropriate.

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+resource: compares an auction item's minimum bid against same-complex real transaction prices to produce a discount rate and surface yield. It also positions itself explicitly within the '경매 가격판단 3종' axis and names the sibling it must not be confused with (realty_auction_sale_rate), so an agent can distinguish it without opening any schema.

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 explicit routing: '이 물건 싸?'는 이게 1차다, use realty_auction_sale_rate together for bid pricing but never mix the two denominators, and use realty_area_price_bands/region_price_stats when setting a manual baseline. Both when-to-use and when-not-to-mix conditions are spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds high-value interpretive context: warning_baseline/warning_dispersion must be read before avg_price, because the source is outlier-unfiltered and mixes complex-level data, so citing avg_price as the regional price can flip a comparison conclusion. That is exactly the kind of non-obvious caveat annotations cannot express.

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?

Front-loaded correctly: purpose sentence, then routing rule, then caveat. Every block is load-bearing, though the warning paragraph is somewhat long and references a sibling source in a way that could be tightened.

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?

No output schema exists, and the description partially compensates by naming return-side fields (warning_baseline, warning_dispersion, avg_price, footnotes) and their interpretation. It does not describe overall return shape or pagination, but for a comparison tool the critical interpretive guidance is present.

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 description coverage is 100% (regions format, months range 1-60, include_footnotes behavior are all documented in the schema). The description adds no syntax or format detail beyond that, so the baseline 3 applies; it does visually surface the footnotes/warning fields but not the parameters themselves.

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+resource+scope: it compares multiple regions' 매매·전세 시세와 추이 side by side, and adds the use case (갈아타기·투자처 비교). An agent can distinguish it from realty_region_price_stats and realty_region_rankings without opening any schema.

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?

Explicitly routes ranking/exploratory questions ('어디가 제일 ○○해?') to the free realty_region_rankings first and states the exact condition for using this tool instead ('비교 대상이 정해졌을 때'). This is a when/when-not/alternative rule stated outright.

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

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

Annotations already cover read-only/idempotent/no-destructive, but the description adds substantial beyond them: transactions are sorted by contract date descending, average/median use the most recent 5 (with summary_basis echoing those), outliers are flagged not removed with rationale in outliers.method, floor bands include *_ex_outliers variants, and presale rights are separated into presale_rights_trades. It also discloses refusal behavior for mixed units and that name-based complex isolation is logged in meta.complex_isolation.

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?

Front-loaded with purpose and sibling routing before the detailed mechanics, which is good structure for a 14-parameter tool. It is long and occasionally overlaps with schema text (unit conversion rules appear in both), but nearly every sentence carries a behavioral rule or guardrail; only minor trimming would help.

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?

No output schema exists, so the description must carry return semantics — and it does: price_by_floor_band with average, count, and premium vs lowest band; per-transaction fields; outlier and *_ex_outliers parallel values; summary_basis; meta.complex_isolation; quote_check; presale_rights_trades. An agent knows what to expect and how to phrase results without a return schema.

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?

With 100% schema description coverage the baseline is 3, but the description adds genuine strategy beyond the schema: convert nothing client-side (server converts ㎡↔pyeong), map user units to the correct parameter, reject quoted-prices-only assumptions by noting the server has no asking-price data (MOLIT only), and explain compare requires an area and consumes limit per complex. This meaningfully supplements the structured schema rather than repeating it.

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+resource+scope: per-complex, per-pyeong, last 6 months of sale transactions with contract date, floor, price at the transaction level. It explicitly distinguishes itself from realty_search_complexes (prices_by_area), realty_region_price_stats (multi-complex/floor decomposition/longer windows), and realty_complex_rent_by_pyeong (rent). An agent can route correctly without opening any schema.

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?

Explicit when-to-use rules for every adjacent case: summary-only → search_complexes prices_by_area; multi-complex floor breakdown or >6-month window → region_price_stats; rent → rent_by_pyeong. It also gives a fallback behavior (call without area if pyeong unknown) and states what not to do (don't guess pyeong, don't mix ㎡ into pyeong params).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing that compare_sale makes the server compute jeonse ratio, conversion rate and gap over a matched 12-month window, and that footnotes toggle full derivation text.

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 paragraphs, purpose stated first, then the key-resolution rule, then the row-key caveat. Content earns its place; the historical aside about the old note could have been trimmed but it justifies compare_sale's default.

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?

No output schema exists, and the description does name the row key and its basis, but it does not enumerate the remaining return fields (deposit/rent medians, footnotes structure). Adequate for an open-world read tool whose annotations already carry the safety profile.

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, but the description adds a constraint the schema lacks — both key fields are nullable with no required list, yet one of complex_key/complex_name is mandatory — and explains the supply_pyeong row key is 분양평 via a specific formula.

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?

Opens with a specific verb and resource: median jeonse deposit / monthly rent per pyeong for a complex. The line "전세가율(전세÷매매)의 전세 축이다" implicitly marks it off from the sale-price sibling realty_complex_pyeong_price, though that sibling is never named outright.

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 a clear precondition (complex_key or complex_name is mandatory) and routes the agent to realty_search_complexes to resolve the key first, plus the region fallback when complex_ambiguous comes back. Missing only an explicit when-not / 'use the sale-price tool instead' clause.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive=false, but the description adds real value beyond them: it flags the tool as paid ('[유료]'), names the data source (poi 원장), and warns that score_demotion makes certain scores unverified reference values. It also discloses that the response carries latitude/longitude and complex_key, which an agent needs for chaining.

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?

Purpose is front-loaded in the first line, followed by interpretation rules and chaining advice, with bold emphasis aiding scanability. It is somewhat dense and multi-clause, but every sentence carries actionable content (do-not-use warning, follow-up tool names).

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 partly compensates by naming key response fields (location.facts contents, coordinates, complex_key) and their reliability caveat. For a two-optional-param paid report tool this is largely complete, though it leaves other returned sections (전세/시세 detail shape) unmentioned.

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 description coverage is 100%, so name ('단지명, e.g. 반포자이') and complex_key are already documented in the schema, establishing the baseline of 3. The description only incidentally notes that complex_key appears in the response for reuse, adding no lookup semantics or precedence rules between the two optional, mutually-substitutable parameters.

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 resource: an integrated lookup of 시세·전세·기본정보 for a single complex, with '[유료]' scope and '단지 하나' narrowing. This differentiates it from sibling specialists like realty_complex_pyeong_price or realty_complex_rent_by_pyeong by its aggregated nature, though it never explicitly contrasts itself with them.

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 concrete qualitative guidance: answer location questions using location.facts, do NOT use overall_score/scores for ranking or 'good location' judgments, and feed the returned coordinates/complex_key into realty_poi_nearby and realty_predict_price. It covers how to use the output and which tools to chain, but does not state when to pick this tool over the other complex-level siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: meta.data_as_of is the true freshness anchor, warnings must be relayed verbatim, stale figures must not be presented as current, annual series need their reference year stated, and ambiguous district names trigger a candidates-plus-retry flow. This is unusually rich operational context.

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?

The purpose and usage examples are front-loaded and the operational caveats follow logically. There is mild redundancy between the opening line and the second paragraph's restatement of '지역 인구통계를 조회한다', which keeps it from a 5.

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 covers freshness fields (meta.data_as_of), warning handling, annual vs monthly semantics, and the region-naming failure mode, which is enough for an agent to call it correctly. Return-shape detail beyond the timestamps is limited but acceptable for a read-only statistics tool.

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, but the description adds real meaning the schema lacks: the province-prefix requirement for same-named districts ('서울특별시 중구') and what happens when it is omitted. It also reinforces the monthly-vs-annual distinction that the months parameter only partially conveys.

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 resource domain: regional population, households, aging, and net-inflow statistics, plus concrete example questions that pin the domain. It is clearly distinct from sibling tools like realty_region_price_stats or realty_macro_indicators, but it never names a sibling or explicitly excludes adjacent tools, so it falls short of the top tier.

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?

The example questions ("인구 줄고 있어?", "1인 가구 비율은?", "순유입 되는 동네야?") give clear usage context and map directly to the metric enum values. There is no explicit when-not guidance or named alternative tool, which keeps it below a 5.

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

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

Annotations already declare a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the description is judged on added runtime behavior. It delivers real value: the cross-court case-number collision (avg 2.8 courts) with the candidate-list error path, court-omission retry semantics, rights=null meaning 'not yet collected' rather than 'no encumbrances', the claim_amt_10k trap (applicant's claim, not tenant deposit), and stale min_bid when min_bid_source=item_list. These are genuine behavioral disclosures beyond the annotations.

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?

Front-loaded with the core action and per-case-condition cue, then organized into labeled concerns (rights, claim amount warning, min_bid warning, axis positioning). It is on the long side and the closing '이 축의 자리' paragraph partly repeats routing already implied earlier, but no sentence is filler.

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?

There is no output schema, so the description carries the return-value burden and does: it enumerates rights fields (priority setup, assumed rights, risk flags, dividend deadline), rights.disclaimer requirements, rights_note on null, market_context content and its +2-4s cost, and min_bid_note. An agent knows what will come back and how to phrase it to the user.

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 description coverage is 100% and the schema itself already documents case_no format, the court_name fallback/retry, market_context latency cost, and rights_analysis scope in detail. The description restates the court-omission fallback and the rights_analysis split, adding framing but little syntax or semantics the schema lacks, so the baseline 3 applies.

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?

The opening line states a specific verb and resource (retrieve auction item details by case number) and the description explicitly contrasts itself with realty_search_auctions (multi-result scanning), realty_auction_history (bid history/price drops/photos), realty_auction_rights_analysis (registry-based analysis), and fetch (document-form vs structured fields). An agent can route to the correct sibling without opening any schema.

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?

It names concrete usage conditions: start here for per-case sale conditions such as re-auction deposit ratios; use rights_analysis=true for ledger-only analysis versus realty_auction_rights_analysis when registry/tenant data must be supplied; omit court_name only to trigger the candidate-list error path and re-call with a court. Alternatives and exclusions are both spelled out.

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

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

Annotations already establish a safe, read-only, idempotent profile, so the description's job is to add traits beyond that — and it does: it flags the tool as [유료] (cost-bearing) and discloses that the response carries a disclaimer field the agent must relay. That is genuine behavioral context beyond the structured annotations. It stops short of describing output shape or limits, so not a 5.

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?

Front-loaded with the core action and axes, then a single operational instruction. Two short sentences with no filler; the only minor cost is that the paid/disclaimer notes are interleaved with purpose rather than separated.

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?

For a single-parameter read-only tool with no output schema, the description conveys what is computed (three axes), that the result is a score, and an important response-side obligation (disclaimer). What is missing is any hint at the return structure or how scores should be interpreted, which matters slightly more given the absence of an output schema.

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 description coverage is 100% with a single well-described 'region' parameter (시군구명 예: 강남구), so the schema already carries the semantics. The description adds no parameter-level detail (e.g., accepted granularity or edge cases) beyond the schema, which is the baseline-3 case.

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?

The description names a specific verb (점수화한다 / scores) and resource (지역 투자 위험도 / regional investment risk) and even enumerates the scoring axes (변동성·유동성·공급압력 / volatility, liquidity, supply pressure). This is clear on its own, but it does nothing to distinguish itself from plausible siblings like realty_market_signals, realty_supply_demand_balance, or realty_location_scores, so it stays below a 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?

There is no statement of when to use this tool versus the many adjacent risk/market tools, nor any prerequisites or exclusions. The only guidance provided is a post-call instruction about relaying a disclaimer, which is not usage guidance for selecting the tool. The [유료] marker signals cost but not applicability.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context on top: inputs like homes_owned/first-time/newlywed are declarations the server does not fact-judge, limits are deliberately not calculated here, and rule uncertainty lives in each product `topic`. This is substantive disclosure well beyond what annotations provide.

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?

The core purpose is front-loaded and each boundary clause carries useful information. It is somewhat verbose, with bold markup and meta-narrative (the pinned date, '이 도구가 존재하는 이유') that could be trimmed, but the structure remains readable and front-heavy.

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 tells the agent what comes back (usable products plus reasons for exclusion, and the `topic` pointer for rule basis/uncertainty). All 8 parameters are documented in the schema, and the read-only safety profile is covered by annotations, so an agent has everything needed to call this correctly.

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 description coverage is 100% and the per-parameter descriptions are already extremely rich (defining 세대 기준, 순자산, 전세 vs 전세반환 direction). The description only restates that purpose/region/homes are the judgment axes and adds no syntax or format detail beyond the schema. Baseline 3 is correct when the schema carries the load.

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 action (side-by-side eligibility judgment) on a specific resource (loan products), with the exact axes (purpose × region × homes owned). It explicitly names the sibling it is not (realty_loan_limit) and explains its router role, so an agent can distinguish it from siblings without opening any schema.

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 explicit when-to-use (the caller does not know which of the 7 rule topics to ask), an explicit alternative (realty_loan_limit handles limit amounts for purchase-purpose bank loans), and explicit when-NOT-to-expect-calculations (jeonse/mid-payment governed by guarantee agencies, jeonse-return being document-based). Routing guidance is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral context: borrower type is a user declaration the server does not adjudicate (echoed in inputs_declared), the output is a ceiling that banks may cut further, DSR swings sharply with rate_type (default '변동' being the worst case), and the agent must relay uncertainties/disclaimer rather than assert 'N억까지만 된다'.

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?

The purpose is front-loaded and the boundary list is dense and useful for a 17-parameter domain tool, so the length is largely earned. Minor flaws: the circled-number marker ③ is used twice and the third bullet restates guidance already present in the schema, adding slight redundancy.

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 compensates well: it names expected response pieces (inputs_declared echo, dsr.by_rate_type comparison table, desired.credit_room_after_mortgage, footnotes, uncertainties, disclaimer) and explains what changes appear in the output (e.g., maturity adjustment surfaced in the response). An agent has enough to call it and to interpret the result.

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 description coverage is 100%, so the per-parameter semantics (rate_type axis, stress_stage limited to non-metro, credit_loan_10k traps, desired_loan_10k judging) are already carried by the schema. The description largely restates those same caveats rather than adding new parameter meaning, so the baseline of 3 applies.

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?

The opening sentence states a specific verb and resource (deterministically computing the mortgage regulatory cap) and enumerates the concrete outputs: LTV cap, metro/regulated-area price-band caps (6/4/2억), 30-year maturity cap, stressed-DSR max loan, and which rule is binding. It even anchors the canonical user question ('10억 집, 생애최초, 연소득 8천이면 얼마까지 나와?'), and names the siblings it is not (realty_policy_rules, realty_presale_funding_plan).

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?

It gives explicit routing: this is the seat for 'how much can I get' questions, while rule tables go to realty_policy_rules, regulated-area status to topic=regulated_area, acquisition-tax rates to topic=acquisition_tax, and time-phased presale funding to realty_presale_funding_plan. It also states a clear exclusion — the result is a regulatory ceiling, not an approval or commitment.

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

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

Annotations only cover the read-only/idempotent profile, but the description adds substantial behavioral context: scores are labeled unverified reference values with 82% of transit scores ≥90 and no discriminative power, null means unmeasured (not 0), school score is a v5 composite not school assignment, complex_key is normalized to a single space, and missing complexes yield not_found with a no-fabrication rule.

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?

Dense but front-loaded: the bolded 'location_facts first' directive leads, followed by field contents, caveats, and sibling routing. Some parenthetical asides (30km rural examples, v5 composition) add length, but nearly every sentence carries information an agent needs.

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 carries the full burden and delivers: it names the response container (location_facts), the specific sub-fields, the score_demotion flag, and the fallback behavior. Nothing essential for correct invocation is missing.

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, but the description genuinely adds meaning beyond the schema — it explains the region-alone case (region aggregate + top-5 complexes by score, with ranking citation forbidden) versus complex_key/complex_name (complex rows, raw values for the first 5), which the schema only states tersely.

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+resource (returns raw location facts — nearest subway name/line/distance, station/bus-stop counts, school counts, hospital/mart counts) and explicitly contrasts itself with the unverified reference scores in the same row. An agent can distinguish it from realty_poi_nearby and realty_search_complexes without opening any schema.

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?

Explicit routing: use realty_search_complexes once for multiple complexes (rank by price_per_exclusive_m2), use [paid] realty_poi_nearby for facility name-level lists, and do NOT call this tool for reputation/resident reviews. It also states when-not (no ranking by score, no '역세권/학군 좋음' verdicts) and the not_found fallback.

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

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

Adds substantial non-obvious behavior beyond the readOnly/idempotent annotations: publication cadence differs per series, the latest month varies by series (M2 lags one to two months), and meta.series_as_of in the response is the authority rather than any date in the description. This is exactly the kind of operational caveat annotations cannot convey.

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?

Purpose is front-loaded in the first sentence, then the freshness warning, which earns its length given the real risk of misquoting a lagged series. Slightly verbose in restating the no-hardcoded-dates rationale, but nothing is wasted.

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 usefully points at meta.series_as_of but does not otherwise describe the returned shape (e.g., date/value structure). For a two-param, read-only, default-everything tool with full schema coverage, this is nearly complete.

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 description coverage is 100% — the schema already enumerates every indicator key, units, the 1~240 month range, and the reject-unknown-names behavior. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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 resource — retrieving monthly time series for named macro indicators (한국 기준금리·KOSPI·M2, 미 연준금리·S&P500). It is distinguishable from trend/market siblings by being macro-level and cross-country, though it never names a sibling tool explicitly.

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 a clear use context ('금리가 집값에 어떤 영향?'류 배경 분석용) and concrete do/don't guidance about freshness — don't quote a lagged series as the current rate, always state the series' as-of point. No explicit alternative-tool routing, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavioral content beyond them: the default 6-month window, that nationwide windows drop oldest months and surface this in meta.truncated / meta.truncated_note, and that region restores the full window. It does not mention the '유료' (paid) cost/auth implications flagged only in the title.

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?

Front-loaded with the combined purpose, then layered detail on output keys and windowing. Sentences are dense but each covers distinct information (response keys, window default, truncation semantics); no filler.

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 carries responsibility for return shape and does so partially by naming the unsold_completed and unsold_sigungu keys and the meta.truncated fields. It stops short of describing the sentiment-index output structure, but the annotations and 100% schema coverage cover the rest.

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 description coverage is 100% and the schema already documents months (including the truncation caveat and 1-36 range), region, sigungu, and include_footnotes. The description largely restates the schema's own param behavior (default window, sigungu separate key), so it adds only marginal value over structured fields.

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 specific verbs and resources: querying unsold-inventory trends (미분양) and the market sentiment index together, framed as a macro buy-timing signal. The scope is concrete enough to distinguish it from pure price tools, but it never names a sibling (e.g. realty_macro_indicators or realty_supply_demand_balance) that an agent might confuse it with.

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?

Implies usage via '매수 타이밍 판단의 거시 신호' and explains the months/region window tradeoff, which is useful operational guidance. However there is no explicit when-to-use versus alternatives, and no statement of when another tool would be preferable.

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

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

Annotations already cover read-only/idempotent/open-world, so the bar is lower, and the description still adds substantial behavioral context: it declines to assert without a declaration, admits '판정 불가 실토' when 인가일·착공일 data is missing, and flags the 부칙 trap plus the separate 토지거래허가구역 regime. No contradictions. Slightly short of 5 only because it leaves response-shape specifics to '전하라' without describing the output it will actually return.

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?

Front-loaded with the core judgment and the concrete example before the boundary list. The four numbered boundaries and the sibling-routing sentence are dense but each earns its place by preventing a misuse; only mild verbosity keeps it from a 5.

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?

For a deterministic multi-factor legal judgment with no output schema and 100% schema coverage, the description supplies everything an agent needs: inputs to declare, what the tool will and will not judge, the addendum edge case, the separate permit-zone caveat, and where to route adjacent questions. Nothing material is missing.

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, but the description adds real meaning beyond the schema: it explains that region/project_name auto-join the Seoul stage list, that project_name matches only unique matches, that outside Seoul project_stage must be declared, and that re-declaring the returned stage reproduces the same judgment. That elevates it above the schema-only baseline.

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 resource (조합원 지위양도 승계 가능 여부) with the exact legal basis (도시정비법 39조 2항) and the three-way determinant (투기과열지구 × 사업유형 × 단계). The '한남3구역 지금 사도 입주권 나와?' framing makes the concrete decision it renders unmistakable and separates it from sibling policy tools.

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?

Explicitly routes alternatives: realty_policy_rules for statute text, realty_redevelopment for project lists/stage, realty_redevelopment_entitlement when subscription eligibility itself is uncertain, and topic=regulated_area for designation status. It also states scope exclusions (소규모정비사업 not judged, exceptions handed off as forks).

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

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

Annotations only declare read-only/idempotent safety; the description adds the substantive behavioral facts: the default window points forward from today, the dataset is a lower bound because notices precede move-in by ~30 months, and meta.window_direction / reading.interpretation must be honored in conclusions. The 세종 2028~2030 undercount incident concretely demonstrates the failure mode, and the no-double-counting rule between the notice and pipeline axes is stated.

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?

The opening sentence '지역의 입주 예정 물량을 연월별로 집계한다' is duplicated verbatim as the first two lines, and the window-direction warning is restated in both the description body and the from_ym/months schema text. The content is valuable and the core routing is front-loaded, but a third of the text is redundant.

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?

No output schema exists, yet the description surfaces the response fields an agent actually needs — by_sido, reading.interpretation, coverage.region_recent_annual_rate, meta.window_direction — along with the interpretation rule and the cross-tool follow-up. Nothing needed to call it correctly or read it correctly is missing.

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% and the parameter descriptions already carry much of the window-direction and to_ym/months exclusivity detail, so the description largely reinforces rather than originates that. It does add genuine semantics beyond the schema — the region-vs-sigungu contract divergence from realty_supply_pipeline and the double-counting caveat on include_pipeline.

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 resource — aggregating expected move-in supply (입주 예정 물량) by year-month for a region — and explicitly contrasts its contract with realty_supply_pipeline (region accepts 시군구/동 there but only 시도 here). An agent can route between the two without opening either schema.

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?

Names the triggering question types ('입주장 리스크 있어?', '내년에 입주 물량 얼마나 쏟아져?'), forbids per-sido loops by pointing to the by_sido response field, and prescribes the fallback (call realty_supply_pipeline or set include_pipeline=true) when the lower-bound reading looks thin. Alternative routing is explicit in both directions.

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

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

Annotations only supply readOnly/idempotent/openWorld, but the description discloses far more: the response shape (recent rows + stats with sample count, price, composition), the silent-failure mode where a mistyped property_type still returns HTTP 200 with populated rows backed by a dated QA incident, the 도시형생활주택 gap with its urban_housing_notice signal, and that aggregation excludes 지분/해제 rows. These are exactly the traps an agent cannot infer from structured fields.

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?

Front-loaded and forceful — the exclusion and the routing alternatives come first, and bolding makes the decision points scannable. It is longer than needed: the '아파트는 이 도구가 아니다' exclusion is restated four times across description and schema, which is defensive reinforcement rather than new 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?

No output schema exists, and the description compensates by explaining what comes back (recent transactions plus stats, by_area_band distribution, footnotes toggled by include_footnotes, note/urban_housing_notice). With 7 parameters, one enum, and zero nested objects, nothing an agent needs to call and interpret this tool correctly is missing.

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% and the schema itself already repeats the apartment warning on property_type and the house/전용면적 caveat on area_band, so much of the parameter text is duplication. The description still adds cross-parameter meaning the schema lacks: the land 면적 기준 (계약면적·지목·용도지역), the rule that share_type='지분' rows must not be used for per-area price comparison, and the 'don't call this just to narrow by 동' guidance on region.

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+resource (빌라·오피스텔·단독주택·토지의 매매 실거래가 조회) and immediately scopes what it is NOT (아파트는 이 도구가 아니다). It names the sibling tools that own the apartment axis (realty_region_price_stats, realty_search_complexes, realty_complex_pyeong_price), so an agent can route without opening any schema.

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?

Explicit when-to-use and when-not: '질문에 아파트가 있으면 여기서 멈추고 아파트 축으로 가라' with the three named alternatives and the specific question each answers. It also adds the reverse exclusion (동 단위로 좁히려고 이 도구로 오지 마라) and states the domain limit (매매 데이터만 있다 — 전월세를 물으면 데이터가 없다고 답하라).

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behaviour, so the bar is lower. The description still adds real operational context: the 64KiB truncation behaviour, meta.truncated/meta.omitted_sections with re-fetch arguments, the unverified_source_text fallback path, and the requirement to cite notice_version plus page numbers.

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?

Front-loaded with purpose, then usage, then the truncation caveat. There is some redundancy — the phrase about extracting/verifying from the original notice is repeated in the opening two paragraphs — and the block is dense, but every remaining sentence carries actionable 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?

For a 7-parameter tool with no output schema and complex fallback paths, the description covers the important edges: truncation recovery, unverified text warning, citation discipline, and the sibling tools to use for what it lacks. The only gap is that the general shape of a non-truncated response is not described.

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 would be 3. The description goes beyond the schema by clarifying that keyword doubles as a brand token ('자이', '힐스테이트') and returns total_matched, and by explaining section-name variance across notice versions and the text_query/text_pages/text_pages_only interplay.

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+resource — a fact sheet (팩트시트) extracted and verified from the original 입주자모집공고 — and enumerates the exact data it holds (resale/re-win restrictions, per-floor price table, option prices, interim payment schedule). This is clearly distinguishable from realty_notice_text (raw page text) and realty_presale (listing data).

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?

Explicitly names the question types that belong here, routes detailed clause reading to realty_notice_text, routes builder-level sales records to realty_builder_presale_record, and forbids fabrication for values not present. It even states the counting use case ('자이 브랜드 공고 몇 개야?') via keyword.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds real behavioral context beyond them: table pages may be misaligned by pdftotext so columns must not be over-asserted, the response is capped at 6 pages, meta.matching_pages always carries the full hit list, and pages_only is silently ignored when pages is given (reported via meta.pages_only_ignored). This is strong disclosure, though the fallback mechanics of the 0-page case are only sketched.

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?

Purpose is front-loaded and the dense body is almost all actionable (conflict error, table caveat, page cap, pages_only-first workflow). It loses a point because the opening line is effectively repeated ('원문을 쪽 단위로 읽어 준다' then '원문을 쪽 단위로 읽는다'), a wasted sentence in an otherwise tight definition.

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?

For a 5-parameter read tool with no output schema and no nested objects, the description covers everything needed to call it correctly: return size limit, where the full matching-page list lives, error naming, fallback behavior, and the pages_only-first workflow. Nothing material is left for the agent to guess.

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 description coverage is 100%, so the baseline is 3 and the schema already documents match, pages, query, pages_only and house_manage_no. The description still adds semantic value the schema does not: the AND semantics of multi-word queries with concrete examples, the workflow of using pages_only to pick pages before narrowing with pages, and the documented fallback result set when a query returns 0 pages.

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 resource ('입주자모집공고문 원문을 쪽 단위로 읽는다') and scopes it to page-level reading of the recruitment notice original. It distinguishes itself from the fact-sheet sibling by saying the details absent from 팩트시트 (특별공급 소득·자산 기준, 부적격 처리, 계약 유의사항) are exactly what this tool is for, so an agent can separate it from realty_notice_facts.

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?

Explicit routing: use this when the fact sheet lacks detail, use pages_only=true first when the page is unknown, and if 0 pages come back, narrow with per-word hits / partial-match pages or widen via match='any'. It also names the query-vs-pages tradeoff and the conflict error, covering when-not and alternatives rather than leaving them to inference.

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

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

Goes far beyond the read-only annotations: cumulative sample from 2026-06-01, only successful bids enter the ratio, sample_period/ledger is authoritative (not a fixed window), ratio_missing means unknown not zero, median vs inflated mean (386% outlier), and region is parsed from property names with stated coverage (96.1% overall / 90.0% successful bids).

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?

Front-loads the core question and the sibling distinction before the caveats, and the bolded warning blocks are scannable. It is long and repeats the region-coverage point across description and schema, but nearly every sentence carries an actionable constraint for a trap-heavy statistical tool.

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 and a complex statistics surface, the description supplies the missing return semantics (sample_period, outcome_mix, ratio_missing, median/p25/p75, region_basis) and the sampling caveats an agent needs to interpret and cite results correctly.

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% and each parameter is already richly documented, so the baseline is 3. The description adds rationale not in the schema — that omitting property_type yields a near-wrong number (31.6% vs 106.3%) and that region filtering silently drops unparsed rows, pointing back to region_basis.

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 the specific question it answers (공매 낙찰가율 and 유찰 rate from actual 개찰 결과) and immediately distinguishes itself from the same-named sibling realty_auction_sale_rate, explaining the denominator/valuation differences. It also positions itself on the 공매 axis against realty_search_onbid.

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?

Explicit routing instructions: if the user asks about '경매 낙찰가율', confirm which axis is meant; for individual items and per-round minimum prices use realty_search_onbid; read the rate split by property_type. When/when-not and the alternative tool are both named.

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

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

Annotations cover read-only/idempotent/open-world safety, but the description adds the crucial non-structured fact that this is a paid ([유료]) tool, which is the key cost decision an agent must weigh against free siblings. It does not describe rate limits or result volume, but the cost signal is the meaningful addition.

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 tight paragraphs: purpose first, coordinate source second, alternative-tool routing third. The paid tag is front-loaded and every sentence carries routing or sourcing 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 supplies the essential inputs source, scope, and sibling distinctions an agent needs. It could say more about result shape or limits, but nothing critical is missing for correct invocation.

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 description coverage is 100%, so the schema already documents lat/lng source, poi_type combinations, and radius bounds. The description restates the coordinate source but adds no syntax or behavioral detail beyond the schema, so the baseline 3 applies; note the description's mention of 마트 slightly overstates the schema's three coordinate-searchable types.

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 resource (조회 of nearby POI by coordinates), names the concrete facility categories, and specifies the output ordering (거리순). It is clearly separable from realty_location_scores and realty_poi_stats by the stated purpose.

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?

Explicitly routes the agent: use this when a facility list with per-name distances is needed; use the free realty_location_scores for nearest-station distance and in-radius counts; use realty_poi_stats for non-coordinate categories. It also names the upstream tool that supplies lat/lng.

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

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

Annotations already declare readOnly/idempotent/openWorld/destructive=false, so the safety profile is covered. On top of that the description discloses a genuine data-coverage limitation (지방 시군구 may return 0 due to collection scope) and instructs how to phrase results, which is real behavioral context not present in any structured field.

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?

Purpose is front-loaded in the first line, followed by the region-key rule and the zero-value caveat. Every sentence carries distinct information; the only slight cost is the somewhat fragmented multi-paragraph layout for a two-parameter tool.

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?

For a read-only, two-parameter tool with no output schema, the description covers purpose, region key format, limit behavior is handled by the schema, and the key interpretation pitfall (zeros). Nothing critical to a correct call is missing, though return shape is only implied.

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 goes beyond the schema by specifying the exact region key format ('시도축약 시군구' 2 tokens, 세종 as 1 token), which is format guidance the schema does not state, and reinforces that empty input means nationwide.

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?

The first sentence gives a precise verb and resource: counts of hospitals, schools, and subway stations aggregated per 시군구, scoped as a paid tool. The '지역 간 인프라 비교용' framing implicitly separates it from the per-POI sibling realty_poi_nearby, though no sibling is named explicitly.

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?

States the use case clearly (cross-region infrastructure comparison) and gives a meaningful usage constraint: don't interpret 0 counts as absence because collection is centered on 수도권/광역시. It stops short of naming an alternative tool or an explicit when-not-to-use condition.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds crucial behavioral context beyond them: it does not make determinations, it surfaces uncertainties and disclaimer, it warns against hardcoding rates, and it explains that applicable_if/exceptions require user confirmation. These are meaningful disclosure points for a reference tool with no output schema.

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?

The description is long, but it is front-loaded with purpose and then organized around examples, alternatives, caveats, and exclusions. Given the tool's 26-topic scope and the number of sibling calculators it must route away from, the length is largely justified, though some topic-list detail overlaps with the schema.

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?

For a complex, multi-topic reference tool with no output schema, the description is nearly complete: it explains citations, confirmation dates, uncertainties, disclaimer, non-judgment behavior, and sibling boundaries. It does not fully describe the actual response structure, but it provides enough to call the tool correctly.

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 description coverage is 100%, so the very detailed query/topic/section descriptions already carry parameter semantics. The tool description itself adds little about how to use these parameters beyond general routing, so the baseline 3 is appropriate.

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?

The description states a specific verb+resource: it provides general real-estate regulations (tax rates, regulated areas, loans, leases) with citations, independent of any complex. It explicitly distinguishes itself from calculator and case-analysis siblings, so an agent can tell what belongs here without opening the schema.

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?

It gives concrete when-to-use examples ("취득세 얼마야?", "갱신권 썼는데 집주인이 팔면?") and explicit when-not-to-use routing to realty_loan_limit, realty_subscription_score, realty_redevelopment_burden, realty_capital_gains_tax, realty_member_transfer_check, and several case-specific tools. Usage is unusually well-scoped for a policy-reference tool.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial non-obvious behavior: a fixed 1-month horizon that ignores the months param, honest refusal outside coverage, measured error rates (2-4x off for new builds, 16.3% exceeding ±10%), and mandatory relaying of caution/as_of_ym/disclaimer. This goes well past what annotations convey.

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?

Purpose and the required-identifier rule are front-loaded, and each subsequent sentence carries a distinct operational fact (horizon limit, refusal cases, rerouting, mandatory field relaying). It is dense rather than padded, though the length is near the upper bound for a description.

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 compensates by naming the response fields an agent must surface (predictions[].caution, as_of_ym, disclaimer) and the footnotes behavior toggled by include_footnotes. Nothing needed to call or report this tool correctly appears to be missing.

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 description coverage is 100%, so the schema already documents each field, making 3 the baseline. The description nonetheless adds what the schema cannot: an at-least-one-of complex_name/complex_key constraint (the schema shows 0 required params) and the dependency on realty_complex_report to obtain complex_key.

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+resource+scope: predicting next month's average sale price by pyeong band via a named model version. It is clearly distinguished from similar siblings like realty_complex_pyeong_price (current price) by explicitly framing the output as a forecast for 익월.

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?

Explicitly states the alternative and the condition: if multiple complexes share a name, resolve with realty_complex_report first and call with complex_key. It also defines when the tool will NOT answer (under 3 monthly transactions in 3 months, brand-new complexes with no history) and routes the agent to 실거래 도구 in that case.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), and the description goes far beyond them: apply_status/apply_status_text are pre-judged against meta.today and must not be re-derived, rank1_result=published-false means unknown (not 'no competition'), unsold_history absence is not proof of no history, and regulation flags are announcement-date snapshots that must not be asserted as current. This is unusually rich disclosure.

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?

Front-loads the purpose and the answer-shaping rule (status='접수중') before the caveats, and every paragraph maps to a real failure mode. It is dense and long, with some redundancy against the schema's own parameter descriptions, but no sentence is filler.

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?

No output schema exists and the tool has 9 params with layered output fields, yet the description explains the returned status fields, the rank1_result semantics, the unsold_history caveats and the routing fields (meta.today, house_manage_no, question_routing). Nothing an agent needs to call or interpret it is missing.

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, but the description adds interpretation beyond the schema: status and upcoming are mutually exclusive and status supersedes upcoming, notice_kind='접수마감' switches the response from a list to per-complex 회차 집계, and price_min/price_max are per-house-type extremes. Much of this is mirrored in the schema, so it is not fully additive, but the aggregation behavior adds real meaning.

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?

Opens with a specific verb+resource (아파트 청약(분양) 공고를 조회한다) and enumerates the returned fields (분양가·접수 일정·당첨자 발표일·입주 예정·위치). It also names the siblings it is NOT — realty_presale_vs_market, realty_subscription_odds, realty_presale_price_trend, realty_notice_facts — so an agent can separate it without opening any schema.

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?

Explicitly routes questions: '오늘/지금 접수 가능한' → status='접수중', upcoming=true only covers pre-start notices, '넣을 만해?' → hand off to realty_presale_vs_market, 경쟁률 → realty_subscription_odds, 추이 → realty_presale_price_trend, 원문 규제 → realty_notice_facts. When-to-use and when-to-use-something-else are both stated.

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

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

Annotations already declare readOnly/idempotent/no-destructive, so the description focuses on domain behavior: minimum-3-sample suppression of percentiles, '표본 부족' verdict being the answer, unknown 중도금 meaning undetermined rather than interest-bearing, per-year coverage gaps, and 전용면적 vs 공급면적 axis mismatch. These are non-obvious traps that materially change interpretation, though return shape/pagination is not described.

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?

Content is valuable but lengthy and repetitive — the opening restates the same 5-axis comparison twice (once in prose, once as a numbered list), and several caveats repeat across sections. Front-loading is good, but the busywork sentences dilute it.

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?

Complete for a no-output-schema analysis tool: it covers what the tool returns (5-axis values plus percentile, or slice distribution alone), the sample-size gate, and the routing to siblings. Missing only return shape details and how the 'slice distribution only' mode is triggered (e.g., which params).

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% (baseline 3), and the description adds semantics beyond the schema: keyword vs house_manage_no may yield candidate list, region is background-only and not a conclusion basis, sigungu vocabulary form, and the uniform filter applied to all cells. Adds real meaning but the schema already carries the per-param detail.

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 (견준다/compare), resource (분양 공고), and scope (same sigungu·same pyeong, 5 named axes), and explicitly frames itself as a cross-sectional comparison across notices versus sibling tools that handle individual facts, text, market fit, or trends.

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?

Explicitly names the four alternative siblings (realty_notice_facts, realty_notice_text, realty_presale_vs_market, realty_presale_price_trend) and states what each covers so the agent can route correctly. Also states the when-not conditions: don't draw year-crossing trends, don't fall back to background (시도) values, don't use market comparison alone.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the calculation is deterministic on the factsheet, defaults assume standard tax rates while 중과·감면 live in realty_policy_rules, and — critically — it instructs the agent that assumptions must be surfaced to the user. It stops short of describing return shape in detail, but the disclosure of the assumption-handling obligation is valuable.

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?

The core purpose and boundary are front-loaded well, but the text is dense with self-referential asides (신고 #43의 선 그대로, 실측 124만원) that add persuasion rather than actionable content. Several parentheticals could be dropped without losing invocation-relevant meaning, so it reads as verbose rather than tight.

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?

For a 7-parameter, no-output-schema financial calculation, the description supplies the missing context: deterministic vs. personal-parameter split, assumption disclosure duty, and the sibling that owns each excluded concern. It also hints at return shape ('행마다 한 줄 요지' vs footnotes), which is enough given no output schema. Minor gap: no explicit note on which parameters are needed to get a meaningful result when all are optional.

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 description coverage is 100%, so every parameter (keyword, house_ty, movein_ym, mid_rate_pct, house_manage_no, extra_options_krw, include_footnotes) is already documented in the schema with defaults, ranges, and cross-tool hints. The description adds only the general note that rates may differ from the default; it does not extend parameter semantics meaningfully, so the baseline 3 applies.

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 a precisely bounded resource (분양 한 건의 층별 총 소요자금), then enumerates the exact components: 분양가·발코니·중도금이자·취득세. The agent can immediately tell this apart from sibling cost tools like realty_presale_funding_plan without reading any schema.

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?

Explicitly draws the boundary: it computes only what is deterministically derived from the notice + tax law, and names the alternatives for everything outside that line — realty_complex_rent_by_pyeong for jeonse prices, realty_presale_funding_plan for loan/funding judgment, realty_policy_rules for the tax table itself. This is a textbook when/when-not/alternatives statement.

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

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

Annotations only establish read-only/idempotent safety, but the description adds substantial behavior the annotations cannot: judgment is deterministic and locked to current regulation and current own funds (no projection of future rates/regulation/savings), borrower type and income are user declarations rather than server-verified facts, output is not an approval or commitment, and parallel 시세·전세 scenarios appear only when declared.

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?

Purpose is front-loaded in one sentence and the numbered ①–⑤ boundary block is easy to scan. It is dense and the opening sentence is echoed by the title, which costs a little, but essentially every clause carries routing or constraint 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?

For a 22-parameter, no-output-schema tool this is complete: it covers the required inputs' contract (house_manage_no, own_funds_10k, borrower), the movein_ym dependency, the conditional scenarios returned (scenario_at_expected_price, jeonse_scenario), and the assumptions/uncertainties the response carries. Nothing needed to call it correctly is missing.

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, but the description adds cross-parameter meaning: own_funds_10k is modeled as fully deployed from 계약금 to 잔금 (0 is valid and honestly fails at the 계약금 gate), borrower/credit_loan share the realty_loan_limit contract, and rate_type's 변동 default is the most conservative stress case. These interpretive notes go beyond the per-field schema text.

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+resource+scope: deterministically judges whether one presale closes with own funds + loans at each stage (계약금→중도금 회차→잔금), including the loan's regulatory cap check. It explicitly positions itself against siblings (realty_loan_limit engine, realty_presale_cost, realty_presale_vs_market, realty_policy_rules), so an agent can distinguish it without opening the schema.

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?

Names the exact question it answers ('이 분양 당첨되면 진행 가능해?') and enumerates five boundaries, including explicit when-not routing: savings planning, 갈아타기 strategy and purchase-appropriateness are out of scope, price comparison goes to realty_presale_vs_market, and the raw rule table to realty_policy_rules. It also tells the agent to relay assumptions/uncertainties.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description goes well beyond by defining the metric basis (분양평 평당 최고 분양가, 만원/평, excluding 발코니 확장·유상옵션) and disclosing a statistical caveat about median instability when the housing-type mix differs by year. This is genuine analytical behavior an agent cannot get from annotations alone.

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?

Bold header lines and a front-loaded purpose are good, but the opening sentence '같은 지역 분양 공고들의 연도별 평당 분양가 추이를 낸다' is then repeated verbatim in the second paragraph, which is pure redundancy. The philosophical framing around 기다림의 비용 earns its place, but the duplicated lead-in does not.

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?

For a 5-param, all-optional, no-output-schema tool, the description covers method, caveats, sibling positions, and filter usage. It stops short of describing what the returned time series looks like (e.g., yearly buckets, price units per row), which an agent producing downstream answers would benefit from.

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, but the description adds real semantic guidance: exclusive_m2_min/max pins the pyeong band (국평=80~85), and it directs neighborhood/district-level analysis to keyword. It even flags the sigungu contamination caveat. Minor gap is it doesn't explain region scoping in detail.

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?

Starts with a specific verb+resource: '같은 지역 분양 공고들의 연도별 평당 분양가 추이를 낸다'. It then distinguishes itself explicitly from two siblings (realty_presale_vs_market for individual-announcement appropriateness, realty_region_price_stats for 실거래 trend) by declaring '이 도구는 분양가끼리의 시계열이다'. An agent can route correctly without opening the schema.

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 explicit when-to-use framing ('지금 넣을까, 기다릴까' — cost-of-waiting axis, especially for 재당첨 제한 decisions) and when-NOT-to: 'announcements가 1~2건인 연도는 추이로 읽지 말고'. It also names the correct alternative tool for adjacent questions, so the agent knows both the selection and the exclusion conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds substantive beyond-schema behavior: which baseline gap_pct uses (nearby_baseline vs regional average), that regional average is always separately in gap_pct_region_avg, that baseline_divergence flags a large split, and an explicit prohibition on calling something 'expensive' off the regional average when the baselines diverge. It also discloses the candidate-list / multi-call interaction and the truncation behavior.

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?

Front-loaded with the purpose, then pivots to notice identification, baseline semantics, and sibling routing in a logical order. It is dense and every section is load-bearing, though a few meta phrasings ('this is the tool's reason for existing', 'a dead end otherwise') could be trimmed without losing meaning.

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?

For a 7-parameter, zero-required tool with no output schema, the description names the key returned fields (gap_pct, gap_pct_region_avg, baseline_divergence, price_trend, comparison_truncated, footnotes) and explains the two-baseline logic an agent must not misreport. It stops short of a full return-shape description, but the critical interpretation rules are present.

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, but the description adds real meaning: it explains the region+keyword fallback ordering, that house_manage_no is the most precise identifier, and that pyeong defaults to the top 5 by household count and can be used to re-fetch types dropped into comparison_truncated. That is operational semantics the schema alone does not convey.

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 computation: comparing a presale notice's price against nearby actual transaction prices, per housing type, and frames it as a quantitative answer to 'is this presale worth applying to'. It explicitly carves out boundaries against realty_subscription_odds (competition rate), realty_area_price_bands (regional cross-check) and realty_presale_price_trend (time series), so an agent can distinguish it without opening schemas.

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 an explicit decision procedure: if house_manage_no is absent, search by region+keyword, and if multiple notices come back, pick one from the candidate list and re-call rather than guessing. It also routes adjacent questions — 'should I apply' to realty_subscription_odds, regional verification to realty_area_price_bands, and 'wait or buy now' trends to realty_presale_price_trend.

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

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

Annotations already cover readOnly/idempotent/destructive/openWorld, but the description adds substantial behavioral context beyond them: coverage gaps (meta.coverage.not_covered), cache freshness semantics (meta.freshness), truncation/total_matched, and the crucial 접수예정 vs 접수중 distinction. It warns not to interpret 0 results as 'no recruitment', which is real operational guidance.

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?

Front-loaded with the core scope in the first sentence, then example questions, then a bulleted '결론에 반드시 옮길 것' block. Appropriate for a tool with several caveats, though some points (rental type enumeration) overlap the title and schema.

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 carries the return-value burden and does so: it lists returned fields (유형·지역·진행상태·마감일·남은 일수, source_url), sort order, and meta fields (total_matched, truncated, freshness, coverage, next_offset). Combined with annotations covering safety, nothing needed to call it correctly is missing.

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 description coverage is 100%, so the schema already documents region, keyword, rental_type, limit, offset thoroughly (including 광주 disambiguation and keyword scope). The description largely restates the rental types and does not add parameter syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.

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?

Specific verb+resource (마감 전 공공임대 모집공고) with the source enumerated (LH 행복주택·국민임대·영구임대·통합공공임대·공공임대·매입임대·전세임대). An agent can tell this apart from sibling notice tools (realty_notice_facts, realty_notice_text) because the scope is recruitment notices, not notice text/facts.

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?

Provides concrete example questions ('행복주택 모집 공고 있어?', '서울 청년 전세임대 지금 신청돼?') that clearly delineate when to use it, plus explicit when-not scope (자격 판정 안 함, SH·GH·iH 미포함). It lacks named sibling alternatives to route to, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly/idempotent/openWorld), so the description earns credit for adding context beyond them: the exact scoring formula, the explicit disclosure that feasibility factors (용적률, 대지지분, 안전진단, 조합 단계) are excluded, and the requirement to relay the response disclaimer verbatim. Auth/cost implications of '[유료]' are only implied by the title, not explained.

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 tightly packed sentences, front-loaded with the purpose, then the formula, then the limitation. Every sentence carries information the agent cannot get from the schema or annotations; nothing is padded.

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 does enough to set expectations: it reveals the score composition, that ranking is national-by-default, and that the response carries a disclaimer. It could say more about the shape of the returned list (fields, ordering guarantees), which is the one remaining gap for a tool with no output schema.

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 description coverage is 100%, so the schema already documents limit, region, and district (including the region/district synonymy). The description adds no parameter-level guidance (e.g. how to format a district, or what happens when limit is large), so the baseline of 3 is appropriate.

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?

The description names a specific verb and resource ('재건축 후보 스크리닝 상위 단지를 조회한다') and even enumerates the exact ranking inputs (building age + 12-month transaction percentile). It is precise about what the tool returns, but it never distinguishes itself from the closely named sibling realty_redevelopment, so an agent must guess which one to pick.

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?

It gives a clear scope boundary: '후보 발굴용이지 투자 판단 근거가 아니며' explicitly tells the agent this is for candidate discovery, not investment judgment, and instructs relaying the disclaimer. What's missing is naming the alternative sibling (e.g. realty_redevelopment or realty_remodel_feasibility) that would be appropriate for feasibility questions.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description goes beyond them by disclosing Seoul-only source coverage, that 세대수·준공예정 are null, and that ~2% of rows have a blank stage meaning '단계 미상' not '진행 없음'. These are genuinely useful data-quality and scope caveats. However it does not describe result ordering or how paging interactss with the filters, so it is strong-but-not-exhaustive.

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?

Front-loaded with the core capability and caveats, and mostly dense with no filler. The one inefficiency is the near-duplicate opening line ('[유료] 서울시 정비사업… 목록을 조회한다' repeated as '…목록 — 사업명·유형…'), which costs a sentence.

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 takes on the job of describing returns (사업명·유형·진행 단계·위치) and pre-empts the obvious failure modes (fabricating null household/completion values, misreading blank stage, answering for non-Seoul regions). For a 7-param read tool with annotations already covering safety, this is complete enough to call correctly.

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% and the schema already maps every enum (stage, project_type) and alias (region/sigungu), so the description's restatement of the filterable fields adds little new meaning. Baseline 3 applies when the schema carries the parameter burden; no extra semantics or format hints are supplied.

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 resource ('서울시 정비사업 사업장 목록을 조회한다') and enumerates the returned fields (사업명·유형·진행 단계·위치). It names the sibling it does NOT cover — realty_reconstruction for 유망도 점수 and realty_member_transfer_check for 승계 — so an agent can distinguish it without opening any schema.

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 concrete triggering questions ("○○구 재개발 어디까지 진행됐어?", "면목동 재개발 어디 있어?"), states the filter dimensions (region/dong/project_type/stage), and explicitly limits scope ('타 시도는 이 도구로 답할 수 없다고 밝혀라'). It also routes two adjacent intents to their correct tools, which is full when/when-not/alternative coverage.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial behavior the schema cannot convey: inputs are declared and unverified by the server, the formula is common practice rather than statutory, 비례율 keeps changing until completion, and the caller must relay the response's sensitivity and disclosures. This is exactly the added context the annotations leave open.

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?

Front-loaded with the purpose and formula, then numbered boundaries; every section carries real information. Slightly verbose with the title/description overlap and the ①②③ scaffolding, but no padding sentences.

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 carries the return burden and does so by naming the sensitivity and disclosures fields. Combined with the formula, the declared-input caveat, the volatility warning, and sibling routing, an agent has everything needed to call and present results correctly.

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 description coverage is 100%, so the schema already documents each parameter, including optionality of 비례율 and the fallback to the three project-total inputs. The description's formula shows how parameters combine into output, but adds no syntax, units, or edge-case detail beyond 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 concrete verb and two concrete outputs (권리가액, 추가 분담금) and gives the exact formulas that produce them. It also differentiates from siblings by routing formula provenance to realty_policy_rules(topic=redevelopment_rules) and eligibility questions to redevelopment_entitlement.

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?

Explicitly names the question this tool answers ("감정평가 3억에 비례율 98%면 얼마 더 내?") and gives concrete when-to-use-elsewhere rules: go to redevelopment_rules for the formula source, redevelopment_entitlement first if sale eligibility is uncertain. It also warns that results are unstable before 관리처분인가.

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

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

Goes well past the read-only/idempotent annotations: region matching is token-exact and ambiguous names are rejected with candidates rather than guessed, rental silently uses all-pyeong data and discloses it via warning_pyeong_fallback, top_n returns window highs (not all-time highs), cells under 3 samples are suppressed with a count of omissions, and post-baseline windows are incomplete due to the 30-day reporting deadline.

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?

Front-loaded and sectioned with bold headers, but bloated well past what an agent needs: the rental/pyeong fallback caveat is repeated verbatim across five parameter descriptions and the body, and internal changelog artifacts (ticket IDs T-2026W34-352, S364, dates, a truncated trailing sentence) add noise rather than selection signal.

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?

For an 11-parameter, output-schema-less tool this covers what an agent needs to call it correctly: unit handling, metric-specific degradations, ambiguity rejection protocol, aggregation-vs-list behavior, sample-size suppression, and window limits.

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 earns more by adding a cross-cutting rule the schema fragments do not state (put the unit the user spoke in, the server converts; ㎡ values in pyeong params are rejected with reasons and two exits) and by explaining the by_dong/compare_from window interactions.

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+resource+granularity (지역 아파트 실거래 시세 월별 추이 조회) and immediately positions itself among three 시세 tools, naming realty_area_price_bands (level/quote) and realty_search_complexes (specific complex) as the alternatives with the conditions that select each.

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?

Explicit routing rules for every branch: monthly flow → this tool; price level quoting → bands; specific apartment → search_complexes; per-dong comparison → by_dong instead of per-dong calls; per-pyeong rental → realty_complex_rent_by_pyeong; listing questions → top_n. It also states what to do when a name is rejected (re-ask with the returned candidate list).

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

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

Beyond the readOnly/idempotent annotations it discloses genuinely behavioral facts: the price metric is volume-weighted with a 5-transaction minimum and the latest month may still be in progress, and transit/school are suspended as of 2026-09-26 because scores above 90 covered 86.7% of cases and lost discriminating power. The one gap is that with no output schema, the description never says what a row actually contains beyond 'methodology 산식·단위', leaving the response shape implicit.

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?

It is front-loaded with the trigger questions and the sibling routing before the metric glossary, which is the right ordering. It loses a point for a redundant opening — "시군구 순위를 … 축으로 조회한다" is immediately restated as "지역(시군구) 순위를 조회한다" — and the metric block is dense enough to need a second read.

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?

For a 6-parameter, enum-driven ranking tool with no output schema, the description covers what each metric means, which metrics are currently unavailable and why, and where to go instead. Minor omissions remain: default ordering/limit behavior and what the returned rows look like are left entirely to the schema.

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, but the description earns more by explaining *why* each metric is computed as it is — area_bucket removes pyeong-mix distortion within a single band, price uses dedicated-only pyeong price weighted by transaction volume, and investment pairs sale/jeonse within the same pyeong cell. That rationale is not recoverable from the enum strings alone.

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?

The description states a specific verb and resource (시군구 순위 조회) plus the axes it ranks on, and it explicitly separates itself from realty_compare_regions (rank/explore vs. head-to-head) and realty_rental_yield (region ranking vs. same-complex pyeong-level). An agent can route among these without opening any schema.

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?

It gives concrete trigger questions (제일 비싼 동네, 요즘 많이 오른 지역, 전세가율 높은 곳), names three alternatives with the exact condition that selects each (location_facts for 교통 좋은 동네, realty_compare_regions for A vs B, realty_rental_yield for 같은 평형·단지), and states what this tool is not for. Exclusions and alternatives are both explicit.

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

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

Beyond the read-only/idempotent annotations, it discloses meaningful operational behavior: cancellations and direct deals are excluded, building/floor composition within a complex is not corrected, and thin baskets make the value untrustworthy. It also tells the agent the response contains naive vs basket side by side and how to interpret the gap via composition_effect.

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?

The core definition and scope are front-loaded in the first sentence, followed by a rationale, output description, and caveats with bold labels that make skimming easy. It is somewhat long and the limitation sentence runs several clauses together, but each block carries distinct information rather than repetition.

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?

For a six-parameter analytical tool with no output schema, it covers the essential ground: what is computed, the data exclusions, the known unmodeled variance, and the named output fields (naive, basket, composition_effect, footnotes). The response shape is only sketched rather than specified, which is a modest gap given there is no output schema to fall back on.

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, but the description adds interpretation the schema does not: values are per-pyeong so pyeong-mix shifts inside a complex are absorbed, and narrowing pyeong_supply thins the basket and erases the tool's advantage, prompting the agent to check the returned complex count. Parameter mechanics themselves are still left largely 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?

The description states a specific, non-obvious operation: computing a regional price trend restricted to the same complexes that transact in both comparison windows, returning naive and basket values plus a composition_effect. It conceptually separates itself from the naive 'old monthly average' trend approach, but never names the actual sibling tool (e.g. realty_region_price_stats) that an agent would otherwise reach for, leaving the routing decision partly inferential.

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?

It gives clear context for when this tool is the right choice: when the sample is thin enough that composition churn dominates the regional average (illustrated with the 2026-08-14 Yongsan incident). However, it states no explicit exclusions and names no alternative tool for the cases where a plain average is fine.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld), and the description goes far beyond them: it discloses per-layer coverage rates (100% normative vs 11.2% structure-type mentions, 0% for completed apartments), warns that 'unknown' is not 'no', and states that coverage plus how_to_find_out always accompany the response. This is unusually rich behavioral context.

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?

Heavy but front-loaded: the two-axis framing and the 'model is confidently wrong here' hook come first, followed by coverage facts and the unknown-handling rule. The dense archive statistics earn their place by calibrating trust, though a few sentences could be tightened.

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 tells the agent what comes back (two layers, embedded coverage, how_to_find_out) and how to relay it. Nothing an agent needs to call this 3-parameter, zero-required tool correctly is missing.

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 description coverage is 100%, so the baseline is 3; the description adds meaning about how axis maps onto the two analytical layers and what an empty complex_name yields (normative-layer-only answer with its own validity). It reinforces rather than merely repeats the schema's parameter text.

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 judgment task (can this apartment be altered, on a wall axis and a plumbing axis) with the concrete questions it resolves. It differentiates itself from siblings by naming realty_policy_rules (full statute text) and realty_presale/realty_notice_facts (house_manage_no source), though the boundary with realty_policy_rules is slightly blurred since the normative layer's full text is said to live there.

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?

Lists the exact user questions it answers and explicitly says complex_name may be omitted (normative-only answer). It adds a negative rule (do not infer structure type from completion year) and directs the agent to how_to_find_out when values are missing, but offers no explicit 'use sibling X instead when Y' routing for the general case.

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

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.

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

Annotations already declare a safe read-only, idempotent profile, yet the description still adds substantial non-obvious behavior: past-due sale dates are not filtered by the backend, `sort=date_asc` yields a 60.7% past-date prefix with `meta.past_prefix_skipped`, and empty `items` with `has_more=true` does not mean no results. It also discloses per-row provenance risk (`min_bid_source` court_schedule vs item_list, with staleness rates) — exactly the kind of context annotations cannot carry.

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?

Front-loads purpose, then routing, then caveats, so the highest-value information comes first and nearly every sentence carries an operational fact. It is nonetheless long, with three bolded warning blocks and some restatement of unit rules already in the schema, so it is dense rather than perfectly tight.

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?

For an 11-parameter tool with no output schema, the description covers the essentials an agent needs: response field names (`past_auction_note`, `past_auction_count`, `min_bid_stale_risk_count`, `sample_period`), pagination behavior, and the summary-only nature of the listing. Nothing material to correct invocation is missing.

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, but the description adds cross-parameter semantics the schema cannot express: the `exclude_past=true` + `sort=date_asc` interaction and skipped-prefix bookkeeping, the offset/requested_offset/next_offset paging contract, and the `min_bid_source` caveat. Units (만원) and the '토지' rejection are also reinforced, though these partially restate schema text.

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?

Opens with a specific verb+resource+scope: filter court-auction items by region, type, appraised price and failed-bid count. It explicitly positions itself against siblings, naming `search` for natural-language queries and `realty_get_auction_case`/`fetch` for per-case detail, so an agent can route correctly without opening a schema.

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?

States when to use this tool vs alternatives with concrete conditions: NL one-liners go to `search`, detail goes to `realty_get_auction_case`, onbid goes to `realty_search_onbid`/`realty_onbid_sale_rate`, and discovery questions go to `realty_auction_alerts`. It even supplies the disambiguating signal (사건번호 formats `2025타경1234` vs `2026-0600-031235`) and warns against merging the two ledgers.

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