Skip to main content
Glama

Search tracked jobs

search_vacancies
Read-only

Search the user's tracked vacancies: finished fit analyses and vacancies tracked without an analysis (analysis_status 'none'); ones with an analysis running or failed are not listed. Filter by free-text query (title, company, location, notes, description), minimum match percentage (drops unanalyzed ones), location (best-effort substring, falling back to the job description), tracker status and analysis_status. Newest first; total says how many match in all. Default limit 10, max 50. Empty list is a normal result.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_vacancies"
  }
}

Input Schema

NameRequiredDescriptionDefault
inputNo

Output Schema

NameRequiredDescriptionDefault
totalNoHow many vacancies match in all; vacancies holds at most limit of them.
vacanciesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / $defs / VacancyItem / properties / verdict_category / description
      Previous value: -"One of 'apply' | 'consider' | 'skip' | 'not_eligible' | 'invalid', or null if not categorized. 'not_eligible' means a hard eligibility blocker applies — the user cannot take this role as posted no matter how high match_percentage is; eligibility_blockers carries the reason."New value: +"One of 'apply' | 'consider' | 'skip' | 'not_eligible' | 'confirm_status' | 'invalid', or null if not categorized. 'not_eligible' means a hard eligibility blocker applies — the user cannot take this role as posted no matter how high match_percentage is; eligibility_blockers carries the reason. 'confirm_status' means the posting requires a status the user has not stated, so the verdict is open until they answer the blocker's question."
  2. Changed2 schema fields changed
    • changedOutput schema / $defs / VacancyItem / properties / analyzed_at / description
      Previous value: -"ISO 8601 timestamp."New value: +"ISO 8601 timestamp of when the vacancy was analyzed or, if never analyzed, added."
    • addedOutput schema / $defs / VacancyItem / properties / is_pinned
      Added value: +{
      +  "default": false,
      +  "description": "The user pinned it to the top of their tracker; lists put pinned vacancies first.",
      +  "title": "Is Pinned",
      +  "type": "boolean"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare it a safe read (readOnlyHint true, destructiveHint false, openWorldHint false), and the description adds real behavioral facts on top: records with running/failed analyses are silently omitted, min_match drops unanalyzed vacancies, location matching is best-effort substring with a fallback to the job description, and results are newest-first with a total count. The 'empty list is a normal result' note preempts a common misread of the response.

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?

Front-loaded with the searchable population and roughly one clause per concern, with no filler. The single dense paragraph with semicolons packs a lot in, but a short bulleted layout would have made the filter list easier to scan.

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 read-only filtered-search tool with annotations and an output schema, this covers everything an agent needs to decide to call it and interpret results: scope, filter interactions, ordering, limits, and the empty-result case. Return value details are correctly left 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?

The schema descriptions cover the individual fields, but the description adds cross-parameter semantics the schema does not: that min_match implicitly filters out unanalyzed vacancies, and that location is a best-effort substring that can fall back to the job description. Limit behavior (default 10, max 50) is restated but already in the schema, so it adds little.

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 ('Search the user's tracked vacancies') and immediately delimits the population: finished analyses plus never-analyzed vacancies, excluding those whose analysis is running or failed. That scope statement separates it cleanly from siblings like get_recent_vacancies and get_vacancy_detail.

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

Usage Guidelines4/5

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

It gives clear operating context: what is searchable, which filters exist, what min_match excludes, ordering ('newest first'), default and max limits, and that an empty list is a normal result. It stops short of explicitly naming an alternative sibling for the 'I want recent items rather than a search' case, but the inclusion/exclusion rules make the intended use unambiguous.

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.