atlas-add-tool
Skill2 starsChanged 5 months agoApache-2.0View on GitHub
Add a new MCP tool to the atlas-fs or atlas-rag server. Covers tool definition, handler function, parameter schema, and register call. Use when implementing a new feature that needs to be exposed as an MCP tool.
In this repository16 other files it gives its agents.
- architecture-decision-recordsSkill
- atlas-build-bundleSkill
- atlas-ci-releaseSkill
- atlas-optimization-patternsSkill
- atlas-rag-evaluationSkill
- embedding-strategiesSkill
- hybrid-search-implementationSkill
- mcp-builderSkill
- python-code-styleSkill
- python-observabilitySkill
- python-resilienceSkill
- python-testing-patternsSkill
- python-type-safetySkill
- readme-maintenanceSkill
- skill-creatorSkill
- uv-package-managerSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Read the existing tool implementations in:
- Distinctive: line 83
Keep the handler thin; business logic goes in private helpers.
- Very specific: line 96
If the tool needs a CLI equivalent, add an entry in pyproject.toml under [project.scripts]:
- Very specific: line 113
Use description on every parameter — the LLM client reads these.
- Very specific: line 114
Use enum for constrained values:
- Very specific: line 121
Use default for optional parameters (omit from required array).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
When to use
- User asks to "add a new tool", "create a tool for X", "expose Y as an MCP tool"
- User is building a new capability that needs to be callable by an LLM
- User wants to understand the existing tool registration pattern
Not for
- General code changes outside tool definitions
- Modifying the embedder or chunker internals
- Changing the MCP server lifecycle (startup, shutdown, transport)
Prerequisites
Read the existing tool implementations in:
atlas/rag_server.py— tools on the RAG server (semantic search, etc.)atlas/fs_server.py— tools on the filesystem server (read, list, search, etc.)
Workflow
1. Locate the right server file
| Tool belongs to | Server file |
| Document search / RAG | atlas/rag_server.py |
| File listing / reading | atlas/fs_server.py |
| Build / maintenance | Consider a new server or atlas/doctor.py |
2. Follow the existing pattern
Each tool has three parts in the server file:
a) Tool docstring + @server.list_tools() handler
@server.list_tools()
async def list_tools() -> list[Tool]:
return [
# existing tools ...
Tool(
name="your_tool_name",
description="What the tool does — be specific",
inputSchema={
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "What this parameter is for",
},
},
"required": ["param_name"],
},
),
]- Tool names:
snake_case, conventionally matching the function name. - Descriptions: written for an LLM reader. Include edge cases, defaults, and example values.
- Parameters: use JSON Schema types (
string,integer,array, etc.). Markrequiredexplicitly.
b) The @server.call_tool() handler branch
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "your_tool_name":
result = await your_handler(arguments)
return [TextContent(type="text", text=result)]
elif name == "existing_tool":
...- Handler returns
list[TextContent]. - For errors, raise
ValueErrorwith a clear message — the MCP framework serialises it. - Keep the handler thin; business logic goes in private helpers.
c) The business logic function (inline or imported)
async def your_handler(args: dict) -> str:
param = args["param_name"]
# ... do the work ...
return json.dumps(result, indent=2, default=str)3. Register the tool as a console script (if needed)
If the tool needs a CLI equivalent, add an entry in pyproject.toml under [project.scripts]:
atlas-your-tool = "atlas.module:main"4. Sync vs async decision
| Criterion | Use |
| I/O-bound (file read, HTTP, subprocess) | async def |
| CPU-bound (embedding, chunking) | async def that calls loop.run_in_executor for the heavy part |
| Trivial (string formatting, data lookup) | def is fine |
5. Parameter schema rules
type: one ofstring,integer,number,boolean,array,object.- Use
descriptionon every parameter — the LLM client reads these. - Use
enumfor constrained values:"backend": { "type": "string", "enum": ["mlx", "onnx-cpu", "onnx-gpu"] } - Use
defaultfor optional parameters (omit fromrequiredarray).
Example
See atlas/rag_server.py for a real tool (semantic search), and atlas/fs_server.py for filesystem tools (list publications, list files, read file, search).
References
atlas/rag_server.py— RAG tool pattern (embed queries + cosine similarity + return results)atlas/fs_server.py— FS tool pattern (MCP resource enumeration + tool calls)- MCP Python SDK documentation for
Tool,TextContent,server.list_tools,server.call_tool
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

