datagokr — 한국 공공데이터 검색 (Korean public data search)

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the server does not proxy or store the file, it returns instructions (URL/params/steps) for the client to execute, and it enumerates the response shapes (access_kind, url vs post_url/get_url, params, version_keys, message, page_url). This prevents the classic mistake of assuming the call itself downloads data.

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 key claim ('server never stores files') and the core verb+resource are front-loaded, and the bilingual redundancy is mostly justified for a user-facing help tool. The return-field enumeration is somewhat expendable given an output schema exists, but the description is not bloated.

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 an output schema, the description covers the essential behavioral surprise (no server-side storage, instructions-only response) and shows realistic triggers. The only real gap is that the required dataset_id argument is never explained, which is the one thing an agent cannot infer for certain.

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?

There is exactly one parameter (dataset_id) and schema description coverage is 0%, so the description must carry the burden of explaining it. It never mentions dataset_id, its format, or where to obtain it; the numeric IDs appear only inside example user queries, which is indirect at best. The description instead spends its detail on return fields, which the output schema already covers.

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 English sentence states a specific verb+resource: 'Get client-side download instructions (URL, params, steps)'. It also pre-empts the most likely misreading by saying 'The server never stores files', which separates it from an actual file-fetch tool. No sibling tool is named, but none of the listed siblings (fields, get_preview, record, search, show) overlap in function.

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?

Usage is only implied through two sample queries ('15028200 전체 JSON 받는 법', '15000001 원본 파일 다운로드 주소'), which show the agent when such a request arises. There is no explicit when-to-use statement, no condition that selects this over get_preview or show, and no exclusions.

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 (readOnlyHint=true, destructiveHint=false). The description adds non-obvious behavior beyond that: AND semantics (only datasets containing every column), the inverted-index basis, narrowing via dtype/org, and a hard cap of n ≤ 20. It does restate return fields, which the output schema already provides.

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 routing rule (this tool vs. `search`) is front-loaded and the constraint/return details follow logically. Length is inflated by bilingual duplication of the same content and by listing return fields already in the output 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?

Covers the essential selection logic, match semantics, filter options, and result cap, which is sufficient for a read-only query tool with an output schema and annotations. The only real gap is the undocumented `group` parameter.

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 the load, and it mostly does: `names` requires ALL listed columns to match, `dtype`/`org` are narrowing filters, and `n` is capped at 20. The boolean `group` parameter is never mentioned in either place, leaving one gap.

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 (find datasets) and the exact scope constraint: ALL given columns present and no topic. It explicitly names the sibling `search(query, fields=...)` for the topic case, so an agent can distinguish 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?

Gives both when-to-use and when-not-to-use in one move: use this when columns are the only condition (query fixed to an empty string), and use `search` instead when a topic exists. The alternative and the condition selecting it are stated 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes beyond them: keys are never returned or stored, ok=false means the portal is temporarily unresponsive (retry later), and truncation is capped at 50 columns/20 rows. This is useful operational context for an agent deciding how to react to 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?

The key operational facts are reasonably front-loaded, but the content is duplicated in Korean and English ('ok=false: retry later. data means actual rows...' restates the Korean), and the return-field enumeration is long. It is serviceable but not 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?

An output schema exists, so the description need not enumerate return values, yet the key behavioral nuance (ok=false → retry, data present → real rows received) is genuinely additive. Combined with the source-type routing rules, an agent has enough to call and interpret the tool, though input parameter meaning remains a gap.

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% and neither parameter is described: dataset_id has no explanation of expected format, and n (default 5) is only indirectly implied by the '20 rows' truncation note without stating it controls row count or its cap. The description compensates with output-field semantics but leaves the two inputs essentially undocumented.

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 ('실제 첫 행 보기' / preview the actual first rows) and adds source-type routing (STD_FILE·PORTAL_FILE, OPEN_API→request_templates, LINK→url, STD 하위행→parent_id). It is clear what the tool returns, but it never names or contrasts itself with the sibling tools (download_url, fields, record, search, show), so differentiation relies on the reader inferring from the routing hints.

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/when-key-is-needed conditions: files are previewed without a key, only attachments the portal cannot preview require X-DataGoKr-Key, and API/link/subset cases return guidance instead of rows. It stops short of stating when NOT to use this tool or explicitly naming an alternative sibling to call instead.

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=true and destructiveHint=false. The description adds genuinely useful behavioral context beyond them: internal state is excluded and nothing is applied or saved server-side, so the agent knows this is a purely local, side-effect-free read.

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 message is front-loaded, but the same content is repeated in Korean and English, and the return-field list overlaps heavily with the output schema, so a meaningful share of the text is redundant rather than additive.

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, single-parameter tool with an output schema, the safety profile, scope, and alternative are all covered. Only the `dataset_id` semantics remain unexplained, which is a minor but real gap.

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% and the single parameter `dataset_id` is not explained in the description at all – no format, source, or where to obtain the id. With one undocumented required parameter, the description fails to compensate for the schema gap.

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 (returns raw metadata needed for viewing/applying/downloading) and explicitly scopes it to the local datagokr client. It also distinguishes itself from the sibling `show` by naming it as the preferred tool for normal use.

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 usage condition ('local datagokr package only') and an explicit alternative ('prefer `show` for normal use'), so an agent can route correctly without opening any schema.

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/non-destructive annotations, the description discloses non-obvious behavior: similar datasets are folded together under `group=True` and expanded via `group_ids` with `show`, `n` is capped at 20, synonyms are auto-applied (expanded_terms), and region_gap/region_fallback/scope_warning signals are emitted when regional data is missing or out of scope. This is substantive context the 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?

The bullet structure is scannable and the routing rule is front-loaded, but the entire content is duplicated in Korean and English, roughly doubling length. It also re-describes the return payload in the 반환 section even though an output schema exists, which is redundant by the stated criteria.

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 search tool with an output schema, the description covers routing, parameter meaning, folding/expansion mechanics, region fallback behavior, and the recommended next step (`show`). Nothing an agent needs to invoke or chain 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 description coverage is 0%, so the description carries the full burden, and it mostly succeeds: it explains `fields` (topic+column combination), `group` (folding behavior and default), `n` (max 20), `dtype` (API/FILE), and `org` (institution), plus the required `query` via worked examples. Only minor gaps remain (e.g., exact enum values for dtype).

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 in both Korean and English ("주제로 공공데이터를 찾습니다" / "Search Korean public datasets by topic") and immediately distinguishes itself from the `fields` sibling by scope: topic-based search vs. column-only filtering. An agent can separate `search` from `fields` 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 states the routing rule: topic + column constraints go here with `fields=[...]`, while column-only queries belong to the `fields` tool. It also adds concrete example queries and notes that supplying dtype (API/FILE) and org improves accuracy, covering both when-to-use and how-to-use.

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 (readOnlyHint=true, destructiveHint=false), but the description adds genuine behavioral traits: responses are trimmed to ~20KB, columns capped at 50, version_keys limited to the latest 3, and a truncated field reports what was cut. This is real context an agent needs to interpret partial 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?

Purpose is front-loaded and useful, but the same content is duplicated in Korean and English, roughly doubling length, and the return-field enumeration is largely redundant with the existing output schema. Adequate but not 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?

Since an output schema exists, enumerating return fields is not strictly required, yet the description still supplies the operation-selection workflow, the 20KB truncation caveat, and the get_preview handoff. An agent has enough to call it correctly; only minor edge cases (e.g. behavior when truncated) are left implicit.

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 the load. It explains the operation parameter concretely with syntax ('show(id, operation=\'기능명 또는 operation_seq\')'), clarifying it accepts either a name or a sequence. dataset_id is only implicitly covered, which keeps this from 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 specific verb and resource in both Korean and English: inspect a dataset's schema and access methods ('데이터셋의 구조와 접근 방법을 봅니다'). An agent can immediately distinguish this from search (discovery), get_preview (row data), fields, and record.

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 selection context ('검색에서 고른 데이터셋' – a dataset picked from search) and routes to a sibling: use get_preview to check the actual first row. It also explains the when-to-use for the operation parameter (when an API has many operations). It lacks an explicit 'when not to use', so not quite a 5.

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