Cayman Job Finder

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description is free to add real value — namely that this returns only 'basic facts' and that the job page link leads to the official advert for full details. That sets expectations on completeness of the payload, a useful disclosure 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 sentence that front-loads the action and key, then the return shape. No filler.

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 returns and does so by listing the fields plus the outbound link. It omits edge-case behavior (invalid or expired slug), which keeps it from a 5.

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 schema already documents the slug as 'A job slug from search_jobs', which the description only restates. No extra semantics (format, casing, failure on bad slug) are added, so 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), resource (one current job) and lookup key (slug), then enumerates the fields returned. An agent can distinguish it from search_jobs and list_employers immediately.

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?

Makes the dependency explicit: the slug must come from search_jobs, so the intended workflow is clear. It does not spell out when not to use this vs. search_jobs, but for a detail-fetch tool the routing is essentially unambiguous.

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 added value is provenance and caveats: 'exactly as published', the link to the full report and method, and the warning that these are Cayman Job Finder counts of public adverts rather than official WORC statistics. That is genuinely non-obvious context an agent would otherwise misattribute. Return-format details are the only gap.

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 core purpose is front-loaded and the provenance caveat closes the text, but the middle is one very long parenthetical list that strains readability. Nearly every clause carries information the agent needs (especially the field list, since there is no output schema), so the density is justified, if inelegant.

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 compensates by enumerating what the response contains (adverts, positions, employers, median pay, sectors, advert length) plus the link to the full report and method. Combined with annotations covering safety, an agent has everything needed to call this correctly and interpret the result.

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 single `edition` parameter is fully documented in the schema (100% coverage, enum, default stated), and the description's 'Defaults to the latest edition' merely restates it. The description adds no format or edition-availability detail beyond the schema, so this sits at the 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?

The description names a specific resource (headline figures from the published monthly Cayman Hiring Report) and enumerates the exact measures returned: adverts, positions, employers, median advertised pay, sectors, advert length. That scope is unmistakably distinct from the sibling tools get_job, list_employers and search_jobs, which operate on individual records.

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 gives clear context for when the tool applies – aggregate/headline figures rather than individual adverts – and states the default behaviour (latest edition), which is the main invocation decision here. It stops short of explicitly naming when not to use it or pointing at a sibling for per-advert lookups.

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 behavior beyond that, which it does: it discloses the implicit filter (only employers with current vacancies) and the shape of each result (job count + link). It doesn't say whether results are ranked or what happens when a category/location yields nothing, but the extra context is genuine.

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 that front-loads the resource, then scope, then the value of each returned entry. No filler, nothing repeated from annotations or schema.

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 three-optional-parameter, read-only list tool with no output schema, the description supplies the key missing piece — what each result contains (open-job count and a link) — and the vacancy-only filter. Only a note on result ordering or filtering behavior is absent, which is minor.

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%: limit (with default and 1-100 range) and the two enum-typed filters are fully self-documenting. The description never references category or location filtering at all, so it adds no meaning 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 pairs a specific verb ('List') with a specific resource ('employers') and adds scope: current vacancies in the Cayman Islands, plus what each entry carries (open-job count, jobs link). This makes it clearly a directory-of-employers tool rather than a job-listing tool, implicitly distinguishing it from search_jobs/get_job, though it never names those 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: an agent can infer this is the entry point when it wants employers rather than individual postings, and the schema's category/location filters suggest narrowing scenarios. There is no explicit when-to-use/when-not statement, no mention of choosing it over search_jobs, and no note that results are restricted to employers with live vacancies.

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, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that: results are ordered newest first, sourced from WORC and employer pages, and each result links to a caymanjobfinder.com page that in turn links to the official advert. Pagination caps (limit 20, offset 2000) are left to the 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?

Three sentences, front-loaded with what is searched and how results are ordered, then the optional-filter note, then result shape. No redundant restatement of the title or schema.

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 sketches the result shape (a link to the job page, which links to the official advert) and the ordering. It could go slightly further on what fields each result carries and on paging behavior across the 0–2000 offset window, but nothing essential for a correct call is missing.

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%, including enum slugs and date patterns, so the schema does the heavy lifting and a 3 is the baseline. The description only adds that filters are optional and that results are newest-first; it does not explain filter combination behavior or how keyword matching interacts with category/location.

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 (search) and resource (current, open job vacancies in the Cayman Islands), plus provenance (WORC Jobs Portal and employer careers pages) and sort order (newest first). The search-a-collection scope is self-evidently distinct from the sibling get_job (single record) and list_employers (employers, not vacancies).

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?

"All filters are optional" tells the agent it can call with zero arguments, and the description clarifies what a result is and how to reach the official advert to apply. It stops short of explicitly routing between siblings (e.g. use get_job once you have an id, or when to prefer list_employers), so no exclusion guidance.

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