getwork.dev

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds only the return content (full text and metadata), with no detail on pagination, size, or what happens when the id is missing.

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 tight sentence with no filler; the essential scope and id provenance are front-loaded.

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?

Adequate for a one-parameter read tool whose annotations cover safety, especially with no output schema to explain returns. Still missing the distinction from get_job and any failure-mode 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 coverage is 0%, so the description must carry the parameter meaning. It partially does by specifying the id is a job id obtained from search results, but adds no format, validation, or error behavior for an unknown id.

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 with scope: full text and metadata for exactly one job id. It is clear what it does, but it never differentiates from the sibling get_job, which appears to serve the same purpose.

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?

"Returned by search" implies the id must come from search results, giving implicit workflow guidance. However, there is no explicit when-to-use, when-not-to-use, or mention of the near-identical get_job alternative.

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, so the safety profile is covered. The description adds genuinely new context by flagging the employer description as untrusted_description, warning the agent to treat returned content as untrusted input — a real behavioral trait beyond the 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?

One front-loaded sentence with zero filler; the untrusted-content note is placed usefully at the end. It is efficient, though its brevity trades off against the missing usage and parameter guidance.

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?

An output schema exists so return values need no explanation, and annotations cover safety, keeping the bar low. However, for a lookup tool the description never explains how to obtain a valid id or what happens on an unknown id, leaving a real operational 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?

The single `id` parameter has 0% schema description coverage, and the description does not say what the id identifies, its format, or where to source it. With one parameter at zero schema coverage the description was obliged to compensate and does not.

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 ("Full JobSpec for one job") and scopes it to a single record, which implicitly separates it from batch/search siblings. It does not name any sibling explicitly, and the ambiguous sibling set (fetch, search_jobs, similar_jobs) leaves room for confusion about which retrieval tool to use.

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 statement of when to use this versus search_jobs, similar_jobs, or fetch. "one job" hints at single-record lookup but the agent gets no prerequisite (e.g., obtain id via search_jobs first) and no 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=true, idempotentHint=true and openWorldHint=false, so the safety and determinism profile is covered. The description adds only that results are scoped to companies 'in the index' with active-job counts; it says nothing about ordering, pagination or result size beyond what the output schema provides.

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 short clause with zero waste, and the key information (company + active job count) is front-loaded. The fragmentary, verb-less phrasing is the only structural weakness.

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 parameters, an output schema covering the return shape, and annotations covering safety, little more is required. The description supplies the conceptual scope of the list, making it adequate 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool 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 the resource precisely and states what each entry carries ('Companies in the index with their number of active developer jobs'), so an agent knows exactly what data comes back. It lacks a leading verb and does not distinguish this from siblings such as market_overview, which keeps it below 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?

There is no explicit when-to-use statement and no mention of alternatives among the seven siblings. The reference to 'active developer jobs' only implicitly suggests market/company-analysis scenarios.

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 and openWorldHint=false, so safety and determinism are covered elsewhere. The description adds the meaningful scope detail that results span all active jobs (no filtering), which is useful context an agent would otherwise lack. It stops short of saying anything about what a 'total' aggregates or how the technologies are ranked.

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 short sentence with no filler and the scope qualifier included. It is efficient, though so terse that it borders on under-specification rather than optimal density.

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?

An output schema exists, so return values need not be explained, and there are no parameters to document. The remaining gap is interpretive — what 'totals' counts and whether results are global-only — which the description gestures at but does not resolve.

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?

Zero parameters, so there is nothing to disambiguate and no schema gap to compensate for. The baseline of 4 applies; the description correctly implies the tool is unfiltered and global.

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 sentence names the resources returned (totals and most-requested technologies) and the scope (active jobs), so an agent can broadly infer an aggregate reporting tool. But there is no verb and no differentiation from siblings like salary_insights or list_companies, which also summarize job data. 'Totals' is left undefined, so the purpose is only loosely pinned down.

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 when-not-to-use, and no mention of any alternative among the seven siblings. The agent must guess that this is the tool for cross-job aggregate stats rather than search/salary tools.

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 safety (readOnly, idempotent, closed-world), so the description only needs to add disclosure beyond that. 'Active jobs' and 'from employer-published ranges' are genuinely useful caveats implying coverage gaps where employers don't publish pay, but nothing is said about aggregation behavior, minimum sample sizes, or how currencies are grouped in 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?

A single front-loaded sentence with the resource first and the scoping/source caveats after; no filler and nothing that could be cut without losing 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?

An output schema exists, so return-value explanation is not required, and annotations cover safety. But with 11 optional parameters and a percentage-style aggregation, the description leaves unclear how filters combine (AND vs OR, especially for exclude and regions) and what 'percentiles' means in the payload, which is a real gap for a tool of this complexity.

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 64%, and several parameters (remote, countries, seniority, role_family, posted_within_days, currency beyond 'per currency') carry no description in the schema. The description says only 'matching the filters' and 'per currency', adding essentially no meaning over the structured fields where the burden should fall on it.

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 (yearly salary percentiles) and constrains scope to active jobs matching the filters, plus the data source (employer-published ranges). It does not explicitly distinguish itself from the sibling market_overview, which likely reports similar aggregate pay data, so sibling differentiation is left implicit.

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?

No when-to-use / when-not-to-use guidance and no named alternatives, despite the presence of market_overview, search_jobs and similar_jobs which an agent could reasonably confuse with this. The only hint is the phrase 'matching the filters', which implies usage but doesn't route the agent.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely non-obvious behavior: it reports how the query was interpreted via a 'filters' field and discloses that it may broaden/relax filters to return results. It does not mention result caps or pagination, which is the only notable 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?

Dense but front-loaded: example first, then return shape, then routing advice. Every sentence carries information, though the return-shape clause is packed into a single long sentence that an agent must parse carefully.

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, and the description compensates by enumerating the returned fields (ids, titles, URLs, total, filters, broadened) including the two interpretive fields an agent must read to trust results. Missing only result-volume/pagination behavior.

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 0% schema coverage and a single opaque 'query' parameter, the description carries the full burden and does it well: it explains that salary floors ('over €120k') and exclusions ('no crypto') are understood, and that the query maps onto search_jobs arguments. It stops short of stating grammar limits or what phrasing is unsupported.

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 (natural-language job search) and immediately illustrates it with a concrete query example. It also distinguishes itself from both siblings it could be confused with: 'Use fetch for details' and 'Prefer search_jobs when you can set filters 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?

Explicit routing: use search_jobs when filters can be set directly, use fetch for full details, otherwise use this free-text entry point. The when-not condition is stated, not implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-open-world), so the bar is lower. The description still adds useful behavior beyond them: results are truncated to compact JobSpecs without descriptions and ordering follows relevance or recency, which materially shapes how an agent should consume the output.

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 purpose, then return shape, then the escape hatch to get_job. No redundant restatement of the title or 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?

An output schema exists, so return details needn't be spelled out, and the description correctly gestures at the compact result shape anyway. What's missing is any hint about combining the many optional filters or pagination behavior, but for a zero-required-parameter search tool the definition is adequate.

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 16 parameters and 63% schema coverage, several filters (limit, offset, remote, seniority, role_family, posted_within_days) carry no description in either place. The description adds no parameter guidance at all, so it neither compensates for the gap nor detracts; baseline 3 for mid-coverage 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 ('Search active developer jobs') plus the return shape ('compact JobSpecs, no description') and sort order. It explicitly distances itself from get_job, which returns details, so an agent can distinguish the two 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 line 'Use get_job for details' gives a clear routing rule to the sibling that returns full records. It doesn't state when not to search (e.g. use list_companies for slugs, market_overview for aggregate stats), but the primary alternative is named explicitly.

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 and closed-world, so the safety profile is covered. The description adds real value with its similarity criteria and the deduplication rule about the same role at other locations, but says nothing about behavior when the id is unknown or how the match threshold is applied.

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 sentence that front-loads the output ('Roles similar to a given job') and packs the similarity criteria and exclusion rule into one clause. No 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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. However, for a two-parameter tool with zero schema descriptions, the unspecified id format and completely undocumented limit leave gaps an agent would need to guess at.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely fails: 'a given job' implies the required id but never states whether it is a job ID, slug, or URL. The limit parameter — with a default of 10 and a cap of 25 — is not mentioned at all.

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 the resource ('roles similar to a given job') and defines similarity concretely (title, stack, description overlap), plus a negative rule (excludes the same role at other locations). It does not reference the sibling tools (get_job, search_jobs) to help an agent distinguish when this is preferable, but the retrieval itself is unambiguous.

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: it is clear you need a seed job in hand, and the exclusion clause hints at 'more like this' exploration, but the description never states when to choose this over get_job or search_jobs, nor any prerequisite that the id must exist.

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