CoderSwap MCP Server
Enables ingestion and semantic search of research papers from arXiv, with automatic crawling, chunking, and embedding capabilities for building topic-specific knowledge bases
Supports ingestion of OpenAI research content and documentation into vector search projects for semantic search and knowledge base creation
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CoderSwap MCP Servercreate a project for quantum computing research and ingest the latest papers from arXiv"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CoderSwap MCP Server
Model Context Protocol (MCP) server that lets Claude (and any MCP-aware agent) stand up a topic-specific knowledge base end-to-end—project creation, ingestion, progress tracking, search validation, and lightweight session notes—without exposing low-level APIs.
Features
🚀 Create and list vector-search projects
📚 Ingest research summaries + URLs with auto-crawling, chunking, and embedding
🧠 Auto-ingest curated sources (crawl → chunk → embed) with relevance tuning handled by the CoderSwap platform team
🔍 Execute hybrid semantic search with intent-aware ranking
📊 Monitor ingestion jobs, capture blocked sources, and run quick search-quality spot checks
✨ Rich, formatted output optimized for AI agents
Installation
cd packages/mcp-server
npm install
npm run buildConfiguration
Set the following environment variables before launching the server:
CODERSWAP_BASE_URL(default:http://localhost:8000)CODERSWAP_API_KEY(required)DEBUG(optional: set totruefor detailed logging)
Running
Development (Local Backend)
# Set environment variables
export CODERSWAP_BASE_URL=http://localhost:8000
export CODERSWAP_API_KEY=cs_dev_nmVDJupuxflYYWd34HiRxbtxONul3hv1_f981
# Run the server
npm startClaude Desktop Configuration
Update your Claude Desktop config file:
macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Local Development:
{
"mcpServers": {
"coderswap": {
"command": "node",
"args": ["C:/Users/tayav/CascadeProjects/CoderSwapIO/packages/mcp-server/dist/index.js"],
"env": {
"CODERSWAP_BASE_URL": "http://localhost:8000",
"CODERSWAP_API_KEY": "cs_dev_nmVDJupuxflYYWd34HiRxbtxONul3hv1_f981"
}
}
}
}Production:
{
"mcpServers": {
"coderswap": {
"command": "npx",
"args": ["-y", "@coderswap/mcp-server"],
"env": {
"CODERSWAP_BASE_URL": "https://api.coderswap.ai",
"CODERSWAP_API_KEY": "your_production_api_key"
}
}
}
}Available Tools
Project Management
coderswap_create_project– Create a new vector search projectcoderswap_list_projects– List accessible projects with document countscoderswap_get_project_stats– Pull basic stats (created_at, document totals)
Research & Ingestion
coderswap_research_ingest– Crawl, chunk, and embed vetted URLs (advanced tuning is managed by the platform team)coderswap_get_job_status– Poll ingestion job progress, crawl counts, blocked domains
Search & Validation
coderswap_search– Execute hybrid semantic search with ranked snippetscoderswap_test_search_quality– Run quick multi-query smoke tests (or a predefined suite) to gauge relevance
Session Continuity
coderswap_log_session_note– Record lightweight summaries (job_id, ingestion metrics, follow-ups) so humans stay in the loop
Guardrails & Security
The server loads
mcp_starter_prompt.yamlat startup and injects it as a non-removable system prompt.Startup fails if the prompt is missing, invalid, or tampered with (hash mismatch).
Advanced tuning endpoints are intentionally omitted; when deeper adjustments are required, Claude guides users to loop in the CoderSwap platform team.
All operations must go through the MCP tools; direct HTTP/DB access is disallowed.
Each tool:
✅ Validates inputs with Zod schemas
✅ Returns both structured data and AI-friendly text summaries
✅ Includes comprehensive error handling
✅ Logs operations for debugging (when DEBUG=true)
Example Usage
Autonomous Research Workflow
Claude can execute this workflow autonomously:
Create a project:
Use coderswap_create_project with name "AI Research"Ingest research content:
Use coderswap_research_ingest with URLs: - https://arxiv.org/abs/2103.00020 - https://openai.com/research/gpt-4Monitor progress (Claude keeps polling until complete):
Use coderswap_get_job_status to check ingestionSearch the knowledge base:
Use coderswap_search with query "transformer architecture"Optional: run a quick multi-query smoke test:
Use coderswap_test_search_quality with test queries or run_full_suite: trueLeave yourself a handoff note (e.g., sources blocked, next steps):
Use coderswap_log_session_note with project_id "proj_123", summary_text "Ingested 9/10 sources; FDA site blocked by robots.txt. Run follow-up after manual download." job_id "job_456" ingestion_metrics {"sources_succeeded": 9, "sources_failed": 1}
Output Format
Search results are formatted with rich details:
Found 5 result(s) for: "hybrid search"
🥇 Score: 85.2%
About hybrid search | Vertex AI
Vector Search supports hybrid search...
🥈 Score: 72.1%
Hybrid Search | Weaviate
Hybrid search combines semantic and keyword...
🥉 Score: 68.4%
...Debugging
Enable debug logging:
export DEBUG=true
npm startLogs are written to stderr and include:
Timestamps
Operation details
Error messages with context
Development
# Install dependencies
npm install
# Build TypeScript
npm run build
# Watch mode (for development)
npm run devArchitecture
Claude Desktop → MCP Server (stdio) → CoderSwap Backend API → Oracle ADW 23ai
↓
- Tool validation (Zod)
- Error handling
- Response formattingWith the MCP server, Claude can autonomously build, test, and optimize vector knowledge bases in minutes! 🚀
Available Tools
8 toolscoderswap_create_projectCreate CoderSwap ProjectB
Create a new vector search project in CoderSwap
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| description | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| status | No | |
| project_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool creates something but doesn't mention permissions required, whether this is idempotent, what happens on duplicate names, rate limits, or what the output contains. For a creation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.
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 creates a project (a mutation operation) with no annotations and an output schema exists, the description is minimally complete. It identifies the action and resource but lacks details on behavior, parameters, or context. The output schema may cover return values, but the description doesn't address permissions, errors, or integration with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter semantics beyond what the schema provides. With 0% schema description coverage, the schema documents the parameters (name, description) but without descriptions. The description doesn't explain what 'name' or 'description' represent in context, their constraints, or examples. However, with only 2 parameters and a simple structure, the baseline is 3 as the schema provides basic typing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new vector search project in CoderSwap'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'coderswap_list_projects' or 'coderswap_research_ingest' in terms of when to use creation versus other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when creation is appropriate versus listing existing projects, or any context about the project lifecycle. Users must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_get_job_statusGet CoderSwap Job StatusB
Check the status of a research ingestion job
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| state | Yes | |
| job_id | Yes | |
| failed_count | No | |
| crawled_count | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a 'check' operation, which implies read-only behavior, but doesn't confirm if it's safe, idempotent, or has side effects. It lacks details on authentication needs, rate limits, error conditions, or what the status check entails (e.g., polling, immediate response). The description adds minimal behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It avoids redundancy with the tool name and title, and every part of the sentence contributes directly to understanding the tool's function. No fluff or wasted space is present.
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 low complexity (1 parameter) and the presence of an output schema (which likely defines status values), the description is minimally adequate. However, with no annotations and incomplete parameter semantics, it leaves gaps in understanding behavioral traits and usage context. It meets basic needs but doesn't fully compensate for the lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, so the schema provides no semantic information. The description doesn't mention the 'job_id' parameter at all, failing to explain what it is, where to get it, or its format. However, with only one parameter, the baseline is higher; the tool's purpose inherently implies a job identifier is needed, but explicit parameter guidance is missing.
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 ('Check') and resource ('status of a research ingestion job'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'coderswap_research_ingest' (which likely creates jobs) and 'coderswap_get_project_stats' (which focuses on projects rather than jobs). However, it doesn't specify what a 'research ingestion job' entails or what status values might be returned.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a job ID from a previous operation), exclusions, or relationships to siblings like 'coderswap_research_ingest' (which might create the jobs being checked). Usage is implied only through the tool name and description context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_get_project_statsGet CoderSwap Project StatsC
Get statistics and information about a specific project
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| name | No | |
| doc_count | No | |
| created_at | No | |
| project_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves statistics and information, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, error handling, or what happens if the project doesn't exist. This leaves significant gaps for safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action, though it could be slightly more structured (e.g., by listing key statistics) to enhance clarity without sacrificing brevity.
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 low complexity (1 parameter, no nested objects) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete parameter guidance, it lacks details on behavioral traits and usage context, leaving room for improvement in supporting the 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?
The input schema has 1 parameter with 0% description coverage, so the description must compensate. It implies the parameter is for identifying a project but doesn't specify format (e.g., numeric ID, string), constraints, or examples. This adds minimal meaning beyond the schema's basic type and requirement, meeting the baseline for low coverage without fully addressing gaps.
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 resource ('statistics and information about a specific project'), making the purpose understandable. It distinguishes from siblings like 'coderswap_list_projects' by focusing on a single project rather than listing multiple. However, it doesn't specify what types of statistics or information are included, keeping it from being fully specific.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid project ID), exclusions, or comparisons to siblings like 'coderswap_get_job_status' or 'coderswap_search'. The agent must infer usage from the tool name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_list_projectsList CoderSwap ProjectsB
List all CoderSwap projects available to your API key
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| projects | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists projects 'available to your API key,' hinting at authentication and scope, but lacks details on pagination, rate limits, error handling, or output format. For a list operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('List all CoderSwap projects') and includes essential context ('available to your API key'). Every part of the sentence earns its place, making it highly concise 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 tool's simplicity (0 parameters, output schema exists), the description is minimally adequate. It covers the basic purpose but lacks behavioral details (e.g., pagination, error handling) that aren't provided by annotations. The output schema should handle return values, so the description doesn't need to explain those. However, for a list tool with no annotations, more context on behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter information, which is appropriate here. A baseline of 4 is applied for tools with zero parameters, as there's nothing to compensate for, and the description doesn't introduce confusion.
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 ('List') and resource ('CoderSwap projects'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'coderswap_search' or 'coderswap_get_project_stats', which might also retrieve project information in different ways. The description is specific about scope ('all...available to your API key') but lacks sibling distinction.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'coderswap_search' (which might filter projects) or 'coderswap_get_project_stats' (which might provide detailed metrics), leaving the agent without context for tool selection. The only implied usage is for listing all accessible projects, but no exclusions or alternatives are specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_log_session_noteLog Session NoteC
Record lightweight ingestion summary for session continuity (non-DSL)
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| summary_text | Yes | ||
| job_id | No | ||
| ingestion_metrics | No | ||
| tags | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| note_id | Yes | |
| timestamp | Yes | |
| project_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states it 'records' a summary, implying a write operation. It doesn't disclose behavioral traits like permissions needed, idempotency, rate limits, or what 'session continuity' entails operationally, leaving significant gaps.
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 and front-loaded in a single sentence, with no wasted words. However, it could be more structured by explicitly separating purpose from constraints or usage notes.
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 5 parameters with 0% schema coverage and no annotations, the description is incomplete—it doesn't explain parameters or behavioral details. The presence of an output schema mitigates this slightly, but overall, it's inadequate for a tool with multiple undocumented inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter-specific information. It doesn't explain what 'project_id', 'summary_text', 'job_id', 'ingestion_metrics', or 'tags' mean or how they relate to the tool's purpose, failing to address the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Record') and resource ('lightweight ingestion summary for session continuity'), specifying it's for 'non-DSL' contexts. However, it doesn't explicitly differentiate from sibling tools like 'coderswap_research_ingest' or 'coderswap_validate_search', which might involve similar concepts.
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 minimal guidance by mentioning 'session continuity' and 'non-DSL', but lacks explicit when-to-use rules, prerequisites, or alternatives compared to siblings. No clear context for choosing this over other tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_research_ingestCoderSwap Research IngestC
Submit research summary and URLs for web crawling, chunking, embedding, and optional DSL generation
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| research_summary | No | ||
| urls | Yes | ||
| intent | No | ||
| depth | No | ||
| generate_dsl | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| job_id | Yes | |
| status | Yes | |
| project_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool's actions (e.g., 'web crawling, chunking, embedding, and optional DSL generation') but doesn't specify critical details like required permissions, rate limits, whether it's a long-running job (implied by sibling coderswap_get_job_status), or what happens on submission. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Submit research summary and URLs') and lists the processing steps without unnecessary words. Every part earns its place, making it highly concise and well-structured for quick comprehension.
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 (6 parameters, no annotations) and the presence of an output schema (which reduces the need to describe return values), the description is moderately complete. It covers the high-level purpose but lacks details on parameter usage, behavioral traits, and differentiation from siblings, making it adequate but with clear gaps that hinder full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'research summary and URLs' and 'optional DSL generation,' which loosely maps to some parameters (research_summary, urls, generate_dsl) but doesn't explain the purpose or usage of project_id, intent, or depth. This partial coverage fails to fully clarify the semantics, especially for key required parameters like project_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('submit research summary and URLs') and resources ('for web crawling, chunking, embedding, and optional DSL generation'), making it easy to understand what it does. However, it doesn't explicitly differentiate from sibling tools like coderswap_search or coderswap_validate_search, which might also involve research or URL processing, keeping it from a perfect score.
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 no guidance on when to use this tool versus alternatives, such as coderswap_search or coderswap_validate_search, nor does it mention prerequisites like needing an existing project. It implies usage for research ingestion but lacks explicit context or exclusions, leaving the agent with minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_searchCoderSwap Hybrid SearchC
Execute a hybrid search query against a CoderSwap project using DSL-powered ranking
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| query | Yes | ||
| top_k | No | ||
| snippet_length | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| results | Yes | |
| result_count | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'DSL-powered ranking' which hints at ranking behavior, but doesn't explain what 'hybrid search' entails, whether it's read-only or has side effects, authentication requirements, rate limits, or what the output contains. This leaves significant gaps for a search operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a tool description and front-loads the essential information about what the tool does.
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 that there's an output schema (which reduces the need to describe return values), but with 4 parameters having 0% schema coverage and no annotations, the description is incomplete. It covers the basic purpose but lacks crucial details about parameter meanings, behavioral characteristics, and usage context that would make it fully adequate for this search 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?
With 0% schema description coverage for all 4 parameters, the description provides no information about parameter meanings beyond what's in the schema. It doesn't explain what 'project_id' refers to, what format 'query' should take, what 'top_k' controls, or what 'snippet_length' affects in the results. The description fails to compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('execute a hybrid search query') and target resource ('against a CoderSwap project'), which provides a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like coderswap_validate_search or coderswap_research_ingest, which might have overlapping search-related functionality.
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 no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, appropriate contexts, or comparisons to sibling tools like coderswap_validate_search (which might be for validation) or coderswap_research_ingest (which might involve data ingestion).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coderswap_validate_searchValidate CoderSwap Search QualityB
Run validation queries to test search quality and coverage (non-DSL quality check)
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| test_queries | No | ||
| run_full_suite | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| queries_tested | Yes | |
| average_top_score | Yes | |
| zero_result_queries | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'non-DSL quality check', which hints this might be a read-only or diagnostic operation, but it doesn't clarify if it's destructive, requires specific permissions, has rate limits, or what the validation entails. For a tool with zero annotation coverage, this is a significant gap in transparency.
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 highly concise and front-loaded in a single sentence: 'Run validation queries to test search quality and coverage (non-DSL quality check)'. Every word earns its place by conveying purpose and scope without redundancy, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which reduces the need to describe return values), 3 parameters with 0% schema coverage, and no annotations, the description is moderately complete. It covers the core purpose and hints at behavior, but lacks details on usage guidelines, parameter semantics, and behavioral traits, leaving gaps that could hinder effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It adds some meaning by implying 'validation queries' relate to 'test_queries' and 'search quality' relates to 'project_id', but it doesn't explain what 'run_full_suite' does or provide details on query formats or project context. With 3 parameters and low coverage, the description offers marginal value beyond the bare 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's purpose: 'Run validation queries to test search quality and coverage' with the specific verb 'run' and resource 'validation queries', and it distinguishes this from regular search operations by specifying it's a 'non-DSL quality check'. However, it doesn't explicitly differentiate from sibling tools like coderswap_search or coderswap_research_ingest, which keeps it from a perfect score.
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 minimal guidance: it implies this tool is for testing rather than production use through 'test search quality', but it doesn't specify when to use this versus alternatives like coderswap_search or coderswap_research_ingest, nor does it mention prerequisites or exclusions. This leaves the agent with insufficient context for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v1.0.0- First observed
coderswap_create_project - First observed
coderswap_get_job_status - First observed
coderswap_get_project_stats - First observed
coderswap_list_projects - First observed
coderswap_log_session_note - First observed
coderswap_research_ingest - First observed
coderswap_search - First observed
coderswap_validate_search
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose with no ambiguity. The tools cover different aspects of the workflow: project management (create, list, get stats), job monitoring (get job status), ingestion (research_ingest, log_session_note), and search operations (search, validate_search). There is no overlap in functionality that would cause misselection.
All tools follow a consistent 'coderswap_verb_noun' pattern throughout, using snake_case uniformly. The verbs are descriptive and appropriate for each action (e.g., create_project, get_job_status, list_projects), making the naming highly predictable and readable.
With 8 tools, the count is well-scoped for a vector search project management server. Each tool earns its place by covering essential operations: project lifecycle (create, list, get stats), ingestion workflows (research_ingest, log_session_note), job monitoring, and search functionality (search, validate). This is neither too sparse nor bloated.
The tool set provides comprehensive coverage for core CoderSwap workflows, including project CRUD, ingestion, and search. A minor gap exists in the lack of update or delete operations for projects, which might limit full lifecycle management, but agents can likely work around this given the server's focus on ingestion and search.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Shared knowledge base for AI agents. Semantic search across agents, no setup required — just a URL.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Curated knowledge API for AI agents - skill packs, semantic search, validated patterns.
- OneLoreOAuthai.onelore
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
