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
- fauguste/boondmanager-mcp-servertheir own version, first seen Nov 15, 2026
- alunduil/alunduil-chezmoitheir own version, first seen Nov 13, 2026
- Md-Nisar/neurontheir own version, first seen Nov 11, 2026
- HalemoGPA/whatsapp-mcp-servertheir own version, first seen Nov 8, 2026
- ooloth/dotfilestheir own version, first seen Nov 6, 2026
- Adham-Aly/quartermastertheir own version, first seen Nov 1, 2026
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.
PydanticSkilladd-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
MicrosoftSkillrelease
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
Other versions21 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 21
- takeshy/obsidian-gemini-helper★ 117same name
- Azure-Samples/art-voice-agent-accelerator★ 74same name
- takeshy/obsidian-llm-hub★ 41same name
- ooloth/dotfiles★ 24same name
- Cognigy/cognigy-plugin★ 21same name
- fauguste/boondmanager-mcp-server★ 21same name
- microsoft/PilotSwarm★ 17same name
- PinMeTo/pinmeto-location-mcp★ 15same name
- HalemoGPA/whatsapp-mcp-server★ 9same name
- alunduil/alunduil-chezmoi★ 2same name
11 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- commitSkill
- release-checkSkill
- release-writeSkill
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
- Very specific: line 22
Verify the Intervals.icu API endpoint exists in openapi-spec.json — check the request/response schema, enum values, and required fields.
- Distinctive: line 24
Check for confusable names in the existing tool surface.
- Very specific: line 33
Add an async method to ICUClient following the existing pattern.
- Very specific: line 102
Use a small _to_dict(item) helper if the response payload needs field selection.
- Distinctive: line 108
Import the function with the others in its category, then register with appropriate annotations:
- Distinctive: line 197
Before marking the work done, run through these.
- Distinctive: line 205
Response payload: keep median responses under ~1500 tokens.
- Distinctive: line 216
If your tool name shares a prefix, suffix, or noun with another tool, the opening sentence MUST disambiguate.
- Distinctive: line 232
If adding to one of these clusters, study how the existing siblings differentiate and follow that pattern.
- Distinctive: line 236
If the tool has any of:
- Very specific: line 251
Auto-metadata bloat: Don't add fetched_at, query_type, or other debug fields to the response metadata — ResponseBuilder handles metadata.
- Very specific: line 252
Raw Pydantic dumps: Don't return model.model_dump() or model.dict() directly.
- Distinctive: line 253
Pass-through API descriptions: Don't copy-paste the OpenAPI summary into the tool description.
- Very specific: line 260
All tools return JSON via ResponseBuilder.build_response():
- Distinctive: line 283
Never return raw API responses or unstructured strings.
“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.
Files
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) orfull(specialty/coach, opt-in viaINTERVALS_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 resultTrust 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")— theawaitis required.- Wrap in
tryfor bothICUAPIError(HTTP-level) andException(unexpected). - Validate enum-style parameters at the boundary with
validation_errorresponses 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 — seetools/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-releaseConfirms 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— theassert len(tools) == Nassertion 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
Annotatedparams): aim for ≤200 tokens. Top-end tools with many parameters can go higher; review them especially carefully. - Per-
Annotatedparameter: 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. Seeintervals-icu://workout-syntaxas 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
Annotateddescriptions 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):
- 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."
- 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.
- 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) vsicu_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) vsicu_get_wellness_for_date(ONE specific date)icu_get_*_curves(best-effort across durations) vsicu_get_*_histogram(time-in-zone distribution per activity)icu_*_message(singular = write) vsicu_*_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 —ResponseBuilderhandles metadata; if you have a meaningful per-tool addition (count,message, etc.), pass it via themetadata=param. (Issue #25 is removing the auto-debug fields entirely.) - Raw Pydantic dumps. Don't return
model.model_dump()ormodel.dict()directly. Use a_to_dicthelper 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.
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.

