LucyESL — English teaching jobs in Korea

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuine extra context: only 'live' (not expired) adverts are counted, and the data is CC BY 4.0 licensed, which matters for downstream attribution.

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 and enumerates the measured fields, with the license tucked at the end. Slightly list-heavy phrasing but no wasted clauses.

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 return-value burden and does so: per field, the count that disclose it, the denominator, and the percentage. The one real gap is temporal scope — whether the figures are all-time, current, or over a window.

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 are zero parameters, so there is nothing for the description to disambiguate; the baseline applies. The enumerated metric list does clarify what the (absent) filters would otherwise have scoped.

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 resource (live Korean ESL job adverts) and the exact measurement (count and percentage disclosing salary, hours, severance, pension, insurance, airfare, vacation, split shifts). A verb is implied rather than stated and it never names how it differs from the sibling salary_stats, so it falls short of full sibling differentiation.

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 domain ('live Korean ESL job adverts') implies when the tool applies, but there is no explicit when-to-use, when-not, or routing versus salary_stats and market_stats, which are the obvious overlapping siblings. The agent must infer the choice from the field list.

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 safety is covered. The description adds real value beyond that: it discloses the return shape (a document with title, URL and a plain-text body) and the failure mode (closed/expired ids error and the message names the id). It does not say whether closed listings can ever be retrieved by other means, nor whether the body is truncated, which are the remaining behavioral gaps.

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 boilerplate, and the core operation plus return shape is front-loaded in the first clause. The field enumeration is long but earns its place because there is no output schema to describe the returned document.

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 with annotations covering the safety profile and no output schema, the description does the necessary work by explaining the returned document and the error case. The one thing an agent still needs is how this differs from get_job.

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?

With a single required parameter at 100% schema coverage, the schema already defines the id including its format ("290"). The description adds only the qualifier that the listing must be live — a semantic constraint worth noting, but thin beyond baseline.

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: fetch one live job listing by id, and enumerates what the returned document contains (title, URL, plain-text body covering employer, pay, hours, housing, visas, benefits, dates). However, it never distinguishes itself from the sibling get_job, which on its name alone looks like the same operation, so the agent cannot tell the two apart from this 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?

There is no statement of when to use this versus search/search_jobs (the discovery path) or get_job. The only conditional given is a failure case — an id that has closed or expired returns an error — which is behavioral, not usage guidance.

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), and the description adds genuinely new behavior: null fields mean the advert left the fact unstated, and a closed/expired id returns an error naming that id. That error contract is exactly the kind of context annotations cannot express.

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?

Front-loaded with the verb, resource, and identifier, then the return contents and the failure case. The field enumeration is long but each item is informative; only minor tightening is possible.

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 responsibly enumerates the returned fields and null semantics, plus the error case for stale ids. Only the interplay with search/search_jobs (how an id is obtained) is left unstated.

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% and the id parameter is already documented with an example ('such as 290'), so the baseline is 3. The description only reinforces 'numeric id' and adds the live-listing constraint, adding little 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 and resource ('Get one live LucyESL job listing by its numeric id as a structured record') and the cardinality ('one') implicitly separates it from the plural search/search_jobs siblings. An agent can tell immediately this is a single-record lookup, not a query.

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: 'by its numeric id' signals it is a follow-up call after obtaining an id, but no sibling is named and no when-not-to-use is given (e.g. 'use search_jobs when you don't have an id'). This is minimum-viable routing guidance.

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, and destructiveHint=false, so behaviour is largely covered structurally. The description still adds real value beyond them: it discloses data provenance ('computed from the live listings'), the statistical caveat that each median reports its underlying advert count, and a CC BY 4.0 licensing/attribution requirement. No return format or caching/freshness detail, so not a 5.

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?

Front-loaded with the scope, then a compact metric list; the sample-size caveat and licence are tacked on as short clauses that each carry information. It reads as fragments rather than full sentences, but no clause is filler and it is well under the length where truncation risk matters.

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 must carry the return shape, and it does by naming every metric returned plus the per-median sample size. What is missing is any hint about output structure/format or how fresh the underlying listings are, which an agent deciding between this and market_stats would want.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies a single global aggregate with no filtering arguments, consistent with the empty 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 specific resource (English-teacher salaries in South Korea) and enumerates the exact statistics produced: median, quartiles, region, employer type, effective hourly pay, disclosure rates, housing. That is far more than a restatement of the title. It stops short of 5 because it never distinguishes itself from siblings like market_stats or disclosure_stats, which plausibly cover overlapping ground.

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?

Use is implied by the scope statement – it is the tool for pay figures rather than individual listings – but there is no explicit 'use this when…' or exclusion against market_stats or disclosure_stats, despite obvious topical overlap. The agent has to infer routing from the sibling names 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?

The annotations already establish that this is a read-only, idempotent, non-destructive search. The description adds useful behavioral context: live job listings, filter interpretation, a maximum of 20 results, and the fields returned for each match.

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 three sentences, front-loads the core search behavior, and then covers filter interpretation and return shape without filler. Every sentence contributes useful 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 one-parameter search tool with no output schema, the description sufficiently covers query interpretation, result limits, and returned fields. The main remaining gap is that it does not clarify its relationship to the sibling search_jobs tool.

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 already adequate. The description adds meaning by explaining that plain-language words are interpreted as filters across specific dimensions such as region, student age, housing, schedule, visa, and direct hire.

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 and resource: searching live English-teaching jobs in South Korea on LucyESL. It is clear what the tool does, but it does not distinguish this tool from the sibling search_jobs, which appears to be an overlapping search operation.

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 explains that the query should be plain language and that words for region, age, housing, schedule, visa, or direct hire are treated as filters. However, it gives no explicit guidance on when to use this tool versus search_jobs, fetch, or get_job.

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 is not obligated there. It nonetheless adds genuinely useful result semantics absent from annotations and schema: it returns a match count plus a page, pay is KRW per month unless stated otherwise, and null means the advert was silent.

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, front-loaded with the filter scope before the return-shape note. The enumerations are dense but every clause maps to actual parameters; nothing is padding.

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 15 optional parameters and no output schema, the description does the important work of explaining the response shape (count + record page) and the null/pay conventions. Minor omissions remain: no default sort order, no statement of what an unfiltered call returns.

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% with 10 enums fully documented, so the schema carries parameter meaning. The description's list of filter dimensions largely restates the schema, and the one extra fact (KRW per month) concerns output rather than inputs. 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 and resource with scope: 'Filter the live LucyESL board of English-teaching jobs in South Korea', then enumerates the dimensions it filters on. It is clearly a filtered-listing tool, though it never names how it differs from the overlapping `search` and `fetch` 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 implied by the enumerated filter dimensions and the note that it returns a count plus a page of records, which suggests browsing/discovery. But there is no explicit when-to-use guidance and no exclusion against `search`, `fetch` or `get_job`, which is a real gap given the sibling set.

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