Skip to main content
Glama

Analyze a job posting

analyze_vacancy

Analyze the text of a job posting that is not in ResumeQuick yet against a resume. Creates a NEW vacancy in the tracker; a vacancy already in the tracker is analyzed in place by analyze_tracked_vacancy, a radar match by analyze_radar_match. The same posting text analyzed before returns that analysis with status 'completed' and spends nothing, unless the resume or what the user told about themselves changed since; force=true re-runs it. Runs asynchronously — this returns an analysis_id immediately; get_vacancy_detail(analysis_id) shows the match, verdict and gaps once done, usually within 10 seconds. company, location and url are stored on the vacancy, shown on the tracker card, and make the analysis findable by search_vacancies(location=...). Counts as one vacancy analysis against the user's plan; text that turns out not to be a job posting ends with verdict 'invalid' and spends nothing. Returns 'not_found' if resume_id is given but does not belong to the current user, 'no_resume' when the account has no resume yet (nothing is spent), and 'limit_exceeded' naming the day it frees up if the plan quota is reached.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "input": "<input>"
    },
    "name": "analyze_vacancy"
  }
}

Input Schema

NameRequiredDescriptionDefault
inputYes

Output Schema

NameRequiredDescriptionDefault
reusedNoTrue: the same text was analyzed before against the same resume and nothing was spent; company, location and url passed with the call are written onto that analysis.
statusNo'processing' — the analysis runs asynchronously; 'completed' — this posting text was analyzed before and that analysis is returned as is.processing
task_idYesBackground task id (informational; get_vacancy_detail shows progress).
analysis_idYesId of the created analysis; pass to get_vacancy_detail once ready.
vacancy_titleNoTitle stored on the vacancy. A new analysis keeps a passed title; without one it is the posting's first line until the analysis names the role. A returned earlier analysis keeps its own title.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare a non-read-only, non-destructive, non-idempotent, closed-world mutation, and the description adds substantial context beyond that: asynchronous execution with an immediate analysis_id, ~10s completion, get_vacancy_detail polling, quota consumption, and the invalid/non-posting path that spends nothing. The only tension is that the dedupe/return-existing behavior reads as near-idempotent while idempotentHint=false, though force=true and resume changes keep that from being a real contradiction. Since the annotations already carry the safety profile and the extra value is scoping and cost detail rather than omission, this lands mid-scale rather than top.

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

Conciseness4/5

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

Dense but front-loaded: identity and routing come first, then caching, then async contract, then errors. Every sentence carries operational weight, though the single unbroken paragraph makes the error codes and cost rules slower to scan than they should be.

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?

For a parametrized mutation with nested input and an output schema, the definition covers everything an agent needs before calling: cost, async lifecycle, where results surface, and the four named failure outcomes. It deliberately leaves return-shape explanation to the output schema.

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 reported as 0%, so the description must carry parameter meaning, and it does for the consequential ones: company/location/url are persisted on the vacancy and drive later search_vacancies(location=...) lookups, force re-runs, and resume_id can yield not_found or no_resume. The description and title fields are only implied by the surrounding prose, leaving a small gap.

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?

States a specific verb and resource (analyze the text of a job posting against a resume) and immediately distinguishes the tool from analyze_tracked_vacancy and analyze_radar_match by input state. An agent can tell exactly which of the three analysis tools applies without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules (not-yet-tracked text goes here, tracked vacancies and radar matches go elsewhere), states the caching rule that repeated identical text returns the prior result, and names the escape hatch force=true plus the conditions that invalidate the cache. Only mild inference remains about what counts as 'changed' resume/profile data.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.