一个 MCP (Model Context Protocol) 服务器，用于将 Claude 和 ChatGPT 等 AI 智能体连接到您的 Iridium 健身数据。您可以从 Claude Code、Claude Desktop、ChatGPT 或任何兼容 MCP 的客户端查询您的锻炼、营养、身体测量和训练量，并在聊天时直接将食物条目记录到您的 Iridium 日记中。
Node.js 18+
Iridium 应用程序，并启用了 AI 数据同步（设置 > AI 数据同步）
Related MCP server: Intervals.icu MCP Server
在您的 iPhone 上打开 Iridium 应用程序
前往 设置 > AI 数据同步
开启 启用 AI 数据同步
复制您的 同步 ID (Sync ID) 和 同步密钥 (Sync Key)
npm install -g iridium-mcp-server或者从源代码克隆并构建：
git clone https://github.com/iridium-fitness/iridium-mcp-server.git
cd iridium-mcp-server
npm install
npm run build将以下内容添加到您的 Claude Code MCP 设置 (~/.claude/claude_desktop_config.json) 中：
{
"mcpServers": {
"iridium": {
"command": "npx",
"args": ["iridium-mcp-server"],
"env": {
"IRIDIUM_SYNC_ID": "your-sync-id-here",
"IRIDIUM_SYNC_KEY": "your-sync-key-here"
}
}
}
}用户的时区在以下两个地方使用：
读取工具（如 get_nutrition_log）使用它来确定日期边界——否则深夜记录的食物可能会溢出到第二天的结果中。
写入工具（如 log_food_entry）使用它来锚定相对日期："yesterday"（昨天）、"today T14:00"（今天 14:00）或 "2026-04-29" 都是在用户的本地时区而非 UTC 中解释的。如果没有此设置，处于 MDT 时区的用户记录 "yesterday" 时，其食物在 iOS 应用程序中会落入两天前（因为 UTC 午夜在本地是前一天晚上）。
默认情况下，服务器会自动检测运行它的机器的时区。Iridium iOS 应用程序不会将用户的时区推送到服务器。 如果 MCP 服务器运行在用户自己的机器之外（例如云托管智能体、虚拟机、具有不同系统时区的服务器），请将 IRIDIUM_USER_TZ 设置为用户的 IANA 时区：
{
"mcpServers": {
"iridium": {
"command": "npx",
"args": ["iridium-mcp-server"],
"env": {
"IRIDIUM_SYNC_ID": "your-sync-id-here",
"IRIDIUM_SYNC_KEY": "your-sync-key-here",
"IRIDIUM_USER_TZ": "America/Denver"
}
}
}
}如果 MCP 服务器和用户处于同一时区（典型的 Claude-Desktop 在笔记本电脑上运行的设置），请将其留空。
如果您是从源代码安装的，请使用绝对路径：
{
"mcpServers": {
"iridium": {
"command": "node",
"args": ["/path/to/iridium-mcp-server/build/index.js"],
"env": {
"IRIDIUM_SYNC_ID": "your-sync-id-here",
"IRIDIUM_SYNC_KEY": "your-sync-key-here"
}
}
}
}工具 | 描述 |
| 获取最近的锻炼历史，支持可选的日期范围和类别过滤 |
| 获取特定锻炼的完整详细信息（练习、组数、重量、次数、RPE） |
| 获取日期范围内的每日营养摘要（总量 + 目标 + 日记备注）——用于趋势和目标跟踪 |
| 获取一天或长达 90 天日期范围内的完整个人食物条目（名称 + 每种营养素）——用于查询实际食用的内容 |
| 获取用户的当前营养意图——目标类型（减脂/维持/增肌）、目标每周速率以及每日卡路里/蛋白质/碳水化合物/脂肪目标。在进行教练指导或提供取决于用户处于减脂、增肌还是维持阶段的建议时使用 |
| 按名称或肌肉群搜索练习数据库 |
| 获取特定练习的性能历史和 1RM 趋势 |
| 获取身体测量历史（体重、体脂等） |
| 获取用户个人资料，包括训练目标、方法和经验水平 |
| 获取汇总的训练统计数据（总锻炼次数、连续记录、模式） |
| 获取每个肌肉群的容量适应记录，包含疲劳和恢复数据 |
| 获取每周 AI 教练分析日志，包含建议和见解 |
| 获取计划的每周训练时间表 |
| 获取带有练习配置的已保存锻炼模板 |
| 列出用户保存的可重复使用食物（“我的食物”）——自制奶昔、常备能量棒、自定义餐点。当用户提到一个食物名称，仿佛它是已知食物时，请先调用此工具 |
工具 | 描述 |
| 将单个食物条目（名称 + 宏量营养素）记录到用户的 Iridium 食物日记中 |
| 更新之前通过 |
log_food_entry 注意事项当智能体调用此工具时，条目会立即进入 Iridium 的后端，并在下一次同步时被拉取到 iOS 应用程序中——通常在应用程序处于前台时几秒钟内完成，否则在下一次前台启动或 5 分钟轮询时完成。来自 MCP 的条目在食物日志中会带有“Chat”标签，以便用户一眼就能看出哪些条目是由外部聊天机器人记录的。
必填项： name（名称）、calories（卡路里）、protein（蛋白质）、carbs（碳水化合物）、fat（脂肪，单位为克）。
重要提示 — 总量，而非单份： 卡路里和宏量营养素必须是实际消耗量的总量。如果用户吃了 2 份 200 卡路里的食物，请发送 calories: 400，而不是 calories: 200 且 numberOfServings: 2。Iridium 按原样存储值，不会进行乘法计算。
选填项： date（日期）、mealType（餐次类型：breakfast | lunch | dinner | snacks | preWorkout | postWorkout | other，默认为 snacks）、numberOfServings（份数）、brand（品牌）、notes（备注），以及智能体确定的任何微量营养素——fiber（纤维）、sugar（糖）、sodium（钠）、cholesterol（胆固醇）、saturatedFat（饱和脂肪）、transFat（反式脂肪）、monounsaturatedFat（单不饱和脂肪）、polyunsaturatedFat（多不饱和脂肪）、potassium（钾）、calcium（钙）、iron（铁）、magnesium（镁）、zinc（锌）、vitaminA、vitaminB6、vitaminB12、vitaminC、vitaminD、vitaminE、vitaminK、folate（叶酸）、niacin（烟酸）、riboflavin（核黄素）、thiamin（硫胺素）、caffeine（咖啡因）、water（水）。对于智能体不确定的值，请省略而不是猜测。
date 接受的日期格式（默认为当前时间）：
格式 | 存储为 |
| 当地今天中午 |
| 当地昨天中午 |
| 当地当天的该时间 |
| 该日期当地中午 |
| 用户当地时区的该时间 |
| 原样传递 |
所有裸日期和相对日期格式都锚定在用户的本地时区（参见上文 时区）——智能体无需知道用户的时区即可正确记录食物。裸日期锚定在中午，以避免跨越夏令时转换时的偏移。
限制： 每个用户每分钟最多接受 10 次写入，每天最多 200 次写入；超出 calories ≤ 50000、protein/carbs/fat ≤ 5000、numberOfServings ≤ 100 或字符串超出 name ≤ 200/brand ≤ 100/notes ≤ 1000 字符的值将被 HTTP 400 拒绝。
配置完成后，您可以询问 Claude 或 ChatGPT 如下问题：
查询：
“显示我上周的锻炼记录”
“过去 3 个月我的卧推进度如何？”
“我昨天吃了什么？” / “我过去 7 天记录的所有内容” / “我这周周二的晚餐是什么？”
“我达到蛋白质目标了吗？” / “我这个月的卡路里趋势如何？”
“上周我摄入的大部分糖分来自哪里？”
“我的胸部训练量看起来如何？”
“我的每周训练计划是什么？”
教练循环： 智能体全天候关注用户，可以通过三次调用构建实时图景：
get_nutrition_goals — 用户设定的目标（减脂/增肌/维持 + 每日宏量营养素数值）
get_food_entries(date: today) — 已经消耗的内容
get_body_measurements（按需） — 最近的体重趋势
然后进行指导：“你还剩下约 40 克蛋白质和约 600 卡路里的余量，考虑到你每周减重 1 磅的缓慢减脂目标，这符合一顿正常的晚餐。”
记录食物：
“午餐记录一个芝士汉堡”
“在我的零食中添加一个士力架”
“我刚吃了两个炒鸡蛋和一片吐司——记录一下”
“记录我的蓝莓奶昔” — 聊天机器人先调用 list_my_foods，找到您保存的 MyFood，并复用其宏量营养素
“再记录一个 Nuun” — 同样的路径：通过您保存的食物名称识别
事后编辑：
“等等，那是 2 个芝士汉堡，不是 1 个” — 聊天机器人使用之前记录的 ID 调用 update_food_entry
“实际上把它改成零食，而不是午餐”
“把那个汉堡上的奶酪去掉”
编辑仅适用于通过聊天记录的条目。您直接在 Iridium 应用程序中添加的条目只能在应用程序中编辑。
聊天机器人从其自身知识（或从您的 list_my_foods 查询）中填充宏量营养素，调用相关工具，更改会在下一次同步时（应用程序打开时几秒钟内）显示在您的 Iridium 食物日志中。
确保这两个环境变量都在您的 MCP 服务器配置中设置。您可以在 Iridium 应用程序的“设置 > AI 数据同步”下找到这些值。
您的同步密钥可能已重新生成。打开 Iridium，前往“设置 > AI 数据同步”，并复制当前的同步密钥。使用新密钥更新您的 MCP 配置。
数据端点可能尚未可用。请确保您至少通过打开 Iridium 并点击“设置 > AI 数据同步”中的“立即同步”来同步过一次数据。
如果您看到数据同步时间过久的警告，请打开 Iridium 应用程序并点击“立即同步”以推送最新数据。当数据超过 24 小时未更新时，服务器会显示过时警告。
确保配置 JSON 有效
在进行配置更改后重启 Claude Code
检查是否安装了 Node.js 18+：node --version
# Install dependencies
npm install
# Build
npm run build
# Watch mode (rebuild on changes)
npm run dev
# Run directly
IRIDIUM_SYNC_ID=xxx IRIDIUM_SYNC_KEY=yyy npm startMIT
Get body measurement history including weight, body fat percentage, and other measurements over time. Dates accept 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601; bare dates are whole days in the user's local timezone. Each measurement carries its own unit — mass types are converted to the user's preference, while circumference measurements have a null unit because the app records the number without a unit.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, inclusive: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| from | No | Start date: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| type | No | Measurement type filter (e.g. 'weight', 'body_fat') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since annotations are absent, the description carries the burden. It discloses date parsing behavior, timezone handling, and unit semantics (mass conversion, null for circumference). It does not mention auth, rate limits, or overall read-only nature, but the verb 'get' implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first covers purpose with examples, the second adds critical data format details. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description explains expected fields (weight, body fat, etc.) and unit behavior. It also clarifies date handling. Missing details on sorting or pagination, but sufficient for a history retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds value by explaining date formats and unit behavior in returned data, but does not provide additional parameter-level context beyond what the schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves body measurement history with examples (weight, body fat percentage). The tool name and description align, and it is distinct from sibling tools which focus on other domains like workouts or nutrition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching historical body measurements but does not provide explicit guidance on when to use this tool versus alternatives like get_workout_history or get_nutrition_log. No when-not or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get performance history and 1RM trends for a specific exercise. Shows recent sets, weight progression, and estimated one-rep max over time.
| Name | Required | Description | Default |
|---|---|---|---|
| exercise_id | Yes | The exercise ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It indicates a read-only operation (no side effects mentioned) and outlines returns: recent sets, weight progression, estimated 1RM. However, it does not disclose edge cases like empty history, time range limitations, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-loaded with the verb and resource ('Get performance history and 1RM trends'). No filler words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and no annotations, the description adequately explains the tool's output (recent sets, weight progression, estimated 1RM). It could mention that progress data must exist or that it covers all time, but overall it is largely sufficient for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'The exercise ID'. The description adds context by stating 'for a specific exercise' but does not provide format constraints or usage examples. Baseline 3 applies since schema already defines the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'performance history and 1RM trends for a specific exercise', using domain-specific terms like '1RM' and 'weight progression'. It effectively distinguishes from siblings which cover trainers, weekly schedule, workouts, nutrition, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when or when not to use this tool, nor alternatives among siblings. The description implies usage for querying progress per exercise but lacks prerequisites like 'requires logged workout data' or 'best used for strength exercises'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full individual food entries with name, macros, and all nutrients — plus hydration entries and a hydrationByDay rollup with consumed water and saved daily goals when available — for a single day or a date range (up to 90 days). Use this when the user asks about WHAT they ate ("what did I eat yesterday?", "show me everything I logged this week", "what was my dinner Tuesday?") or when you need entry-level detail for analysis (meal patterns, top sources of a macro, identifying repeat items, etc.). For daily totals / goal tracking / trends, use get_nutrition_log instead. Pass EITHER date (single day) OR from + to (range). Date parameters accept 'today', 'yesterday', 'YYYY-MM-DD', or full ISO timestamps; bare dates are interpreted in the user's LOCAL timezone so late-night meals correctly land on the same day the user went to bed. Ranges are inclusive on both ends and capped at 90 days; results are capped at 1000 entries with a truncated flag if that cap hits.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Range end (inclusive): 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601. Requires `from`. | |
| date | No | Single date: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601. Use this OR from+to. | |
| from | No | Range start: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601. Requires `to`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that results include food entries, hydration entries, and a hydrationByDay rollup. It details date format support ('today', 'yesterday', YYYY-MM-DD, ISO timestamps) and local timezone interpretation. Constraints are explicit: ranges up to 90 days, results capped at 1000 entries with a truncated flag. There is no mention of authentication or rate limits, but for a read-only tool this is generally sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of about 150 words. It front-loads the main function and then provides usage guidance and constraints. While every sentence adds value, it is somewhat verbose and could be more tightly organized. A bulleted breakdown might improve scannability, but it is not excessively long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no output schema, no annotations), the description covers the returned data, constraints, and alternative tool. It lacks explicit mention of output structure details but does describe the rollup. The tool's behavior is well-specified for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already describes each parameter. The description adds value by clarifying the exclusive use of date vs. from+to, explaining that ranges are inclusive and capped at 90 days, and detailing date format nuances including timezone handling. This context goes beyond what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full individual food entries with macros, nutrients, hydration data, and a rollup. It provides specific use cases ('what did I eat yesterday?') and explicitly distinguishes from get_nutrition_log for daily totals. This differentiates it from siblings effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: use this for detailed entry-level queries about 'what they ate' and for analysis, while referencing get_nutrition_log as the alternative for daily totals. It also explains parameter combinations (EITHER date OR from+to). However, it doesn't list every scenario where the tool should be avoided, but the provided context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the user's water intake — individual hydration entries plus per-day totals against their saved hydration goal. Use this for 'how much water have I had today?', 'am I hitting my hydration goal?', or any question about fluid intake. Each day in byDay carries consumedML/consumedOz, goalML/goalOz, remainingML, and progress (0-1) when a goal exists for that day. Compare consumedML against goalML, and report in whichever unit the user speaks in. Note this covers hydration only — it does NOT include the water content of foods, which the Iridium app also excludes from the hydration ring. Dates accept 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601; bare dates are whole days in the user's local timezone. Pass EITHER date for a single day OR from + to for a range.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Range end, inclusive: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| date | No | Single day: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| from | No | Range start: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It discloses the output structure (byDay with consumedML, goalML, etc.) and the fact that it covers hydration only, not food water content. It is transparent about the tool's behavior without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a single paragraph of about four sentences. It is front-loaded with the main purpose and efficiently adds necessary details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema and annotations, the description sufficiently covers input parameters and output structure. It explains the key fields and the scope of data, though it could mention error handling or empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining the exclusive relationship between 'date' and the 'from'/'to' pair, and by expanding on valid date formats. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the user's water intake with individual entries and per-day totals against a saved goal. The verb 'Get' and resource 'hydration' are specific, and it distinguishes itself from sibling tools like log_hydration and get_nutrition_log by focusing on hydration data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios (e.g., 'how much water have I had today?') and clarifies what the tool does not cover (food water content). It explains date formats and parameter combinations, but does not explicitly compare to sibling tools for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the user's current nutrition intent — what they are trying to do with food right now. Returns: goalType (lose | maintain | gain), weeklyWeightChangeGoal (e.g. -1 for losing 1 per week; negative means loss, positive means gain) with weeklyWeightChangeUnit (lbs or kg), daily targets calorieGoal / proteinGoal / carbGoal / fatGoal (grams for macros), hydration fields when available (hydrationGoalML, hydrationGoalOz, and hydration for today's consumed/goal/progress), and mode context (calorieGoalMode, macroDistributionMode, macroPriority, macroPresetSplit). IMPORTANT — calorieGoal is the LIVE EFFECTIVE target for today, matching what the Iridium app shows on the Nutrition tab. In automatic + HealthKit-active mode this includes today's active calories burned, so it changes throughout the day as the user moves. The static base (BMR ± deficit, before activity) is exposed separately as calorieGoalBase. When you compare consumed vs target, ALWAYS use calorieGoal (not calorieGoalBase). The optional todaySnapshot field breaks down where the number came from: restingEnergyBurned (BMR), activeCalories, goalMode, hydration, and lastUpdated (the iOS sync timestamp — be aware the active-calories and hydration numbers may be a few minutes stale). Use this when coaching the user ("am I on track?", "how much room for dinner?", "is this deficit aggressive or conservative?"), or whenever your recommendation depends on whether they are cutting, bulking, or maintaining. Combine with get_food_entries(date: today) for what has already been consumed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it explains the difference between calorieGoal and calorieGoalBase, mentions that values may be stale due to sync timestamps, and describes how the goal changes throughout the day in automatic+HealthKit mode. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-structured with bullet points and clear sections. It front-loads the purpose and uses natural breaks. It could be slightly more concise, but the detail is justified given the complexity of the return object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains all return fields and their meanings in detail, including optional fields and usage notes. It provides sufficient context for an agent to correctly interpret the data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. Baseline is 3. The description adds no parameter info because none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the user's current nutrition intent, including goal type, weight change, and daily targets. It distinguishes from sibling tools like get_nutrition_log by focusing on the current 'intent' and explicitly suggests combining with get_food_entries for consumption data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (coaching the user, assessing deficit/conservativeness) and when to combine with get_food_entries. It also explains nuances like the dynamic nature of calorieGoal in HealthKit mode, ensuring the agent uses the correct field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get DAILY NUTRITION SUMMARIES over a date range — one row per day with the user's actual consumed totals (live, computed from the food log on every call), their goals and targets for that day, hydration intake/goal when available, and any day notes (e.g. 'I didn't log everything today', 'was sick'). Use this for daily check-ins, trends, goal checking, and weekly/monthly review. For individual food-level detail (name + all nutrients per entry), use get_food_entries instead. Dates accept 'today', 'yesterday', 'YYYY-MM-DD', or full ISO timestamps; bare dates are interpreted in the user's local timezone. IMPORTANT — each summary row includes: (a) consumed — an object with the day's actual totals (calories, protein, carbs, fat, fiber, sugar, sodium, cholesterol, saturatedFat, transFat); always live, includes food logged via this tool earlier even before the iOS app has synced, (b) calorieGoal — the static BASE: BMR ± weight-goal deficit, BEFORE activity, (c) effectiveCalorieGoal — the real daily target that includes activeCalories burned and the daily-minimum floor; matches what the Iridium app actually displays. (d) hydration — an object with consumedML, goalML, remainingML, progress, and individual hydration entries when hydration data exists. ALWAYS compare consumed.calories vs effectiveCalorieGoal, not vs calorieGoal. For water/hydration, compare hydration.consumedML vs hydration.goalML when goalML is present. Some rows may have consumed populated but no goal fields — that's a day where food was logged before any goal-bearing data existed for that day; fall back to the top-level goals for targets. The same applies to the goals object at the top level for today.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date (YYYY-MM-DD, 'today', 'yesterday', or ISO 8601) | |
| date | No | DEPRECATED shortcut — returns individual entries for this date. Prefer `get_food_entries` for entry-level detail. | |
| from | No | Start date (YYYY-MM-DD, 'today', 'yesterday', or ISO 8601) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description provides extensive behavioral details: consumed totals are live and computed on every call, includes food logged before iOS sync, explains goal variants (calorieGoal vs effectiveCalorieGoal), and handles missing data gracefully with fallback instructions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long but well-structured with bullet points and clear sections. Front-loads purpose and usage, then details. Every sentence adds value, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 params, no output schema, and no annotations, the description is exceptionally complete. It details the return structure (consumed object, goal fields, hydration), edge cases (missing goals), and interpretation instructions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value: explains accepted date formats ('today', 'yesterday', YYYY-MM-DD, ISO 8601), local timezone interpretation, and deprecation of the 'date' parameter with alternative suggestion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns daily nutrition summaries over a date range with one row per day, including consumed totals, goals, hydration, and notes. Explicitly distinguishes from sibling tool get_food_entries for individual food-level detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies use cases (daily check-ins, trends, goal checking, weekly/monthly review) and explicitly directs to get_food_entries for food-level detail. Provides guidance on comparing effectiveCalorieGoal vs calorieGoal and hydration fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get personal records (PRs) across all exercises or for a specific exercise. Shows best 1RM, heaviest weight, most reps, and when each PR was set.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of exercises to return PRs for (default 20) | |
| exercise_name | No | Filter by exercise name (e.g. 'bench press') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the returned fields (1RM, heaviest weight, most reps, date) and the filtering behavior, but does not mention authentication requirements, rate limits, or handling of empty results. This is adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and contains no superfluous information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two optional parameters and no output schema, the description adequately explains what data is returned and the two modes of use. It does not specify ordering or behavior when limit is exceeded, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds context by mentioning 'across all exercises or for a specific exercise', reinforcing the exercise_name parameter's purpose. No additional meaning is needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves personal records (PRs) for all or specific exercises, and lists the specific metrics shown (1RM, heaviest weight, most reps, date). This distinguishes it from sibling tools like get_exercise_progress or get_training_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving PR data and mentions filtering by exercise, but does not explicitly state when to use this tool versus alternatives (e.g., get_exercise_progress), nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the user's profile including demographics, training goals, methodology, experience level, and app settings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly states the tool retrieves a profile and lists what it includes, which is sufficiently transparent for a read-only operation with no parameters. No side effects or auth requirements are mentioned, but not critical here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is compact and front-loaded with the action and resource, followed by a concise list of contents. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and a simple retrieval purpose, the description fully covers what the tool does. It provides sufficient context for an AI agent to understand its function without additional details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so description does not need to add param info. Schema coverage is 100% trivially, meeting the baseline of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Get' and the resource 'the user's profile', listing specific contents like demographics, training goals, etc. This clearly distinguishes it from sibling tools like get_workout_history or get_nutrition_log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving overall user profile, but does not explicitly compare to siblings or provide context on when to use this versus more specific tools like get_training_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get weekly AI trainer analysis logs containing training recommendations, progress assessments, and coaching insights.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of logs to return (default 10, max 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It does not mention authentication needs, pagination behavior, or what happens when no logs exist. The tool name implies read-only, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 14 words that conveys the essential purpose with no redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, no annotations, and the description does not explain the structure of return values (e.g., fields, types). For a tool returning analysis logs, this leaves a significant knowledge gap for the AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'limit', which is already fully described in the schema. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('weekly AI trainer analysis logs') and clearly distinguishes from sibling tools like get_weekly_schedule or get_workout_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor when not to use it. The description simply states what it does without contextual recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate training statistics including total workouts, exercise frequency, streaks, and workout patterns.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adequately states that the tool returns aggregate statistics (summaries) and hints at the types of data included. It does not disclose data freshness or caching, but for a simple read-only operation with no parameters, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that captures the tool's core function without any redundant or extraneous information. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description provides a reasonable overview of what the output contains (workouts, frequency, streaks, patterns). It could be slightly more detailed about the output structure, but it is sufficient for a simple aggregate tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters and schema description coverage is 100% (trivial). Per guidelines, baseline is 4. The description adds no extra parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get aggregate training statistics' and lists concrete examples (total workouts, exercise frequency, streaks, workout patterns), clearly distinguishing it from sibling tools like get_workout_history (individual workouts) or get_trainer_analysis (likely more analytical).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for aggregate summaries, but it does not explicitly state when to use this tool over alternatives like get_workout_history or get_exercise_progress. No exclusion or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get volume adaptation records showing how training volume has been adjusted for each muscle group over time, including fatigue levels and recovery decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, inclusive: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| from | No | Start date: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| muscle_group | No | Filter by muscle group |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It implies read-only behavior ('get') but does not explicitly state safety, authentication requirements, rate limits, or default ranges. The description adds some context (fatigue, recovery) but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveys the tool's purpose efficiently with no redundant information. Front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could clarify return format, pagination, or default behavior (e.g., date range). It mentions fatigue and recovery but does not specify the structure. Adequate but not fully complete for a 3-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description reinforces that the tool focuses on muscle groups over time, but does not add new parameter-level semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves volume adaptation records with fatigue levels and recovery decisions, which distinguishes it from sibling tools like get_training_summary or get_exercise_progress. However, no explicit differentiation from siblings is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not specify prerequisites, common use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the planned weekly training schedule showing which muscle groups or workout types are assigned to each day.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the basic purpose. It does not disclose behavioral traits such as read-only nature, authentication needs, or data recency. The description adds no value beyond purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that front-loads the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description is adequate but could be improved. It does not specify the time period (e.g., current week vs. any week) or whether it returns data for the authenticated user only.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, so the schema coverage is trivially 100%. According to the rubric, 0 parameters yields a baseline of 4. The description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a weekly training schedule with muscle group or workout type assignments per day. The verb 'Get' and resource 'weekly training schedule' are specific and distinguish it from siblings like get_workout_history or get_training_volume.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not indicate circumstances for use, exclusions, or mention of when to prefer other tools like get_workout_history for past data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a specific workout including all exercises, sets, weights, reps, RPE, and block structure.
| Name | Required | Description | Default |
|---|---|---|---|
| workout_id | Yes | The workout UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It accurately implies a read operation but does not mention any potential limitations, error conditions, or authorization requirements. It is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the key purpose, listing specific details it returns. No unnecessary words; each part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (single parameter, no output schema required), the description adequately covers the return content. It does not mention error handling or missing data cases, but for a basic retrieval tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no additional meaning beyond the input schema, which already describes workout_id as 'The workout UUID'. With 100% schema description coverage, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full details of a specific workout', listing specific included fields (exercises, sets, weights, reps, RPE, block structure). This distinguishes it from sibling tools like get_workout_history (which lists workouts) and get_exercise_progress (which focuses on progress over time).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. While the purpose is clear, the description does not mention when not to use it or suggest alternative tools for related tasks (e.g., listing workouts vs. getting details).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent workout history with optional filtering by date range or category. Returns workout summaries including date, exercises performed, duration, and completion status. Dates accept 'today', 'yesterday', 'YYYY-MM-DD', or a full ISO 8601 timestamp; bare dates are interpreted as whole days in the user's LOCAL timezone, so an early-morning session and a late-evening one on the same day both come back from a single-day query. To ask about one specific day, pass the SAME date as both from and to. IMPORTANT: a day often contains MORE THAN ONE workout — report every workout in the response, not just the first or the most recent.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, inclusive: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| from | No | Start date: 'today', 'yesterday', 'YYYY-MM-DD', or ISO 8601 | |
| limit | No | Number of workouts to return (default 20, max 100) | |
| offset | No | Pagination offset | |
| category | No | Filter by workout category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing date interpretation in local timezone, multiple workouts per day, and the instruction to report every workout. It lacks mention of authentication or rate limits, but the behavioral details provided are strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose sentence, output description, date behavior details, a usage tip, and an important warning. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, all documented, and no output schema. The description explains return fields (date, exercises, duration, completion status) and covers key behaviors. It is missing default sort order and error handling for invalid dates, but overall it is complete for a filtered list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining date formats in detail, giving a usage example for single-day queries, and clarifying timezone handling, which goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves recent workout history with optional filtering, using a specific verb (Get) and resource (workout history). It distinguishes from siblings like get_workout_detail by specifying it returns summaries, not details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (getting recent history with filters) and provides usage tips like how to query a single day and warning about multiple workouts per day. It does not explicitly state when not to use it, but the context of sibling tools implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's saved reusable foods ("My Foods" in Iridium) — things like their homemade shakes, favourite bars, go-to salads. Call this FIRST whenever the user refers to a food by name as if it were already known — for example: "log my blueberry shake," "another Nuun," "my usual lunch." If a match exists, reuse its macros and pass the MyFood's name verbatim to log_food_entry so the logged entry reads naturally. Scale macros by the actual servings consumed if it differs from the default (defaultServingSize / defaultServingUnit). If nothing matches, fall back to your own macro knowledge. You usually only need to call this once per conversation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It explains the tool lists personal foods, should be called early, and implies it returns macros and serving info. However, it does not mention pagination, rate limits, or assume a complete list, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a coherent paragraph with front-loaded purpose, then usage guidance. Each sentence adds value, though it could be slightly more terse. It is well-structured but not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the tool's purpose, usage context, and result handling (macros and serving scaling). It lacks explicit output format specifications but is complete for decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description need not add parameter details. Baseline 4 applies, and the description adds useful context about when to call the tool but no parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists the user's saved reusable foods ('My Foods in Iridium') and provides concrete examples (homemade shakes, bars, salads), making the purpose unmistakable and distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions to call this FIRST when the user refers to a known food by name, with examples like 'log my blueberry shake' and fallback guidance. Also details how to reuse macros and scale servings, leaving no ambiguity about when and how to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a single food entry (cheeseburger, snack, meal, etc.) into the user's Iridium food diary. Required: name + calories + protein + carbs + fat (grams). IMPORTANT: calories and macros MUST be the totals for the amount actually consumed, NOT per-serving values. If the user ate 2 servings of a 200-cal item, send calories: 400. Optional: any micros you are confident about (fiber, sugar, sodium, vitamins, etc.) — omit values you don't know rather than guessing. WATER: do NOT log drinking water here. This tool has no water field — use log_hydration, which is the only thing that feeds the hydration ring the user sees. For a drink that is both food and fluid (shake, juice, milk), log the calories/macros here AND the volume with log_hydration. The entry appears in the iOS app on the next sync (typically within minutes when the app is foregrounded). DATE/TIMEZONE: pass date in any of these forms — 'today', 'yesterday', 'YYYY-MM-DD', 'today T14:00', 'yesterday 14:30', 'YYYY-MM-DDTHH:MM:SS', or a full ISO 8601 timestamp with offset. All bare/relative forms are interpreted in the user's local timezone, so 'yesterday' lands on the user's yesterday — you do not need to know their timezone. DEDUPLICATION: calls with identical arguments within one hour are deduplicated (the same entry is returned, not a new one). If the user genuinely ate the same thing twice and wants two entries, set numberOfServings: 2 on a single call, OR include a differentiating value like a distinct notes line or a more specific date on the second call.
| Name | Required | Description | Default |
|---|---|---|---|
| fat | Yes | ||
| date | No | When the user ate. Accepts 'today', 'yesterday', 'YYYY-MM-DD', 'today T14:00', 'yesterday 14:30', 'YYYY-MM-DDTHH:MM:SS', or full ISO 8601 with timezone (e.g. '2026-04-29T14:00:00-06:00'). Bare dates anchor to noon local; relative keywords resolve in the user's timezone. Defaults to now. | |
| iron | No | mg | |
| name | Yes | ||
| zinc | No | mg | |
| brand | No | ||
| carbs | Yes | ||
| fiber | No | ||
| notes | No | ||
| sugar | No | ||
| folate | No | mcg | |
| niacin | No | mg | |
| sodium | No | mg | |
| calcium | No | mg | |
| protein | Yes | ||
| thiamin | No | mg | |
| caffeine | No | mg | |
| calories | Yes | ||
| mealType | No | Defaults to 'snacks' if omitted | |
| transFat | No | ||
| vitaminA | No | mcg RAE | |
| vitaminC | No | mg | |
| vitaminD | No | mcg | |
| vitaminE | No | mg | |
| vitaminK | No | mcg | |
| magnesium | No | mg | |
| potassium | No | mg | |
| vitaminB6 | No | mg | |
| riboflavin | No | mg | |
| vitaminB12 | No | mcg | |
| cholesterol | No | mg | |
| saturatedFat | No | ||
| numberOfServings | No | ||
| monounsaturatedFat | No | ||
| polyunsaturatedFat | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: mutation (logging), deduplication within one hour, sync timing to iOS app, and date/timezone interpretation. It also warns against logging water and instructs to omit uncertain micros.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (examples, warnings, date/timezone, deduplication). While a bit lengthy, every sentence adds value. Front-loads the core purpose and required fields effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (35 parameters, no output schema), the description is remarkably complete. It covers usage guidelines, deduplication, sync behavior, date handling, and explicit exclusions (water). No gaps remain for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema: it explains that required fields must be totals for consumed amount, not per-serving, and clarifies the date parameter with examples of accepted formats and timezone resolution. It also advises on optional micros and the numberOfServings parameter for deduplication, which the schema does not detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool logs a single food entry into the user's Iridium food diary, with examples like cheeseburger, snack, meal. It specifies required fields (name + calories + protein + carbs + fat) and distinguishes itself from the sibling tool log_hydration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use this tool vs log_hydration (e.g., do not log water here, use log_hydration instead). It also provides guidance on handling drinks that are both food and fluid, and explains deduplication behavior and how to log multiple servings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log water (or any hydrating drink volume) into the user's Iridium hydration tracker. USE THIS — not log_food_entry — whenever the user says they drank water, e.g. 'I had a glass of water', 'log 16 oz of water', 'just finished my water bottle'. The water field on a food entry is the water CONTENT of that food and does NOT count toward the hydration ring the user sees in the app; only this tool does. Pass EITHER amountOz OR amountML — give whichever unit the user used and the server stores both. Common volumes: a cup is 8 oz, a pint 16 oz, a standard bottle 16.9 oz (500 mL), a litre 33.8 oz. If the user drank something that is both food and fluid (a protein shake, juice, milk), log the calories and macros with log_food_entry AND the fluid volume with this tool — they are separate records and the app expects both. Plain water needs only this tool. DATE/TIMEZONE: date accepts 'today', 'yesterday', 'YYYY-MM-DD', 'today T14:00', 'yesterday 14:30', or a full ISO 8601 timestamp; bare and relative forms resolve in the user's local timezone. Defaults to now. DEDUPLICATION: identical calls within an hour are treated as the same entry. For a genuine second drink, pass a more specific date or a distinguishing note.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | When they drank it: 'today', 'yesterday', 'YYYY-MM-DD', 'yesterday 14:30', or ISO 8601. Defaults to now. | |
| note | No | Optional context, e.g. 'post-workout' or 'with lunch'. | |
| amountML | No | Volume in millilitres. Use this when the user speaks in mL or litres. | |
| amountOz | No | Volume in US fluid ounces. Use this when the user speaks in oz, cups, or bottles. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses behavioral traits: date parsing formats, deduplication (identical calls within an hour treated as same entry), mutual exclusivity of amountOz/amountML. Does not mention authentication or rate limits, but covers key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is long but well-organized with clear sections (first sentence, 'USE THIS', 'PASS EITHER', 'Common volumes', 'DATE/TIMEZONE', 'DEDUPLICATION'). Every sentence adds value and is front-loaded. Could be slightly more concise but structure is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and complexity (date parsing, dual units, deduplication), the description covers essentials: when to use, parameters with examples, date handling, dedup rules. Minor gap: no mention of return value, but overall comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The description adds value beyond schema: common volume conversions (cup=8 oz, etc.), requirement to pass EITHER amountOz OR amountML, date format details, and deduplication hints. Adds substantial context for parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool logs water or hydrating drink volume into the user's hydration tracker, distinguishes from log_food_entry by explaining that the 'water' field in food entries does not count toward the hydration ring. It provides specific usage examples like 'I had a glass of water' and 'log 16 oz of water'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'USE THIS — not log_food_entry' when the user mentions drinking water. Provides scenarios for when to use both tools (e.g., protein shake should log both food and fluid). Includes guidance on date/timezone parsing and deduplication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a food entry you previously logged via log_food_entry — e.g. if the user says "wait, that was 2 cheeseburgers, not 1" or "actually that had no cheese." Required: id (from the prior log_food_entry response). Only pass fields you actually want to change — omitted fields stay as they were. IMPORTANT: if you are changing calories or macros, they must still be the TOTAL for the amount actually consumed, not per-serving. This tool only works on entries that were logged via chat in the first place. If the entry was logged in the Iridium app itself, you will get a 404 — apologise and let the user edit it in the app.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The UUID returned by log_food_entry | |
| fat | No | ||
| date | No | Same forms as log_food_entry: 'today', 'yesterday', 'YYYY-MM-DD', 'yesterday 14:30', 'YYYY-MM-DDTHH:MM:SS', or full ISO 8601 with timezone. Bare/relative forms resolve in the user's local timezone. | |
| iron | No | mg | |
| name | No | ||
| zinc | No | mg | |
| brand | No | ||
| carbs | No | ||
| fiber | No | ||
| notes | No | ||
| sugar | No | ||
| folate | No | mcg | |
| niacin | No | mg | |
| sodium | No | mg | |
| calcium | No | mg | |
| protein | No | ||
| thiamin | No | mg | |
| caffeine | No | mg | |
| calories | No | ||
| mealType | No | ||
| transFat | No | ||
| vitaminA | No | mcg RAE | |
| vitaminC | No | mg | |
| vitaminD | No | mcg | |
| vitaminE | No | mg | |
| vitaminK | No | mcg | |
| magnesium | No | mg | |
| potassium | No | mg | |
| vitaminB6 | No | mg | |
| riboflavin | No | mg | |
| vitaminB12 | No | mcg | |
| cholesterol | No | mg | |
| saturatedFat | No | ||
| numberOfServings | No | ||
| monounsaturatedFat | No | ||
| polyunsaturatedFat | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors beyond simple mutation: only works on chat-logged entries, omitted fields remain unchanged, and calories/macros must be totals for consumed amount. With no annotations, description carries full burden and does so well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single well-structured paragraph with examples, warnings, and important notes. Slightly dense but every sentence adds value. Could benefit from bullet points for clarity but still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 36 parameters and no output schema, description covers all critical context: id requirement, field omission behavior, special rules for calories/macros, and the chat vs. app distinction. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage at 58% means many parameters have descriptions already. Description adds overarching semantics: only pass fields to change, total vs. per-serving rule. Given 36 parameters, this meta-information is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it updates a food entry logged via log_food_entry, with explicit examples ('wait, that was 2 cheeseburgers'). Distinguishes from sibling tools by referencing the source (chat vs. app) and the required id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance (after log_food_entry), example corrections, required id from prior response, and a clear error-handling instruction (apologise and direct to app on 404).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct a hydration entry you previously logged via log_hydration — e.g. "that was a 32 oz bottle, not 16". Required: id (from the prior log_hydration response). Only pass what you want to change. This only works on entries logged via chat; water added in the Iridium app itself returns a 404 and has to be edited there.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id returned by log_hydration | |
| date | No | Same date forms as log_hydration | |
| note | No | ||
| amountML | No | Corrected volume in millilitres | |
| amountOz | No | Corrected volume in US fluid ounces |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: it discloses the 404 error for Iridium app entries, implies it performs a partial update, and notes that the id is required. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences: action+example, required param, and constraint. No wasted words; front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description still covers error conditions (404) and valid entry scope. For a simple update tool, this is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% (4 of 5 params have descriptions). The description reiterates key points (id required, amount fields are corrected volumes) but adds no new meaning beyond the schema. Baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'correct' and resource 'hydration entry', and provides a concrete example ('that was a 32 oz bottle, not 16'). It distinguishes itself from log_hydration and get_hydration by specifying it updates existing entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the required id from prior log_hydration response, advice to only pass changed fields, and a critical constraint: only works on chat-logged entries, not those from the Iridium app (returns 404). This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.13.0get_body_measurementsget_exercise_progressget_food_entriesget_hydrationget_nutrition_goalsget_nutrition_logget_personal_recordsget_profileget_trainer_analysisget_training_summaryget_training_volumeget_weekly_scheduleget_workout_detailget_workout_historylist_my_foodslog_food_entrylog_hydrationupdate_food_entryupdate_hydration_entryScored across 19 tools
Most tools have clearly distinct purposes, with detailed descriptions that clarify overlaps (e.g., get_nutrition_log vs get_food_entries). A few pairs like get_workout_history/get_workout_detail and get_exercise_progress/get_personal_records could cause minor confusion, but descriptions resolve boundaries.
All tools follow a consistent verb_object pattern in snake_case (e.g., get_*, log_*, update_*, list_*). No mixing of conventions like camelCase or inconsistent verb styles.
19 tools cover the full domain of fitness tracking (training, nutrition, hydration, body measurements, profile) without feeling bloated or sparse. Each tool serves a clear purpose within the scope.
Covers nutrition and hydration entry well, but training tools are mostly read-only (no create/update workouts, no log training sessions). Body measurements are get-only. Notable gaps in data entry for training and measurements limit full lifecycle coverage.
Your strength-training data for any AI assistant: workouts, progress, muscle volume, routines.
Log workouts and meals by telling your AI. 873 exercises, muscle diagrams, food lookup.
Manage fitness coaching clients, workouts, programs, chats and funnels from your assistant.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
