Free, read-only access to job listings rated by AI level, from Little AI to Builds AI.
Scored across 8 tools
Most tools have clearly distinct purposes, but two pairs overlap: latest_ai_jobs is essentially a preset search_jobs, and list_companies_by_ai_level vs top_hiring_companies both rank companies hiring for AI (one by average AI rating, one by job count). Descriptions clarify the differences, but an agent could still misselect.
All names use snake_case, but the pattern is mixed: four tools start with a verb (get_job, get_level_definitions, list_companies_by_ai_level, search_jobs) while four are noun phrases (latest_ai_jobs, market_stats, salary_stats, top_hiring_companies). Readable, but not a consistent verb_noun convention.
Eight tools is well-scoped for an AI job board API. Each tool covers a distinct capability: single job retrieval, search, latest feed, company rankings, market stats, salary stats, and level definitions.
Core read-only workflows are covered: search, retrieve jobs, latest feed, company rankings, market and salary stats, and AI-level definitions. Minor gaps remain, such as no dedicated tool to get a specific company's full profile or all its listings, but agents can work around these via search filters.
Returns the full detail of a job listing published on Level, by its UUID or its slug (e.g. "senior-ml-engineer-acme-corp"). Includes recently expired listings, like the public page. Never returns a direct link to the employer's ATS: use the returned url (the canonical jobsbylevel.com page) to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_slug | Yes | The listing's UUID, or its slug. |
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 genuinely non-obvious behavior: it surfaces recently expired listings and never returns a direct ATS link, directing the agent to the returned `url` instead. That is real value beyond the annotations, though it doesn't cover latency or caching.
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 tight sentences; the primary purpose is front-loaded, followed by scope (expired listings) and then the practical apply-path caveat. No filler or repetition.
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 tool with no output schema, the description compensates by describing what is returned (full detail, including expired listings) and the important `url` field and its ATS behavior. An agent has everything needed to call and use 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?
Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description goes further by giving a concrete slug format example ('senior-ml-engineer-acme-corp'), which the schema's bare 'UUID or its slug' does not convey.
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 ('Returns the full detail of a job listing published on Level') and identifies the two accepted lookup keys (UUID or slug). An agent can tell this apart from search_jobs and latest_ai_jobs without opening a 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?
The description establishes the keyed-lookup use case by requiring an ID or slug, but never explicitly says when to prefer this over the sibling search_jobs/latest_ai_jobs, nor states any exclusions. Usage is implied by the required identifier rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the definition of Level's four AI-impact levels (AI Level 1 to AI Level 4), the scale every job listing on jobsbylevel.com is rated against.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is fully covered structurally. The description adds only the fact that this is a fixed four-level scale, with no notes on caching, freshness, or anything 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 front-loaded sentence stating what is returned, followed by a compact clause that contextualizes the scale's role. No filler or repetition of the tool name.
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 reference lookup with no output schema, the description adequately tells the agent what comes back (four level definitions). It could go slightly further by describing how levels are labeled or ordered, but 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?
The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter behavior for the description to clarify, and nothing misleading is claimed about inputs.
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 (returns) and resource (the definitions of Level's four AI-impact levels, AI Level 1 to AI Level 4), plus the scope of what the scale applies to. It is clearly distinct from the job/company/stats siblings, though it never names an alternative to differentiate itself 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?
Usage is only implied: by noting the scale is 'the scale every job listing ... is rated against', it hints the agent should call this to interpret AI-level values returned by search_jobs or list_companies_by_ai_level. There is no explicit when-to-use statement, prerequisite, or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The newest AI jobs published on Level (jobsbylevel.com): listings rated Works on AI (AI Level 3) or Builds AI (AI Level 4), posted in the last 24 hours by default, newest first. Level checks employer career sites every hour. Optional filters: free text, remote, visa sponsorship, minimum yearly salary in USD, seniority. Same data as the page https://jobsbylevel.com/new-ai-jobs. Every result links to its canonical page on jobsbylevel.com. The response also carries search_url, the page on jobsbylevel.com to browse the full list. Ranking never depends on payment: paid or boosted listings get no priority here.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page, starting at 1 (default 1). | |
| hours | No | Posting age window in hours (default 24, max 168). | |
| query | No | Optional free text: title, tool or skill. | |
| remote | No | true to keep remote roles only. | |
| seniority | No | Seniority level of the role: intern, junior, mid, senior, lead or executive. Exact match on the level Level assigned to the listing; listings with no clear seniority are left out when this is set. | |
| min_salary_usd | No | Minimum yearly salary in US dollars (1 to 1,000,000), e.g. 150000. Keeps listings whose published salary range tops out at or above this amount. Only listings with a yearly salary in USD are compared; listings paid in other currencies, hourly or monthly rates, and listings with no published salary are left out when this filter is set. Values under 15,000 are treated as 15,000. | |
| visa_sponsorship | No | true to keep only listings whose text says the employer sponsors work visas (H-1B). Listings that only sponsor in some cases, refuse sponsorship or do not mention it are left out. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive) and closed-world. The description adds genuinely non-obvious behavior: hourly re-crawl of employer career sites, paid/boosted listings get no ranking priority, results link to canonical pages, and the response includes a `search_url` field.
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?
Dense but front-loaded: identity, scope, freshness, filters, then source/return notes. Sentences are informative rather than padded, though the source-page and ranking-policy sentences could be trimmed slightly.
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, and the description compensates by describing result shape (canonical links, `search_url`) and data provenance/sync with the site page. Combined with full parameter coverage, an agent has what it needs to call and interpret the 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%, so the schema already documents all seven parameters in detail (including the salary floor and seniority exclusion rules). The description only names the filter categories, adding little semantics beyond the schema; baseline 3 is appropriate.
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 and scope: newest AI jobs on Level, restricted to AI Level 3/4, default 24-hour window, newest first. It does not explicitly contrast itself with the sibling search_jobs, so an agent could still be unsure when to choose this over the broader search.
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 clear context for use (freshness window, hourly crawl cadence, default-only behavior, optional filter list) and points to the browsable page for the full list. It stops short of naming when NOT to use it or which sibling to pick for older/non-AI listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks companies currently hiring on Level by how central AI is to their open roles: the average AI rating (0-100) of their live listings. This is a Level-specific aggregation, not a third-party ranking. See the returned method field for the exact rule. Companies with too few live listings, and known job-board republishers, are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return (default 20). | |
| min_jobs | No | Minimum number of live listings required to be ranked (default 10). |
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 bar is lower. The description adds real value beyond them: it discloses the exclusion rules (too few live listings, known job-board republishers) and points to the returned `method` field for the exact ranking rule.
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 tight sentences, front-loaded with the core action and metric, then scope clarification, then exclusions. Every sentence carries information, though the 'not a third-party ranking' line is slightly defensive framing.
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 two-param aggregation tool with no output schema, the description supplies the metric definition, exclusion rules, and a pointer to the `method` output field. It is largely self-sufficient, with only minor gaps around result ordering/fields.
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 both `limit` and `min_jobs` are already documented with defaults and bounds. The description only indirectly touches `min_jobs` via the 'too few live listings excluded' statement and adds no format or interaction detail 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?
States a specific verb+resource (ranks companies by AI centrality of their live listings) and defines the metric precisely (average AI rating 0-100). It also clarifies the aggregation is Level-specific rather than third-party, which separates it from external rankings, though it never names a sibling tool directly.
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 description (use this when you want company-level AI-centrality rankings), but there is no explicit when-to-use vs. when-not guidance and no sibling alternatives (e.g. market_stats, latest_ai_jobs) are named as routes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated statistics over currently published Level listings: distribution by AI level (AI Level 1 to AI Level 4), share of remote roles, and the most frequent tools and categories. Computed directly from the database, not an estimate.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | Number of top tools/categories to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds meaningful context beyond them: the data is aggregated, computed directly from the database rather than estimated, and scoped to currently published listings. It does not discuss performance, rate limits, or response format, keeping it from 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?
Two sentences, front-loaded with the resource and operation, then the enumerated aggregates. Every clause carries information, and the closing distinction ('not an estimate') is a compact, useful qualifier.
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-only tool with rich annotations and a fully described input schema, the description is complete. Although no output schema exists, the enumeration of computed aggregates effectively communicates what the tool returns, leaving no critical gap for correct invocation.
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% for the single top_n parameter, so the schema already documents its range, default, and meaning. The description does not mention top_n or explain how it affects the output, so it adds no parameter-level value beyond the structured 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 names a specific resource (currently published Level listings) and a precise operation (aggregated statistics), then enumerates the exact aggregates: AI level distribution, remote share, and frequent tools/categories. This cleanly separates it from siblings like search_jobs, get_job, and latest_ai_jobs, which return individual listings rather than aggregates.
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 description implies usage by framing the tool as aggregate market statistics, so an agent can infer it is for trend/overview queries rather than individual job lookup. However, it never explicitly states when to choose this over siblings such as latest_ai_jobs or search_jobs, nor does it give any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Salary statistics over the live Level listings that publish a yearly salary range: number of listings, median, 25th and 75th percentile of the middle of each range, in one currency at a time (default USD, currencies are never mixed). Hourly and monthly rates are excluded. Optional filters: keyword in the job title, AI level (1 = Little AI, 2 = Uses AI, 3 = Works on AI, 4 = Builds AI), remote. The response carries the date of the figures and the exact method. Computed directly from the database, not an estimate.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Keyword in the job title, e.g. "machine learning". | |
| remote | No | true to keep remote roles only. | |
| ai_level | No | Keep only listings at exactly this AI level (1 to 4). | |
| currency | No | Three-letter currency code (default USD). Only listings in this currency are counted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real operational context on top: figures are computed directly from the database rather than estimated, currencies are never mixed, the response carries the date of the figures and the exact method, and hourly/monthly rates are excluded. That is substantive disclosure beyond structured fields.
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?
Dense but front-loaded: the population and metrics come first, then filters, then methodology. Most sentences earn their place, though the closing 'Computed directly from the database, not an estimate' partially overlaps with the earlier 'live Level listings' framing.
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 correctly compensates by describing the return payload (count, median, 25th/75th percentile of range midpoints, date of figures, method). An agent has everything needed to call it and interpret results.
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 3, but the description adds meaning the schema lacks: it spells out the AI level scale (1 = Little AI through 4 = Builds AI) where the schema only says '1 to 4', and confirms the default currency is USD and that only one currency is counted at a time.
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+resource (salary statistics over Level listings) and precisely bounds the population (only listings that publish a yearly salary range, excluding hourly and monthly rates). It is highly self-contained, but it never distinguishes itself from the sibling market_stats tool, which is the most likely source of confusion.
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 context is implied rather than stated: the description explains which listings are counted and which filters exist, so an agent can infer when the tool applies. However, it never says when to choose this over market_stats or search_jobs, and no exclusion or alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search job listings published on Level (jobsbylevel.com), an AI job board that rates every listing by how central AI is to the role, from Little AI (AI Level 1) to Builds AI (AI Level 4). Filters: free-text query, AI level range, remote, city, company, posting age, visa sponsorship, minimum yearly salary in USD, seniority, job category. Returns at most 20 results per page. With query: whole-word search with stemming ("engineer" also matches "engineering", but a fragment like "eng" alone no longer matches), ranked by relevance, and total is capped at 1,000 (see total_capped in the response). Without query: ranked by AI rating and recency, total is exact. Every result links back to its canonical page on jobsbylevel.com. The response also carries search_url, the page on jobsbylevel.com that shows the same search as a full list: offer it to the user to browse beyond the first 20 (search_url_omitted_filters names any filter that page cannot apply). This tool never returns a direct link to the employer's ATS. Ranking never depends on payment: paid or boosted listings get no priority here.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City or location text, partial match against the listing's location. | |
| page | No | Page, starting at 1 (default 1). | |
| sort | No | "recent" = newest first. Default: relevance with `query`, otherwise AI rating then recency. | |
| query | No | Free text: job title, tool or skill (also matches company name). | |
| remote | No | true to keep remote roles only. | |
| company | No | Company name, partial match. | |
| category | No | Job category, one of: software-engineering, data, product, design, marketing, sales, customer-support, operations, finance, hr, legal, security, research, healthcare, education, content, data-annotation, other. Exact match on the category Level assigned to the listing. | |
| seniority | No | Seniority level of the role: intern, junior, mid, senior, lead or executive. Exact match on the level Level assigned to the listing; listings with no clear seniority are left out when this is set. | |
| ai_level_max | No | Maximum AI level (1 to 4). | |
| ai_level_min | No | Minimum AI level (1 to 4). | |
| min_salary_usd | No | Minimum yearly salary in US dollars (1 to 1,000,000), e.g. 150000. Keeps listings whose published salary range tops out at or above this amount. Only listings with a yearly salary in USD are compared; listings paid in other currencies, hourly or monthly rates, and listings with no published salary are left out when this filter is set. Values under 15,000 are treated as 15,000. | |
| visa_sponsorship | No | true to keep only listings whose text says the employer sponsors work visas (H-1B). Listings that only sponsor in some cases, refuse sponsorship or do not mention it are left out. | |
| posted_within_hours | No | Only listings posted in the last N hours (1 to 168). 24 = posted today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, it discloses the 20-results-per-page cap, the 1,000 `total` cap and its `total_capped` flag, the no-ATS-link guarantee, and that ranking is never payment-influenced — all behavioral facts an agent cannot get from structured fields. It also flags that `search_url_omitted_filters` names unappliable filters, which is genuinely useful side-channel context.
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-loads what the tool is before describing filters and return semantics, and nearly every sentence carries decision-relevant information. It is long for a tool description, and the filter enumeration partially duplicates the schema, so it is efficient but not maximally tight.
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: result count per page, `total` semantics and capping, `search_url`, `search_url_omitted_filters`, and the canonical-link/no-ATS behavior. All 13 parameters are documented in the schema, so combined coverage is complete for an agent to call and interpret results.
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 3; the description goes beyond it by documenting `query` matching mechanics (whole-word with stemming, so "engineer" matches "engineering" but "eng" does not) and how ranking/interaction of `query` with `total` works. The enumerated filter list itself largely restates schema fields, but the stemming detail is real added meaning.
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 (job listings on Level/jobsbylevel.com) and immediately scopes it with the AI-level rating scheme unique to this board. An agent can distinguish it from get_job (single fetch), latest_ai_jobs (recency feed), and the stats siblings without opening a 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?
Explains the conditional behavior that drives tool choice: with `query` you get relevance ranking and a capped `total`, without it you get AI-rating/recency ranking and an exact `total`. It also tells the agent when to surface `search_url` versus staying in pagination. It stops short of explicitly naming sibling alternatives (e.g. get_job for a single listing) or stating exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The 10 companies with the most live AI jobs posted in the last N days on Level: listings rated Works on AI (AI Level 3) or Builds AI (AI Level 4). Ranked by number of listings only, free, never by payment. Each company links to its page on jobsbylevel.com. Companies that only republish other employers' listings are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window in days (default 30, max 90). |
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), but the description adds real behavioral context: ranking is by listing count only, placement is never paid, results link to jobsbylevel.com, and republisher-only companies are filtered out. That is substantive 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?
Front-loaded with the core definition, then qualifications. Four sentences, each carrying information (rating tiers, ranking basis, links, exclusion rule), with minimal waste.
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-optional-param, read-only ranking tool with no output schema, the description covers what is returned (10 companies, their ranking basis, page links) and the filtering rules. Minor gaps (result ordering ties, whether companies with zero listings within the window appear) are not addressed.
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?
Only one optional parameter (days) with 100% schema description coverage, so the schema already documents default 30 and max 90. The description's 'last N days' restates the schema rather than adding format or edge-case guidance, 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?
States a precise verb and resource: the top 10 companies by live AI job count within a day window, restricted to AI Level 3/4 employers. The scope (10 companies, AI-ratings, last N days) makes it distinguishable in effect from siblings like list_companies_by_ai_level, though no sibling is named 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?
Usage is implied — an agent can infer this is for 'who is hiring the most AI talent' — and the exclusion of republishers signals appropriateness. But there is no explicit when-to-use/when-not statement or named alternative (e.g. list_companies_by_ai_level or latest_ai_jobs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
latest_ai_jobs2 fields changedInput schema / properties / min_salary_usdAdded value: +{
+ "description": "Minimum yearly salary in US dollars (1 to 1,000,000), e.g. 150000. Keeps listings whose published salary range tops out at or above this amount. Only listings with a yearly salary in USD are compared; listings paid in other currencies, hourly or monthly rates, and listings with no published salary are left out when this filter is set. Values under 15,000 are treated as 15,000.",
+ "maximum": 1000000,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / seniorityAdded value: +{
+ "description": "Seniority level of the role: intern, junior, mid, senior, lead or executive. Exact match on the level Level assigned to the listing; listings with no clear seniority are left out when this is set.",
+ "enum": [
+ "intern",
+ "junior",
+ "mid",
+ "senior",
+ "lead",
+ "executive"
+ ],
+ "type": "string"
+}search_jobs3 fields changedInput schema / properties / categoryAdded value: +{
+ "description": "Job category, one of: software-engineering, data, product, design, marketing, sales, customer-support, operations, finance, hr, legal, security, research, healthcare, education, content, data-annotation, other. Exact match on the category Level assigned to the listing.",
+ "enum": [
+ "software-engineering",
+ "data",
+ "product",
+ "design",
+ "marketing",
+ "sales",
+ "customer-support",
+ "operations",
+ "finance",
+ "hr",
+ "legal",
+ "security",
+ "research",
+ "healthcare",
+ "education",
+ "content",
+ "data-annotation",
+ "other"
+ ],
+ "type": "string"
+}Input schema / properties / min_salary_usdAdded value: +{
+ "description": "Minimum yearly salary in US dollars (1 to 1,000,000), e.g. 150000. Keeps listings whose published salary range tops out at or above this amount. Only listings with a yearly salary in USD are compared; listings paid in other currencies, hourly or monthly rates, and listings with no published salary are left out when this filter is set. Values under 15,000 are treated as 15,000.",
+ "maximum": 1000000,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / seniorityAdded value: +{
+ "description": "Seniority level of the role: intern, junior, mid, senior, lead or executive. Exact match on the level Level assigned to the listing; listings with no clear seniority are left out when this is set.",
+ "enum": [
+ "intern",
+ "junior",
+ "mid",
+ "senior",
+ "lead",
+ "executive"
+ ],
+ "type": "string"
+}latest_ai_jobs1 field changedInput schema / properties / visa_sponsorshipAdded value: +{
+ "description": "true to keep only listings whose text says the employer sponsors work visas (H-1B). Listings that only sponsor in some cases, refuse sponsorship or do not mention it are left out.",
+ "type": "boolean"
+}salary_statssearch_jobs1 field changedInput schema / properties / visa_sponsorshipAdded value: +{
+ "description": "true to keep only listings whose text says the employer sponsors work visas (H-1B). Listings that only sponsor in some cases, refuse sponsorship or do not mention it are left out.",
+ "type": "boolean"
+}top_hiring_companieslist_ai_native_companieslist_companies_by_ai_levelsearch_jobs1 field changedInput schema / properties / sort / descriptionPrevious value: -"\"recent\" = newest first. Default: relevance with `query`, otherwise AI score then recency."New value: +"\"recent\" = newest first. Default: relevance with `query`, otherwise AI rating then recency."latest_ai_jobssearch_jobs2 fields changedInput schema / properties / posted_within_hoursAdded value: +{
+ "description": "Only listings posted in the last N hours (1 to 168). 24 = posted today.",
+ "maximum": 168,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / sortAdded value: +{
+ "description": "\"recent\" = newest first. Default: relevance with `query`, otherwise AI score then recency.",
+ "enum": [
+ "default",
+ "recent"
+ ],
+ "type": "string"
+}get_jobget_level_definitionslist_ai_native_companiesmarket_statssearch_jobsFree, read-only data on about 4,900 AI companies, open AI jobs and dated AI news, with source links.
Search AI tools, browse categories and read tool details with source links. Free, read-only access.
Open jobs and hiring changes per company, daily. Free keyless lookup. AI-compiled from job boards.
Semantic search over 3.5M+ live US job postings pulled straight from company ATSes. Read-only.
Add one secure layer between your agents and this server.
