LucyESL — English teaching jobs in Korea

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 burden is lower. The description adds two useful traits the annotations lack: the data is restricted to 'live' adverts, and the scope is Korean ESL postings. It does not disclose the shape or granularity of the numbers, which is a gap given 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?

One front-loaded sentence plus a license tag; no filler. It is slightly awkward as a question rather than a declarative statement, which costs a point.

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 parameterless stat tool the description does enumerate the exact attributes measured, which partially substitutes for the missing output schema. However it never says whether results are counts, percentages, or broken out by time period, leaving the return shape ambiguous.

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 tool takes zero parameters, so the baseline of 4 applies. Schema coverage is 100% and there is nothing for the description to disambiguate.

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: disclosure counts for eight specific attributes across live Korean ESL job adverts. That is enough for an agent to know what comes back, but it never states the operation as a verb (list/aggregate?) and does not distinguish itself from salary_stats or market_stats.

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 statement, no alternatives named among the six siblings, and no condition that selects this tool over salary_stats or market_stats. The agent must infer routing from the topic alone.

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 the return-format fact ('as a plain-text document with its facts'), which is genuinely useful beyond the annotations, but says nothing about error behavior for unknown ids or the document's structure.

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 with the action, resource, key, and return format; 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?

For a one-parameter read tool with rich annotations and no output schema, the description covers action, key, and response format adequately. The main omission is disambiguation from get_job/search_jobs, which is the only thing an agent could get wrong here.

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 'id' parameter has no schema-level description, so the description carries the burden. It does identify the parameter's meaning ('one LucyESL job listing by id'), which is more than the schema offers, but adds no format, source, or example of a valid id.

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 (Fetch) and resource (one LucyESL job listing) plus the lookup key (by id), so the operation is unambiguous. However, it does not distinguish itself from the sibling get_job or search_jobs, which likely retrieve the same entity, leaving the agent to guess which fetch tool to pick.

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?

No when-to-use guidance is given: nothing says when this is preferable to get_job, search, or search_jobs, nor any prerequisite such as a valid id. The only implied context is that the caller already has an id, which the agent must infer.

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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes only the word 'live' (data freshness) and 'structured', adding marginal context but nothing about missing-id behavior or scope.

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 short sentence with no filler and no buried lede, which is structurally sound. The problem is under-specification rather than verbosity, so it reads as sparse rather than efficiently concise.

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?

This is a low-complexity, single-parameter tool with no output schema, so the description carries the burden of explaining the record's shape, fetch semantics, and failure mode for a nonexistent id. 'Structured record' is too vague to tell an agent what it will receive or how to recover from a bad 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?

Schema description coverage is 0%: the required integer parameter 'id' (minimum 1) is documented nowhere in the schema, and the description never mentions a parameter at all. It does not say the id is a listing/job identifier or what happens for an unknown id, so it fails to compensate for the coverage 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?

The phrase 'One live listing as a structured record' conveys that a single listing is retrieved, which is more than the title alone. However it has no explicit verb, names no resource type (job? listing?), and gives no differentiation from the sibling tools fetch, search, or search_jobs. The purpose is only broadly inferable.

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 statement of prerequisites, and no routing against alternatives. An agent cannot tell from this text whether to call get_job, fetch, or search_jobs for a given need. Score 2 rather than 1 only because nothing stated is actually wrong or misleading.

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 establish the safe-read profile (readOnly, idempotent, closed-world), so the bar is lower, yet the description still adds real context: data is 'live', counts are of adverts rather than employers, and the median salary is only reported 'where the sample allows'. That last point usefully warns about missing values.

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 dense sentence front-loads the scope (South Korea, by region) and then enumerates the metrics, closing with the licence. Efficient, though the mid-sentence clause stack is slightly heavy.

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 parameters and no output schema, the description carries the burden of describing what comes back, and it does so by naming the four reported measures plus the advert-vs-employer caveat. A note on granularity (e.g. region unit) or sample-size threshold would make it 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond confirming the tool is parameterless and returns a fixed aggregate.

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 precise resource (live English-teaching job adverts in South Korea) and the exact aggregation (counts by region, direct-hire vs recruiter split, on-site hours, median advertised salary). It is clearly distinguishable from siblings like salary_stats or disclosure_stats by naming the region-and-metric scope.

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 aggregation framing, but there is no explicit when-to-use or when-not-to-use guidance, and no sibling (e.g. salary_stats, disclosure_stats) is named as the alternative for a different question. An agent must infer that this is the region-breakdown aggregate.

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 safety and determinism are covered structurally. The description adds genuinely useful context beyond that: results are computed from live listings (data recency/source) and output is CC BY 4.0 licensed (attribution obligation). It does not disclose whether stats are cached, how listing recency is bounded, or sample-size 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 dense sentence that front-loads the subject (English-teacher salary statistics for South Korea) and then lists covered dimensions without filler. The trailing license fragment is slightly bolted on but still earns its place for attribution compliance.

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 input schema fields and no output schema, the description carries the burden of describing what comes back, and it does so by enumerating the statistic families produced plus the data source and license. An agent can decide relevance and call it with no arguments; only the exact response shape and any caveats on sample size remain unspecified.

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 tool takes zero parameters, which is the baseline-4 case per the rubric. The description instead specifies the output dimensions (median, quartiles, region, employer type, hourly pay, disclosure, housing), which adds framing value even though there is nothing to disambiguate on the input side.

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 resource and scope: English-teacher salary statistics for South Korea computed from live listings, and enumerates the exact metrics produced (median, quartiles, by region/employer type, effective hourly pay, disclosure rates, housing). That is far more specific than a tautology, though it never explicitly positions itself against siblings like market_stats or disclosure_stats, so an agent must infer the boundary from scope alone.

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 explicit when-to-use statement or named alternative, but the enumerated metric list strongly implies the question types this tool answers (regional pay comparisons, hourly-rate normalization, housing). Usage is inferable rather than stated, and the overlap in scope with market_stats/disclosure_stats is left unresolved.

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 the safety profile is covered. The description adds value beyond that by disclosing the return shape (ids, titles, URLs) and that only 'live' listings are searched, which the annotations do not convey.

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, zero filler, with the scope statement front-loaded and the return values in second position. Everything present 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?

With no output schema, the description helpfully lists returned fields, and the annotation set covers safety. However, for a tool whose name barely differs from the sibling 'search_jobs', the definition leaves the agent without the differentiation or query-format detail needed to invoke it confidently over its twin.

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% for the single 'query' parameter, so the description must carry the burden. It partially does by stating the search is 'by free text', telling the agent the input is a natural-language string rather than a structured filter, but it adds no syntax, format, or matching-behavior 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?

The description names a specific verb (Search), resource (live English-teaching jobs in South Korea on LucyESL) and input mode (free text), so the agent knows exactly what is being queried. It does not, however, distinguish itself from the sibling tool 'search_jobs', which by name appears to do the same thing, leaving the agent unable to choose between them.

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 guidance on when to use this over search_jobs, get_job, fetch, or the stats tools. 'Search live ... jobs' implies a listing/lookup use case but the agent gets no exclusions or alternative 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 openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context absent from annotations: results are structured records, pay is expressed in KRW per month unless stated, and null means the advert was silent. Return-data semantics are the right thing to disclose 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?

One dense sentence front-loads the board and scope before the facet list, then a second sentence covers return semantics. No filler, though the facet enumeration is somewhat list-like rather than prioritized.

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 15-parameter, no-output-schema filter tool the description covers return format, currency, and null meaning, which is the most valuable missing piece. It still omits pagination behaviour (page/limit), default ordering, and what happens when no filters are supplied, leaving real 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 only 47% across 15 parameters, so the description must compensate. It names the filterable facets (region, student age, housing, visa, schedule, contract, setting, direct hire, minimum salary, free text), which helps map intent to parameters, but it adds no syntax, default, or combination guidance beyond the enumerations already in 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?

"Filter the live LucyESL board of English-teaching jobs in South Korea" gives a specific verb (Filter), resource (job board), and domain scope, and then enumerates the filterable facets. It is clear enough to call, but it does not distinguish itself from the sibling named 'search', so an agent cannot tell the two apart from this text alone.

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 facet list implies the tool is for browsing/filtering, but there is no explicit when-to-use, when-not-to-use, or pointer to siblings such as get_job for a single posting or salary_stats for aggregates. The agent is left to infer routing.

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