VeritaHire live jobs

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

Annotations give only readOnlyHint=true and openWorldHint=false, so the description adds the meaningful behavior: free summary, first full report free (a cost/paywall signal), data measured from employers' own careers sites, and the async "building" state with retry_after_seconds for unpublished roles. That retry/readiness disclosure is exactly the kind of context an agent needs and cannot get from 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-loads what the report is and what it returns, then moves to identification and the async status. The output-metric sentence is a long run-on with stacked parentheticals, so it is dense rather than maximally tight, but there is little wasted content given there is no output 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?

Complete and useful for a read-only benchmarking tool with no output schema: it describes returned fields, the free/full split, data provenance, and the "building" retry path. Minor gaps remain around what happens after the free full report (cost/limits) and permissions, which 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?

With six parameters at 50% schema coverage, the description compensates by explaining the valid identification combinations: job_url (careers-site link or veritahire.com/j/ link), job_id, or employer + title (+ city, state). It adds format and combination semantics beyond the bare schema, though city/state/title/employer semantics are only implied by the grouping.

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 (Competitive Hiring Report) and precise scope (one US healthcare clinical job posting that is not filling), then enumerates the returned metrics. It never names a sibling tool, so differentiation from get_job or request_full_report is left implicit, which keeps it at a 4.

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 a clear triggering context: a single US healthcare clinical role that is not filling, with the qualifier that a not-yet-benchmarked role returns status "building" plus retry_after_seconds. Alternatives (e.g. the full-report request path) are described conceptually but the sibling tool is never named, so no explicit when-not 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds substantive behavior beyond that by enumerating what the call actually returns (full posting text, education/licence/year requirements, skills, pay, benefits, open status, apply link) – valuable because there is no output schema. It stops short of noting failure behavior when neither url nor job_id is supplied.

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?

It is a single, reasonably short sentence with no padding, but it is a grammatical fragment (no subject or verb) and reads as a sprawling comma-separated inventory. Nothing is front-loaded as the primary action or the key selection criterion.

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 the right thing by describing the returned fields, which largely compensates on the output side. However, for a tool with two optional identifiers and near-duplicate siblings, leaving both the parameter contract and the sibling routing unexplained makes the definition adequate but incomplete.

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 50%: job_id is documented but url is bare. The description adds zero parameter meaning – it never clarifies url vs job_id, whether either is required, or how they interact when both or neither are given. For a 2-param tool with 0 required parameters, that gap is the main usability risk and is left entirely unaddressed.

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 is a noun phrase enumerating the posting's contents rather than a verb+resource statement, so the action (fetching one posting) is inferred from the name and title rather than stated. Scope is implied by 'The whole posting text from the employer' and the content list. It offers no differentiation from siblings such as is_job_still_open or search_live_jobs, which is a real risk here.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no exclusions, and no reference to alternatives. This is a notable gap because the sibling is_job_still_open overlaps directly with the description's 'whether it is still open' content, and nothing tells the agent which tool to prefer for that question.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the ~36-hour re-read/close latency and the three possible return states with a last-confirmed timestamp, which an agent needs to interpret 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?

Three tight sentences, front-loaded with the core purpose, then mechanism, then return values and applicability. 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?

No output schema exists, so the description correctly carries the return-value semantics (open/closed/unknown, last confirmed). The only gap is the undocumented job_id parameter, which leaves how to call the tool partially ambiguous given zero required parameters.

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 50% – url is documented but job_id has no description anywhere. The description's mention of 'the employer's careers-site link' loosely mirrors the url param but adds no syntax or format detail, and leaves job_id entirely unexplained despite its presence in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('checks whether a job posting is still on the employer's own careers site') and explains the mechanism behind the check. An agent can distinguish this freshness check from get_job or search_live_jobs without opening either 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?

Gives clear applicability context: 'Works for postings found anywhere, given the employer's careers-site link.' However, it does not name when to prefer this over get_job or search_live_jobs, nor any exclusion conditions, so it stops short of explicit routing.

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 declare a non-read-only, non-destructive, non-idempotent write, and the description adds genuinely useful context: reports are about data rather than people and 'a person at VeritaHire reads every one', signaling human review and that duplicate submissions are not deduplicated. It still does not describe what happens after submission (confirmation, response, tracking).

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 purpose, then the kind enumeration, then the job_id/search disambiguation and the human-review note. Efficient, though the long kind list is dense and could be tightened.

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 write tool with no output schema and a nested search object, the description covers what is reportable, how job_id and search disambiguate, and that a human reviews submissions. Missing only post-submission behavior such as return value or whether follow-up is expected.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema coverage at 50%, the description compensates by explaining the two least obvious parameters: job_id identifies one job and search holds the search arguments for a results problem. The kind values are implicitly mapped to problem categories in prose, though detail is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Records a problem with VeritaHire data') and enumerates the concrete problem categories, so an agent knows exactly what is reportable. It does not contrast itself with the closest sibling (is_job_still_open), which an agent might otherwise reach for first.

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 enumerated kinds give clear context for when this tool applies (job_closed, wrong_location, wrong_pay, irrelevant_results, missing_jobs, duplicate), and the job_id/search sentence routes each scenario to the right input. No when-not-to-use or explicit alternative (e.g. is_job_still_open for a single verification) is given.

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=false, openWorldHint=true and idempotentHint=false, so the write/external nature is partly covered. The description adds real context beyond them: the recipient's click creates a free VeritaHire account, that click is what opens the report, and 'nothing more is sent unless they click' bounds the side effects. A 4 rather than 5 because it doesn't say whether repeat calls resend or what happens on failure.

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 tight sentences with the action and recipient front-loaded, followed by the side-effect caveat. Nothing is padded and 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?

There is no output schema, so the description owns the burden of explaining behavior, and it does cover the main side effect well. However, with 7 parameters at 14% coverage and no explanation of how the posting is identified or what happens on a bad job_id, an agent lacks enough to invoke it confidently.

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 only 14% (just the email field), so the description must carry the load. It clarifies email ('their work email') but leaves city, state, title, job_id, job_url and employer completely unexplained — an agent must guess which combination identifies the posting to report on.

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 ('Emails') and resource ('the full Competitive Hiring Report for a posting') plus the recipient. None of the siblings (benchmark_role, get_job, save_search, etc.) send anything, so an agent can distinguish it 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?

Usage is only implied: the description makes clear it targets 'the person who will use it (their work email)', i.e. the hiring manager. It never states when to reach for this over benchmark_role or get_job, and gives no prerequisites, but the intended scenario is inferable from the text.

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?

With only a generic annotation set (readOnlyHint false, non-idempotent, openWorld), the description does the heavy lifting: it discloses that exactly one email is sent, that the click is what triggers the recurring digest, that a free account is created as a side effect, and that nothing more is sent without consent. It does not cover deliverability, rate limits, or what a failed/unclicked email means.

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 short sentences, front-loaded with the core action (one email to the person) and then the consequence of their click. No filler, no repetition 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?

There is no output schema, and the description does explain the observable outcome (an email is sent; a click starts a recurring digest and creates an account), which is the most important missing piece. However, for a 6-parameter search-subscription tool with 33% schema coverage, it leaves the search-shaping parameters completely unexplained.

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 only 33% (6 parameters, 4 of them — what, remote_only, radius_miles, employment_type — carry no schema description). The description reinforces only the email parameter ('the person's own address') and says nothing about how the search criteria parameters shape the digest, so it does not compensate for the coverage gap.

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 states a specific action chain: send one email to the person's own address, and their click starts a daily job-email digest while creating a free account. That is far more precise than the name 'save_search' alone and clearly separable from search_live_jobs, which returns results immediately rather than emailing them. It stops short of naming any 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?

Usage is implied rather than stated: the opt-in/callback mechanics make it clear this is for subscribing someone to a daily digest, not for retrieving jobs. There is no explicit 'use this when…' clause, no exclusion such as 'do not use to fetch results now', and no mention of the alternatives in the sibling list.

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

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

Annotations only cover read-only/open-world hints, so the description carries the rest and does: it discloses result cap (up to 25), freshness semantics (re-read on a schedule, retired within ~36 hours of leaving), and the non-obvious rule that unposted pay is kept and ranked last rather than filtered out.

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 purpose and freshness, then inputs, then returns. Dense but every clause carries information; the long sentences slightly cost readability but not correctness.

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 enumerates what comes back (pay, asks, distance, last-confirmed time, apply link, job_id) and the 25-job cap, which is what an agent needs to plan. It omits any pagination behavior, which is the only real gap.

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 only 43%, so the description must compensate, and it does for the core fields (what/where/remote_only) and for filtering semantics. The enum-bearing params (radius_miles, employment_type, posted_within_days) are left to the schema, but their enums are self-describing.

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 (live US jobs on employers' own careers sites), plus the defining scope: jobs live right now, re-read on a schedule, retired within ~36 hours. This cleanly separates it from siblings like get_job and is_job_still_open.

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?

Tells the agent what to supply ('what' and 'where', or remote_only) and clarifies the filtering contract: only the filters given are applied and the listed 'asks' are never used to drop a job. No explicit when-not or named alternative, but context is clear.

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