Koreanics: Korea law, Acts and bills in English

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

Annotations already declare readOnly, idempotent, non-destructive, and not open-world, so the safety profile is covered. The description adds the useful behavioral detail that it returns facts for a single bill, but says nothing about what happens for an unknown bill number (null, empty, or error).

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?

A single well-structured sentence that front-loads the identity of the resource and then lists the return fields. Efficient, though the colon-separated field list is slightly dense.

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?

Given one totally documented parameter, a clear annotation set, and no output schema, the description is complete enough for an agent to call it correctly. It could disclose the not-found behavior, but that is a minor 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 100% and the schema already carries the seven-digit format with an example, so the description adds little on parameters. It reinforces that the lookup key is the bill number, but the schema does the heavy lifting; baseline is around 3-4 with no additional 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 (get) and resource (National Assembly bill) keyed by an exact identifier, and enumerates the returned facts. The scope ('by its bill number') distinguishes it from search_bills, so an agent can route between them without inspecting 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?

The phrase 'by its bill number' implies this is the lookup path once you already have an identifier, which tacitly contrasts with search_bills. But no explicit when-to-use or when-not-to-use guidance is offered, so the routing must be inferred.

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 closed-world, so the safety profile is covered. The description adds useful return-shape context (plain-English explanation, version date, official Korean source link) and the 'where available' caveat signaling the explanation may be absent. It does not say what happens for an invalid law or article number.

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?

A single front-loaded sentence that packs the content type, language, scope and returned fields with no filler or 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?

With no output schema, the description usefully enumerates what comes back (English text, explanation, version date, source link). It is nearly complete for a simple two-parameter lookup; only error/absence behavior is left unaddressed.

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% — both 'law' and 'article' are documented with slug format and numbering examples, and 'law' even cross-references list_laws. The description adds no parameter 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 (get/fetch) and resource (one article of a South Korean statute or enforcement decree) with the scope 'one article', which cleanly separates it from the plural sibling search_law_articles. An agent can tell what this returns 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?

Usage is implied: fetch the full text of a single article once the law slug and article number are known. However, it never states when to prefer this over search_law_articles or list_laws, nor any prerequisite such as resolving the slug first.

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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context. It does add the return payload fields (title, date, summary line, URL), which is useful since there is no output schema, but it says nothing about pagination, rate limits, or ordering beyond 'most recent'.

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?

A single sentence with no filler; the resource and its scope are front-loaded, and the return fields are appended compactly rather than as a separate list.

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 simple two-optional-parameter read tool with no output schema, the description covers purpose, the two result kinds, and the returned fields. The only gap is that it does not say what happens if no briefs exist or how results are ordered.

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 both the enum for 'kind' and the limit bounds/default are already documented. The description's 'or Weekly Briefs' phrasing loosely maps to the enum values but adds no syntax, formatting, or behavioral detail beyond the schema, 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?

Names a specific resource (Koreanics Bill Briefs / Weekly Briefs) and a scope qualifier (most recent), and glosses what a bill brief actually is. It is clearly distinct from every sibling (get_bill, list_laws, search_bills, etc.), though it is phrased as a noun phrase rather than an explicit verb+resource.

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: the mention of two brief kinds tells the agent this tool spans both, and the schema supplies the default (bill). There is no statement of when to prefer this over search_bills or get_bill, nor any exclusion or prerequisite.

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=false, so the safety profile is covered. The description adds useful content context (English-language scope, version in force, translation counts) but says nothing about pagination, result size, or ordering 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?

A single compact sentence with no filler, front-loading the resource scope before the returned fields. It is a noun phrase rather than a full statement of action, but every element 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 read-only, zero-required-parameter list tool with no output schema, the description usefully enumerates the returned fields, compensating for the missing return specification. Only the absence of usage/alternative guidance keeps it from being fully 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% and the single optional 'area' parameter is fully documented in the schema, including an example value. The description adds nothing about filtering by area, 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 description names a specific resource (South Korean statutes and enforcement decrees available in English) and enumerates the fields returned, so the agent knows what this tool surfaces. It lacks an explicit verb and does not distinguish itself from the sibling search_law_articles, so it falls short of the 5 bar.

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 when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as search_law_articles or get_law_article. The agent must infer from the name alone that this is a browse/list operation rather than a filtered search.

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, closed world), so the description's job is to add scope detail — and it does, disclosing the matching fields and the return contents (stage, dates, topic tags, URL). That is meaningful context an agent could not derive from the annotations alone; pagination/ordering behavior is the only notable omission.

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?

Two tight sentences with zero filler; the search scope is front-loaded and the return fields are compactly enumerated at the end.

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 appropriately names the returned fields and clarifies the searchable corpus. Combined with 100% schema coverage on the three parameters, an agent has nearly everything needed; what is missing is only minor (result ordering, behavior when query matches nothing).

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 query, stage and limit are already documented in the schema, setting the baseline at 3. The description reinforces that queries are English keywords but adds no syntax, matching, or stage-filter semantics 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 specific verb (keyword search) and resource (bills), and narrows the searchable surface to 'English titles and one-line summaries', which tells the agent exactly what text is matched. It does not name or distinguish itself from the sibling search/get tools by name, but the scope statement is concrete enough to place 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?

Usage is implied rather than stated: the 'English titles and one-line summaries' scope implicitly warns that non-English queries or full-text body matching will not work, and the tool's nature suggests it is the discovery step before get_bill. However, there is no explicit when-to-use, when-not, or pointer to an alternative sibling.

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 closed-world, so the safety profile is covered. The description adds useful behavioral context beyond that: the result shape (matching articles with a short snippet and URL) and the fact that only English text is searched.

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, front-loaded with the core purpose and scope, followed by return shape and the alternative-tool pointer. No filler or 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?

No output schema exists, and the description adequately covers the return format (snippet and URL) plus the English-text constraint. It is complete enough for an agent to call correctly, though a note on result ranking or empty-result behavior would add polish.

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 all three parameters (query, law, limit) are already documented in the schema, including the law slug source and limit default. The description adds no syntax, format, or default details beyond what the schema provides, 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+resource with scope ('Keyword search over the English text of South Korean statutes and enforcement decrees') and names the database. It also distinguishes itself from the sibling get_law_article by clarifying that this returns only snippets, not full text.

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 to get_law_article when full text is needed, which is a clear alternative with a condition. It does not address when to prefer search_bills or list_laws, but the resource distinction (statutes vs bills) is implied by the scope statement.

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