Integrates with the Google Maps Geocoding API to resolve place names to coordinates and enable map-region job search via bounding boxes and radius.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@j-hunt-mcp search for remote Python jobs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local job-hunting MCP server built on the official Python SDK (mcp / FastMCP).
It runs over stdio for Claude Desktop / Claude Code and helps with the full loop:
Discover jobs across pluggable web sources — including geo / map-region search.
Track applications through a status lifecycle.
Store a profile & resume the assistant can reference.
Tailor resumes / cover letters via reusable prompts (the client LLM does the writing).
Strict, one-directional layering keeps business logic out of the MCP glue:
tools/ • resources.py • prompts.py (thin MCP adapters — no logic)
│
▼
services/ (all business logic; constructor-injected deps)
│
┌────────┼─────────────┐
▼ ▼ ▼
repositories/ scraping/ geo.py (SQLite • job sources • Google Maps)
│
▼
models/ (pure Pydantic domain types, reused by every layer)Layer | Location | Responsibility |
Models |
| Pure Pydantic domain types (one file per domain) |
Repositories |
| SQLite persistence; map rows ↔ models (SQLAlchemy tables kept separate) |
Services |
| Business logic (search, tracking, profile, geo) |
Scraping |
| Pluggable |
Tools/Resources/Prompts |
| Thin MCP adapters over services |
Related MCP server: job-search-mcp
Requires Python ≥ 3.10 and uv.
uv sync # install deps
cp .env.example .env # optional: add GOOGLE_MAPS_API_KEY for geo search
uv run pytest # run the test suite (offline)uv run j-hunt-mcp # run the stdio server directly
uv run mcp dev src/jhunt_mcp/server.py # open the MCP Inspector (needs Node/npx)uv run mcp install src/jhunt_mcp/server.py --name "Job Hunt" \
-v GOOGLE_MAPS_API_KEY=your_key_hereRestart Claude Desktop; the Job Hunt server's tools then appear.
Tools
Tool | Purpose |
| Keyword search; optional |
| Search inside a map-selected bounding box (NE/SW corners) |
| Resolve a place name → coordinates + formatted address |
| Persist and list jobs |
| Record an application (by saved |
| Move an application through its lifecycle (validated) |
| Set a follow-up reminder on an application |
| List applications, optionally filtered by status |
| Manage the stored profile & resume |
Resources: profile://me, resume://current, jobs://saved, applications://{status} (use all).
Prompts: tailor_resume, draft_cover_letter, application_followup_email.
There is no map UI in the server itself — a client passes the result of a map
selection as parameters. Three shapes are supported, all requiring GOOGLE_MAPS_API_KEY:
a place string + radius_km (search_jobs),
a bounding box (search_jobs_in_region) — what a map rectangle yields,
(internally) a center + radius.
Geocoding results are cached in SQLite to conserve API quota. Without a key, plain keyword search still works; geo paths return a clear error.
Major boards (LinkedIn, Indeed) actively block scraping and forbid it in their ToS. v1 therefore ships sources that expose public JSON/RSS and are scraping-tolerant: RemoteOK, WeWorkRemotely, Hacker News "Who is hiring?". Requests are rate-limited per host. Add a board by implementing
scraping/base.py:JobSource.
Never commit credentials. The only secret today is GOOGLE_MAPS_API_KEY, read from a
gitignored .env via pydantic-settings. When authenticated boards are added later,
use the OS keyring for passwords and the SQLite DB for session cookies — never JSON in
the repo. mcp install ... -v KEY=value injects env vars without writing them to source.
The SQLite database lives at data/jhunt.db by default (override with JHUNT_DB_PATH).
The data/ directory is gitignored.
Resolve a place name to coordinates + a formatted address (Google Maps).
| Name | Required | Description | Default |
|---|---|---|---|
| place | Yes |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| coordinates | Yes | |
| formatted_address | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions using Google Maps but does not disclose limitations, error handling, rate limits, or that the tool may require authentication. The behavioral transparency is minimal.
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 sentence that directly conveys the tool's purpose without any extraneous information. 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?
Given the tool's simplicity (one parameter) and the existence of an output schema, the description is adequate but lacks details on return structure, error states, or usage constraints. It meets the minimum viable completeness.
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 description does not explain the 'place' parameter beyond the schema's title and type. With 0% schema description coverage, the description fails to add any semantic detail about the parameter's format, examples, or constraints.
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 verb 'Resolve' and the resource 'place name to coordinates + a formatted address', specifying the output. It distinguishes from sibling tools as no other tool performs geocoding.
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?
Though no explicit when-to-use guidance is given, the purpose is self-evident. The description implies usage for converting place names to coordinates, and no similar sibling tools exist, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the stored job-hunt profile (name, skills, resume, preferences).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| full_name | No | |
| headline | No | |
| skills | No | |
| years_experience | No | |
| locations_preferred | No | |
| remote_ok | No | |
| resume_text | No | |
| links | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses it returns profile data with no side effects, but lacks details about authentication, caching, or any special conditions. Since no annotations are provided, the description carries the full burden, and it meets basic expectations but adds no extra context.
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?
Single sentence, no filler, front-loaded with the action and contents. 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?
Given the low complexity and presence of an output schema, the description adequately covers the tool's function. It lists key fields but could be slightly more specific about the structure of preferences.
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?
No parameters exist, so schema description coverage is 100%. The description adds no parameter info (none needed), and the baseline for zero parameters is 4.
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?
Description clearly states it returns the stored job-hunt profile, listing specific fields (name, skills, resume, preferences), and is easily distinguishable from sibling tools like update_profile and set_resume which are write operations.
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 explicit guidance on when to use this tool versus alternatives. While it's implied that it should be used when profile info is needed, there is no mention of context, prerequisites, or prohibitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tracked applications, optionally filtered by status.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states it lists applications; no mention of pagination, ordering, rate limits, 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?
One clear, front-loaded sentence with no redundancy. Efficiently conveys the tool's 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?
Simple tool with output schema, so return format is covered. Missing details on default behavior (e.g., unfiltered returns all?), pagination, or sorting. 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 coverage is 0% (no parameter descriptions in schema). The description adds 'optionally filtered by status' but doesn't explain status values beyond the schema's enum definition. Baseline 3 with low coverage.
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 'List tracked applications, optionally filtered by status' clearly states the action (list), resource (applications), and optional filter. It distinguishes from siblings like list_saved_jobs.
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 on when to use this tool vs. alternatives (e.g., list_saved_jobs). Lacks context on prerequisites or when filtering is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all jobs that have been saved locally.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not disclose any behavioral traits beyond the basic action, such as side effects, return format for empty results, or authentication requirements.
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, concise sentence with no wasted words. The key action is front-loaded ('List all jobs...'), making it quick to parse.
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 tool with no parameters and an existing output schema, the description is adequate but lacks context about what 'saved locally' means operationally. Additional behavioral details would improve completeness, but the tool's simplicity reduces the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema coverage is 100%, so baseline is 4. The description adds no parameter information, but this is acceptable since there are no parameters to document.
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 'List all jobs that have been saved locally,' which is a specific verb-resource combination. It distinguishes itself from siblings like 'save_job' (which saves) and 'search_jobs' (which searches all jobs).
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 provided on when to use this tool versus alternatives such as 'search_jobs' or 'list_applications'. There is no mention of conditions, prerequisites, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an application for a job (by saved job_id or an ad-hoc url).
Creates the application, or updates the existing one for that job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| url | No | ||
| status | No | applied | |
| notes | No | ||
| applied_at | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| job_id | Yes | |
| status | No | |
| applied_at | No | |
| next_action_at | No | |
| next_action_note | No | |
| notes | No | |
| created_at | No | |
| updated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses upsert behavior and identification methods, but lacks details on parameter interactions (e.g., if both job_id and url are given, or how notes/applied_at update on existing records). No annotations provided.
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 concise sentences that front-load the purpose and behavior. No unnecessary words.
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?
Covers core upsert logic but missing details on parameter interactions, return values, and edge cases. Output schema exists but is not referenced in description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description partially explains job_id and url as identifiers but does not elaborate on status, notes, or applied_at. Adds some value but incomplete.
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 records/updates an application for a job, distinguishing it from siblings like save_job or update_application_status.
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 explains the two identification methods (job_id or url) and upsert behavior, but does not explicitly contrast with siblings or specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a job (e.g. one returned by search) so it can be tracked.
| Name | Required | Description | Default |
|---|---|---|---|
| job | Yes |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| source_job_id | Yes | |
| title | Yes | |
| company | No | |
| location_text | No | |
| remote | No | |
| url | Yes | |
| description | No | |
| salary_text | No | |
| posted_at | No | |
| id | No | |
| coordinates | No | |
| scraped_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'persist' without describing side effects (e.g., overwrites? duplicates?), auth needs, rate limits, or return 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?
One sentence, no wasted words, but lacks structure (e.g., no separation of purpose, usage, behavior). Appropriate length for minimal info but insufficient for 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?
Given the single complex parameter, the description is too brief. It does not explain what 'job' should contain (fields from schema are not referenced) or what happens after persistence. Output schema exists but is unmentioned.
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%; the description does not mention the 'job' parameter or its structure. The schema itself is rich, but the description adds no additional meaning beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it persists a job for tracking, but does not distinguish from siblings like list_saved_jobs or search_jobs. It is specific enough with verb+resource.
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 on when to use this tool versus alternatives (e.g., search_jobs, list_saved_jobs). No exclusions or contextual cues provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search job listings across configured sources.
Provide location + radius_km to restrict results to jobs near a place
(requires GOOGLE_MAPS_API_KEY). Omit them for a plain keyword search.
sources optionally restricts to named sources (e.g. ["remoteok"]).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| location | No | ||
| radius_km | No | ||
| remote | No | ||
| sources | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses the API key dependency for location, but omits other behaviors such as pagination, empty result handling, default sources, or whether the tool returns jobs from all configured sources by default. Insufficient for a full behavioral understanding.
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?
Concise with four sentences, no fluff. Front-loads the main action and uses bullet-like structure for clarity. Every sentence adds 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?
Covers the main functionality and key parameters (query, location/radius, sources). Missing explanation for 'remote' parameter, which is not obviously inferred. Output schema exists so return values are documented elsewhere. Overall adequate for a search tool with multiple parameters.
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?
Adds meaning beyond the schema (0% description coverage) by explaining location/radius_km combo and sources parameter. However, 'remote' parameter is not explained (e.g., boolean for remote-only or include remote?), and max_results default is mentioned but not elaborated. Adds moderate value.
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?
Clearly states 'Search job listings across configured sources' with a specific verb and resource. Differentiates from sibling tools like search_jobs_in_region and geocode_location by focusing on general search with optional location filtering.
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 clear guidance: use location+radius_km for geospatial search (requires API key), omit for plain keyword search. Also mentions optional sources restriction. Lacks explicit when-not-to-use versus alternatives like search_jobs_in_region, but context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search jobs inside a map-selected rectangular region (a bounding box).
Pass the north-east and south-west corners of the selected area. Requires GOOGLE_MAPS_API_KEY (job locations are geocoded to test containment).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| ne_lat | Yes | ||
| ne_lng | Yes | ||
| sw_lat | Yes | ||
| sw_lng | Yes | ||
| remote | No | ||
| sources | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden of behavioral transparency. It discloses an important dependency: job locations are geocoded to test containment, requiring an API key. This is valuable context for the agent. However, it does not mention whether the tool is read-only, which would be helpful.
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 long, concise and front-loaded. The first sentence defines the purpose, and the second adds the mechanism and requirement. No unnecessary words 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?
Given the tool has 8 parameters, 5 required, and a sibling 'search_jobs' that contrasts with this region-specific variant, the description covers the key distinguishing aspects (region-based, geocoding) but lacks details on pagination, error handling, or optional parameter behavior. An output schema exists, which reduces the need to describe return values.
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 0% description coverage, so the description must compensate. It explains the four coordinate parameters (ne_lat, ne_lng, sw_lat, sw_lng) by stating to 'pass the north-east and south-west corners.' However, it does not describe the 'query', 'remote', 'sources', or 'max_results' parameters, leaving a gap in semantics for those.
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: 'Search jobs inside a map-selected rectangular region (a bounding box).' The verb 'Search' and resource 'jobs' are specific, and the scope 'inside a map-selected rectangular region' distinguishes it from the sibling tool 'search_jobs' which likely performs a general search without geographic constraints.
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 explains when to use the tool (when a bounding box is selected on a map) and mentions a prerequisite: 'Requires GOOGLE_MAPS_API_KEY.' It does not explicitly state when not to use it or reference alternatives like 'search_jobs' for non-geographic queries, which would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a follow-up reminder (date + note) on an application.
| Name | Required | Description | Default |
|---|---|---|---|
| application_id | Yes | ||
| when | Yes | ||
| note | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| job_id | Yes | |
| status | No | |
| applied_at | No | |
| next_action_at | No | |
| next_action_note | No | |
| notes | No | |
| created_at | No | |
| updated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like side effects (e.g., whether it overwrites existing reminders), permissions needed, or idempotency. It only states 'set a follow-up reminder' without any behavioral context.
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 sentence, very concise. However, it sacrifices necessary detail for brevity. It is not bloated, but it is under-informative.
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 and an output schema (not shown), the description should explain return behavior or success confirmation. It lacks any completeness regarding what the tool returns or how to interpret the result.
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 mentions 'date + note' but does not explain the 'when' format, that 'application_id' is required, or that 'note' is optional. The added value is minimal.
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 uses a specific verb 'Set' and resource 'follow-up reminder' on an application, clearly differentiating it from sibling tools like 'log_application' or 'update_application_status'. It is not a tautology and effectively communicates the tool's primary function.
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 provided on when to use this tool versus alternatives (e.g., when to set a next action instead of logging an application). The description does not mention prerequisites or context for using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store/replace the resume text used by the tailoring prompts.
| Name | Required | Description | Default |
|---|---|---|---|
| resume_text | Yes |
| Name | Required | Description |
|---|---|---|
| full_name | No | |
| headline | No | |
| skills | No | |
| years_experience | No | |
| locations_preferred | No | |
| remote_ok | No | |
| resume_text | No | |
| links | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only indicates mutation (store/replace) without detailing side effects, size limits, or overwrite 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 a single sentence with no wasted words, but it is too brief to provide necessary context for an AI agent.
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 an output schema and one required parameter, the description lacks details on return values or error conditions, leaving the agent underinformed for a simple but critical operation.
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 description does not add meaning to the single parameter 'resume_text'. No format, length, or semantics beyond what the parameter name suggests.
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 action (store/replace) and the resource (resume text). It is specific and distinct from sibling tools like get_profile or update_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?
No guidance on when to use this tool vs alternatives like update_profile. No mention of prerequisites or conditions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an application to a new status (validates allowed transitions).
| Name | Required | Description | Default |
|---|---|---|---|
| application_id | Yes | ||
| status | Yes | ||
| notes | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| job_id | Yes | |
| status | No | |
| applied_at | No | |
| next_action_at | No | |
| next_action_note | No | |
| notes | No | |
| created_at | No | |
| updated_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions validation of transitions, which is helpful, but fails to disclose side effects (e.g., are old statuses preserved?), authentication needs, or any rate limits. For a mutation tool, more detail is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence that captures the core purpose. No wasted words, but could be slightly more detailed without becoming verbose. Front-loaded with the action.
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 existence of an output schema, the description does not need to explain return values. However, for a mutation tool with no annotations, more context is needed: what happens on success, validation error handling, and relationship to sibling tools like list_applications. The description is adequate but not 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 description coverage is 0%, and the description adds no explanation for parameters. The agent cannot infer what application_id refers to, the meaning of each enum status, or how notes are used. The description does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves an application to a new status, which is a specific verb+resource. It also mentions validation of allowed transitions, adding clarity. It distinguishes from siblings like log_application (create) and set_next_action (next action).
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 for changing status but does not provide explicit context on when to use versus alternatives, nor does it mention prerequisites or error conditions. No guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update profile fields. Only the fields you pass are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes |
| Name | Required | Description |
|---|---|---|
| full_name | No | |
| headline | No | |
| skills | No | |
| years_experience | No | |
| locations_preferred | No | |
| remote_ok | No | |
| resume_text | No | |
| links | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full responsibility. It discloses partial update behavior but omits critical details: required permissions, side effects, null vs. missing field semantics, rate limits, or error conditions.
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?
Single sentence, no redundancy. Could expand slightly with usage context without losing conciseness.
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?
Output schema exists (not shown) but description doesn't reference it or explain what the tool returns. No mention of identity assumptions (which profile is updated) or validation behavior. Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for individual properties, but the description states partial update behavior, and the $defs description adds 'all fields optional'. This adds some value but does not explain per-field meaning or constraints beyond 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 updates profile fields with partial update semantics ('Only the fields you pass are changed'). It implicitly distinguishes from read-only siblings like get_profile, but does not explicitly differentiate from other mutation tools like set_resume.
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 on when to use this tool versus alternatives (e.g., set_resume for resume_text, or get_profile before updating). No mention of prerequisites or when not to use.
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.
v0.1.0geocode_locationget_profilelist_applicationslist_saved_jobslog_applicationsave_jobsearch_jobssearch_jobs_in_regionset_next_actionset_resumeupdate_application_statusupdate_profileScored across 12 tools
Each tool has a clearly distinct purpose: geocoding, profile management, job searching with two variants, saving jobs, logging applications, tracking status, setting follow-up actions, and updating resume. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_applications, save_job, update_application_status). The only minor variant, search_jobs_in_region, still adheres to the pattern with a qualifier.
12 tools cover the core workflows of a job hunt assistant: searching, saving, applying, tracking, profile/resume management, and geolocation. The count is well-scoped without redundancy.
The tool surface covers search, save, apply, status updates, follow-up actions, and profile management. Minor gaps exist (no delete operations for saved jobs or applications), but these are non-critical for the domain.
Public MCP server for discovering open jobs. Search, filter, and get application links.
GetJobzi MCP server for job search, application tracking, and career forecasting.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
Read-only MCP server for public WeJob jobs, formations, and companies.
