WhatJobs Job Search

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint, so safety is covered. The description adds real behavioral context beyond them: the cap of 6 keyword x location combinations, the market default behavior per location, and the fact that each row contains a link to the WhatJobs search.

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 purpose sentence, then an explicit 'Use this when' sentence with examples, then a compact bulleted Inputs block. Every sentence adds selection or invocation information; nothing is wasted.

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 covers the important return-shape detail (one row per comparison with a search link) and the comparison cap. It stops short of saying what else a row contains besides the link (e.g., the count field) and what format 'market' accepts, which would be helpful for a 3-param tool with zero schema documentation.

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%, so the description must carry all parameter meaning, and it largely does. It documents the non-obvious convention that keywords may be [""] to count all jobs, clarifies that locations should not be the user's own location unless they ask about nearby jobs, and explains that leaving market empty makes each location use its own country.

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 ('Compare how many jobs are live on WhatJobs right now') plus the comparison axes (places and/or roles). An agent can distinguish it from search_jobs or search_latest_jobs, which return listings rather than counts.

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 explicit trigger conditions ('when the user asks where the most jobs are, how much demand there is, or to compare cities or roles') backed by three concrete example queries. It lacks an explicit negative/alternative clause (e.g., 'use search_jobs instead if the user wants actual listings'), so a sibling-routing rule 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 read-only, open-world, non-destructive, so the description's job is added context — and it delivers: a hard cap of 4 role x place combinations, per-country currency with no conversion between rows, the pay period per row, and a link back to the WhatJobs search. These are non-obvious result-shape constraints an agent would otherwise discover only by trial.

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?

Well front-loaded: purpose sentence, then usage trigger with examples, then a bulleted Inputs block, then result behavior. The long enumerated market list is verbose but earns its place because the schema supplies no enum; the only real cost is overall length for a three-parameter tool.

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 still explains the return shape (rows with typical range and median, in local currency, with pay period and a link). Combined with the documented combination cap, default market semantics, and the no-conversion caveat, an agent has everything needed to call and interpret results correctly.

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% and the market parameter has no enum in the schema, so the description carries the full load — and does: keywords is restricted to job roles only, locations is restricted to places with an explicit exclusion of the user's own location, and market is documented with its default behavior plus a complete list of 24 supported country codes.

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 up front ("Compare what a job pays across places, or what different jobs pay in one place") and scopes the data source ("salaries in current WhatJobs listings"). The two comparison modes named (roles across places vs. roles within a place) make it clearly distinct from siblings like get_salary_insights or compare_job_counts.

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 an explicit when-to-use rule in imperative form ("Use this when the user wants pay compared") backed by three concrete example queries that map directly onto the two comparison modes. It does not name the sibling alternatives (e.g. get_salary_insights for a single salary lookup) or state when not to use it, so it falls short of a full routing instruction.

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, openWorld, non-destructive), yet the description adds real value: the data source is current WhatJobs listings, figures are in local currency with a variable pay period, and the response includes a link to all matching jobs. Auth, rate limits, and pagination are unmentioned, which keeps it below 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 purpose sentence, then a usage block, then a labeled Inputs section — well organized and mostly waste-free. The 25-value market enumeration is long but justified because the schema has no enum for it.

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 0% schema coverage and no output schema, the description supplies exactly what's missing: input definitions, currency and pay-period semantics, and the shape of the result including the jobs link. An agent has everything needed to call it correctly and interpret the response.

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%, so the description must carry all parameter meaning — and it does. It defines keyword as the role only, warns that location is the searched place rather than the user's own location and may be empty for country-wide results, and explains that market is optional, inferred from location, and enumerates all 25 supported country codes.

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 opens with a specific verb and resource ('Show what a job pays, from the salaries in current WhatJobs listings') and enumerates the returned metrics (typical range, median, lowest, highest). It implicitly separates itself from compare_salaries by scoping to a single role, but never names a sibling explicitly.

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 explicit trigger conditions ('when the user asks how much a role pays or earns, salary ranges, or whether a salary is good') plus two concrete example queries. It stops short of stating when-not to use it or pointing to compare_salaries for multi-role comparisons.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: counts are based on the latest 50 listings, results include links to company listings and all matching jobs, and market is inferred when omitted.

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 front-loaded with the core action and usage trigger, then organizes inputs and result behavior into compact sections. The long list of market codes earns its place because the schema provides no enum or per-parameter descriptions.

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-parameter read-only lookup with no output schema, the definition explains the purpose, usage trigger, all parameter meanings, market inference, count basis and returned links. Nothing essential for correct invocation 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 0%, so the description carries the full parameter burden and does so well. It explains keyword should be the role only, location should be the searched place rather than the user's own location unless nearby jobs are requested, and market is an optional country code inferred from location with a complete list of supported values.

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 opens with a specific verb and resource: it lists companies posting the most jobs for a role and place, including job counts and example listings. That output shape implicitly distinguishes it from job-search siblings such as search_jobs, but it never names an alternative explicitly.

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 when-to-use guidance with concrete user phrasings such as 'Who's hiring software engineers in Berlin?' and explains the employer-discovery intent. It does not state when not to use it or name a sibling tool for adjacent needs.

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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the ranking criteria, the 1-4 title and 10-skill caps, market inference from location, and the fact that results include a link to all matching jobs on WhatJobs. It does not cover result volume, pagination, or behavior when no matches exist.

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?

Well front-loaded: purpose, then when-to-use with an example, then a bulleted input list, then a privacy constraint and a note on the returned link. The long enumeration of 25 market codes is the one bulky element, but it substitutes for a missing schema enum so it earns most of its space.

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 4-parameter, read-only search tool with no output schema and 0% schema description coverage, the description supplies enough to call it correctly: input semantics, market inference and supported values, plus an explicit rule never to pass CV text or personal data. Missing only edge-case behavior such as empty results or result limits.

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%, so the description must carry the whole burden and it largely does — it defines what job_titles should be (titles chosen from the user's background), what skills are (up to 10 key skills/tools, with examples), that location is the place to search, and that market is an optional country code inferred from location. It even enumerates all supported market codes, which is critical since the schema has no enum.

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 ('Find WhatJobs listings') plus the ranking logic — title match strength and skill mention count — which no sibling tool offers. It is clearly distinguishable from search_jobs or search_latest_jobs, which do keyword searches rather than profile-based ranking.

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 names the trigger condition (user shares CV, experience or skills and asks what jobs suit them) with a concrete example utterance. It also states limits on how many titles and skills to pass, giving clear positive guidance; the main gap is that it does not explicitly name a sibling alternative for plain keyword searches.

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?

Beyond the readOnly/openWorld annotations, the description discloses the market-inference rule (omitted market derived from location), the full supported market value set, and pagination semantics via chunk_number. It also lists the return payload contents, which matters since no output schema exists. Auth, rate-limit, and empty-result behavior are not covered.

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?

Usage guidance is front-loaded, then inputs, then constraints, then examples — a sensible order with no filler prose. The sixteen examples are useful for keyword normalization but repeat the same pattern well past the point of diminishing returns, particularly for the English-market cases.

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 four-parameter search tool with no output schema and zero schema-level parameter docs, the description supplies everything needed to construct a correct call and describes the return shape. The remaining gap is routing: nothing explains how this differs from search_latest_jobs or when match_jobs_to_profile should win.

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%, so the description carries the full burden and does so: it defines scope for keyword (role/function/skill/industry only), for location (search location, not the user's physical location), for market (with an enumerated value list and inference fallback), and for chunk_number (start at 1, increment for more). The worked examples convert these rules into directly actionable patterns.

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 opens with a specific verb and resource ("Search WhatJobs for public job listings") and states the structured-field approach, so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the close sibling search_latest_jobs, which an agent could easily confuse with this one.

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 a clear trigger condition: use only when the user wants jobs, vacancies, internships, or asks to see more results, and it explains that chunk_number increments on follow-up requests. It stops short of naming exclusions or alternatives such as search_latest_jobs or match_jobs_to_profile for the cases this tool should not handle.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that - market inferred from location when omitted, a 7-day default window with a 30-day ceiling, and the fact that results carry a link to all matches - but says nothing about result volume, pagination, or how the external live search behaves on failure or empty results.

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?

Purpose and usage trigger are front-loaded, followed by a clean per-input breakdown and a single sentence on results - structure an agent can parse quickly. The 24-value market list is long, but it substitutes for a missing schema enum, so it earns its space; minor trimming of parenthetical country names would be 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 does disclose the shape of the return ('includes a link to all matching jobs'), and every input is explained, including the inference rule for market. What remains unstated is result count, pagination or truncation behavior, and whether an unsupported market or location fails or silently degrades - relevant for an open-world external search.

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%, so the description carries the full burden and does so: keyword is narrowed to 'the job role only', location is disambiguated against the user's own location, posted_within_days gains real meaning (1 = today/yesterday, 7 = this week, ceiling of 30, default 7), and market's free-form string is backed by an enumerated list of 24 supported country codes despite the schema having no enum.

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 precise verb and resource ('Show only recently posted WhatJobs listings') plus ordering ('newest first') and scoping ('for a role and place'). It implicitly separates itself from the sibling search_jobs via 'only recently posted', but never names the sibling, so the differentiation must be inferred.

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 states an explicit usage trigger ('when the user asks for new, fresh, recent or today's jobs') with two concrete example phrasings. It does not state a when-not-to-use condition, such as directing users to search_jobs for older or unrestricted listings, which is the main remaining routing gap among siblings.

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