Openings

Prepare job search

prepare_job_search

Idempotent

Download and refresh the local job index so searches have data to read. The first call fetches the shared index of every verified source (thousands of employers); later calls crawl only missing or stale sources, at most 25 per call, returning a continuation token until nextAction reports ready. Call it when a search says setup is needed, not before every search, and not at all on the hosted server, where the index is already prepared and this returns ready at once. Uses the network and writes job data under the local Openings data directory; it never reads, writes or transmits a resume.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`countries`	Yes	Two-letter codes whose sources should be prepared, such as IN or US
`continuation`	No	Opaque token from the previous call's result. Pass it back to prepare the next batch of at most 25 sources; omit it to start

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No
`crawl`	No	What this batch crawled: selected, succeeded, and the sources that failed
`status`	Yes	ready means searches can run now; partial means sources are still missing
`sources`	No	How many sources are in the catalog, indexed, fresh, stale, missing and pending
`coverage`	Yes
`nextAction`	Yes	call_again means pass continuation back for the next batch; retry_later means the network refused and waiting is the fix
`continuation`	No	Token for the next batch; present only when nextAction is call_again
`networkAttempted`	No	Whether this call actually reached out to employer boards

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 22, 2026

changedInput schema / properties / continuation / description

Previous value: -"Opaque token returned by the preceding preparation batch"New value: +"Opaque token from the previous call's result. Pass it back to prepare the next batch of at most 25 sources; omit it to start"

addedInput schema / properties / countries / description

Added value: +"Two-letter codes whose sources should be prepared, such as IN or US"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "continuation": {
+      "description": "Token for the next batch; present only when nextAction is call_again",
+      "type": "string"
+    },
+    "coverage": {
+      "additionalProperties": true,
+      "properties": {
+        "countries": {
+          "description": "Per-country live and recent role counts",
+          "items": {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "snapshotUpdatedAt": {
+          "description": "When the index this answer came from was last refreshed",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "crawl": {
+      "additionalProperties": true,
+      "description": "What this batch crawled: selected, succeeded, and the sources that failed",
+      "type": "object"
+    },
+    "networkAttempted": {
+      "description": "Whether this call actually reached out to employer boards",
+      "type": "boolean"
+    },
+    "nextAction": {
+      "description": "call_again means pass continuation back for the next batch; retry_later means the network refused and waiting is the fix",
+      "enum": [
+        "ready",
+        "call_again",
+        "retry_later"
+      ],
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "sources": {
+      "additionalProperties": true,
+      "description": "How many sources are in the catalog, indexed, fresh, stale, missing and pending",
+      "type": "object"
+    },
+    "status": {
+      "description": "ready means searches can run now; partial means sources are still missing",
+      "enum": [
+        "ready",
+        "partial"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "nextAction",
+    "coverage"
+  ],
+  "type": "object"
+}

First observedSep 22, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already mark the tool as not read-only, but the description adds genuinely new behavioral context: it uses the network, writes under the local Openings data directory, and never reads, writes, or transmits a resume. It also discloses the batch limit of at most 25 sources per call and the hosted-server shortcut, which are not visible in annotations. These details align with idempotentHint and destructiveHint without contradiction.

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

Conciseness5/5

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

Every sentence carries weight: core purpose, first-call vs continuation behavior, usage timing, environment exception, and side effects/privacy. The most decision-relevant information is front-loaded, and there is no filler or repetition of schema content.

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

Completeness5/5

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

The description covers the full invocation flow including first fetch, continuation tokens, batch size, readiness signaling, the hosted-server exception, and side effects. It also includes a privacy guarantee. With an output schema present, return values need no further elaboration, and nothing an agent needs to call this tool correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the schema already documents both parameters. The description adds semantic value for 'continuation' by explaining it is returned until nextAction reports ready and that at most 25 sources are prepared per call, going beyond the schema's generic 'Opaque token from the previous call's result' line. Countries receives no extra detail beyond the schema, but the existing schema description is already adequate.

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

Purpose5/5

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

The description opens with the concrete verb phrase 'Download and refresh the local job index', clearly stating the resource and intended effect. It further distinguishes this tool from consumers like search_jobs by framing it as the setup step that gives searches data to read. No ambiguity remains about what the tool does.

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

Usage Guidelines5/5

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

The description gives an explicit call condition: 'when a search says setup is needed', plus clear negations: 'not before every search' and 'not at all on the hosted server'. It also explains first-call versus continuation-call usage, so an agent knows exactly when to invoke and when to skip.

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

All Openings tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.