Sourced, task-level facts on how AI changes jobs, for agents answering 'what should I do?'
Scored across 19 tools
Most tools target clearly distinct resources and actions (resolve vs search vs describe_coverage, get_change vs get_change_history vs find_affected, get_occupation vs get_role_tasks). A few clusters require careful reading to separate — notably find_notes / find_notes_for_occupation / get_note, and get_ontology (entity-scoped structured view) vs query_ontology (raw graph walk). Descriptions do help clarify each, but the note-family overlap is a real risk.
Strong, predictable verb_noun convention throughout (describe_, find_, get_, list_, resolve_, query_). The only real deviations are a bare 'search' with no noun and compound suffixes like '_for_occupation', but these stay readable and consistent with the overall scheme.
19 tools is on the heavier side, but the domain is genuinely multi-faceted (occupations, tasks, majors, evidence, changes, notes, ontology, transitions, business functions), and each tool appears to serve a distinct need rather than duplicating. No obvious filler, though consolidation of the note tools would tighten it.
Coverage looks robust: name resolution, coverage listing, keyword search, task-level and occupation detail, majors, evidence, changes, notes, transition paths, ontology traversal, business functions and a composite action brief. Minor gaps — no explicit list-all/compare operations and regulation access only via ontology traversal — but agents can work around these.
What VOLO covers and what it does not: the full list of covered occupations and degrees (slug and name), which occupations have no evidence yet, and the counts. Call this when someone asks whether their job is covered, and whenever resolve_occupation_or_major returns null — then decide from the list which entry, if any, the person means. The answer is a fact about this site rather than a guess about their job.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It usefully warns that the answer is a fact about the site rather than a guess about the person's job, tempering over-eager matching. However, it says nothing about auth needs, caching, rate limits, or whether the result is a static snapshot.
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 sentences, front-loaded with the content scope before the usage triggers, and the parenthetical '(slug and name)' earns its space by describing return structure. The final sentence is slightly editorial but adds behavioral value.
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 does well to outline the returned fields (covered slugs/names, uncovered list, counts). But the undocumented locale parameter and absence of any behavioral constraints leave gaps for an agent that must supply arguments correctly.
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?
There is one parameter, 'locale', with 0% schema description coverage, and the description never mentions it. An agent cannot tell whether locale selects a language, a regional occupation registry, or is optional cosmetic filtering, so the description fails to compensate for the schema 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 names the resource (VOLO coverage) and enumerates its contents precisely: covered occupations and degrees with slug and name, occupations with no evidence yet, and counts. It implicitly distinguishes itself from resolve_occupation_or_major by framing itself as the authoritative list rather than a resolver. It lacks an explicit action verb, which keeps it from 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?
It gives explicit triggers ('when someone asks whether their job is covered') plus a concrete fallback condition ('whenever resolve_occupation_or_major returns null'), and says what to do next with the result. This is unambiguous routing an agent can follow without inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which occupation and which specific tasks a change record bears on.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It implies a read-only query operation but does not disclose any edge cases, required permissions, output behavior, or what happens when a change record has no affected occupations or tasks.
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 description is very short and contains no wasted words, but it is under-specified as a sentence fragment. It lacks the structure needed to convey usage, parameter details, or behavioral context, so brevity comes at the cost of completeness.
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 two undocumented parameters, no annotations, and no output schema, the description is not complete enough. The sibling list contains several similar find_* tools, and without clearer context or parameter guidance, an agent may struggle to invoke this tool correctly or disambiguate it from alternatives.
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%, and the description adds almost no parameter meaning. It does not explicitly state that 'id' is the change record ID, and 'locale' is entirely unexplained despite being a parameter. The tool name and description weakly imply the role of 'id' but not its format or the purpose of 'locale'.
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 the specific purpose: identifying which occupations and tasks are affected by a change record. This distinguishes it from sibling tools like get_change (change record details) and find_evidence (evidence lookup), though it does not explicitly name 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?
Usage is implied rather than stated: the agent can infer to use this tool when it needs affected occupations/tasks for a change record. However, there is no explicit guidance about when not to use it or how it differs from alternatives like find_evidence or get_change.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verified evidence records for an occupation, optionally for one task. Each record carries its scope (where it applies), its stage, whether that stage can move a task judgement at all, and its source tier. Repeat the scope rather than smoothing it away.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No | ||
| taskId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does meaningful work: it enumerates what each record contains (scope, stage, whether the stage can move a judgement, source tier) and gives a specific data-shaping instruction ('Repeat the scope rather than smoothing it away'). This reveals behavior that would otherwise be unknown.
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 description is compact, front-loaded with the core purpose, and each sentence contributes: the first defines scope, the second defines record contents, and the third gives a distinctive behavioral instruction. The final sentence is slightly cryptic but still purposeful.
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 read-only lookup with no output schema and no annotations, the description provides a reasonable picture of return contents and filtering scope. It falls short on documenting the locale parameter and on giving any clarity about how slug should be formatted or resolved, leaving some ambiguity for an agent.
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 compensate. It maps 'occupation' to the required slug and 'optionally for one task' to taskId, which adds meaning beyond the bare parameter names. However, the locale parameter is not mentioned, and no format or value constraints are given for any parameter.
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 identifies the resource ('verified evidence records') and its primary scope ('for an occupation, optionally for one task'), which sets it apart from note- or transition-related siblings like find_notes or find_transition_paths. It lacks an explicit verb like 'list' or 'retrieve', but the noun phrase clearly implies a lookup operation.
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 gives no explicit guidance on when to choose this tool over alternatives, and it does not name any sibling tools or exclusions. The intended usage is only implied by the phrase 'for an occupation, optionally for one task'; there is no 'use when...' or 'not for...' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which degrees lead into this occupation.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the basic purpose and provides no information about return format, ordering, filtering, locale behavior, or any other operational characteristics.
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 text is very concise and front-loaded with the core purpose, with no wasted words. However, it is a fragment rather than a structured explanation and is too sparse to be considered appropriately sized for a tool with two parameters and no annotations.
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 description conveys the essential occupation-to-degree mapping but leaves crucial operational details unexplained, especially the 'locale' parameter and the meaning of 'slug'. With no output schema or annotations, this description is not sufficient for fully reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain either the 'slug' or 'locale' parameters. The agent must guess what 'slug' refers to and has no basis for understanding the role of 'locale'.
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 clearly states the tool's purpose: mapping an occupation to the degrees/majors that lead into it. It is specific enough to distinguish itself from most siblings, though it does not explicitly differentiate from similar tools like find_transition_paths.
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 gives no guidance on when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The intended use case is only weakly implied by the phrase 'which degrees lead into this occupation.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
VOLO's long-form answers to the big questions — how many jobs AI has actually taken, what actually gets automated, how long someone has, what AI law already changed, where AI lands in a company. Call this FIRST for any question that is about the whole picture rather than one occupation: those are exactly the questions you can answer fluently without evidence, and these notes are the evidence. Each result carries the note's own limits.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that each result carries the note's own limits, which is useful context. However, it does not state read-only behavior, query/locale semantics, or result format.
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 description is front-loaded and readable, but the list of example questions and the repeated emphasis on evidence make it longer than strictly necessary. Still, each sentence carries some purpose.
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 no annotations, no output schema, and 0% parameter coverage, the description leaves important gaps: parameter semantics, optional-parameter behavior, and return shape. It provides usage guidance and a caveat, but an agent needs more to invoke it correctly.
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%, and the description never mentions the query or locale parameters. 'Question' is referenced conceptually, but there is no mapping to the parameter names, types, or expected values, so the description adds no parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as VOLO's long-form notes/evidence for big-picture questions and distinguishes these from occupation-specific notes. The verb is indirect ('Call this FIRST' rather than 'search' or 'get'), but the resource and scope are clear.
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 explicitly says to call this first for questions about the whole picture rather than one occupation, and warns that these are questions an agent might otherwise answer without evidence. It implies exclusion of occupation-specific queries, though it does not name sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which notes argue from this occupation's own records or task judgements. Use it to point someone from their own page to the wider answer.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not explain whether the tool requires any authentication, what the output format is, or whether it is read-only. The phrase 'argue from this occupation's own records' hints at the tool's logic but is not enough to inform an agent about side effects, performance, or error behavior. The description adds some context but leaves significant behavioral aspects undisclosed.
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 description is extremely concise: one sentence that names the tool's function and its intended use case. It is front-loaded with the key purpose, and every word adds value, with no filler or repetition. This is an exemplary concise structure.
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 the tool's simple schema (2 params, no enums, no output schema), the description still lacks important context: it does not define what 'own records or task judgements' means, nor does it reference the sibling tools that might be competitors or complements. It also doesn't explain any return format. For a tool with zero annotations and no output schema, the description should provide more context beyond a single sentence to be considered complete.
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 compensate for the two parameters (slug and locale). The description does not explain that 'slug' is the occupation's identifier or that 'locale' might affect the language of results collecter. However, the parameter names are self-explanatory to some extent. Given the low coverage, the description falls short of fully clarifying the parameters' semantics, but it is not entirely absent—so I grant a 3 as the baseline for minimal compensation.
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 and resource ('find notes for an occupation') and adds a distinctive qualifier ('argue from this occupation's own records or task judgements'), which distinguishes it from the generic 'find_notes' sibling. It is clear enough for an agent to understand the tool's focused scope, though it could be more explicit about the exact nature of the notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: 'Use it to point someone from their own page to the wider answer' gives a clear context. However, it does not explicitly compare with sibling tools like 'find_notes' or 'find_evidence', and there are no exclusions or criteria for when not to use this tool. The guidance is better than nothing but lacks explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Options for someone in this occupation. Every path carries its real constraints (time, pay cut, seniority) and one action they can take this week that produces information. Never present a path without its constraint.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It provides some behavioral guidance by instructing that every path must include real constraints (time, pay cut, seniority) and one actionable step. This gives the agent an idea of output expectations. However, it does not disclose other behaviors like whether this is read-only, any side effects, or pagination. It is a partial but useful disclosure.
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 description is brief (two sentences) and front-loaded with the core idea, but it is cryptic and mixes behavior instructions with the purpose. It is not structured for clarity; the directive 'Never present a path without its constraint' is an instruction to the agent rather than a descriptive statement, making it less concise in meaning.
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 2 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain what the tool returns, how to interpret 'options,' or what 'slug' and 'locale' are. The behavioral note is the only redeeming part, but it does not cover the basic contract an agent needs to invoke the tool correctly.
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 compensate for the two parameters (slug, locale). It does not mention either parameter or give any hint about their meaning or format. The description is entirely disconnected from the input schema, leaving the agent to guess what 'slug' and 'locale' refer to.
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 says 'Options for someone in this occupation' which is vague and does not explicitly state it finds transition paths, despite the tool name. It fails to name the resource or distinguish from sibling tools like find_majors_for_occupation or find_evidence. The purpose is only implied.
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 guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or compare with sibling tools. The description assumes the agent knows when to call it, which is not the case among 15 find/get tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a person asks what they should do about AI or automation in their job ("I'm an accountant, how do I stay employable?"). One call returns, task by task: where the task is heading and how strong the evidence is; which laws, regulators, courts or collective agreements keep that task (or its signature) with a person; which employers or regulators have already moved it; and transition paths, each with its real constraints and one thing to check this week. Pass the job title as the person said it (any language) or a slug; optionally the task ids they actually do. Build your advice on these facts, keep each record's scope and each task's limits, and never turn it into a probability, a score or a number of years.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | ||
| taskIds | No | ||
| occupation | Yes | Job title in the person's words, or an occupation slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does real work: it discloses that a single call aggregates multiple data domains, that output must preserve each record's scope and each task's limits, and imposes a hard constraint against converting results into probabilities, scores, or year counts. It omits whether the operation is read-only, any auth requirements, and rate/limit behavior, 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?
Front-loaded with the usage trigger, followed by a dense but purposeful enumeration of return contents and closing behavioral constraints. Every clause maps to something the agent needs, though the middle sentence is long and could be broken up for scanability.
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 and no annotations, the description must carry return-value and safety context, and it describes the return shape in detail plus the interpretation constraints. It still leaves the locale parameter undefined and doesn't state side-effect/read-only status, so it is strong but not fully complete for a 3-parameter aggregator.
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 33% (only occupation is documented in the schema), so the description must compensate, and it does for two of three parameters: occupation accepts the person's own words in any language or a slug, and taskIds is explicitly optional and scoped to tasks the person actually performs. The locale parameter is never mentioned in either place, leaving one 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 names a specific verb (get) and a composite resource (an action brief), then enumerates exactly what the brief contains: task trajectories with evidence strength, legal/regulatory retention factors, employer movements, and transition paths. This clearly distinguishes it from narrow siblings like find_transition_paths or find_evidence by positioning it as the aggregate, one-call answer.
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 an explicit trigger condition with a quoted user utterance ("I'm an accountant, how do I stay employable?"), which is strong when-to-use guidance. It does not name sibling alternatives or state when to prefer them (e.g., find_transition_paths for paths only), so the routing guidance is clear but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One verified change record by id, with VOLO's reading: what it means, what it does not yet establish, and what a reader can verify themselves.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the record is 'verified' and that the response includes VOLO's reading, what it does not establish, and what a reader can verify. This gives useful behavioral context about the nature of the output. However, it does not disclose any side effects, error behavior, or access requirements, and 'verified' is somewhat ambiguous.
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 description is a single, compact sentence that front-loads the core action ('One verified change record by id') and then adds the distinctive interpretive value. It is concise and readable, though the phrasing 'with VOLO's reading' is slightly jargon-heavy.
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 simple get-by-id tool with two parameters and no output schema, the description conveys the core purpose and the unique nature of the response. However, it lacks parameter semantics and any guidance on locale, which is a required context for correct invocation. It is adequate but not complete.
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%, and the description does not explain the 'id' or 'locale' parameters. The description mentions 'by id' but does not clarify what the id refers to (e.g., change record id vs. occupation id) or how locale affects the response. With zero schema coverage, the description must compensate, and it 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?
The description states a specific verb ('get') and resource ('one verified change record by id'), and adds a distinctive scope: it returns VOLO's reading of the change, including meaning, limitations, and what a reader can verify. This distinguishes it from siblings like get_change_history and find_affected, though it does not explicitly name a 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?
The description implies usage: use when you need a single verified change record by id and VOLO's interpretive reading. It does not explicitly state when not to use it or name alternatives like get_change_history or find_affected. The context is clear enough for an agent to infer the primary use case, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The verified change timeline for an occupation, oldest first.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the output is a verified timeline, but does not mention whether the call is read-only, any pagination, error conditions, or what constitutes a 'change'. This is insufficient.
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 description is a single, clear sentence with no redundancy. It is concise and front-loaded, but its brevity sacrifices necessary detail.
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 definition is critically incomplete: it lacks parameter explanations, output shape, and any usage nuances. Given two parameters with no descriptions and no output schema, an agent would not be able to call this tool reliably.
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 input schema has zero description coverage, and the tool description does not explain the meaning of 'slug' or 'locale'. An agent cannot infer how to set these parameters correctly, making the tool effectively unusable without external knowledge.
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 clearly indicates the tool returns a change timeline for an occupation, ordered oldest first. It is specific enough to distinguish it from a single-change tool like get_change, though it doesn't explicitly name alternatives.
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 guidance is given on when to use this tool versus its siblings (e.g., get_change, get_occupation). The description doesn't mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A degree and the occupations it feeds. There is no score for a major and never will be — answer 'should I switch majors' by pointing at where it leads and what transfers.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that there is no score and never will be, but it does not describe the returned structure, what 'what transfers' means operationally, pagination, locale effects, or any side effects. This is a meaningful gap for a read tool with zero annotation support.
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 with no filler. The 'no score' disclaimer is purposeful and prevents a common misconception. Slightly more explicit structure could improve it, but it is appropriately sized and 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?
For a tool with no annotations, no output schema, and 0% parameter coverage, the description is too sparse to serve as a complete call contract. It gives a useful mental model but leaves required parameters, response shape, and the meaning of 'transfers' 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 0%, and the description does not mention slug or locale at all. It only implies that a degree/major is being looked up, leaving both parameter formats and meaning entirely to inference.
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 (a degree/major) and what it returns ('the occupations it feeds'), and explicitly disclaims scoring. It distinguishes itself from occupation-centric siblings by focusing on the major, though it uses a noun phrase rather than a clear imperative verb.
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 provides a concrete trigger: answer 'should I switch majors' by pointing at where the major leads and what transfers. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to recognize when get_major is the intended lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full text of one note, section by section, each section with the verified records it rests on. Use it when you need to quote or cite rather than summarise.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It meaningfully reveals the return composition: full note text, section-by-section, each section tied to verified records. It does not mention locale behavior, missing-note errors, or permissions, but it goes well beyond a bare restatement of the tool name.
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 with no filler. The core behavior is front-loaded, and the usage guidance is a single clear clause. Every word 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?
For a simple two-parameter retrieval tool with no output schema, the description adequately conveys what the response contains and when to use the tool. The main gaps are undocumented parameter semantics and no statement about error conditions or locale defaults, but these are modest for this tool's 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 0%, and the description does not explain what 'slug' or 'locale' mean or how they affect the result. It implies the note is identified by some single-key parameter, but the agent must infer that slug is the identifier and locale is an optional filter.
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 clearly states that the tool retrieves the full text of a single note, organized section by section, with the verified records backing each section. This is a specific verb-resource-scope combination and distinguishes it from sibling tools like find_notes or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use the tool when quoting or citing rather than summarizing, giving an agent a clear decision rule. It does not name the sibling alternative to use for summaries or state explicit exclusions, so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full task-level assessment of one occupation. Every task carries direction, basis (evidenced vs inferred) and limits — what that judgement does NOT establish. The impact index is not a probability of job loss and never appears without its confidence and assessment date.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and adds valuable caveats: task judgments have limits, the impact index is not a probability of job loss, and it always appears with confidence and assessment date. This meaningfully reduces misinterpretation, though it does not describe return shape or side effects.
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 with no filler, front-loaded with the core purpose. The second sentence earns its place by preventing misuse of the impact index and clarifying what the assessment does not establish.
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 description provides strong conceptual context about the assessment's content and caveats, which is important given no output schema or annotations. However, it omits parameter semantics, especially locale, and does not clarify the return structure, leaving an agent unable to confidently construct a correct call from the description alone.
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%, and the description never mentions slug or locale. It only implies that the slug identifies the occupation; locale semantics are entirely absent. The description does not compensate for the schema 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 opening phrase 'Full task-level assessment of one occupation' clearly identifies the resource and deliverable. It distinguishes get_occupation from the sibling find/search tools by emphasizing a single occupation's full task-level detail, though it does not name a specific alternative.
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 guidance is given on when to use this tool versus siblings like get_role_tasks or find_transition_paths. The description implies a use case, but it never states exclusions, prerequisites, or when an alternative would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where an occupation or a degree sits in the official classifications (U.S. Department of Labor ONET 31.0; U.S. Department of Education CIP–SOC crosswalk; the EU's ESCO, the ILO's ISCO-08 and Singapore's SSOC 2024): the matching codes with how well each fits, the skills, knowledge and work activities ONET rates highest (as ONET's own importance words, no numbers), related occupations and which degrees lead to it; each of this site's tasks aligned to ONET detailed work activities (or why none fits); and the rules this site's verified records read, with the verb that matters and whom it binds. For a degree: where the official crosswalk and this site's paths agree and disagree. Every block names its source. O*NET says what a job demands, not what automation is doing to it; never combine it with the impact index.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does substantial work: it names sources, states that O*NET importance values are words rather than numbers, notes that every block names its source, and explicitly warns that O*NET data cannot be combined with the impact index. It does not disclose output size or formatting, but the behavioral caveats are unusually specific and useful.
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 description is dense and long, but it is front-loaded with the core question 'Where an occupation or a degree sits' and every clause adds a distinct piece of information. It would be more digestible as bullets, but for a tool with this much output variety the length is justified.
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 complex tool with no output schema and no annotations, the description covers a remarkable amount: target entities, data sources, output sections, source attribution, fit quality, and a critical caveat. The main missing context is parameter-level behavior, especially locale, which keeps it from being fully complete.
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 compensate for the undocumented slug and locale parameters. It implicitly suggests slug identifies an occupation or degree, but it never explains what values slug accepts, what locale means, how it affects results, or what the default is. This is a meaningful gap for call construction.
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 resource (occupation or degree) and the exact data returned: classification codes with fit quality, top O*NET skills, related occupations, degree pathways, task alignments, and verification rules. It clearly differentiates from siblings like get_occupation and get_major by focusing on ontology/classification placement rather than a single profile.
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 when to use the tool: whenever an agent needs classification, skill, task, or rule context for an occupation or degree. It does not explicitly name alternatives or explain when a sibling like query_ontology or get_occupation would be preferred, though it does give one clear warning: never combine it with the impact index.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The task breakdown for one occupation. The unit of assessment is the task, never the job title.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions that the unit of assessment is the task, which is a useful clarification, but it omits other important behaviors such as whether the result is a list, pagination, error conditions, or side effects. The description is too sparse to fully inform an agent about the tool's behavior.
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 description is two sentences with no wasted words. The first sentence states the core purpose, and the second adds a relevant behavioral nuance. However, it is too terse given the tool's complexity, but as a standalone text it is concise and 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?
For a tool with no output schema, no annotations, and two undocumented parameters, the description is severely incomplete. It does not explain the parameters, return format, usage context, or how it relates to other occupation-related tools. An agent would struggle to call it correctly without additional information.
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% and the description provides no explanation for the two parameters, 'slug' and 'locale.' The agent must guess what 'slug' refers to or how locale affects results. The description completely fails to compensate for the schema 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 clearly identifies the resource as 'task breakdown for one occupation,' which matches the tool name and implies the return of task data. It distinguishes it from siblings like get_occupation by focusing on tasks rather than job details, though it does not explicitly name a sibling. The unit-of-assessment note adds clarification but does not fully differentiate from all 16 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?
There is no guidance on when to use this tool versus alternatives. The description offers a semantic caution ('unit of assessment is the task, never the job title') but does not specify contexts, prerequisites, or exclusions. With a large sibling set, explicit routing or conditions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For the business side: the functions a company is organised into, and which occupations sit in each. Use this when someone describes a company rather than themselves.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does convey the main behavior: returning the functions a company is organized into and which occupations sit in each. It stops short of explaining locale handling or response details, but for a simple listing tool the disclosure is reasonably complete.
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 no filler: the first states the subject matter and output, the second gives the usage trigger. It is front-loaded and 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?
For a straightforward list tool, the description covers purpose and usage context well. However, with no output schema and no explanation of the optional locale parameter, an agent lacks some information needed to call it optimally, so it is only minimally complete.
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%, and the description does not mention the 'locale' parameter at all. Since the description must compensate for the missing parameter documentation and does not, there is no added semantic meaning for the tool's only parameter.
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 clearly identifies the resource: business functions and the occupations that belong to each. The phrase 'rather than themselves' and 'business side' distinguishes this tool from personal/occupation-oriented siblings, giving an agent a precise sense of what it does and when it applies.
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 an explicit trigger condition: 'Use this when someone describes a company rather than themselves.' This is clear usage context, though it does not name alternative tools or provide explicit when-not-to-use guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the VOLO Ontology directly. No arguments: the object types and link types. type: the objects of that type. type + id: one object's properties and everything it links to, grouped by link. Add link (and direction: out|in) to follow one link. Types include Occupation, Task, TaskJudgement, Evidence, Regulation, WorkActivity and ClassificationConcept. Read-only; judgements keep their basis and limits, evidence its scope — carry them into the answer. No aggregate score exists.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| link | No | ||
| type | No | ||
| locale | No | ||
| direction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a solid job: it declares read-only behavior, explains that judgements and evidence retain their basis/scope, and denies the existence of an aggregate score. It omits details like authentication, locale effects, and exact return shape, but the essential behavior is transparent.
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 description is compact, logically ordered from simplest invocation to deeper traversal, and uses code formatting effectively. Every sentence earns its place with distinct information rather than 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?
Given the absence of an output schema and annotations, the description covers the main traversal modes and return categories reasonably well. Still, the unexplained `locale` parameter, lack of a concrete example, and no mechanism for enumerating link names leave noticeable gaps for a 5-parameter 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?
Because schema description coverage is 0%, the description must explain parameters, and it does for type, id, link, and direction. It even explains the no-arguments case. However, `locale` is entirely unexplained, which is a real gap for one of five 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?
The description opens with a clear verb–resource pair ('Walk the VOLO Ontology') and enumerates the main output modes: types/link types, objects by type, and object details with links. It does not explicitly distinguish it from sibling tools like get_ontology, but the core function 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?
It provides a concrete progression of invocation forms: no arguments, type, type+id, then link with direction. It also adds a guardrail by stating 'No aggregate score exists.' It does not name alternatives among the sibling tools, so explicit when-not-to-use guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a job title, a company's internal name for a role, a nickname or a degree name to a canonical VOLO entity. Call this FIRST whenever a person names their job. It matches names; it does not read sentences — so work out yourself which job the person means and pass only that title, in the singular ("taxi driver", not "Will robotaxis replace taxi drivers?"). Returns a match field of exact or approximate — when it is approximate, say which entity you read the question as. Null means this name did not match, not yet that VOLO lacks the job: before saying VOLO does not cover it, call describe_coverage and read its list of covered occupations and degrees — if one of them is what the person means (a synonym, a broader or narrower name), use that one and say which you chose. Only if none fits is it a gap in this site, which is not a statement about the job.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so well: it discloses matching semantics, the exact/approximate match field, the meaning of null, and the necessary follow-up workflow. It omits some operational details such as locale behavior or whether the lookup is read-only, but for a resolution tool the important behavioral traits are covered.
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 description is front-loaded with the primary action and usage rule, and each sentence carries useful operational information. It is somewhat long and contains layered instructions about null handling and coverage checking, but none of it is redundant 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?
There is no output schema and no annotations, so the description must explain enough for correct invocation and interpretation. It covers purpose, usage, return match semantics, null handling, and escalation to describe_coverage, though it leaves the locale parameter and exact result shape 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 compensate for both parameters. It adds meaningful constraints for 'query' (pass only the title, in singular, not a full sentence), but says nothing about the 'locale' parameter, leaving half the parameters semantically 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?
The description states a specific verb (resolve) and enumerates the resource types it handles: job titles, internal role names, nicknames, and degree names. It also distinguishes itself from siblings by instructing the agent to call it FIRST and by naming describe_coverage as the fallback. An agent can tell what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Call this FIRST whenever a person names their job'), when-not-to-use guidance ('it does not read sentences'), and concrete alternative routing ('before saying VOLO does not cover it, call describe_coverage'). It even specifies how to interpret a null result and what to do next, leaving little ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search occupations, majors and verified change records by keyword. Returns entries, not judgements.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose one behavioral trait: it returns entries, not judgements, which is useful. However, it does not clarify whether the operation is read-only (implied but not stated), how results are paginated or limited, or any potential side effects. The single behavioral note is insufficient given the lack of 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?
The description is exceptionally concise: two short sentences that immediately state the action and a key boundary. There is no redundancy or filler. The most important information is front-loaded, making it easy for an agent to parse quickly.
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 the tool has no annotations, no output schema, and no parameter descriptions, the description is far too minimal. It does not explain what 'entries' entails, how 'verified change records' are defined, how limit and locale affect results, or how this search relates to the sibling getters. An agent would struggle to use it correctly without additional information.
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 zero descriptions for any of the three parameters (limit, query, locale). The description only implies that 'query' is the search keyword via 'by keyword,' but it does not explain the purpose or format of 'limit' or 'locale.' It fails to compensate for the complete lack of parameter documentation 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?
The description clearly states the tool's purpose: it searches occupations, majors, and verified change records by keyword. It uses a specific verb and resource, and adds a boundary ('Returns entries, not judgements') that distinguishes it from judgment-oriented tools like find_evidence or resolve_occupation_or_major. This is a precise, non-tautological statement.
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 guidance on when to use this tool versus the many sibling tools (get_occupation, get_major, find_evidence, etc.). It does not mention when to prefer this broad search over a specific getter, nor does it state any exclusions or alternative conditions. The usage context is only implied by the search verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_action_briefquery_ontologyget_ontologydescribe_coveragefind_affectedfind_evidencefind_majors_for_occupationfind_notesfind_notes_for_occupationfind_transition_pathsget_changeget_change_historyget_majorget_noteget_occupationget_role_taskslist_business_functionsresolve_occupation_or_majorsearchTask-by-task AI exposure assessment of a job (Spain): 0-100 index, task map, weekly plan.
1.2M+ jobs from employer career sites, salary benchmarks and company hiring signals for AI agents.
Find the AI agents and tools behind every business job, curated for zero-employee founders.
Task and planning workspace for humans collaborating with AI agents
Add one secure layer between your agents and this server.
