kschoolinfo

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description adds real context beyond them: weekend/holiday gaps in coverage and the flagging semantics of the allergies input. It stops short of describing response shape or what happens when a date falls on a holiday, which would be the final increment.

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 with zero filler; the resource and its scopes come first, the allergy behavior second, and the availability constraint last. Nothing is redundant with the title.

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 discloses what each dish carries (calories, macros, allergens). For a read-only lookup tool this is nearly complete; only the behavior on holidays or empty ranges is 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 100%, so all six parameters are already documented in detail (date formats, enums, code sources, allergy list). The description restates the allergy-flagging behavior and date scopes but adds no syntax or format detail beyond the schema, 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 (school meal menu for breakfast/lunch/dinner) plus the time scopes it supports and the data fields returned (calories, macronutrients, allergens). This is clearly distinct from siblings like get_schedule, get_timetable, and get_school_info.

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 actionable use context: pass the user's allergies to flag matching dishes, and note that there are no meals on weekends or school holidays. It does not explicitly route the agent between siblings (e.g., when to prefer get_timetable instead), but the resource boundary is obvious enough that this is a minor gap.

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 and destructiveHint=false, so the safety profile is covered and the bar is lower. The description does add useful behavioral context — the next-30-days default window when dates are omitted — but says nothing about ordering, result volume, or whether events outside the school year are excluded.

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 short sentences, front-loaded with the resource and its contents, then the default range. Nothing is redundant or padded.

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 read-only, four-parameter, no-output-schema tool, the description plus the fully documented schema give an agent enough to call it correctly. The only minor gap is that it does not hint at the returned event fields or ordering, which is tolerable given the absence of an output schema.

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 'from' and 'to' semantics, formats and omission behavior are already documented in the schema. The description's 'between two dates' and 'defaults to the next 30 days' restate the schema's own omission rules rather than adding new meaning, 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?

The description names a concrete resource (school academic calendar) and enumerates its contents (exams, vacations, holidays, field trips, ceremonies), which plausibly separates it from get_timetable. However, it never states an explicit retrieval verb, relying on the noun phrase to imply 'list events', so it stops just short of maximum clarity.

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 by the event-type list and the default window, so an agent can infer this is the calendar tool rather than the timetable tool. There is no explicit when-to-use statement, no alternative named (get_timetable is the obvious confusion candidate), and no mention that eduCode/schoolCode must first come from search_schools.

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 fully covered. The description adds the useful detail that high schools additionally return departments/tracks, which is genuine conditional behavior, but says nothing about failure modes for invalid codes or any result-shape caveats.

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 the field list front-loaded and the conditional high-school clause appended at the end. Every clause conveys information; there is no filler or repetition of the title.

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 carries the burden of describing the return value, and it does so by enumerating the fields—including the conditional department/track data. What remains missing is error behavior for unresolvable codes and any note on the search_schools prerequisite, which keeps it short of 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%: both eduCode and schoolCode are documented with patterns and concrete examples ('B10', '7010082'). The description adds no meaning beyond that, so the baseline 3 applies; it neither compensates for a gap nor wastes space restating 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?

The description names the resource (school) and enumerates the exact fields returned—Korean/English name, type, address, phone, fax, homepage, founding date, public/private, coeducational, supervising office—plus a conditional extension for high schools. That is a specific, unambiguous purpose. It does not explicitly contrast itself with siblings like search_schools, which keeps it from a 5.

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 gives no when-to-use guidance, no prerequisites, and no mention of alternatives. The only routing signal lives in the schema ('code from search_schools'), not in the description, so an agent must open the schema to learn this is a follow-up call to search_schools.

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 genuinely new behavioral context: the result set widens to every class when grade/class are omitted, which is not inferable from the annotations and matters for result interpretation.

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 sentences, no filler, with the resource and scope front-loaded and the filtering caveat immediately after. Every clause carries information an agent can act on.

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 five-parameter read-only lookup with no output schema, the definition covers purpose, scope and filter-omission behavior adequately. It does not describe the shape or volume of the returned period/subject data, but that gap is minor given the annotations and the low complexity.

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 the baseline is 3; grade, class_name, eduCode and schoolCode are already documented with formats and examples in the schema. The description only adds omission semantics for grade/class, which is a useful but marginal increment over 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?

The description gives a specific verb and resource ('Class timetable (period and subject)') plus the scoping dimensions (school, grade, class, day), so an agent knows exactly what it returns. It does not explicitly distinguish itself from the sibling get_schedule, which leaves a small ambiguity about which to pick for schedule-like data.

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?

'Without grade/class it returns every class, so pass them when known' tells the agent when to include the optional filters and what happens if it doesn't. It stops short of naming an alternative tool or stating exclusions, so it is clear context rather than full when/when-not routing.

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 genuinely new context beyond them: the result cap ('up to 15'), the returned fields (field, courses, address, phone), the data source (offices of education registration data), and the fact that returned data is in Korean. It stops short of saying what happens when results exceed 15 or how to retrieve more.

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 no filler: the first establishes the resource, filter, and provenance; the second states the result cap, payload, and language. The most decision-relevant information (what the data is and how it is filtered) is front-loaded.

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 does well to name the returned fields and the 15-result cap, and the annotations cover the safety profile. However, it omits that region is required and that district, while strongly recommended, changes result breadth, and it gives no guidance on truncation when more than 15 matches exist. For a search tool whose main failure mode is over-broad or truncated results, that is a meaningful 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%, so every parameter already carries its own guidance and Korean examples. The description echoes the subject and district filtering concepts and the 'Data in Korean' note usefully signals that keyword values must be Korean, but it does not document the required region parameter or add format constraints beyond the schema. 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 (registered private academies/hagwon and tutoring centers) and its scope (a South Korean district, offices of education registration data), which cleanly separates it from the sibling search_schools. It never uses an explicit action verb, but the filtering behavior and entity type are unambiguous enough that an agent can pick it over its 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?

Usage is only implied through phrasing like 'filtered by subject keyword' and the schema note that district is 'strongly recommended'. There is no explicit statement of when to use this versus search_schools or get_school_info, and no exclusion guidance. An agent can infer the intent but gets no routing help from the description itself.

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 behavior, so safety is covered. The description adds genuinely new context: partial-name matching works and the result carries school type, province, and address, which matters because there is 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?

Two sentences, both earning their place: the first states the search capability and matching behavior, the second states what it returns and why. Nothing is redundant or buried.

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 two-parameter read tool with full schema coverage and no output schema, the description covers purpose, matching behavior, and return fields adequately. It omits minor operational details such as result limits or empty-result behavior, which is a small 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 100%, so the baseline is 3, but the description earns an extra point by stating that partial Korean names like '상계고' succeed — a matching behavior the schema's examples do not explicitly promise.

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+resource: find South Korean elementary, middle, and high schools by name. The scope (Korean, school levels) implicitly separates it from search_academies, but no sibling is named explicitly, so differentiation relies on inference.

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 clearly frames the tool as a lookup step that yields eduCode and schoolCode 'needed by the other tools', which tells an agent when to reach for it in a workflow. It does not say when NOT to use it or point to get_school_info as an alternative for detail.

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