The resume-mcp-server provides structured access to a collection of job application documents (resumes, cover letters, application materials) with tools for browsing, searching, and extracting detailed information.
Document Browsing
List all documents, optionally filtered by type (resume, cover_letter, application_material, other)
List lightweight resume summaries (ID, name, email, phone) for token-efficient orientation
Retrieve the full extracted text of any document by path
Get a resume's structured profile (contact info, professional statement, education) without nested data
Searching
Full-text search across all documents by keyword or phrase, with optional type filtering
Search resumes by person name (partial match supported)
Search resumes by badge skill (e.g., find everyone who lists "Python")
Search badge skills/technologies by title keyword
Work Experience & Achievements
List and retrieve individual work experience entries, optionally filtered by resume or current roles
Search work experiences by company name, position title, or achievement content
List, retrieve, and directly search achievement bullets for token-efficient matching
Skills & Projects
List and retrieve badge skills (technologies, tools, languages), optionally scoped to one resume
Search side projects by name, description, or associated technologies
Education
Search education entries by institution, degree, or competencies
The server supports common document formats (.docx, .pdf, .md, .txt), auto-parses files on startup with hot-reload on changes, and integrates with AI clients like Claude Desktop, Claude Code, and VS Code via HTTP or stdio transport.
An MCP server that gives Claude (or any MCP client) structured, searchable access to your resume collection — resumes, cover letters, and application materials in .docx, .pdf, .md, or .txt format.
Job seekers accumulate document sprawl fast: multiple resume versions tailored to different roles, cover letter drafts, reference sheets. Manually digging through them to draft a new application is tedious. Point this server at your resume folder and Claude can answer questions like "which of my resumes highlights Kubernetes experience?", "what achievements have I listed across my backend roles?", or "draft a cover letter drawing from my work at Acme Corp" — without you pasting anything.
The server parses each document into structured data (contact info, work history, education, skills, side projects) and exposes 20 tools covering full-text search, skill lookup, company and role queries, achievement mining, education search, ATS-style job-match ranking, collection analytics, and more. Files are watched and re-indexed automatically, so edits to your documents are reflected immediately.
Multi-format parsing — .docx, .pdf, .md, and .txt documents are parsed into structured data: contact info, work history, education, skills, and side projects.
Automatic de-duplication — resumes for the same person across multiple files (e.g. a .docx and a .pdf of the same resume) are matched by email or name and collapsed to the richest copy, so search and analytics aren't skewed by duplicates.
Automatic hot-reload — a filesystem watcher re-indexes your documents as soon as they change, no server restart needed.
Document type inference — files are automatically classified as resume, cover_letter, application_material, or other based on filename patterns, which can be overridden per category via environment variables.
Full-text and structured search — search whole documents with search_resumes, or filter any entity type (skills, work experience, achievements, side projects, education) with a scoped query, technology, or competency parameter.
Three search modes — and, or, and regex matching, available consistently on every tool that accepts a query-like parameter.
Uniform pagination — every list-style tool returns the same total_count / items / has_more / next_offset / message envelope, with validated limit/offset and a 200-item cap.
Unified error shape — every failure returns {"error": "..."}, so callers only need to check for one shape regardless of which tool they called.
Collection analytics — get_collection_stats and get_skill_frequency surface aggregate counts and cross-resume skill popularity.
ATS-style job-match ranking — list_ranked_resumes scores every resume against a pasted job description (fuzzy skill matching plus keyword coverage) and ranks them best-match-first; match strictness and score weighting are tunable per call.
Read-only and safe by construction — every tool is annotated readOnlyHint / idempotentHint / openWorldHint: false; nothing mutates your files or reaches outside the local document collection.
Flexible deployment — run over stdio or HTTP, standalone or via Docker/Docker Compose with CORS support, configured through environment variables or a .env file.
See MCP Tools below for the full list of tools this exposes. For best extraction quality, see the Resume Formatting Guide.
Related MCP server: Resume Forge MCP
Give Claude structured access to your resume collection. The server parses your documents on startup and exposes 20 tools for searching by name, company, skill, education, side project, or full text, ranking resumes against a job description, plus analytics tools for skill frequency and collection statistics — with automatic hot-reload when files change.
Try it immediately with the included sample resumes:
pip install resume-mcp-server
RESUME_DIR=./sample_resumes resume-mcp-serverThen connect Claude Code:
claude mcp add resume-mcp-server resume-mcp-server -e RESUME_DIR=$(pwd)/sample_resumesFor a persistent setup with Docker or your own documents, see Docker Deploy or Dev Environment.
The recommended way to run the server. Docker Compose exposes the server over HTTP so any AI client can connect to it.
Copy the example env file and set your documents path:
cp .env.example .env
# then edit RESUME_DIR_HOST in .envStamp the image with the current pyproject.toml version:
python scripts/sync_version.pydocker compose build resume-mcp
docker compose up -dThe server is now available at http://localhost:8001/mcp.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"resume-mcp-server": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"resume-mcp-server": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}Claude Code:
claude mcp add resume-mcp-server --transport http http://localhost:8001/mcpTo add it globally across all projects, add the following to ~/.claude.json instead:
{
"mcpServers": {
"resume-mcp-server": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}docker compose downRun the image directly — no Compose needed — for MCP clients that use stdio transport (including Glama.ai and Claude Desktop):
docker run -i --rm -v /path/to/your/resumes:/resumes resume-mcp-serverClaude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"resume-mcp-server": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "/path/to/your/resumes:/resumes", "resume-mcp-server"]
}
}
}For local development or running the server without Docker.
Python 3.12+
pip install .
# include test dependencies:
pip install ".[dev]"resume-mcp-server
# with a custom directory:
RESUME_DIR=/path/to/docs resume-mcp-serverOr create a .env file in the directory you run the server from:
# .env
RESUME_DIR=/path/to/docs
FASTMCP_PORT=8001Then just run resume-mcp-server — the .env is loaded automatically. Variables already set in your shell or by the MCP client always take precedence over .env values.
Claude Desktop:
{
"mcpServers": {
"resume-mcp-server": {
"command": "resume-mcp-server",
"env": {
"RESUME_DIR": "/path/to/your/resumes"
}
}
}
}If resume-mcp-server is not on your PATH, use the full path (e.g. ~/.venv/bin/resume-mcp-server).
Claude Code:
claude mcp add resume-mcp-server resume-mcp-server -e RESUME_DIR=/path/to/your/resumesuvx:
{
"mcpServers": {
"resume-mcp-server": {
"command": "uvx",
"args": ["resume-mcp-server"],
"env": {
"RESUME_DIR": "/path/to/your/resumes"
}
}
}
}Docker Compose (.env):
Variable | Description |
| Path on your machine to the documents directory — mounted to |
| Port the HTTP server listens on (default |
| Logging verbosity: |
Local run (environment variables or .env):
Variable | Default | Description |
|
| Directory scanned for documents |
|
| Transport protocol ( |
|
| Bind address |
|
| Port the HTTP server listens on |
|
| Regex used to classify a filename as |
|
| Regex used to classify a filename as |
|
| Regex used to classify a filename as |
A .env file in the working directory is loaded automatically on startup if present. Shell environment variables and values set by the MCP client always take precedence over .env values.
Each DOC_TYPE_PATTERN_* variable replaces the default regex for that category (filenames are matched in order: resume, then cover letter, then application material, then everything else falls back to other). Leave a variable unset to keep its default; an invalid regex is ignored and the default is used instead.
The server scans RESUME_DIR recursively on startup and reloads automatically when files change.
Types are inferred from filenames:
Type | Filename patterns |
| contains |
|
|
|
|
| everything else |
Each of the three regexes can be overridden with DOC_TYPE_PATTERN_RESUME, DOC_TYPE_PATTERN_COVER_LETTER, and DOC_TYPE_PATTERN_APPLICATION_MATERIAL — see Configuration.
Most tools that accept a query (or technology/competency) parameter split it on whitespace and support three match modes via the optional mode parameter:
| Behavior |
| All tokens must appear within the same field. |
| Any token is sufficient. |
| The query is compiled as-is (not tokenized or escaped) into a case-insensitive regular expression and matched against the field. Use this for grep-style power — alternation, wildcards, anchors, etc., e.g. |
Multi-field note: For tools that search several fields (company name, position title, achievement text, etc.), AND mode requires all tokens to co-occur in the same field, not spread across fields. Use OR mode when you want a looser cross-field match. Regex mode also matches per-field.
Single-word queries behave identically in and/or mode.
Every tool that accepts a query-like parameter — including search_resumes, the whole-document keyword search — shares this same "and"/"or"/"regex" vocabulary.
search_resumes_by_skill accepts either a single skill string or a list of skills. For a list, mode does double duty: it also controls whether a resume must match EACH skill in the list ("and") or ANY skill ("or"); "regex" mode combines multiple skills with OR semantics.
An empty query or an empty skill list returns {"error": "..."} rather than an empty result — this distinguishes a caller mistake from a legitimate zero-match search.
All list_* tools (and search_resumes/search_resumes_by_skill) accept limit and offset parameters and return a consistent envelope:
{
"total_count": 247,
"items": [...],
"has_more": true,
"next_offset": 100,
"message": "100 of 247 results shown. Call again with offset=100 to see more."
}total_count is the full match count before slicing. has_more and next_offset tell you directly whether to page further — no need to compute offset + len(items) < total_count yourself — and message restates that in plain language, ready to act on. When there's nothing left, has_more is false, next_offset is null, and message reads "All N results shown.".
limit must be greater than 0 and offset must be 0 or greater — otherwise the tool returns {"error": "..."}. An offset beyond the total result count is not an error; it's a valid "past the end" page (items: [], has_more: false).
Cap and defaults. limit is silently capped at 200 regardless of what's requested — if you ask for more, the response still comes back (not an error), but message is prefixed with "Requested limit N capped to 200." so you know it happened. Default limit varies by tool, generally lower for heavier, deeply-nested responses:
Tool | Default |
| 10 (each item is a fully nested resume) |
| 25 |
| 50 |
| 100 |
| 20 (not part of the pagination envelope, but shares the same 200 cap) |
Every tool returns a dict. On failure, the dict is exactly {"error": "<message>"} — this is the only failure shape in the API, so a caller can check for the "error" key regardless of which tool it called. This covers: not-found IDs, a resume_id filter that doesn't match any resume, invalid regex patterns, and invalid limit/offset values. A resume_id filter that does match a resume but simply has zero matching child records (e.g. list_work_experiences(resume_id=<valid>) for someone with no work history) is not an error — it returns an empty items list.
get_resume's success shape is {"text": "..."} so that success and failure are both dicts, distinguishable by key.
20 tools are exposed, covering full-text search, skill lookup, company and role queries, achievement mining, education search, ATS-style job-match ranking, collection analytics, and more. Every tool is read-only (readOnlyHint: true) — none mutate state or reach outside the local document collection (openWorldHint: false).
Tool | Description |
| Lightweight identity records (id, name, email, phone) for orienting before fetching details; optional |
| A resume's top-level fields (contact info, statement, education) without nested lists |
| A resume's complete nested structure (work experiences, skills, side projects, education) in one call |
| List all documents, optionally filtered by type |
| Full extracted text of a document, keyed by path (not resume_id) |
| Full-text search across all documents, sorted by match count |
| List badge skills, optionally scoped to a resume and/or filtered by title |
| A single badge skill by ID |
| Find which resumes list one or more given badge skills (accepts a string or a list) |
| Badge skills ranked by how many resumes list them |
| Rank every resume against a pasted job description (fuzzy skill match + keyword coverage) |
| List work experiences, optionally scoped to a resume, current-only, and/or a keyword query |
| A single work experience entry with its achievement bullets |
| List achievement bullets, optionally scoped to a resume and/or a keyword query |
| A single achievement bullet by ID |
| List side projects, optionally scoped to a resume and/or matched by keyword or technology |
| A single side project by ID, including demonstrated technologies |
| List education entries, optionally scoped to a resume and/or matched by keyword or competency |
| A single education entry by ID, including its competencies |
| Aggregate counts and averages across the entire loaded collection |
See docs/TOOLS.md for full parameter tables and return shapes for every tool.
Get a single achievement (phrase skill) by ID. Returns {"error": ...} if id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Achievement ID from list_achievements |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds value by specifying error return behavior on invalid ID, which annotations do not cover. No contradictions.
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 sentences with no extraneous words. First sentence clearly states purpose, second adds error behavior. Efficient and front-loaded.
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 simple tool with one required parameter and existing output schema, the description fully covers essential behaviors (what it does, error case). No gaps.
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 covers 100% of parameters, so baseline is 3. Description only repeats 'by ID' and does not add additional semantics beyond the schema's existing description of the id parameter.
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?
Explicitly states the verb 'Get', the resource 'achievement (phrase skill)', and the key parameter 'by ID'. Clearly distinguishes from sibling 'list_achievements' which returns multiple.
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?
Implies usage when a single achievement is needed by ID. Indicates error handling if ID not found. However, lacks explicit exclusions or alternative suggestions beyond the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single badge skill by ID. Returns {"error": ...} if id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Badge skill ID from list_skills |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: returns an error object if the ID is not found, which is not covered by annotations. This is useful beyond the structured fields.
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 sentences with no redundant information. Every part is essential: the action, the resource, the error behavior. Front-loaded with the main 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?
Given the tool's simplicity (single parameter, simple retrieval), the description is complete. It explains the return value behavior (error on not found) and the parameter source. Output schema exists, so return format is covered.
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 100%. The parameter 'id' is described as 'Badge skill ID from list_skills', adding meaning about the source and type of the ID beyond the schema's type definition.
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 'Get a single badge skill by ID', specifying the verb (Get), resource (badge skill), and scope (single by ID). It distinguishes from sibling tools like list_skills which retrieves multiple, and other get_* tools for different resources.
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 retrieving a specific badge skill by ID, but does not explicitly state when to use this tool vs alternatives (e.g., list_skills for browsing all). No 'when not to use' or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return aggregate counts and averages across the entire loaded resume collection.
Returns total_resumes, total_work_experiences, total_unique_skills, total_side_projects, total_education_entries, total_achievements, avg_skills_per_resume, avg_work_experiences_per_resume. Example: get_collection_stats()
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by enumerating the exact fields returned, which clarifies the scope of data. No behavioral traits are hidden or contradicted.
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 extremely concise, with a clear front-loaded purpose sentence, a bullet-style list of outputs, and a single example. Every sentence is necessary and free of fluff.
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 parameters, an output schema exists (implied by the field list), and annotations cover safety and idempotency, the description is fully adequate. It explains what is returned and how to call it.
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 tool has no parameters, so the description need not add parameter details. Baseline is 4, and the description appropriately skips parameter information.
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 returns aggregate counts and averages across the entire resume collection, listing specific fields (e.g., total_resumes, avg_skills_per_resume). This distinguishes it from sibling tools that operate on individual items (e.g., get_resume, list_resumes).
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 obtaining aggregate statistics but does not explicitly state when to use or not use this tool versus alternatives. It provides an example call but lacks guidance on context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single education entry by ID, including its competencies. Returns {"error": ...} if id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Education entry ID from list_education |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns an error if the id is not found and includes competencies, providing useful behavioral context beyond annotations.
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 short sentences, front-loaded with the core purpose, then adding error handling. Every word adds value with no unnecessary details.
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 required parameter, annotations, output schema exists), the description covers the essential behavior: what it does, what it returns, and error case. No gaps for its intended use.
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 100% and the schema description for 'id' says 'Education entry ID from list_education', which tells the user where to obtain the ID. The description does not repeat this but the parameter's purpose is clear.
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 starts with 'Get a single education entry by ID, including its competencies', clearly stating the verb and resource. It distinguishes from sibling tools like list_education (which lists all entries) by focusing on a single entry by ID.
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 when you have an ID but does not explicitly state when to use this tool versus alternatives (e.g., list_education to get IDs first). No indication of when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full extracted text of a document, as {"text": "..."}. Note: takes a file path (see list_resumes), not a resume_id — use get_resume_profile or list_resumes to fetch structured data by resume_id instead. Returns {"error": ...} if path is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path as returned by list_resumes, e.g. 'MyResume_v2.docx' or 'Acme/MyResume.docx' |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm read-only and idempotent behavior; description adds return format and error handling details, going beyond structured data.
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 front-loading the purpose, with no extraneous information.
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 one parameter, clear annotations, and a straightforward return format, the description provides all necessary context including error case.
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 covers the path parameter completely with examples; description reinforces but adds no new semantic information 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 returns full extracted text as a JSON object, and distinguishes it from siblings by specifying it takes a file path not a resume_id.
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?
Explicitly tells when to use (with a file path from list_resumes) and when not to (use get_resume_profile or list_resumes for structured data by ID), plus notes error handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a resume's complete nested structure in one call: profile fields plus all work experiences (with achievements), badge skills, side projects (with technologies), and education entries (with competencies). Prefer get_resume_profile plus the scoped list_* tools (list_work_experiences, list_skills, list_side_projects, list_education) when you only need part of this — it's more token-efficient. Use get_resume_full when you need the whole picture at once. Returns {"error": ...} if resume_id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| resume_id | Yes | Resume ID from list_resume_summaries |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), description adds that it returns the full nested structure and mentions error handling for missing resume_id, providing useful 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?
Four sentences, no wasted words. Purpose is front-loaded, followed by usage guidance and error behavior. Efficient and well-structured.
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?
Description fully explains what data is returned, and context signals indicate output schema exists. Complete for a read-only retrieval tool with one parameter.
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?
Single parameter resume_id is described well in schema as 'Resume ID from list_resume_summaries'. Description reinforces this and adds context about its source, adding value 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?
Description clearly states it retrieves the complete nested structure of a resume, listing all included components. This distinguishes it from siblings like get_resume_profile and list_* tools.
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?
Explicitly advises to prefer get_resume_profile plus scoped list_* tools for partial data for token efficiency, and to use get_resume_full when the whole picture is needed. Provides clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a resume's top-level fields (contact info, professional statement, education) without the nested work experience and badge skill lists. See also: get_resume_full for everything about this resume in one call. Returns {"error": ...} if resume_id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| resume_id | Yes | Resume ID from list_resume_summaries |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint as true. The description adds value by detailing what is omitted (nested fields) and error responses, without contradicting annotations.
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 sentences plus a see-also and error note; every sentence provides value. Front-loaded with the core 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?
Given the presence of an output schema and simple single-parameter input, the description fully covers purpose, scope, alternatives, and errors, leaving no gaps.
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 100% with an inline description for resume_id. The description adds context by noting the source ('from list_resume_summaries'), which aids parameter understanding 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 specifies the verb 'Get' and the resource 'resume's top-level fields', listing included fields (contact info, professional statement, education) and excluded ones (nested work experience, badge skill lists), clearly distinguishing it from get_resume_full.
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?
Explicitly suggests when to use (for top-level fields) and directs to get_resume_full for complete resume data. Also documents error behavior when resume_id is not found.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single side project by ID, including the technologies it demonstrates. Returns {"error": ...} if id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Side project ID from list_side_projects |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent. The description adds that it returns technologies and an error object if not found, which is useful beyond annotations.
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, front-loaded with purpose. No wasted 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?
Given the presence of an output schema, the description adequately covers return value shape (includes technologies, error on not found). Complete for a simple get-by-ID 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 covers 100% of parameters. The description adds context 'Side project ID from list_side_projects', which provides semantic guidance beyond the schema's type and required flag.
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 specifies 'Get a single side project by ID' with a verb and resource, and distinguishes from list_side_projects (list vs single). It also notes the inclusion of technologies and error handling.
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 when you have an ID (from list_side_projects), but does not explicitly state when not to use or compare to siblings. The error return note provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return badge skills ranked by how many resumes list them, in descending order.
Useful for identifying the most common technologies across all candidates.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of skills to return (default 20) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent behavior. The description adds the descending order ranking detail, which is non-obvious. No contradictions.
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 short sentences with no fluff. The first sentence directly states the action and result format. Every word is 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?
For a simple, one-parameter, read-only tool with an output schema, the description covers purpose, usage context, and parameter. No missing information needed for an agent to invoke it correctly.
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 only parameter 'limit' is fully documented in the input schema with description and default. The tool description adds no further semantic value beyond the schema, so baseline 3 is appropriate.
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 returns badge skills ranked by frequency in descending order, differentiating it from sibling tools like list_skills and search_resumes_by_skill.
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 context that it is useful for identifying common technologies across all candidates, but does not explicitly state when not to use or list alternatives. Still clear enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single work experience entry with its achievements. Returns {"error": ...} if id is not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Work experience ID from list_work_experiences |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe behavior. The description adds that it returns an error object if the id is not found, which is useful but does not elaborate on other behavioral traits (e.g., whether achievements are nested or how many).
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 extremely concise at two sentences, with the primary action front-loaded. Every word adds value, and there is no redundancy or waste.
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 simple nature of this read tool (single parameter, output schema present), the description covers the core purpose and error behavior. It mentions that achievements are included, aligning with the tool's scope. The presence of an output schema compensates for missing return value details.
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 provides full coverage (100%) with a clear description for the 'id' parameter. The tool description does not add any additional meaning beyond what the schema already provides.
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 'Get' and the resource 'a single work experience entry with its achievements'. It distinguishes itself from sibling tools like list_work_experiences (which lists) and get_achievement (which gets a single achievement).
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 by stating the tool gets a single entry, and the parameter description indicates the id comes from list_work_experiences. However, it does not explicitly state when to use this tool versus siblings, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List achievements (resume bullet points), optionally filtered to a specific resume and/or a keyword query matched against the achievement text (absorbs the old search_achievements tool).
Response shape depends on the arguments given, to keep the common case cheap:
resume_id given, query omitted: bare {id, desc} per item (cheapest — you already know which resume these belong to).
query given, and/or resume_id omitted: each item also includes company_name, position_title, work_experience_id, and resume_id, since that context would otherwise be unrecoverable from the achievement alone. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode for query — 'and' (default) requires all words to appear in the description; 'or' requires any word to match; 'regex' treats query as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 50) | |
| query | No | Optional text to search for in achievement descriptions (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| resume_id | No | Optional resume ID from list_resume_summaries to filter results |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, so the description adds value by explaining conditional response shape, pagination, and error handling. No contradictions.
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?
Description is detailed but well-structured, with each paragraph adding value. Could be slightly more concise, but front-loads purpose and explains complex behavior efficiently.
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 complexity (5 params, conditional output), the description covers purpose, filtering, response shape, pagination, and error handling. Output schema exists, so return details are not needed. Sibling differentiation is partially addressed.
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 has 100% coverage and descriptions, but the description adds meaningful context about how parameters affect response shape (e.g., resume_id and query omitted vs. given). This goes beyond 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?
Clearly states the tool lists achievements (resume bullet points) with optional filtering by resume_id and keyword query. Mentions it absorbs the old search_achievements tool, distinguishing it from siblings.
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 on when to use filtering options and how response shape depends on arguments. Does not explicitly state when not to use or compare to alternatives like get_achievement, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List education entries (degree, institution, year, and relevant coursework/competencies), optionally filtered to a resume and/or matched by keyword or competency (absorbs the old search_education and search_education_by_competency tools).
If competency is given, entries are matched against competency names only, and each result uses a lighter shape: id, institution, degree, year, matched_competencies, resume_id.
Else if query is given, entries are matched against institution, degree, or competency names, and each result includes the full nested structure plus resume_id.
If both are given, competency takes precedence and query is ignored.
If neither is given, today's plain listing behavior applies. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode — 'and' (default) requires all words to match within the same field; 'or' requires any word to match; 'regex' treats query/competency as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 25) | |
| query | No | Optional text to match against institution, degree, or competency (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| resume_id | No | Optional resume ID from list_resume_summaries to filter results | |
| competency | No | Optional skill/competency name fragment to match (case-insensitive, partial match); takes precedence over query |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint and idempotentHint true, consistent with a safe read operation. The description adds behavioral details like different result shapes per mode, pagination, and error handling, going beyond annotations.
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 structured with bullet-like clauses and front-loaded with the main purpose. It is somewhat lengthy but each sentence adds value, avoiding 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's complexity (multiple modes, filtering, pagination, error cases), the description covers necessary details. Response structure and error handling are mentioned, making it complete for an agent.
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 100%, but the description adds functional context: precedence between competency and query, result shape differences, and pagination behavior. This adds significant value beyond the schema alone.
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 lists education entries with filtering options. It explicitly mentions absorbing two old search tools, distinguishing it from siblings that handle other resume sections.
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 competency vs query vs neither, including precedence rules. It lacks explicit when-not-to-use guidance but effectively conveys context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all documents. When doc_type is 'resume' (or omitted), structured resume data is returned if available; otherwise flat file metadata is returned. Response includes total_count and items for pagination. See also: list_resume_summaries for a lighter-weight, more token-efficient listing; get_resume_full for one resume's full nested structure by resume_id.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default 10 — each item is a fully nested resume) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| doc_type | No | Optional filter — one of: resume, cover_letter, application_material, other |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context about returning structured data vs flat metadata depending on doc_type and includes pagination details.
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?
Three sentences with no waste. Front-loaded with main purpose, efficient and well-structured.
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 and sibling tools, the description provides sufficient context including doc_type behavior, pagination, and references to alternatives.
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 100% with parameter descriptions. The description adds extra meaning for doc_type behavior (structured data when resume) and mentions pagination parameters implicitly.
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 lists documents and explains the behavior based on doc_type. It distinguishes from sibling tools like list_resume_summaries and get_resume_full.
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 provides explicit references to alternative tools (list_resume_summaries, get_resume_full) for different use cases, giving good guidance. Lacks a direct 'use this when' statement but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List resumes as lightweight identity records — id, name, email, phone only. Use this to orient and pick a resume_id before fetching details with other tools. Much more token-efficient than list_resumes when you only need to identify who is present. Pass query to filter by first or last name (absorbs the old search_resumes_by_name tool). Response includes total_count and items for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode — 'and' (default) requires all words to appear in the same name field; 'or' requires any word to match; 'regex' treats query as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 100) | |
| query | No | Optional name fragment to filter by first or last name (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: true, idempotentHint: true) already signal safe read operation. The description adds behavioral context: it returns only 'id, name, email, phone', includes pagination fields 'total_count and items', and that query filters by first or last name. No contradictions. The description enhances understanding beyond the annotations.
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?
Five concise sentences, each adding distinct value. Front-loaded with purpose and output format. No redundant information. Every sentence earns its place, making it highly efficient for agent consumption.
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 presence of an output schema (context signal: true), the description need not detail return structure, but it mentions total_count and items for pagination, which is helpful. Covers filtering, the absorbed sibling tool, and the lightweight nature. Fully sufficient for an agent to understand usage in context.
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 100%, so baseline is 3. The description adds minimal parameter context: 'Pass query to filter by first or last name' relates to the query parameter, but the schema already describes it well. Mode and pagination parameters are not elaborated in the description beyond what schema provides. No significant value added beyond 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?
Clearly states it lists resumes as lightweight identity records with specific fields (id, name, email, phone). Distinguishes from sibling 'search_resumes_by_skill' by contrasting name-based filtering vs skill search, and mentions absorbing the old search_resumes_by_name tool. The verb 'list' combined with the lightweight scope makes the purpose immediately clear.
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?
Explicitly advises using this tool to 'orient and pick a resume_id before fetching details with other tools' and highlights token-efficiency over a presumably heavier 'list_resumes' tool. Implicitly contrasts with sibling 'search_resumes_by_skill' by focusing on name filtering. Does not explicitly list when not to use, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List side projects (personal/portfolio projects, distinct from work experience), optionally filtered to a resume and/or matched by keyword or technology (absorbs the old search_side_projects and search_side_projects_by_technology tools).
If technology is given, projects are matched against technology names only, and each result uses a lighter shape: id, name, description, matched_technologies, resume_id.
Else if query is given, projects are matched against name, description, or technology names, and each result includes the full nested structure plus resume_id.
If both are given, technology takes precedence and query is ignored.
If neither is given, today's plain listing behavior applies. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode — 'and' (default) requires all words to match within the same field; 'or' requires any word to match; 'regex' treats query/technology as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 25) | |
| query | No | Optional text to match against name, description, or technology (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| resume_id | No | Optional resume ID from list_resume_summaries to filter results | |
| technology | No | Optional technology/skill name fragment to match (case-insensitive, partial match); takes precedence over query |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and idempotentHint. Description adds behavioral details: filtering interplay, result shape differences, error handling for missing resume_id, and pagination. No contradictions.
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?
Well-structured with bullet points and clear hierarchy. Lengthy but justified given the complex filtering behavior. Could be slightly more concise, but no fluff.
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 all filtering modes, pagination, error handling, and result shapes. With output schema present and no nested objects, the description is sufficiently complete for an AI agent to use correctly.
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 100%, so parameters are already documented. The description adds value by explaining how query and technology interact, precedence rules, and result shape changes, which goes beyond the schema's individual field 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 explicitly states the tool lists side projects (personal/portfolio projects) and distinguishes them from work experience. It also mentions absorbing old search tools, providing clear scope.
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 detailed filtering logic (technology vs query precedence, pagination) but does not explicitly compare to sibling tools like get_side_project or list_work_experiences; however, the context of listing vs retrieving is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List badge skills (technologies, tools, languages), optionally filtered to a resume and/or a keyword query matched against the skill title (absorbs the old search_skills tool). Note: badge skills are deduplicated and shared across resumes by title, so — unlike work experiences, side projects, and education — items here do not carry a resume_id. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode for query — 'and' (default) requires all words to match; 'or' requires any word to match; 'regex' treats query as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 100) | |
| query | No | Optional text to search for in skill titles (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| resume_id | No | Optional resume ID from list_resume_summaries to filter results |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds valuable context: skills are deduplicated and shared across resumes (no resume_id on items), pagination uses total_count and items, and an error is returned if resume_id is not found. No contradiction with annotations.
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 concise with four sentences, each adding unique value: purpose and filtering, deduplication note, pagination structure, and error behavior. It is front-loaded and efficient.
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 adequately covers pagination and error handling. It could benefit from mentioning default ordering, but overall it sufficiently guides the agent for a list/filter tool among many siblings.
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?
All parameters have schema descriptions (100% coverage), so the baseline is 3. The description does not add significant parameter details beyond what the schema provides, except implicitly linking query to title matching.
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 lists badge skills (technologies, tools, languages) and optionally filters by resume or keyword query. It also notes that it absorbs the old search_skills tool, effectively differentiating it as the combined list/search tool for skills.
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 provides clear context on when to use the tool (listing/filtering skills) and mentions limitations like deduplication and error handling. However, it does not explicitly state when to avoid it or suggest alternatives like get_badge_skill for a single skill.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List work experiences, optionally filtered to a specific resume, only current roles, and/or a keyword query matched against company name, position title, or achievement descriptions (absorbs the old search_work_experiences tool). Each result includes a resume_id field identifying which resume the experience belongs to. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode for query — 'and' (default) requires all words to match within the same field; 'or' requires any word to match; 'regex' treats query as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 25) | |
| query | No | Optional text to match against company name, position title, or achievement descriptions (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| resume_id | No | Optional resume ID from list_resume_summaries to filter results | |
| current_only | No | If True, return only roles where end_date is 'Present' |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and idempotentHint are true. The description adds context about pagination (total_count, items), error handling, and the 'absorbs the old search' behavior. No contradictions.
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 five sentences, front-loading the main purpose and filters. Each sentence adds meaning, though it could be slightly more terse. It effectively communicates key points without 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 6 optional params, an output schema, and strong annotations, the description covers purpose, all filter options, pagination, and error states. It is complete for a list endpoint, providing sufficient context for an agent to decide and invoke correctly.
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 100%, so param descriptions are already detailed. The description adds value by mentioning the resume_id field in results and pagination fields (total_count, items), which are not in param descriptions. This enhances understanding 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 it lists work experiences with optional filters (resume, current_only, query). It distinguishes from siblings like get_work_experience (single) and other search tools by focusing on work experiences. The absorption of the old search tool reinforces its scope.
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 optional filters and pagination, and notes error when resume_id is not found. It mentions absorbing the old search tool, implying it replaces that. However, it could more explicitly contrast with sibling tools like get_work_experience or list_resumes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across all documents for a keyword or phrase. Response includes total_count, items, has_more, next_offset, and message for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode — 'and' (default) requires all words to appear in the document; 'or' requires any word to match; 'regex' treats query as a case-insensitive regular expression | and |
| limit | No | Maximum number of results to return (default 100) | |
| query | Yes | Text to search for (case-insensitive) | |
| offset | No | Number of results to skip for pagination (default 0) | |
| doc_type | No | Optional filter — one of: resume, cover_letter, application_material, other |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds that response includes pagination details (total_count, items, has_more, next_offset, message), which is useful but does not disclose further behavioral traits like rate limits or caching. No contradiction with annotations.
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: first states purpose, second lists response fields. Front-loaded and no wasted words. Efficient structure.
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?
With output schema present (hidden), description covers pagination response well. For a general search tool, it is sufficiently complete. Could optionally mention which document types are searched (implied by 'all documents' but not explicit).
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 100%, so baseline is 3. Description does not add additional meaning beyond the schema; it remains generic. No parameter-specific elaboration.
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 'Search across all documents for a keyword or phrase.' 'All documents' distinguishes it from sibling 'search_resumes_by_skill' which focuses on skill-based search. Also mentions pagination fields in response, adding specificity.
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?
Description implies usage for keyword/phrase search across all documents, but does not explicitly state when to use versus alternatives like 'search_resumes_by_skill' or list tools. No exclusions or when-not guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find which resumes list one or more given badge skills. Returns resume identity and matched skill names only — more token-efficient than list_resumes when filtering by skill. Accepts either a single skill string or a list of skills to filter by multiple at once.
Each result includes: id, first_name, last_name, matched_skills. Response includes total_count, items, has_more, next_offset, and message for pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Token match mode. For a single skill: 'and' (default) requires all words to appear in the skill title, 'or' requires any word to match, 'regex' treats it as a case-insensitive regular expression. For multiple skills, mode also controls whether a resume must match EACH skill in the list ('and') or ANY skill in the list ('or'); 'regex' mode combines multiple skills with OR semantics. | and |
| limit | No | Maximum number of results to return (default 100) | |
| skill | Yes | Skill title fragment, or list of fragments, to search for (case-insensitive, partial match) | |
| offset | No | Number of results to skip for pagination (default 0) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint and idempotentHint annotations, such as returning only resume identity and matched skill names, and pagination details. No contradictions with annotations.
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 concise with three sentences, front-loading the purpose and usage, then listing output fields. Every sentence adds value with no 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 existence of an output schema, the description provides sufficient context: purpose, input, output fields, and pagination. It covers the essential aspects for an agent to use the tool correctly.
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 100%, so baseline is 3. The description reinforces the skill parameter flexibility but does not add new meaning beyond the schema. The mention of result fields aids understanding but pertains to output, not parameter semantics.
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 'Find' and the resource 'resumes', specifying that it filters by badge skills. It explicitly distinguishes itself from the sibling tool 'list_resume_summaries' by highlighting token efficiency for skill-based 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?
The description explicitly advises when to use this tool ('more token-efficient than list_resumes when filtering by skill') and explains that it accepts both a single skill and a list of skills, providing clear guidance on alternative usage.
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.
v1.0.8get_achievementget_badge_skillget_collection_statsget_educationget_resumeget_resume_fullget_resume_profileget_side_projectget_skill_frequencyget_work_experiencelist_achievementslist_educationlist_resumeslist_side_projectslist_skillslist_work_experiencessearch_resumesv1.0.7get_achievementget_badge_skillget_collection_statsget_educationget_resumeget_resume_profileget_side_projectget_skill_frequencyget_work_experiencelist_achievementslist_badge_skillslist_educationlist_resume_summaries2 fields changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to appear in the same name field; 'or' requires any word to match; 'regex' treats query as a case-insensitive regular expression",
+ "type": "string"
+}Input schema / properties / queryAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional name fragment to filter by first or last name (case-insensitive)"
+}list_resumeslist_side_projectslist_work_experiencessearch_achievementssearch_educationsearch_education_by_competencysearch_resumessearch_resumes_by_namesearch_resumes_by_skill10 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / mode / descriptionPrevious value: -"Token match mode — 'and' (default) requires all words to appear in the skill title; 'or' requires any word to match"New value: +"Token match mode. For a single skill: 'and' (default) requires all words to appear in the\n skill title, 'or' requires any word to match, 'regex' treats it as a case-insensitive\n regular expression. For multiple skills, mode also controls whether a resume must match\n EACH skill in the list ('and') or ANY skill in the list ('or'); 'regex' mode combines\n multiple skills with OR semantics."Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Input schema / properties / skill / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+]Input schema / properties / skill / descriptionPrevious value: -"Skill title fragment to search for (case-insensitive, partial match)"New value: +"Skill title fragment, or list of fragments, to search for (case-insensitive, partial match)"Input schema / properties / skill / typeRemoved value: -"string"Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truesearch_resumes_by_skillssearch_side_projectssearch_side_projects_by_technologysearch_skillssearch_work_experiencesv1.0.6get_collection_statsget_skill_frequencylist_achievements6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truelist_badge_skills6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truelist_education6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truelist_resume_summaries6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truelist_resumes6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truelist_side_projects6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truelist_work_experiences6 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of results to return (default 100)",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of results to skip for pagination (default 0)",
+ "type": "integer"
+}Output schema / additionalPropertiesAdded value: +trueOutput schema / propertiesRemoved value: -{
- "result": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- }
-}Output schema / requiredRemoved value: -[
- "result"
-]Output schema / x-fastmcp-wrap-resultRemoved value: -truesearch_achievements1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to appear in the description; 'or' requires any word to match",
+ "type": "string"
+}search_education1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to match within the same field; 'or' requires any word to match",
+ "type": "string"
+}search_education_by_competency1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to appear in the competency name; 'or' requires any word to match",
+ "type": "string"
+}search_resumes_by_name1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to appear in the same name field; 'or' requires any word to match",
+ "type": "string"
+}search_resumes_by_skill1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to appear in the skill title; 'or' requires any word to match",
+ "type": "string"
+}search_resumes_by_skillssearch_side_projects1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to match within the same field; 'or' requires any word to match",
+ "type": "string"
+}search_side_projects_by_technology1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to appear in the technology name; 'or' requires any word to match",
+ "type": "string"
+}search_skills1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to match; 'or' requires any word to match",
+ "type": "string"
+}search_work_experiences1 field changedInput schema / properties / modeAdded value: +{
+ "default": "and",
+ "description": "Token match mode — 'and' (default) requires all words to match within the same field; 'or' requires any word to match",
+ "type": "string"
+}v1.0.4get_educationget_side_projectlist_educationlist_side_projectssearch_educationsearch_education_by_competencysearch_side_projectssearch_side_projects_by_technologyv1.0.1get_achievementget_badge_skillget_resumeget_resume_profileget_work_experiencelist_achievementslist_badge_skillslist_resume_summarieslist_resumeslist_work_experiencessearch_achievementssearch_resumessearch_resumes_by_namesearch_resumes_by_skillsearch_skillssearch_work_experiencesScored across 19 tools
Every tool targets a distinct entity or level of detail: list_* for collections, get_* for individual items, search_* for cross-cutting queries. Even similar-sounding tools like list_resumes vs list_resume_summaries serve clearly different purposes (full vs lightweight).
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_resume_profile, list_work_experiences, search_resumes_by_skill). No mixing of conventions or vague verbs.
19 tools is slightly above the typical 3-15 range, but the number is well-justified by the domain's complexity (multiple entity types: resumes, skills, experiences, projects, education) and the need for both list and detail endpoints per entity.
The tool surface provides comprehensive read-only coverage: every entity (resume, work experience, achievement, skill, side project, education) has a list and get endpoint, plus cross-cutting search and aggregate stats. No obvious gaps for retrieval.
Public MCP server for discovering open jobs. Search, filter, and get application links.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
DocBase MCP server for AI agents
