agentleFS
Sign inStart free
BufferoverflovvBufferoverflovv/FastMCP-Blueprint/.github/skills/add-tool/SKILL.md

add-tool

Skill0 starsChanged 7 months agoApache-2.0View on GitHub

Scaffold a new FastMCP tool following project conventions. Use when: adding a new tool, creating an LLM-callable action, implementing a new MCP tool endpoint, adding tool tests, or extending the server with a new capability. Asks questions then generates the tool file, registers the import, and creates matching tests.

We split this skill into the rules it gives an agent

8 rules. 0 are common, 1 is distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 18 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before asking questions, read pyproject.toml to find the current package name from:

    line 19
  2. Very specific:

    Use this as PACKAGE for all file paths and imports below.

    line 25
  3. Very specific:

    Ask the following questions.

    line 29
  4. Very specific:

    Create src/PACKAGE/tools/TOOL_NAME.py using ./assets/tool_template.md as the base.

    line 43
  5. Very specific:

    Add the import line to src/PACKAGE/__main__.py after the existing tool imports:

    line 58
  6. Very specific:

    Keep the # noqa: F401 comment — the import is intentional for side-effect registration.

    line 64
  7. Very specific:

    Create tests/test_TOOL_NAME.py using ./assets/test_template.md as the base.

    line 68
  8. Distinctive:

    Run and confirm both pass:

    line 77

“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “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

Add a New FastMCP Tool

Scaffolds a fully wired FastMCP tool in the correct location following the conventions already used in this project.

When to use

  • Adding any new MCP tool to the server
  • Wanting a correctly structured tool file and matching tests in one step
  • Unsure about parameter annotations, error handling, or async patterns

Step 1 — Detect the package name

Before asking questions, read pyproject.toml to find the current package name from:

packages = ["src/<package_name>"]

Use this as PACKAGE for all file paths and imports below.

Step 2 — Interview the user

Ask the following questions. Use vscode_askQuestions if available.

#QuestionNotes
1Tool namesnake_case, action-oriented (e.g. fetch_weather, resolve_dns_record)
2What does this tool do?One sentence — becomes the docstring
3ParametersName, type, description for each. Ask one at a time if unclear
4Sync or async?Default: async for any I/O, sync for pure computation
5Read-only or destructive?Read-only → add readOnlyHint=True; destructive → add destructiveHint=True
6What should raise a ToolError?e.g. invalid input, network failure, resource not found
7Does it need external I/O?If yes, suggest adding an HTTP client or DB pool via app_lifespan

Step 3 — Generate the tool file

Create src/PACKAGE/tools/TOOL_NAME.py using ./assets/tool_template.md as the base.

Fill in:

  • The import block (sync or async variant)
  • @mcp.tool() decorator with hints if applicable
  • Function signature with all Annotated parameters
  • Docstring from the tool description answer
  • Logger call using get_tool_logger("TOOL_NAME")
  • Return type annotation
  • ToolError raises for the stated error cases

See ./references/tool-conventions.md for exact patterns.

Step 4 — Register the import in __main__.py

Add the import line to src/PACKAGE/__main__.py after the existing tool imports:

from PACKAGE.tools import TOOL_NAME  # noqa: F401

Keep the # noqa: F401 comment — the import is intentional for side-effect registration.

Step 5 — Generate the test file

Create tests/test_TOOL_NAME.py using ./assets/test_template.md as the base.

Include at minimum:

  • A success-path test using await client.call_tool("TOOL_NAME", {...})
  • An error-path test using raise_on_error=False and asserting result.is_error
  • A test for any default parameter values if applicable

Step 6 — Validate

Run and confirm both pass:

ruff check .
pytest tests/test_TOOL_NAME.py -v

Fix any issues before reporting completion.

Step 7 — Report

Tell the user:

  • The path of the new tool file
  • The path of the new test file
  • What was added to __main__.py
  • Any suggestions for next steps (e.g. if the tool needs lifespan context for an HTTP client)

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.

Reviews can't be read right now.

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.

Check your setup, free