AI Applyd

Get Job Matches

aiapplyd_get_matches

Read-onlyIdempotent

Retrieve your top job matches sorted by score, with posting excerpts, apply URLs, and optional filters for query, location, or remote. Read full postings by passing job_match_ids.

Instructions

List the user's matched jobs: the roles AI Applyd found for them against their saved job preferences, best matches first, each with a job_match_id, title, company, location, match score, a 500-character excerpt of the posting and the apply URL. Pass job_match_ids (up to 10) to read the full posting, skills and benefits of specific matches; job_url to read any posting without saving it; query, location or remote_only to narrow the list; after_job_match_id with the newestJobMatchId you stored to see only matches newer than your last check. Read-only: it spends no credits and changes nothing. Do not use it to change what the user is matched against; use aiapplyd_update_job_preferences for that. Next: pass a job_match_id to aiapplyd_apply, or save or skip a match with aiapplyd_triage_matches.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number, starting at 1 (e.g. 2 for the next page)
`limit`	No	Matches per page, 1 to 50 (default 10)
`query`	No	Narrow the list to titles containing this text (e.g. "Product Designer").
`job_url`	No	Read any job posting by URL without saving it (e.g. "https://jobs.lever.co/acme/123").
`location`	No	Preferred location (e.g. "San Francisco, CA", "New York", "Remote")
`saved_only`	No	If true, only return the matches the user saved
`remote_only`	No	If true, only show remote-friendly positions
`job_match_ids`	No	Read these matches in full: up to 10 job_match_ids (e.g. [48213]). Returns the full posting, skills, benefits and work arrangement.
`after_job_match_id`	No	Return only matches newer than this job_match_id. Store newestJobMatchId from each answer and pass it back.

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	Yes
`page`	Yes
`matches`	Yes
`posting`	Yes	A posting read from job_url. Nothing was saved.
`totalPages`	Yes
`notFoundIds`	Yes	Requested job_match_ids that do not exist on this account.
`totalMatches`	Yes
`newestJobMatchId`	Yes	The highest job_match_id on this page. Store it and pass it back as after_job_match_id to see only newer matches.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.8.0Sep 25, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Even with annotations declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable behavior details: 'Read-only: it spends no credits and changes nothing'. It also clarifies semantics like reading a posting via job_url 'without saving it' and using after_job_match_id with stored newestJobMatchId for incremental checks.

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?

The description is dense but well-structured: core purpose first, then filtering/reading modes, then read-only guarantee, then guardrail and next-step suggestions. Every sentence contributes behavioral or routing information, and the key constraints are front-loaded.

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?

Given the 9 optional parameters, rich input schema descriptions, output schema, and annotations, the description covers all essential usage modes, read-only behavior, credit implications, and next-step routing. Nothing an agent needs to select and invoke 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?

The input schema already fully describes all 9 parameters, so the baseline is 3. The description adds useful context beyond the schema, such as job_match_ids being limited to 10 and returning 'the full posting, skills and benefits', and explaining the after_job_match_id pattern with newestJobMatchId. This justifies above baseline, though much of the added value repeats or summarizes schema descriptions.

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 a specific verb and resource: 'List the user's matched jobs'. It further specifies that these are roles found against saved preferences, sorted best-first, and mentions key fields returned. This clearly distinguishes it from sibling tools like aiapplyd_search_jobs or aiapplyd_get_applications.

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 explicitly states 'Do not use it to change what the user is matched against; use aiapplyd_update_job_preferences for that', giving a direct exclusion and alternative. It also routes the next step: pass a job_match_id to aiapplyd_apply or save/skip with aiapplyd_triage_matches. No ambiguity remains about when 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.

Deploy Server