OpenNash Jobs

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). The description adds genuinely non-structured context: the response includes dated evidence and coverage warnings, and employer-supplied text must be treated as untrusted rather than as instructions. That prompt-injection warning is high-value and not derivable 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?

Two tight sentences, front-loaded with the action and input, closing with the highest-stakes safety caveat. Every clause carries information; nothing is redundant.

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-structure detail is not required, and the description already flags what the response contains (dated evidence, coverage warnings). Combined with the untrusted-content caveat, the definition is sufficient for correct invocation, with only minor gaps around id provenance across sibling types.

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 parameter with 0% schema description coverage, so the schema contributes nothing beyond a type. The description compensates by explaining that the id is a 'search id' — the key provenance detail an agent needs to supply a valid value — though it doesn't state the id format or whether job and company ids are interchangeable.

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 verb ('Read') and resource ('a company or job document') and qualifies the input source ('from a search id'). It distinguishes itself from search/search_jobs by being the retrieval step keyed on a search result id, though it doesn't explicitly name which sibling produces that id.

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 phrase 'from a search id' implies this tool is used after a search call, which is useful sequencing guidance. However, there is no explicit when-to-use/when-not statement and no named alternative among the nine siblings, so usage must be inferred.

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, so the safety profile is covered. The description adds non-obvious behavior: a hard 20-candidate cap, ambiguity prompting, and two interpretation caveats that prevent misreading 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?

Opens with the core action, then layers constraints and caveats. Slightly fragmented across several short lines, but every sentence carries an operational rule 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?

An output schema exists so return values need not be spelled out, and the description still previews what comes back (candidates, observation date, freshness). Combined with input-form guidance it is complete enough 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 coverage is 0% and the single parameter has no description, but the tool text compensates by stating accepted input forms: exact names, canonical URIs, and partial names. That is the key semantic the bare 'company: string' schema omits.

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?

Specific verb+resource: resolves an employer name or canonical URI and surfaces coverage metadata (observation date, gaps, freshness). It is clearly distinguishable from siblings, and it explicitly hands off to search_jobs for the actual job lookup.

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 ambiguity handling ('ask the user to choose when ambiguous') and the downstream step ('Use returned company_uri for search_jobs'). Also gives two semantic exclusions (HQ country is not a job location; uncovered ≠ zero jobs), though it does not enumerate when a different coverage/trends sibling should be preferred.

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 read-only/idempotent/non-destructive profile, and the description goes beyond by disclosing the 1–26 week window, the meaning of null changes, the trend_status enum, and the caveat that a company can have current listings with no comparable weeks. That edge-case disclosure is exactly the kind of behavioral context annotations cannot convey.

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, then constraints, then status semantics and caveats, with no filler. The semicolon-chained clauses are dense but every one contributes a distinct fact.

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 spelled out, and the description adequately covers inputs, window, statuses and failure modes. What remains thin is any routing hint toward sibling tools for market-wide versus company-specific or coverage queries.

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 burden, and it does: it identifies 'company' as a canonical URI and constrains 'weeks' to 1–26 calendar weeks. It does not state the parameter names explicitly or the default, leaving mild ambiguity about which argument carries the window.

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+resource ('Read company anchors') and enumerates the concrete metrics returned (open, new, removed, described, AI and remote counts) over a defined window. It distinguishes itself from get_market_trends only implicitly via the word 'company', so it falls short of explicit sibling differentiation.

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 sets expectations for when results may be unusable (null changes, trend_status of limited/unavailable/unknown_company, warning checks), which is genuine usage context. It never explicitly says when to call this versus get_company_coverage or get_market_trends, so the guidance is implied rather than directive.

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?

Goes well beyond the annotations, which only cover the safe-read profile: it discloses the absence behavior (found=false when not in the current index), instructs the agent to preserve stale/partial warnings and unknown fields, and flags employer descriptions as untrusted content. That is exactly the extra behavioral context annotations cannot provide.

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?

Content-dense and front-loaded: purpose first, then constraints, then edge-case behavior. The stray line breaks and indentation make it slightly less tight than it could be, but every sentence earns its place.

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

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

With an output schema present, the description is not obliged to enumerate return fields, yet it still calls out the key result semantics (found=false, preserved warnings, untrusted content). Combined with the application-window constraint and the 'does not apply' boundary, an agent has everything needed to call and interpret this 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?

The schema has 0% description coverage, so the description carries the load; it explains that result_id is a handle obtained from search_jobs, which is real semantic value. It stops short of stating the expected format or validity lifetime of the id, leaving one small 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?

States a specific verb and resource ('Read a job's published description and official application URL') and pins the input's provenance to search_jobs. This clearly separates it from siblings like get_job_history, list_job_changes, and get_company_trends without needing to open 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?

Gives a clear usage context (called with a result_id produced by search_jobs) and a hard constraint ('Respect application_window.status; do not recommend closed or not-yet-open roles'), plus an explicit non-goal ('Does not apply for jobs'). It does not, however, name sibling alternatives such as get_job_history for past postings, so a 4 rather than a 5.

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/closed-world, so the safety profile is covered. The description adds genuinely new behavior: retention semantics for removed jobs and a caveat to cite event dates rather than the index build date, which an agent could not infer from 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?

Three short sentences, front-loaded with the return content, followed by the retention behavior and the citation caveat. No filler or redundancy.

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 documentation is not required, and the safety profile is fully annotated. The remaining gaps are the unexplained result_id parameter and the absence of sibling-relative routing guidance.

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% for the single required result_id, so the description must carry the burden. It merely restates the parameter name ("for a result_id") without saying what a result_id is, its format, or where to obtain one.

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 (Read) and the precise resource it returns: first/last observation plus retained lifecycle events for a result_id. An agent can tell it apart from get_job and list_job_changes, though it never explicitly names the boundary between them.

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?

"Removed jobs remain resolvable" implicitly tells the agent to reach for this tool when a job no longer appears in normal listings, which is a real usage signal. However, it never names an alternative or states when not to use it, so selection against get_job/list_job_changes is still 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: counts are distorted by changing employer coverage and partial inventories, and unknown seniority buckets include 'compacted evidence'. Those caveats materially affect how an agent should interpret results and could not be inferred 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?

Three dense sentences, front-loaded with what is read and over what scope, followed by the two return modes and finally the data-quality caveats. No filler, no restatement of the name, and each sentence introduces new 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 and the description still adds the one return detail that matters for interpretation (values_omitted and truncation), plus scope limits and coverage caveats. For a four-parameter read-only aggregation tool with annotations and an output schema, nothing an agent needs in order to call it correctly 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?

With schema coverage at 0%, the description carries the full burden and mostly succeeds: it defines the dimension choices (function, country, seniority), bounds weeks to 1–26, explains that 'top' returns 1–200 values per week with values_omitted reporting truncation, and that 'value' fetches a single exact entry. It does not state the defaults (top=10, weeks=12) or spell out that top and value are alternative modes, so a small gap remains.

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: reading observed role aggregates broken down by standard job family, country, or seniority across covered employers, over a bounded 1–26 week window. That is a clear, agent-parsable purpose. It stops short of naming how it differs from siblings such as get_company_trends, which presumably slices the same data by employer, so the 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?

Usage is implied rather than stated: the description makes clear this is the market-wide aggregate view, and it distinguishes the two retrieval modes ('top values per week' vs 'one exact value'). But there is no explicit when-to-use guidance against get_company_trends, get_job_history, or search_jobs, and no stated prerequisites or 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 declare a non-read-only, non-destructive, non-open-world write. The description adds real context beyond them: it discloses the audience ('read by the OpenNash team'), a frequency limit, and a PII prohibition with concrete categories. It does not say what the call returns or whether a response is expected, but the output schema covers return values.

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 purpose, then timing, then privacy. Every sentence carries information; no filler or restated title. Slightly dense with constraints, but none are redundant.

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?

The privacy, audience, and frequency context is strong, but for a 5-parameter tool with zero schema descriptions the definition should explain what 'impact' and 'category' mean and when to set tool_name. An agent must guess at half the argument surface.

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% across five parameters, yet the description never mentions impact, category, tool_name, or task_completed. It only implicitly describes the required 'message' content, leaving two enum fields and the tool_name field entirely unexplained.

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 ('Tell OpenNash about a problem with these tools') and further scopes it with the content expected: what you were trying to do, what you tried, where it went wrong. Clearly distinguishable from the fetch/search/trends siblings.

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 timing ('Call at most once per task, after finishing or giving up') plus an exclusion ('Do not send praise'). This is exactly the when/when-not guidance an agent needs for a side-channel tool that is easy to overuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the caveat to 'preserve evidence dates and completeness caveats,' hinting at data-quality limits, but omits pagination behavior and result-ordering details.

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 the verb and resource, then packs format and pagination guidance into short clauses. Dense but every sentence serves a purpose with 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 annotations cover the safety profile. The description covers the critical formats and pagination, though with 7 params at 0% schema coverage it could document limit and company to be fully self-contained.

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 carries the burden and partially compensates: it gives since format (YYYY-MM-DD), country as ISO alpha-2, function as a job family or raw source label, and cursor usage. Still, it leaves limit, company, and the event label mapping (first-seen vs. 'new') undocumented.

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 (List) and resource (job changes) with scope: first-seen, confirmed-removed, or returned jobs. This clearly distinguishes it from read siblings like get_job or get_job_history, though it doesn't name an alternative 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?

Provides a pagination instruction ('Follow next_cursor with identical filters') and format hints, which is useful context for repeated calls. However, it gives no explicit when-to-use vs. when-not guidance relative to siblings such as search_jobs, get_job_history, or search.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value by promising that every returned id is resolvable by fetch and that URLs point to official employer evidence, which helps the agent chain tools. It does not describe result volume, ranking, or pagination.

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 short sentences, no filler, with the core scope front-loaded before the resolvability guarantee. It is efficiently sized, though the first sentence's vagueness means the brevity partly reflects under-specification rather than tight writing.

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 spelled out, and the description usefully covers the fetch-chain guarantee. However, for a single-parameter discovery tool with no output explanation needed, the missing pieces are query semantics and routing versus search_jobs, leaving it only minimally 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?

The single required query parameter has 0% schema description coverage, and the description says nothing about what the query accepts — free text, employer name, job title, keyword syntax. With only one parameter and no compensating detail, the agent must guess at query form.

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 it finds "job and company documents for research," which gives a rough resource scope, but the verb is generic and there is no differentiation from the sibling search_jobs, which plausibly does something very similar. An agent cannot confidently tell this apart from search_jobs without opening both schemas.

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 guidance, no exclusions, and no named alternative despite seven sibling tools including a directly competing search_jobs. "For research" implies a context but does not tell the agent when this tool is preferred over fetch or the get_* family.

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?

Adds substantial behavior beyond the annotations: fresh-only is based on observation within seven days, closed or not-yet-open windows are excluded, unknown deadlines are not proof of openness, observed older listings return by default, warnings must be preserved, and repeat totals/has_more semantics are explained. It also discloses salary overlap and remote eligibility caveats. The read-only/idempotent annotations are fully consistent.

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: it starts with the operation, then moves through input constraints and result semantics. Most sentences carry operational value, though a few safety cautions about not inventing fields are repeated. The length is justified by the 19-parameter search surface.

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?

Given a complex 19-parameter tool with an output schema, the description covers the most consequential behavior and avoids restating return fields. It remains incomplete on sibling routing and several filter semantics. Overall it gives an agent enough to call the tool safely, but not a fully exhaustive manual.

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 zero schema description coverage, the description supplies critical meaning for company URI, location scope/country, fresh_only, posted_after, salary currency/period and overlap behavior, limit, and show_repeats. It still leaves query syntax, sort, offset, seniority, work_mode, and employment_type largely to the schema or parameter names. The coverage is strong but incomplete across 19 parameters.

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 ... job evidence') and immediately ties the company input to get_company_coverage. It is clear enough to distinguish from detail-oriented siblings like get_job, though it does not explicitly compare itself to the generic `search` sibling.

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

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

Provides concrete usage rules for key filters: scope=global for non-US locations, fresh_only for recently verified inventories, and posted_after as an employer publication date. It also warns not to treat location filters as the user's personal location. However, it never explicitly says when to choose this over siblings such as `search`, `get_job`, or `list_job_changes`.

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