contract-compass

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

Annotations only declare readOnly/idempotent/non-destructive, and the description goes far beyond them: it enumerates the deterministic checks (90-day period, 3% threshold, 15%/10% single-item thresholds, method selection, advance-payment deduction), lists all five verdict values, and explains that the two tracks are independent so a sub-3% rate can still yield single_item_only. It also discloses what is deliberately null and which items are excluded (not_applied), which is exactly the behavioral context annotations cannot supply.

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 one-line purpose and the critical non-capability before the detail, and it uses bolding to route the eye. It is nonetheless long and repeats threshold/exclusion caveats in multiple places, so a small amount of text does not earn its place.

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 14-parameter tool with no output schema, the definition still describes the response surface (verdict enum, computed.track, why_null, computed_skipped, footnotes) and warns about the two-track independence and unfilled exceptions. Nothing an agent needs to call this correctly or interpret the result 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 only 7%, so the description must carry the load, and it does: the Args block documents every parameter's meaning, format ('YYYY-MM-DD'), edge rules (last_adjustment_date must fall between contract_date and check_date; negative rates allowed for reductions; advance_payment_ratio rejects <0 or >1 as invalid_advance_ratio), and the semantic distinction between adjustment_base_amount and single_item_base_amount. This is meaning well beyond the bare schema titles.

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 immediately bounds the scope by declaring what it cannot do ('이 도구는 조정률을 산정하지 못한다'). The example user questions ('90일 지났나', '단품 조정 되나') make it unmistakable versus the law-search and delay-penalty siblings.

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 trigger phrasings for when to call it and a strong negative rule ('없는 값을 지어내지 마라', pass the user-computed rate instead). It does not name sibling alternatives (e.g. get_law_article for the underlying statute text), so routing to alternatives is left implicit rather than resolved.

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 readOnly/idempotent annotations: it discloses the conditional-output mechanism (`vendor_conditional_candidates` when counterparty status is missing), the law-currency signal (`law_currency`, `status` not 'verified' → `note_currency`/`laws_not_verified`), silent-drop reporting via `ignored_inputs` with `kind="price_out_of_band"` and `applicable_bands`, and the ignored-selection path (`selection_ignored_reason`). This is exactly the non-obvious behavior an agent needs in order to interpret results correctly.

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?

Structure is good — purpose first, then output-behavior caveats, then an Args block — and each paragraph carries real information. It is nonetheless a long, dense wall of prose with some repetition (the '플래그를 세워라' warning restated for each enterprise type) 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?

With no output schema, a 20-parameter surface, and a two-stage call protocol, the description supplies what is otherwise missing: the names and meaning of returned fields (`follow_up_questions`, `final_recommendation`, `practice_alternatives`, `ignored_inputs`), the stateless two-step flow, and the legal-document versioning caveat. An agent can make a correct first call and a correct follow-up call from this text alone.

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 only 5% across 20 parameters, so the description must carry the load — and it does, defining near every argument: contract_type values, the service_type/construction_specialty cross-type rule, each status flag with its threshold and legal basis, `product_contract_kind` (manufacture vs purchase affecting 실적제한), `negotiation_reason` including the precise meaning of 'rebid_failure' vs 'small_repeat', and the `{question_id: value}` shape of `follow_up_answers` plus the naming caveat for `small_enterprise_restriction`.

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+mechanism: '계약방법 결정론 판정 — 룰엔진이 적용 가능한 계약방법 후보와 법령 근거를 반환.' It states both the action and the deliverable (candidate contract methods plus statutory citations), which clearly separates it from the sibling law-lookup and penalty-calculation 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?

Gives concrete when-to-use rules: set `is_women_enterprise`/`is_disabled_enterprise`/`is_social_enterprise` when the user names those statuses, do not infer counterparty status but ask the user, and call again with `follow_up_answers` to obtain `final_recommendation`. It also tells the agent what NOT to do (don't put service_type on non-service contracts, don't guess bid_notice_date). Sibling alternatives are never named, 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 declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that inapplicable contract-kind combinations are rejected with ground_not_applicable rather than silently dropped, that filtered items surface in grounds_excluded_by_contract_kind and day_count_rules_excluded, and that it deliberately does not adjudicate eligibility. It also warns about quote_truncated citations, missing corpus originals (general_conditions_in_corpus, admin_rule_version_in_corpus), and forbids fabricating administrative-reply URLs — exactly the failure modes an agent would otherwise fall into.

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, then usage order, then the caveat block, so the structure is sound and each bolded paragraph carries a distinct warning. It is long and dense with dated parentheticals and corpus-versioning detail that could be trimmed, but little of it is genuinely 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?

There is no output schema, so the description has to explain return shape — and it does, naming verification, general_conditions_article_ref, admin_rule_version/issue_no/issued/effective, grounds_excluded_by_contract_kind, day_count_rules_excluded and quote_truncated. For a read-only lookup with two params, nothing an agent needs in order to call it and interpret the response 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 0%, so the description must carry parameter meaning, and it largely does: contract_kind is tied to the same value as estimate_delay_penalty, mapped to a general-conditions family, with a warning that the actually-incorporated conditions are the source of truth; ground is described as selecting one ground for detail and defaulting to the full list for that contract kind. It further notes that the ground list is a cross-type enumeration that must sometimes be narrowed by contract type. It stops short of explaining the individual enum values beyond sw_requirement_change.

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 precise verb+resource in the first line — a map of grounds for excluding days from the delay count — and immediately scopes it against the sibling ('estimate_delay_penalty가 정하지 않는 부분'). It also names the three things it returns (ground list with source quotes, must_establish facts, ministry precedents), so an agent can distinguish it from estimate_delay_penalty 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?

Gives concrete triggering questions ('동절기 공사중지 기간도 지체일수인가', '관급자재가 늦게 와서'), an explicit when-NOT ('이 도구는 해당 여부를 판정하지 않는다'), and an ordered workflow: narrow grounds here → confirm must_establish with the user → feed excluded_days into estimate_delay_penalty, including the halving rule for sw_requirement_change. This is the when/when-not/alternative triad done explicitly.

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?

Far beyond the annotations: it reveals deterministic application, that undeclared excluded_days produces a '미선언' warning (vs. explicit 0 producing none), that counted_days carries a disclaimer, that the 30% cap is date-gated by contract_end_date, and that inferred rates are flagged. With readOnlyHint/idempotent already covered, this is substantial added context, though the openWorldHint implications are not discussed.

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 headline, then bolded pitfalls, then a response-field list, then Args — a sensible reading order with no filler. It is long, and the response-field block is dense, but with no output schema each line carries real information rather than padding.

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?

Nine parameters, an 11%-covered schema, and no output schema — the description fills all three gaps by documenting arguments, enumerating return fields (term, rate, base_amount, cap, amount, warnings, legal_basis), and flagging the disclaimer behavior. An agent can call this correctly without further lookup.

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 only 11%, but the Args section compensates for nearly every parameter: conduct_kind maps 1:1 to rate rows, org_type forbids guessing because rates differ, contract_amount must be per-year for long-term contracts, excluded_days accepts halves only in 0.5 increments with an explicit 3일→1.5 example and rejects other decimals, and contract_end_date explains the cap's effective dates. This is exactly what a low-coverage schema needs.

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 names a specific verb (산정/calculate) plus the exact resource (지체상금/지연배상금), and immediately states the governing rule set — statutory rate, base amount, 30% cap. It even distinguishes the national vs. local terminology split, which no sibling could be confused 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?

Explicit exclusions are given: the tool does not fix delay days, and disputed exemption grounds are routed to search_references. It also mandates confirming org_type with the user before calling. It stops short of naming the closest sibling (delay_exemption_guide), which would have made the routing 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond that: exact error codes and their meaning, that source_url/existence_verified are null/false on failure, that missing bodies cannot be distinguished from nonexistent IDs, and an explicit instruction not to fabricate citation links.

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 nearly every sentence carries operational weight, but the heavy inline bolding and long parenthetical error discussion make it denser and less scannable than ideal.

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 steps in to name the key return fields (source_url, existence_verified, headnote_available, headnote_partial, headnote_note, body_excerpt, referenced_laws) and explains their semantics, so an agent has what it needs to interpret results and handle failures.

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 0%, so the description must carry the burden, and it does: it defines kind as the enum drawn from search_cases results and case_id as the numeric serial number from search_cases, explicitly warning that a 사건번호 is not valid here.

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 ('판례/해석례 본문 조회') and enumerates what it returns (판시사항·판결요지·참조조문 for prec; 질의요지·회답·이유 for expc). It also implicitly distinguishes itself from search_cases by requiring case_id from that sibling's results.

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 precondition that case_id must come from a search_cases result and routes the agent back to search_cases if it does not. Error-specific guidance (case_body_unavailable, case_id_invalid) further directs behavior, though there is no general 'when not to use this tool' 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 declare readOnly/idempotent/openWorld; the description adds far more: the 6,000-character truncation threshold with the exact disclosure fields, the two-corpus split, `notes` semantics including the `deleted_stub` type, `assumption` guessing behavior, `law_currency` staleness states, and 404 `law_in_corpus` meaning. Each of these is a behavioral trait the agent could not 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 with the core behavior and then segmented by bold headers keyed to failure modes, which keeps a very long description navigable. It is longer than ideal — the truncation field list and some response-field detail are restated at length — but almost every sentence maps to a distinct agent mistake, so little is truly 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 and a single opaque parameter, the description must carry both invocation and interpretation, and it does: return shape (`kind`, `notes`, `truncated`, `delegations`, `law_currency`), error shape (`article_not_found` + `corpus_laws`), and citation caveats are all covered. Nothing an agent needs to call and correctly report this 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 coverage is 0% and the schema gives `ref` no description at all, so the description carries the full burden — and it does: it gives three concrete ref formats (article, 별표, 예규), explains abbreviation expansion ('국계법 영 50조'), and documents the paragraph/item/mok suffix behavior that drives `requested_paragraph`/`requested_item_found`/`requested_mok_found`.

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 names a specific verb and resource ('법령 조문 원문 조회') and the body makes clear it also serves 별표 tables and 행정규칙 articles via the same single `ref` argument. It names sibling tools (search_law, get_law_article_asof, search_references) at the points where confusion is likely, so an agent can tell which tool to call.

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?

Extensive when-to-use guidance: re-call with a paragraph suffix when `truncated` is true, follow `implementing_note` refs directly instead of searching again, read `delegations[].how` before answering on delegated values, and route to law.go.kr when `in_corpus` is false. It also states explicit prohibitions (don't cite deleted_stub articles, don't claim 'no rule exists' on out-of-corpus), which is exactly the alternative-routing an agent needs.

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 read-only/idempotent safety, but the description discloses far more: full response field semantics (effective_date, is_current, covered, versions_complete), four distinct error modes (asof_not_covered, article_not_in_version, law_body_unreadable, ref_missing_article), and the explicit rule that no nearest approximation is returned. This is unusually rich behavioral 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-loaded with purpose, then bolded sub-sections for errors and edge cases; every block earns its place given the many failure modes. It is dense and long, but the length is justified by the tool's complexity rather than padding.

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 fully documents the return fields and every error path, plus the future-date and uncovered-date caveats. An agent has everything needed to call it and interpret the result without guessing.

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 0% (no parameter descriptions), so the description must carry the burden, and it does: ref is defined as an article or annex reference with three concrete formats ('국가계약법 제27조', '주택법 시행령 제26조', '주택법 시행령 [별표 4]'), and date is specified as 'YYYY-MM-DD' or 'YYYYMMDD' with a usage example (계약 체결일).

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 explicitly contrasts itself with the sibling get_law_article ('get_law_article은 항상 현행이다'), so an agent can tell them apart immediately.

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 trigger condition ('계약 체결·입찰공고·처분 시점이 과거이면 반드시 이 도구를 쓰라') with three concrete examples (지체상금률, 부정당업자 제재, 감사·분쟁 대응) and names the alternative. Nothing is left 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?

Annotations only say readOnlyHint=false and non-destructive; the description adds substantial context beyond that: both the arguments and the user's prior tool-call summary are persisted server-side for operator review, a privacy policy URL is given, PII must be generalized, and the user must be told what will be sent. It also discloses the response shape (ref number and reply_path) and the contact-handling 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?

It is long but well-organized: front-loaded purpose, then '쓰는 때' / '쓰지 않는 때' sections, then an args block. A few sentences restate the same prohibition (don't call unprompted / don't call before answering), which is mild redundancy for a tool this consequential.

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 write-ish tool with no output schema, the description covers invocation conditions, consent flow, data-persistence notice, PII handling, and return fields (ref, reply_path). Nothing essential to calling 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 0%, so the description carries the full burden — and it does: every one of the six parameters is explained, all nine category enum values are glossed in Korean, contact has a 200-character limit plus a consent prerequisite, and related_tool/related_query/expected are tied to reproduction of the problem.

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 line states a specific verb+resource+scope: relay bug reports/improvement requests/inquiries to operators, and only when the user explicitly asks. This clearly separates it from the sibling tools (search_law, get_case, estimate_delay_penalty, etc.), which are legal-research/calculation tools rather than feedback channels.

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 'when to use' triggers with quoted user utterances ("신고해 줘", "운영자에게 알려 줘") and explicit 'when not to use' rules (don't call just to leave a question; don't call before answering). It also specifies the consent fallback — ask "운영자에게 전해 드릴까요?" once and don't re-ask on refusal — which is exactly the routing logic an agent needs.

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/non-destructive, so the safety profile is covered; the description goes much further by disclosing response fields (searched, retried, body_scope_caveat, axis, off_topic_warning, relevance_floor, unseen_cnt) and the exact conditions that produce them. That is substantive behavior beyond the annotations. However the volume of conditional caveats is large enough that an agent must parse many paragraphs to extract the operating rules, and several are restated rather than distilled.

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 two lines are well front-loaded, but the body is very long and dense with bold markup, release version tags (2026-08-29, 1.74.0, 1.78.6, 2026-11-04) and repeated restatements of the 'do not say there are no precedents' rule. Each paragraph carries a distinct caveat, so little is pure waste, but the version stamps and duplicated warnings dilute scannability.

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 tool has many conditional response shapes, so the description must explain return semantics — and it does, covering search_scope, case_no_lookup, axis boundaries, off_topic_warning, axis_unjudged, relevance_floor flags and truncation. Given the tool's complexity, an agent has enough to interpret results and to avoid overclaiming.

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 0%, so the description carries the full burden and does: query length bounds with named error codes (query_too_short/query_too_long), acceptance of natural-language sentences with up to 2 automatic retries, top_k allowed range 1–10 with clamping semantics and the top_k_applied disclosure field, and kind's three values with prec/expc meanings and the default. This is meaning the bare enum and integer schema do 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?

Opens with a specific verb+resource (판례·법령해석례 검색) plus the data source and freshness guarantee (law.go.kr 실시간 조회, 항상 현행). It explicitly routes the follow-up to the sibling tool get_case(kind, case_id), so an agent can separate search from fetch 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?

States the triggering situation concretely — disputes, 처분취소, interpretation arguments where 조문 alone is insufficient — and gives the alternative path (get_case for the full text) and an out-of-scope route (국세법령정보시스템 for 예규). It also names what NOT to conclude from 0 results, which is guidance about interpretation rather than just invocation.

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/open-world; the description adds far more: two separate corpora, automatic axis selection, top_k clamping, deleted-article notes, degraded semantic search, unverified currency warnings, and specific error codes (no_corpus_match, named_law_in_other_axis) with how to respond to each. Nothing contradicts 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?

Purpose and the sibling exclusion are front-loaded and bolded, but the body is a very long wall of text mixing response-field semantics, error handling, and internal changelog dates like '(2026-08-29)'. The total_found / complete / truncated / total_found_is_lower_bound distinction is restated across several sentences and could be compressed 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?

There is no output schema, so return fields must be explained and they are: corpus, note_corpus, implementing_articles, delegated, related_articles, table_hits, search_scope, degraded, note_currency, and the truncation flags. Combined with error-code handling, an agent has what it needs to call and interpret 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 0%, so the description must carry every parameter and it does: query examples ('수의계약', '시행령 제26조', '소득세법 제55조'), top_k default 8 with allowed 1–20 and out-of-range correction surfaced via top_k_applied, and corpus values "contract"/"tax" including what happens when omitted.

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: returns article snippets by keyword or article number, top_k results. It immediately distinguishes itself from search_references by declaring that only statutes (법률·시행령·시행규칙·별표) are searched and 계약예규 are excluded, so an agent can route 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?

Explicitly says when NOT to rely on it: contract-execution practice questions (설계변경·물가변동·기성·준공·지체·계약보증) are majority 예규 and should go to search_references first or together, with a measured statistic. It also routes follow-up work to get_law_article and even says not to re-search when implementing_articles is present.

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?

Discloses far beyond the readOnly/idempotent annotations: 5~20s cold-query latency and its reranking cause, degradation signals (retrieval_degraded, off_topic, rerank_degraded, search_unavailable error), result-shaping behaviors (guide_demoted, local_excluded, navigation_excluded), and freshness metadata (as_of, as_of_unknown, superseded_risk, vintage_warning). Nothing here contradicts the annotations, and the caveats about what must not be inferred ("없다"로 옮기지 마라) are exactly the behavioral context 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 and sibling differentiation are front-loaded, and the dense caveat paragraphs use bold labels so they are scannable. It is long, but with no output schema most of the response-field guidance has nowhere else to live; a few passages (e.g. the rerank/local+rrf explanation) run longer than needed for the operational takeaway.

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 search tool with only two params, no output schema, and heavy result-shaping behavior, the description covers what an agent must know: scope boundaries, degraded-mode interpretation, freshness/versioning risk, ranking overrides, and which sibling to fall back to. Nothing material is left to inference.

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 0%, so the description must compensate and does: query gets a natural-language example ("적격심사 낙찰하한율 50억 미만") and implicit hinting that keywords like '지자체'/'감사원' change retrieval, while top_k gets default, hard range 1~12, and out-of-range clamping semantics with the top_k_applied disclosure. This is meaning the bare integer/string schema cannot 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?

Opens with a specific verb+resource+scope ("공공계약 코퍼스 통합 검색 — 법령+계약예규+조달청·행안부 세부기준+실무가이드") and immediately distinguishes itself from the sibling search_law ("search_law가 법령 조문 전용인 것과 달리"). It also states the negative scope (세법은 이 도구가 못 본다), 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?

Explicit when-to-use ("낙찰하한율·적격심사 배점·실무 절차 등 법령 본문 밖 질문"), explicit when-not and alternative (세법 질문은 search_law 또는 get_law_article), plus recovery instructions (지자체 질의 재호출, top_k 늘리기, 같은 질의 반복 금지). Alternatives are named by sibling name and paired with the condition that selects them.

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