agentleFS
hhopkehhopke/intervals-icu-mcp/.claude/skills/add-tool/SKILL.md

add-tool

Skill121 starsChanged 9 days agoMITView on GitHub

Step-by-step guide for adding a new MCP tool to this Intervals.icu server. Use when the user wants to add a new tool, endpoint, or API integration. Ensures the established async pattern, response format, naming discipline, and LLM-facing token budgets are followed consistently.

21 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-provider and release.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • PydanticSkill

    add-provider

    Add a new inference provider to genai-prices, including provider data, matching, usage extractors, update automation, cassettes, agentic checks, generated artifacts, and Python/JavaScript/Go parity tests. Use for a new provider, not a new model on an existing provider.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 4 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 9 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    Verify the Intervals.icu API endpoint exists in openapi-spec.json — check the request/response schema, enum values, and required fields.

    line 22
  2. Distinctive:

    Check for confusable names in the existing tool surface.

    line 24
  3. Very specific:

    Add an async method to ICUClient following the existing pattern.

    line 33
  4. Very specific:

    Use a small _to_dict(item) helper if the response payload needs field selection.

    line 102
  5. Distinctive:

    Import the function with the others in its category, then register with appropriate annotations:

    line 108
  6. Distinctive:

    Before marking the work done, run through these.

    line 197
  7. Distinctive:

    Response payload: keep median responses under ~1500 tokens.

    line 205
  8. Distinctive:

    If your tool name shares a prefix, suffix, or noun with another tool, the opening sentence MUST disambiguate.

    line 216
  9. Distinctive:

    If adding to one of these clusters, study how the existing siblings differentiate and follow that pattern.

    line 232
  10. Distinctive:

    If the tool has any of:

    line 236
  11. Very specific:

    Auto-metadata bloat: Don't add fetched_at, query_type, or other debug fields to the response metadata — ResponseBuilder handles metadata.

    line 251
  12. Very specific:

    Raw Pydantic dumps: Don't return model.model_dump() or model.dict() directly.

    line 252
  13. Distinctive:

    Pass-through API descriptions: Don't copy-paste the OpenAPI summary into the tool description.

    line 253
  14. Very specific:

    All tools return JSON via ResponseBuilder.build_response():

    line 260
  15. Distinctive:

    Never return raw API responses or unstructured strings.

    line 283

“Common” is measured: kept by at least 6 in 10 of the 20 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

What you're producing

An MCP tool is an LLM-consumed artifact. The tool's name and description are read by every Claude/GPT/etc. model that connects to this server, on every session, before the user has typed anything. Be ruthless about clarity and length. Write for the model, not for human readers (humans read docs/tools.md and the README).

Prerequisites

Before starting:

  • Verify the Intervals.icu API endpoint exists in openapi-spec.json — check the request/response schema, enum values, and required fields.
  • Decide the tier the tool belongs to: core (daily-use, exposed by default) or full (specialty/coach, opt-in via INTERVALS_ICU_TOOLSET=full). When tier work lands per issue #27, tag accordingly.
  • Check for confusable names in the existing tool surface. If your tool name shares a prefix or noun with another tool (e.g. get_activity_*, *_event, create_*), the opening sentence of the description MUST lead with the distinguishing access pattern, not the shared concept.
  • Decide whether a new API client method is needed in client.py.

Steps

1. Add the API client method (if needed)

File: src/intervals_icu_mcp/client.py

Add an async method to ICUClient following the existing pattern. Type the local variable so pyright doesn't widen Any:

async def get_something(self, athlete_id: str | None = None) -> list[dict[str, Any]]:
    """Fetch something from the API."""
    athlete_id = athlete_id or self.config.intervals_icu_athlete_id
    response = await self._request("GET", f"/athlete/{athlete_id}/something")
    result: list[dict[str, Any]] = response.json()
    return result

Trust the API contract — don't add if isinstance(data, list) else [] defensive ternaries unless there's a real reason. Pydantic models are preferred when the response shape is stable; raw dicts are fine for variable-shape endpoints (e.g. custom_items.content).

2. Create the tool function

File: src/intervals_icu_mcp/tools/<category>.py (existing file or new category)

from typing import Annotated, Any
from fastmcp import Context

from ..auth import ICUConfig
from ..client import ICUAPIError, ICUClient
from ..response_builder import ResponseBuilder


async def tool_name(
    activity_id: Annotated[str, "The Intervals.icu activity ID (use icu_search_activities to find one if you only have a description)"],
    athlete_id: Annotated[
        str | None, "Athlete ID (only for coaches; uses configured default otherwise)"
    ] = None,
    ctx: Context | None = None,
) -> str:
    """Single-line summary that distinguishes this tool from siblings.

    Use when the user says things like: "<concrete user prompt>", "<another
    one>". Match the user's intent to the tool's specific access pattern.

    Args:
        activity_id: The Intervals.icu activity ID
        athlete_id: Athlete ID (uses configured default if not provided)

    Returns:
        JSON string with the data
    """
    assert ctx is not None
    config: ICUConfig = await ctx.get_state("config")

    try:
        async with ICUClient(config) as client:
            result = await client.method(activity_id, athlete_id=athlete_id)

            return ResponseBuilder.build_response(
                data={"key": "value"},
                metadata={"count": len(result)},
                query_type="tool_type",
            )
    except ICUAPIError as e:
        return ResponseBuilder.build_error_response(e.message, error_type="api_error")
    except Exception as e:
        return ResponseBuilder.build_error_response(
            f"Unexpected error: {str(e)}", error_type="internal_error"
        )

Notes:

  • await ctx.get_state("config") — the await is required.
  • Wrap in try for both ICUAPIError (HTTP-level) and Exception (unexpected).
  • Validate enum-style parameters at the boundary with validation_error responses before the API call. Don't let the API tell the user their input was wrong if we can catch it cheaper upstream.
  • Use a small _to_dict(item) helper if the response payload needs field selection. Pattern: only include keys when the value is not None — see tools/custom_items.py:_custom_item_to_dict.

3. Register the tool in server.py

File: src/intervals_icu_mcp/server.py

Import the function with the others in its category, then register with appropriate annotations:

mcp.tool(
    name="icu_<verb>_<noun>",
    annotations={
        "readOnlyHint": True,    # False for writes
        "destructiveHint": False, # True for destructive ops
        "idempotentHint": True,
        "openWorldHint": True,
    },
)(tool_name)

Naming convention: icu_<verb>_<noun> for reads; verb-prefixed for writes (create_, update_, delete_, add_, bulk_*). Plural noun for list-returning tools (get_activity_messages); singular for single-record tools (get_activity_message_by_id if it existed).

4. Write tests

File: tests/test_<category>_tools.py

We use pytest-asyncio configured globally (no @pytest.mark.asyncio decorator needed) and respx for HTTP mocking:

import json
from unittest.mock import AsyncMock, MagicMock

from httpx import Response

from intervals_icu_mcp.tools.<category> import tool_name


class TestToolName:
    async def test_tool_name_success(self, mock_config, respx_mock):
        mock_ctx = MagicMock()
        mock_ctx.get_state = AsyncMock(return_value=mock_config)

        respx_mock.get("/athlete/i123456/endpoint").mock(
            return_value=Response(200, json={"id": 1, "name": "Test"})
        )

        result = await tool_name(arg="x", ctx=mock_ctx)
        response = json.loads(result)

        assert response["data"]["id"] == 1

    async def test_tool_name_validation_error(self, mock_config):
        # Test that invalid input is rejected without an HTTP call
        mock_ctx = MagicMock()
        mock_ctx.get_state = AsyncMock(return_value=mock_config)

        result = await tool_name(arg="invalid", ctx=mock_ctx)
        response = json.loads(result)

        assert response["error"]["type"] == "validation_error"

    async def test_tool_name_api_error(self, mock_config, respx_mock):
        # Test that API errors surface cleanly
        mock_ctx = MagicMock()
        mock_ctx.get_state = AsyncMock(return_value=mock_config)

        respx_mock.get("/athlete/i123456/endpoint").mock(return_value=Response(404))

        result = await tool_name(arg="x", ctx=mock_ctx)
        response = json.loads(result)

        assert response["error"]["type"] == "api_error"

Cover at minimum: happy path, validation rejection (if applicable), API error surfacing, athlete_id override (if applicable).

Fixtures mock_config and respx_mock come from tests/conftest.py.

5. Verify

make can-release

Confirms ruff (formatting + lint), pyright (strict on src/), all tests pass, and pyroma scores 10/10.

6. Update inventories

  • CLAUDE.md — tool count in Project Overview, plus tool category list if a new category was added.
  • README.md — tool count line and the Available Tools table.
  • docs/tools.md — per-category table.
  • tests/test_transport_integration.py — the assert len(tools) == N assertion needs bumping.

Quality checklist (LLM-facing)

Before marking the work done, run through these. They matter more than people expect.

Token budgets

These are targets, not hard caps. Going over with good reason is fine — but justify it in the PR.

  • Tool description (combining docstring + all Annotated params): aim for ≤200 tokens. Top-end tools with many parameters can go higher; review them especially carefully.
  • Per-Annotated parameter: aim for ≤80 tokens. If you need more (e.g. enum lists, schema docs), move the long content into an MCP Resource and reference it. See intervals-icu://workout-syntax as the canonical example.
  • Response payload: keep median responses under ~1500 tokens. Anthropic recommends a 25K-token cap for tool responses; we should be far below that.

Description quality

  • First sentence is critical — Anthropic's research shows it dominates LLM tool selection. Lead with the distinguishing access pattern, not the shared concept. Bad: "Get details about an activity." Good: "Fetch the headline summary of one activity (name, date, distance, time, training load, sport)."
  • Use concrete user prompts in Annotated descriptions where it helps disambiguation: "Use when the user says: 'show me my last ride', 'what's my recent activity?'"
  • Match the user's natural language, not the API's. Example: API calls them "messages"; users call them "comments" or "notes". Mention both.
  • No marketing prose, no "elegant", no "powerful". Every word costs tokens forever.

Confusable-name discipline

If your tool name shares a prefix, suffix, or noun with another tool, the opening sentence MUST disambiguate. Anthropic identifies tool-name similarity as the top cause of LLM tool-selection failures — descriptions are the only thing standing between the LLM and a wrong-tool round-trip.

Technique (per PR #30):

  1. Lead the first sentence with the distinguishing access pattern, not the shared concept. NOT "Get details about an activity." → DO "Fetch the headline SUMMARY of one activity — name, sport, date, distance, training load, weather."
  2. Use ALL-CAPS sparingly on the disambiguator word (ONE / MANY / SUMMARY / RANGE / LIGHT / FULL / RAW / COPY). One word per first sentence. It anchors the LLM's attention to the choice axis.
  3. Cross-reference siblings explicitly in the body — name them and say when to pick each. The LLM evaluates tools partly by what their siblings claim NOT to do.

Existing confusable clusters (study these before adding to them):

  • icu_get_activity_* family (details = SUMMARY / intervals = per-LAP / streams = RAW per-second)
  • icu_search_activities (LIGHT) vs icu_search_activities_full (FULL — heavy)
  • icu_create_event (ONE new) / icu_bulk_create_events (MANY new) / icu_duplicate_events (COPY existing forward)
  • icu_get_wellness_data (RANGE of days) vs icu_get_wellness_for_date (ONE specific date)
  • icu_get_*_curves (best-effort across durations) vs icu_get_*_histogram (time-in-zone distribution per activity)
  • icu_*_message (singular = write) vs icu_*_messages (plural = read)

If adding to one of these clusters, study how the existing siblings differentiate and follow that pattern.

Input examples for complex tools

If the tool has any of:

  • A free-form structured field (workout description, JSON content schema, dict payload)
  • Multiple optional params that interact non-obviously
  • An enum-driven inner schema (different content shapes per item_type)

…ship 1-2 input_examples with the tool definition. Anthropic reports 72% → 90% accuracy on complex parameter handling when examples are included. Token cost is small (~50-200 tokens per example) vs. the round-trip cost of a model getting it wrong. See issue #29 for the project-wide rollout plan.

Cache discipline

Tool descriptions are at the top of Anthropic's prompt-caching hierarchy: tools → system → messages. Any change to a tool description invalidates the cache for everything below it, costing 1.25× (5-min cache) or 2× (1-hour cache) the base input tokens for the next session that hits this server.

Practical rule: batch description changes into one PR. Don't drip them across multiple commits — each commit cascades. If you're touching descriptions, touch them all at once.

Anti-patterns (don't do these)

  • Auto-metadata bloat. Don't add fetched_at, query_type, or other debug fields to the response metadata — ResponseBuilder handles metadata; if you have a meaningful per-tool addition (count, message, etc.), pass it via the metadata= param. (Issue #25 is removing the auto-debug fields entirely.)
  • Raw Pydantic dumps. Don't return model.model_dump() or model.dict() directly. Use a _to_dict helper that selects fields. Lets you skip null-valued fields, control output shape, and keep the response token-lean.
  • Pass-through API descriptions. Don't copy-paste the OpenAPI summary into the tool description. The API docs are written for HTTP clients; tool descriptions are written for LLMs choosing between tools.
  • Generic opening sentences. "Get a thing." / "Manage things." — these tell the LLM nothing. Lead with the distinguishing access pattern.
  • Renaming an existing tool. Tool names are part of the public contract. Users have prompts mentioning them by name; renaming breaks those silently. Description rewrites are safe; renames are not.
  • Pre-mature defensive coding in client methods (if isinstance(data, list) else []). Trust the API contract; if a response really is unstable, model that explicitly with Pydantic + extra="allow".

Response format reminder

All tools return JSON via ResponseBuilder.build_response():

{
  "data": {...},
  "analysis": {...},  // optional - computed insights
  "metadata": {...}   // optional - count, message, etc.
}

Errors via ResponseBuilder.build_error_response():

{
  "error": {
    "message": "...",
    "type": "api_error" | "validation_error" | "internal_error",
    "timestamp": "...",
    "suggestions": [...]   // optional
  }
}

Never return raw API responses or unstructured strings.

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.