kosis_citation

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

No usable annotation flags are verifiable in this context, so the description carries the transparency burden. It adds genuine behavioral context: the KOSIS two-layer (STAT_NM/TBL_NM) structure, the caller-driven layer choice, and the accessed-date requirement for dataset citations. However, it never states what the tool returns (citation string? formatting?), whether the operation is pure/read-only, or any failure behavior — gaps for a 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?

Purpose is front-loaded, and the ⚠️ block economically steers the agent away from overuse by naming alternatives. The layer-semantics paragraph is the longest section but is justified because it determines citation structure. The trailing Args line is minimal; each sentence earns 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 3-parameter, no-nested, no-output-schema tool, the description covers purpose, usage conditions, and layer semantics well. But because no output schema exists, the description should explain the return value, and it does not; two of three parameters also remain under-documented. Adequate for a simple auxiliary tool, with clear gaps.

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 document parameters; it explicitly covers only 'accessed' (YYYY-MM-DD and why it is needed). The two-layer discussion indirectly hints at what 'id' refers to (a table or survey), but the 'style' parameter is never mentioned and no enum/default guidance exists — a meaningful gap for a citation-formatting tool.

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: '통계표 하나를 서지(인용) 칸으로 투영한다' — projecting one statistical table into a citation field, explicitly marked as an auxiliary feature. It also names sibling tools (kosis_search for metadata, kosis_data for numbers) as the mainline, which differentiates this tool without requiring an agent to open other 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 (only when handing off to a bibliographic management tool) and when-not-to (when the goal is using statistics, kosis_search and kosis_data are the main tools). It further instructs the caller to choose the citation layer — container_title for the survey layer, title for the table layer — leaving no ambiguity about selection criteria.

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