Headcount Labs

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

Annotations already cover read-only, idempotent, non-destructive, but the description adds behavior an agent could not infer: description-only counting degrades to an estimate with count_is_estimate and a 95% count_margin, broad filters also trigger estimation with count_note, and grouping is capped at 1,000 jobs with groups_sampled flagging sampling. It also warns that a job with several locations can count under more than one value, which materially affects how a count should be interpreted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core statement and the sibling preference are front-loaded, and each subsequent sentence carries substantive information. It is dense and long, and the estimate behavior is described in two separate places (description-only counting and broad filters), which could be consolidated, but there is little pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes on the return-shape burden and does so for the grouped responses (groups, groups_from_jobs, groups_sampled, groups_unknown_jobs and the employer-specific keys) and the estimate fields. What remains thin is the non-grouped base response and the bulk of the nested filter parameters, which the description largely leaves to the schema.

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%, and the description compensates for the most consequential gaps: q matching semantics (every word must match, use description_advanced for OR), the q + title/company constraint, and the full group_by enum behavior with per-value response keys. It does not explain most of the long filter tail (pay_min/pay_max, posted_since, radius_miles pairing), so it adds value but does not fully close 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?

"Count matching jobs without listing them" gives a specific verb (count) and resource (jobs), and explicitly scopes it as the live count versus the sibling tools market_lookup and market_breakdown. An agent can distinguish it from search_jobs and the market_* tools 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?

It states exactly when to prefer this tool ("how many", "which employers are hiring") and names the alternatives it supersedes. It also gives concrete routing rules for the group_by variants ("which companies are hiring for X", "how are these jobs split by ...") and a constraint on how to count by q (needs a title or company filter).

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 readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds real value beyond that by disclosing the default response shape, the extra fields included (description, currentness, stale, last_checked_at, linked postings), and what view: full expands to.

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 front-loaded sentences with no filler; the default-shape sentence is dense but every clause carries information about what is returned. Slightly list-like but appropriately sized for a read tool with three parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return values and does so for both the compact default and the full view. Minor gap: it does not state error behavior for an unknown job_id, 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?

Schema coverage is 67% and the schema already documents view and fields, but the description reinforces the compact-vs-full distinction and the guarantee that job_id is always included, which helps an agent reason about the fields projection without cross-referencing the 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 ('Get a job by job_id') and immediately positions the result relative to the sibling search_jobs ('Default shape matches search_jobs, plus...'), so an agent can distinguish the two 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 guidance on when to use view: "full" versus fields for picking top-level properties, and implies search_jobs is the discovery path. It stops short of explicitly saying 'use search_jobs to obtain a job_id', so it is clear context rather than full when/when-not 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 already declare readOnly, idempotent, closed-world and non-destructive behavior, so the safety profile is covered. The description adds substantive semantics the annotations cannot: the no-keyword 'list everything' behavior, the filter-vs-field distinction, and what a field state object means (known vs Atlas-derived vs omitted vs extraction failed). It does not mention result count limits or pagination, which is the 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?

Three compact sentences, front-loaded with purpose and followed by call shape, then the result vocabulary. No filler, though the parenthetical 'postings[].x is a posting property' is terse to the point of being slightly cryptic and the field-state sentence is dense.

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 a single optional parameter and no output schema, the description sensibly narrates what comes back (type plus short description, and the meaning of field state objects). That is nearly enough to call the tool correctly; only result limits and the relationship to search_docs are unaddressed.

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 meaning of 'keywords', and it does: it gives concrete example values and states the default semantic (empty array returns everything), which is not derivable from the bare array schema. It does not mention the 20-item cap or 100-character limit, but those are enforced by the schema itself.

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: 'Find search_jobs filters and job fields matching keywords.' It also ties the tool explicitly to the sibling search_jobs and states what each result carries (type and a short description), so an agent can distinguish this discovery tool from consumers like search_jobs, get_job, or count_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?

Usage context is clear: pass keywords like ["pay", "remote"] to narrow, and 'no keywords lists everything' defines the empty-call case, while 'kind is filter or field' tells the agent how to interpret results before using them in search_jobs. It stops short of explicit exclusions, e.g. it never contrasts this with the sibling search_docs for looking things up, so the agent must infer that 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 read-only, non-destructive, idempotent behavior, so the description focuses its budget elsewhere and delivers real added context: the data is a daily snapshot rather than live ('see as_of'), low-volume cells under 30 jobs are silently dropped, and no account is required. Those three facts materially change how an agent should interpret sparse or stale results; only freshness granularity (timezone/refresh cadence) and result shape remain unstated.

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?

Four short sentences, front-loaded with the core action before the alternative tool and the caveats. Every clause carries information an agent needs — enumerated dimensions, sort targets, freshness, suppression threshold, auth — with no filler or restatement of the 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?

With 10 optional parameters, no output schema, and a read-only annotation set, the description covers the essentials: what gets ranked, how to sort, filter scoping, freshness, minimum-cell suppression, and auth. The main residual gap is that with no output schema the description never sketches the shape of a breakdown row (dimension value plus metric), leaving an agent to infer 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 coverage is 100%, so the schema already defines every parameter and the baseline would be 3. The description still earns credit by framing role/title/place/company/seniority/employment_type/remote as filters that narrow the ranking ('optionally inside a filter') and by naming the sort family ('jobs, pay or another figure'), which clarifies the relationship between 'by' and 'sort' that the schema documents only per-field.

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 bounded resource: 'Rank one dimension (by: title, state, city, company, seniority, employment_type or remote) by jobs, pay or another figure'. The enumerated dimensions and sort targets make the operation concrete, and the closing pointer to count_jobs clearly separates it from the sibling that returns live totals rather than ranked breakdowns.

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 the key routing rule explicitly: 'For live counts or who is hiring now, use count_jobs', which is the most likely confusion given the sibling set. It also implies the filter parameters are optional scoping ('optionally inside a filter'). It does not distinguish against market_dimensions, market_lookup or salary_range, so the guidance is clear but not exhaustive across all siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The one genuine addition is 'No account needed,' which tells the agent this is an unauthenticated metadata lookup, but nothing is said about caps (limit max 50), result volume, or whether values are stable/cacheable.

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 tight, front-loaded sentence with no filler; the semicolon cleanly separates the catalog mode from the drill-down mode. Slightly dense parenthetical phrasing ('(and optional q)') costs it a point but 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?

There is no output schema, so the description is the only place the return shape could be explained, and it does not say what a 'dimension' record looks like (plain strings vs. objects carrying metrics, and how limit affects results). For a three-parameter discovery tool with full annotation coverage this is adequate but leaves a real gap around return format.

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 3 is the floor. The description does add meaning beyond the schema by explaining the mode switch: omitting dimension lists dimensions and metrics, while supplying dimension (with optional q) lists that dimension's values, which the per-parameter descriptions do 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 (list dimensions and metrics) and names the three sibling tools that consume those dimensions, which distinguishes it from count_jobs, search_jobs, etc. It is not quite a 5 because the tool's own identity as a discovery/reference endpoint is only implied through the sibling list.

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 a two-mode workflow: call bare to list dimensions/metrics, or pass dimension (and optional q) to list that dimension's values, and it ties the output to market_lookup, market_breakdown and salary_range. However it never explicitly says 'call this before' those tools or when not to use it, so the prerequisite relationship is left to inference.

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/idempotent annotations, it discloses several non-obvious traits: results are a daily snapshot (not live), cells with fewer than 30 jobs are suppressed for privacy/statistical validity, and no account is needed. These are exactly the operational facts an agent cannot infer from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four compact sentences with the capability statement front-loaded and constraints and the sibling redirect after it; almost nothing is wasted. The opening sentence is a long enumeration, but every item is a distinct supported metric rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, zero-required tool with no output schema, the description covers input rules, suppression, freshness and auth well. It says nothing about the shape of the returned figures, and the 'see as_of' reference points at a field that is never defined, leaving the agent guessing about response structure and how to read the snapshot date.

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 3 is the baseline, but the description adds a cross-parameter constraint absent from the schema: at most two of title, place, company, seniority, employment_type and remote may be combined, and metric may be omitted to return everything. That is genuine meaning beyond the per-field descriptions.

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 and resource (look up job market figures) and enumerates exactly which figures: job count, pay, pay share, work arrangement, posting age, new postings, top employers. It also explicitly distinguishes itself from the sibling count_jobs for live counts, so an agent can choose 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?

It gives a concrete when-to-use rule ('up to two of' the six dimensions, omit metric for all figures) and one explicit alternative ('For live counts or who is hiring now, use count_jobs'). It does not route the agent between market_lookup and the closely overlapping market_breakdown, which shares nearly identical filters, so the guidance is clear but not exhaustive.

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 and closed-world, but the description adds genuinely new behavioral facts: the data is a daily snapshot (as_of), cells with fewer than 30 jobs are suppressed, and no account is needed. The suppression threshold and freshness window are exactly the kind of context an agent cannot get from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core payload (percentiles), then constraints, then the alternative tool — a sensible ordering. It is dense but nearly every clause earns its place; the parenthetical "(see as_of)" is slightly cryptic without a defined output field.

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 conveys the return shape (percentiles, sample size, recommendation) plus the two things an agent must know before calling: the snapshot cadence and the small-sample suppression. Nothing material is missing for a zero-required-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%, so the schema already explains role/title synonyms, place formats and seniority values. The description only adds the default-US behavior and that seniority is optional, which is marginal added meaning. Baseline 3 applies when the schema carries the parameter burden.

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 (posted pay percentiles 25/50/75/90) with concrete inputs (title, place, seniority) and even names the returned extras (sample size, short recommendation). This is clearly distinguishable from count_jobs and the other market_* siblings, which deal with counts and breakdowns rather than pay percentiles.

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 routes the agent away from this tool for live counts or current hiring activity ("use count_jobs"), which is a real when-not-to-use statement. It does not differentiate against the other siblings such as market_breakdown or market_lookup, so the routing guidance is partial rather than complete.

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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaning beyond that by disclosing the auth requirement ('works without an account') and the return shape ('matching sections with URLs'). What it does not say is whether results are ranked, how empty results are represented, or whether search is keyword-based or semantic, 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?

Two sentences, no filler, and the topic scope plus return format are front-loaded before the account note. Every clause carries information an agent can act on.

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?

This is a simple read-only tool with only two parameters and no output schema, so the bar is low, and the safety profile plus auth note largely cover it. The remaining gap is parameter semantics: with 0% schema coverage and no output schema, the description is the only place where an agent could learn what 'question' and 'limit' mean, and it omits both.

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 clarify both parameters, and it does not. The phrase 'filters, limits, MCP setup, errors' reads as documentation topics, and could even be misread as parameter names, while neither 'question' (a natural-language query, up to 500 chars) nor 'limit' (result count, default 5, max 10) is explained. The only hint is 'return matching sections', which loosely implies that limit caps the number of sections returned.

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 and resource (search the Headcount Labs docs), enumerates the covered topical scope (filters, limits, MCP setup, errors), and describes the output shape (matching sections with URLs). It is clearly distinct from all siblings, which deal with jobs, markets, and salaries. It stops short of an explicit sibling comparison, but the subject matter alone separates it.

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 states that the tool works without an account, which tells the agent it can be called in unauthenticated contexts. However, it never states when to prefer this tool over the sibling tools, nor does it describe exclusions or prerequisites beyond the login detail. Usage is therefore only implied by the topic 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 already declare read-only, idempotent, non-destructive and closed-world, and the description still adds substantive behavior: a 250-job result ceiling, page sizes of 50 (10 when descriptions is "full"), cursor-based paging via next_cursor, the default compact summary field set, and the snippet-vs-full tradeoff. These are operational constraints an agent cannot infer from 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 purpose and then ordered by what an agent needs next: filter discovery, paging, result caps, output shape, then matching semantics. It is dense and somewhat run-on, but nearly every sentence carries a distinct constraint and none is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 top-level parameters and ~50 nested filters and no output schema, the description covers paging, caps, defaults, result shape and fallback tools well enough to call it correctly. The remaining gap is that most individual filter keys are left to list_fields rather than described inline.

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 71%, and the description adds real meaning on top: comma-separated or array acceptance for country and employment_type, the phrase-in-order semantics of title versus AND/OR/NOT for title_advanced, the allowed sort values, and the limit defaults per mode. It does not explain the many $ref'd filters that carry no schema description (msa, stale, active, has_pay, source_class, etc.), though it does redirect to list_fields for those names.

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?

Opens with a specific verb and resource plus the facet list it searches ('keyword, title, company, place, pay and date'), and names siblings (list_fields, count_jobs, get_job) so an agent can separate this from them 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?

Explicit routing is given at several decision points: list_fields for filter names, count_jobs when the agent only needs match volume, get_job or view/fields when more detail is needed, and title_advanced when boolean word matching is required instead of phrase matching. It also states the escalation path when results are truncated ('narrow filters or use count_jobs').

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