datagokr — 공공데이터포털 검색을 더 쉽게 (find data.go.kr datasets easily)

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the server does not store files and only returns a URL, request values, and a procedure, plus an enumeration of what is returned (access_kind, url/post_url/get_url, params, version_keys, message, page_url).

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 content is front-loaded and the '반환:' field list is useful, but the definition is bilingual with direct Korean/English duplication, so roughly half the text is redundant restatement. Every sentence would need trimming or consolidating to earn a 4-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 single-parameter, read-only tool with an output schema, the description is nearly complete: it covers purpose, the key non-storage behavior, and the return shape. The only meaningful omission is the semantics/format of dataset_id.

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 one parameter, dataset_id, with 0% schema description coverage and no enum. The description never explains what dataset_id is or its expected format; only the examples ('15028200', '15000001') loosely imply it is a numeric dataset identifier. This is a clear gap for the single required input.

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 ('Get client-side download instructions (URL, params, steps)') and adds a valuable negative constraint ('The server never stores files'), which clarifies it is not a file-transfer tool. It does not name or differentiate from the siblings (fields, get_preview, record, search, show), so the routing value is slightly reduced.

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 description implies context via examples ('15028200 전체 JSON 받는 법', '15000001 원본 파일 다운로드 주소'), which show the kind of question this answers. However, it never states when to prefer this over get_preview or search, nor any exclusions or prerequisites.

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 adds real behavior: AND semantics across all listed columns, reverse-index matching, dtype/org narrowing, and n capped at 20. It does not explain what 'group' does or what happens for zero matches, so it is strong rather than complete.

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 dense and front-loaded, with the routing rule first and details second. The Korean/English duplication doubles the length, but each version is tight 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?

For a read-only search tool with an output schema (so return values need not be re-explained), the definition covers the filtering semantics, the query constraint, and the result cap. The unexplained 'group' parameter is the one remaining 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 coverage is 0%, so the description must carry the load. It explains names (all columns required), dtype/org narrowing, and n's maximum of 20, which is genuine added meaning — but the 'group' boolean parameter is never mentioned, leaving one of five parameters undocumented anywhere.

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 ('Find datasets with ALL given columns') and immediately contrasts itself with the sibling search tool. It also names the distinguishing constraint (no topic, query fixed to empty string), so an agent can tell it apart from search 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?

Explicit when-to-use ('no topic', query pinned to empty string) and an explicit alternative ('for a topic use search(query, fields=...)'). Routing 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 only cover read-only/idempotent/open-world; the description goes well beyond by disclosing auth behavior (caller's own X-DataGoKr-Key may be needed, keys are never returned or stored), failure semantics (ok=false means retry later), and hard limits (max 50 columns/20 rows; Seoul/Gyeonggi public paths max 5 rows without a key). This is exactly the behavioral 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?

Purpose is front-loaded, but the entry is bloated: every statement is repeated in Korean and English, and a long enumeration of return fields (columns, rows, total, truncated, source_note, page_url, access_guide) duplicates the output schema that already exists. Significant 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?

Behaviorally rich for a complex multi-source preview tool, but it over-invests in return-value narration that the output schema already supplies while leaving both input parameters undocumented. Coverage is uneven rather than incomplete.

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, yet it never explains `dataset_id` or the `n` row-count parameter by name. Row limits are mentioned incidentally (5/20 rows) but the link to `n` is never made explicit.

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: view the actual first rows of a public-data-portal dataset, split by STD_FILE/PORTAL_FILE types. Clear enough to distinguish from a full download or field listing, though it never names its siblings (download_url, fields, record, search, show) to sharpen the boundary.

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 conditional routing hints ('OPEN_API→request_templates, LINK→url, STD 하위행→parent_id') and notes the key requirement for API fallback, which is useful. But it never says when to prefer get_preview over record/show/search, so the when-to-use guidance is only implied.

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, non-destructive, closed-world behavior. The description adds valuable context: it is allowlisted raw metadata for the local datagokr client, excludes internal state, and does not apply or store anything on the server. It stops short of error handling or rate-limit details, but the added disclosure is meaningful.

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 front-loaded, starting with what the tool does, then the alternative, then return fields and constraints. It is bilingual but not wasteful, and every section adds information, though listing return fields is somewhat redundant given the output schema exists.

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 purpose, usage, return fields, and non-mutation constraints, which is adequate for a simple read-only tool with an output schema. However, the required `dataset_id` parameter is completely undocumented, which is a significant gap 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?

The single required parameter `dataset_id` has zero description coverage in the schema, and the description never explains what the ID is, how to obtain it, or its expected format. The description fails to compensate for the schema gap, leaving the agent without semantic guidance for the only input.

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 ('returns') and resource ('raw metadata'), defines the scope ('lookup, application, download'), and differentiates from sibling 'show' by naming it as the normal-use alternative. An agent can immediately tell what the tool does and when another tool is preferred.

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 directs normal use to the `show` sibling and implies `record` is for raw metadata needs. This is a clear when-to-use/when-not-to-use rule with a named alternative, leaving little 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 already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavior: results are collapsed by topic via group=True and must be expanded with show, n is capped at 20, weird results should trigger a filter-free retry, and region gaps surface as region_gap/region_fallback. Return-format detail duplicates the existing output schema rather than adding to it.

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 remaining content is a tight bullet list where each bullet carries actionable guidance rather than filler. Minor waste comes from restating the Korean purpose line in English and from listing the return shape that the output schema already defines.

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, 0%-coverage search tool, the description covers query phrasing, filtering hints, grouping, result limits, retry strategy, and regional fallback, which is enough for an agent to call it correctly. The output schema removes any need to explain return values, and the only remaining gap is the precise syntax for org and dtype beyond the API/FILE hint.

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 whole burden and largely does so: query format is shown by example, fields is illustrated with fields=['위도','경도'], group's collapsing behavior is explained, n's ceiling is stated, and dtype is enumerated (API/FILE) with org identified as the agency filter. Only the exact accepted values/syntax for org are left unspecified.

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 gives a specific verb and resource ('Search Korean public datasets by topic'), scopes it to datagokr, and shows concrete query examples ('전국 주차장', '재난문자 API'). It also draws a boundary against the sibling 'fields' tool for column-only queries, so an agent can distinguish it without opening the 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?

It explicitly routes to alternatives ('컬럼만 조건이면 `fields` 툴', 'group_ids의 id를 show로 펼치세요') and gives practical conditions: retry after dropping filters, cap n at 20, split evaluation-style queries into 2-3 searches, fall back to region_fallback. It does not address when NOT to use search versus get_preview, record, or download_url, so it stops short of full when/when-not 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 declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: responses are trimmed to ~20KB, columns capped at 50, version_keys limited to latest 3, and a 'more' field describes follow-up retrieval. This concisely communicates truncation and drill-down 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?

The purpose is front-loaded, which is good, but the long enumerated return-field list is heavy and overlaps with the output schema. It's informative rather than wasteful, yet the bilingual duplication and field catalog make it longer than it needs to be.

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, the return-value enumeration is somewhat redundant, but the description usefully adds the trimming threshold and the operation-drill-down strategy, which the schema cannot express. It is complete enough for an agent to invoke correctly, with only the dataset_id parameter 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 well (accepts a function name or operation_seq to view a single operation's full fields), but says nothing specific about 'dataset_id' format or sourcing. Partial compensation only.

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: inspecting a selected dataset's schema and access methods ('데이터셋의 구조와 접근 방법을 봅니다'). It is clearly differentiable from siblings like search, get_preview, and fields, which handle discovery, row sampling, and field listing respectively.

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 show(id, operation='...') when an API has many operations, and 'get_preview' to check actual first rows when the dataset looks usable. This gives clear when-to-use context and names alternatives, though it doesn't state when NOT to use this tool.

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