agentleFS
sagar-shirwalkarsagar-shirwalkar/servicenow-atlas/.agents/skills/atlas-add-tool/SKILL.md

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.

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
  1. Distinctive:

    Read the existing tool implementations in:

    line 23
  2. Distinctive:

    Keep the handler thin; business logic goes in private helpers.

    line 83
  3. Very specific:

    If the tool needs a CLI equivalent, add an entry in pyproject.toml under [project.scripts]:

    line 96
  4. Very specific:

    Use description on every parameter — the LLM client reads these.

    line 113
  5. Very specific:

    Use enum for constrained values:

    line 114
  6. Very specific:

    Use default for optional parameters (omit from required array).

    line 121

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 toServer file
Document search / RAGatlas/rag_server.py
File listing / readingatlas/fs_server.py
Build / maintenanceConsider 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.). Mark required explicitly.

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 ValueError with 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

CriterionUse
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 of string, integer, number, boolean, array, object.
  • Use description on every parameter — the LLM client reads these.
  • Use enum for constrained values:
    "backend": {
      "type": "string",
      "enum": ["mlx", "onnx-cpu", "onnx-gpu"]
    }
  • Use default for optional parameters (omit from required array).

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.