This server connects AI agents to your Iridium fitness data, letting you query workouts, nutrition, body metrics, and training insights — and log food and hydration directly to your Iridium diary.
Query workouts: recent history, full workout details, exercise progress, personal records, training volume, training summary, and weekly schedule
Query nutrition: daily nutrition summaries, individual food entries, nutrition goals, and saved 'My Foods' items
Query body & profile: body measurements, user profile, hydration intake, and AI trainer analysis
Log food: add food entries with macros/micros, meal type, date, and servings; entries appear in the iOS app after sync
Edit chat-logged food: update or correct food entries previously logged via chat (not app-logged entries)
Log hydration: record water or fluid volume in oz or mL, feeding the hydration ring
Edit chat-logged hydration: correct previously logged hydration entries
Coach effectively: combine goals, today's food entries, and body measurements to give personalized nutrition and training recommendations
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Iridium MCP Server How has my bench press progressed over the last 3 months?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that connects AI agents like Claude and ChatGPT to your Iridium fitness data. Query your workouts, nutrition, body measurements, and training volume — and log food entries directly into your Iridium diary while chatting — from Claude Code, Claude Desktop, ChatGPT, or any MCP-compatible client.
Node.js 18+
Iridium app with AI Data Sync enabled (Settings > AI Data Sync)
Related MCP server: Intervals.icu MCP Server
Open the Iridium app on your iPhone
Go to Settings > AI Data Sync
Toggle Enable AI Data Sync on
Copy your Sync ID and Sync Key
npm install -g iridium-mcp-serverOr clone and build from source:
git clone https://github.com/iridium-fitness/iridium-mcp-server.git
cd iridium-mcp-server
npm install
npm run buildAdd the following to your Claude Code MCP settings (~/.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"
}
}
}
}The user's timezone is used in two places:
Read tools like get_nutrition_log use it to pick day boundaries — otherwise food logged late at night can spill into the next day's results.
Write tools like log_food_entry use it to anchor relative dates: "yesterday", "today T14:00", or "2026-04-29" are interpreted in the user's local timezone, not UTC. Without this, an MDT user logging "yesterday" would land their food two days earlier in the iOS app (because UTC midnight is the previous evening locally).
By default the server auto-detects the timezone of the machine it runs on. The Iridium iOS app does not push the user's timezone to the server. If the MCP server runs somewhere other than the user's own machine — a cloud-hosted agent, a VM, a server with a different system TZ — set IRIDIUM_USER_TZ to the user's IANA timezone:
{
"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"
}
}
}
}Leave it unset if the MCP server and the user are in the same timezone (the typical Claude-Desktop-on-your-laptop setup).
If you installed from source, use the absolute path instead:
{
"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"
}
}
}
}Tool | Description |
| Get recent workout history with optional date range and category filtering |
| Get full details of a specific workout (exercises, sets, weights, reps, RPE) |
| Get daily nutrition summaries (totals + goals + day notes) over a date range — use for trends and goal tracking |
| Get full individual food entries (name + every nutrient) for a day or date range up to 90 days — use when the question is about what was actually eaten |
| Get the user's current nutrition intent — goal type (lose / maintain / gain), target weekly rate, and daily calorie / protein / carb / fat targets. Use when coaching or giving recommendations that depend on whether they are cutting, bulking, or maintaining |
| Get performance history and 1RM trends for a specific exercise |
| Get PRs across all exercises or one exercise — best 1RM, heaviest weight, most reps, and when each was set |
| Get body measurement history (weight, body fat, etc.) |
| Get user profile including training goals, methodology, and experience level |
| Get aggregate training statistics (total workouts, streaks, patterns) |
| Get volume adaptation records per muscle group with fatigue and recovery data |
| Get weekly AI trainer analysis logs with recommendations and insights |
| Get the planned weekly training schedule |
| Get water intake — individual hydration entries plus per-day totals against the user's hydration goal. Defaults to today |
| List the user's saved reusable foods ("My Foods") — their homemade shakes, go-to bars, custom meals. Call this first when the user refers to a food by name as if it were already known |
Tool | Description |
| Log a single food entry (name + macros) to the user's Iridium food diary |
| Update a food entry previously logged via |
| Log water into the hydration tracker. Accepts fluid ounces or millilitres |
| Correct a hydration entry previously logged via |
Water is a separate record from food, exactly as it is in the app. log_hydration writes to the hydration tracker — the ring the user actually looks at. The water field that used to exist on log_food_entry has been removed, because a food entry's water value is the water content of that food and never reaches the tracker: water logged there looked saved but was invisible where the user checks.
Pass whichever unit the user speaks in — amountOz or amountML — and the server stores both (16 oz is recorded as 473 mL and reads back as 16 oz).
For a drink that is both food and fluid — a protein shake, juice, milk — log the calories and macros with log_food_entry and the volume with log_hydration. Plain water needs only log_hydration.
log_food_entry notesWhen the agent calls this tool, the entry lands on Iridium's backend immediately and is pulled into the iOS app on its next sync — typically within seconds when the app is foregrounded, otherwise on the next foreground or 5-minute polling tick. Entries that come from MCP are tagged with a "Chat" badge in the food log so the user can tell at a glance which entries were logged by an external chatbot.
Required: name, calories, protein, carbs, fat (grams).
Note on notes: the backend appends "Added by another AI agent" to every entry logged through this tool (on its own line, after any notes you pass). If the agent reads the entry back later, that line will be there even though it did not send it.
Important — totals, not per-serving: calories and macros must be the totals for the amount actually consumed. If the user ate 2 servings of a 200-cal item, send calories: 400, not calories: 200 with numberOfServings: 2. Iridium stores the values as-is and does not multiply.
Optional: date, mealType (breakfast | lunch | dinner | snacks | preWorkout | postWorkout | other, defaults to snacks), numberOfServings, brand, notes, plus any micros the agent is confident about — 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. Omit values the agent does not know rather than guessing.
Date forms accepted by date (defaults to now):
Form | Stored as |
| noon local today |
| noon local yesterday |
| that wall time, local that day |
| noon local on that date |
| wall time, user's local TZ |
| passed through unchanged |
All bare and relative forms are anchored in the user's local timezone (see Timezone above) — agents do not need to know the user's timezone to log food correctly. Bare dates anchor to noon to avoid drift across DST transitions.
Limits: the endpoint accepts at most 10 writes/min and 200 writes/day per user; values beyond calories ≤ 50000, protein/carbs/fat ≤ 5000, numberOfServings ≤ 100, or strings beyond name ≤ 200/brand ≤ 100/notes ≤ 1000 chars are rejected with HTTP 400.
Weights and distances are converted server-side, from the unit system set in the Iridium app (Settings > Units). Responses that contain either carry a _units object describing what you are looking at — this server does not convert anything itself.
Two things worth knowing when reading workout data:
Weight fields are backward compatible. weight remains the legacy total-load field. Newer reviewed base-equipment rows also include recorded_weight (what the user originally entered), total_weight (canonical total resistance), base_weight, added_weight, and review_status. Prefer total_weight for PR, progression, and volume math when it is present. A row with review_status: "unclassified" or "review_required" is intentionally ambiguous: its total/base/added values are null and it must not be compared or aggregated. Older rows without these additive fields remain valid and use weight as total load.
Two-dumbbell and dual-stack values remain explicit. These sets carry per_implement_weight and per_implement_label ("per dumbbell" / "per stack") — quote those when describing what the user actually held while using canonical total load for volume math.
Distances are per-set. Each set records its own distance_unit (m, km, mi, ft, yd) and distance is already expressed in it.
Body measurements carry a per-measurement unit. Mass types (weight, muscle mass, visceral fat mass) are converted to lbs or kg; body fat is a percentage; circumference measurements have a null unit because the app stores exactly the number the user typed without recording whether it was cm or inches.
Once configured, you can ask Claude or ChatGPT things like:
Querying:
"Show me my workouts from last week"
"How has my bench press progressed over the last 3 months?"
"What did I eat yesterday?" / "Everything I logged the past 7 days" / "What's my Tuesday dinner this week?"
"Am I hitting my protein goals?" / "How did my calories trend this month?"
"Where was most of my sugar coming from last week?"
"What does my training volume look like for chest?"
"What's my weekly training schedule?"
Coaching loops: An agent checking in on the user throughout the day can build a live picture with three calls:
get_nutrition_goals — what the user is targeting (cut / bulk / maintain + daily macro numbers)
get_food_entries(date: today) — what has already been consumed
get_body_measurements (as needed) — recent weight trend
Then coach from there: "you have ~40 g of protein left and a calorie headroom of ~600, which fits a normal dinner given your slow-cut target of -1 lb/week."
Logging food:
"Log a cheeseburger for lunch"
"Add a Snickers bar to my snacks"
"I just ate two scrambled eggs and a slice of toast — log that"
"Log my blueberry shake" — the chatbot calls list_my_foods first, finds your saved MyFood, and reuses its macros
"Log another Nuun" — same path: recognized by name from your saved foods
Editing after the fact:
"Wait, that was 2 cheeseburgers, not 1" — chatbot calls update_food_entry with the id from the prior log
"Actually make that a snack, not lunch"
"Drop the cheese on that burger"
Edits only work on entries logged via chat. Entries you added directly in the Iridium app can only be edited in the app.
The chatbot fills in macros from its own knowledge (or from your list_my_foods lookups), calls the relevant tool, and the change shows up in your Iridium food log on the next sync (within seconds when the app is open).
Make sure both environment variables are set in your MCP server configuration. You can find these values in the Iridium app under Settings > AI Data Sync.
Your Sync Key may have been regenerated. Open Iridium, go to Settings > AI Data Sync, and copy the current Sync Key. Update your MCP configuration with the new key.
The data endpoint may not be available yet. Make sure you have synced your data at least once by opening Iridium and tapping Sync Now in Settings > AI Data Sync.
If you see a warning that data was synced a long time ago, open the Iridium app and tap Sync Now to push the latest data. The server will show staleness warnings when data is older than 24 hours.
Make sure the configuration JSON is valid
Restart Claude Code after making configuration changes
Check that Node.js 18+ is installed: node --version
# Install dependencies
npm install
# Build
npm run build
# Watch mode (rebuild on changes)
npm run dev
# Run the test suite (builds first, then runs against build/)
npm test
# Run directly
IRIDIUM_SYNC_ID=xxx IRIDIUM_SYNC_KEY=yyy npm startTests cover the timezone/date helpers (src/utils/dates.ts) and the idempotency
serializer (src/utils/stable-json.ts) — the two places where a subtle bug
silently lands a user's food on the wrong day or silently discards a correction.
Requires Node 22.18+ or 24+ for native TypeScript type stripping.
tsc does not clean its output, so deleting a source file leaves its compiled
artifact behind in build/ — and the files field globs all of build/, so
that dead code would ship. After removing any source file, delete the matching
build/** output, then run npm pack --dry-run to confirm the tarball contains
what you expect before publishing.
MIT
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.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Log workouts and meals by telling your AI. 873 exercises, muscle diagrams, food lookup.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Agent-first strength-training platform across iOS, Web & MCP: read & write workouts, PRs & plans.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RosTeHeA/iridium-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
