UX Jobs

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 structurally. The description adds the data source (jobs.uxjobs.io) and that filters are optional, but says nothing about result limits, ordering direction, or empty-filter behavior beyond what the schema implies.

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 core action and ranking metric, followed immediately by the optional filter scope and two illustrative queries. 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 13 optional parameters, an output schema present, and defaults documented in-schema, the description covers what the agent needs to decide to call it. It is near-complete; only the omission of any mention of ordering or result shape (which the output schema presumably covers) keeps it from being fully comprehensive.

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 92%, so nearly every parameter is self-documenting in the schema. The description only summarizes the filter families (country, remote, seniority, keywords, recency) at a high level, adding no syntax or format detail beyond the schema; 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?

States a specific verb (rank), resource (companies), and ranking metric (number of open UX/product-design roles) on a named source (jobs.uxjobs.io). An agent can distinguish this aggregation tool from sibling list/search tools like search_jobs or get_job without opening any schema.

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?

Provides two concrete usage examples ('who is hiring the most designers in Berlin', 'which companies opened design roles this week') that make the intended question type obvious. It does not, however, name an alternative tool or state when-not to use it (e.g. versus hiring_snapshot or search_jobs), so it stops short of full 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 declare read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description still adds genuine value by disclosing that the returned description is only an excerpt and that the listing URL holds the complete text, which affects how an agent should use the result.

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 tightly packed sentence front-loads the core action, then adds return contents and the full-text pointer with no wasted words. Nothing is redundant or 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?

For a single-parameter read with an output schema, the description supplies everything needed: the source, the required input provenance, the returned fields, and the truncation caveat. An agent can invoke it correctly without further context.

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% with a single well-documented 'id' parameter, so the schema carries the semantics. The description's "by the id returned from search" merely restates the schema's "Listing id from search" and adds no new format or constraint 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 gives a specific verb and resource (retrieve one job listing) plus concrete return contents (location, salary, apply link, description excerpt) and names the id's origin. It does not, however, differentiate itself from the sibling get_job, which an agent would have to disambiguate on its own.

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?

"by the id returned from search" states the precondition and points to the correct upstream tool, which is clear usage context. It stops short of saying when not to use it or how it relates to alternatives like get_job or search_jobs.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely useful behavioral context beyond them: the description text is only an excerpt 'when the source provides one' and 'the listing URL has the complete text', warning the agent that the returned body may be truncated.

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 but well-ordered sentence front-loads the return shape, then closes with a single short caveat about full text. No filler sentences; every clause 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 an output schema present, the description needn't document return values, and it still flags the one thing an agent must know (the excerpt may be partial). Input, provenance, and output caveat are all covered for a single-parameter read 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 description coverage is 100%, and the description's id provenance (search_jobs id or jobs.uxjobs.io slug) largely restates what the schema already documents. Baseline 3 is appropriate since the schema does the heavy lifting.

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 (Return) and resource (one job listing in detail), then enumerates the actual payload (location, workplace, posted salary, apply link, description excerpt). It is immediately distinguishable from sibling search_jobs because it fetches a single listing by id rather than searching.

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 tells the agent where the id comes from — 'the id returned from search_jobs (or the jobs.uxjobs.io page slug)' — which sets up the search-then-fetch workflow. It stops short of naming an exclusion or stating when not to use this tool (e.g. when only a summary is needed).

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that the tool is an aggregate over the same filter set as search_jobs, but gives no detail on caching, freshness of counts, or whether results are computed live versus pre-aggregated.

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 output scope before the filter note. The enumeration is dense but earns its place by telling the agent what fields come back; only minor trimming 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 an output schema present, the description need not explain return values, and the annotations cover the safety profile. Given 11 optional params and 100% schema coverage, the description plus structured fields are sufficient for correct invocation, though it never clarifies the relationship to salary_snapshot or companies_hiring.

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 one of the 11 parameters is already documented in the schema, including the enum values and the ~8% salary-posting caveat. The description only says the filters match search_jobs, which adds no syntax or semantics 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?

States a specific verb+resource (statistical snapshot of the design job market) and enumerates exactly what is aggregated: totals, 7-day postings, remote share, and breakdowns by seniority, discipline, country, city, and company. This clearly distinguishes it from the listing-oriented siblings search_jobs and get_job.

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 second sentence gives concrete usage context: it accepts the same optional filters as search_jobs so you can snapshot a country, discipline, or keyword. It does not, however, explicitly state when to prefer this over salary_snapshot or companies_hiring, nor any exclusions.

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 safety is covered. The description adds genuinely useful domain behavior beyond them: the 5-10% coverage bias, the caution on small samples, and that sample size is returned per level. It does not describe output shape or pagination, but the output schema exists to cover that.

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 waste, and the defining scope plus the sample-bias caveat are both front-loaded before the filtering detail. Every clause carries 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 an 11-parameter stats tool, the description supplies the critical interpretive context (only salaried listings count, samples may be tiny, sample size is returned). Annotations cover safety and an output schema covers return values, so nothing essential 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%, so the schema already explains every one of the 11 parameters, including the enums and the min_salary_usd caveat. The description names a subset of filters (country, remote, discipline, keywords) but adds no syntax or meaning 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?

The description names a specific resource and output (median and quartile posted salary by seniority level) with a clear scope, so an agent can tell it produces salary statistics rather than raw listings. It falls short of a 5 because it never distinguishes itself from the closest sibling, hiring_snapshot, which an agent might reasonably confuse it with.

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: use it to obtain salary distributions, with the caveat that only 5-10% of listings qualify. There is no explicit 'use this instead of search_jobs / hiring_snapshot when...' guidance, and no exclusions, so the agent must infer the correct tool boundary.

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 still adds genuinely new behavior: a hard cap of 20 results and that the response is a lightweight projection (id, title, URL) rather than full listings. It says nothing about pagination or ordering, which is a modest remaining 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?

Two sentences plus examples; scope, return shape, and the next-step handoff are all front-loaded with no filler. Every clause 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 an output schema present and annotations covering safety, the description covers only what the agent still needs: result cap, returned fields, and the fetch handoff. The one real omission is disambiguation from the search_jobs sibling, which matters given the overlapping names.

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% but the schema only says "Search query." The description compensates by showing that natural-language free-text queries are supported, with two concrete phrasings ("remote senior product designer fintech", "UX researcher London"). Those examples teach query style rather than merely restating the parameter.

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), resource (UX & product-design job listings), and the source domain jobs.uxjobs.io, which is concrete and identifiable. It does not, however, differentiate itself from the sibling search_jobs, leaving the agent to guess which search tool is intended when both are present.

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?

"pass an id to fetch for the full listing" explicitly routes the agent onward to the fetch sibling once an id is obtained. What is missing is a condition distinguishing this tool from search_jobs, so the when-to-use guidance is clear for the fetch handoff but silent on the more dangerous ambiguity.

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 non-destructive, so the safety profile needs no description support. The description adds real behavioral context beyond that: results come back as a page of compact records, ordered newest-first or by keyword relevance when a query is present, with a total match count. It stops short of describing rate limits or how paging interacts with total count, so it is 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?

Three sentences: purpose first, then supported filters, then return shape and ordering. Every clause carries information and nothing is repeated, which is a well front-loaded structure for a 13-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 13 optional parameters, 100% schema coverage, and an output schema present, the description need not enumerate parameters or return fields — and it correctly doesn't. It covers corpus, filter surface, and ordering/total-count semantics. The only material omission is disambiguation from the other search-adjacent siblings (search, companies_hiring, 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?

Schema description coverage is 100%, so every parameter — including enums, defaults, and caveats like the ~8% salary-posting rate — is already fully documented in the schema. The description only restates the filter categories (salary, recency) at a higher level and adds no syntax or format detail beyond what the schema provides, 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?

States a specific verb and resource ("Search live UX, product-design... roles on jobs.uxjobs.io") with the domain named explicitly, so an agent knows exactly what corpus this queries. It does not distinguish itself from siblings like get_job or salary_snapshot, so it falls short of 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?

Usage is implied by the filter list (keyword, location, remote, seniority, discipline, company, salary, recency) — an agent can infer "use this to find matching roles." There is no explicit when-to-use guidance, no statement of when a sibling such as get_job should be preferred for a single posting, and no exclusions.

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