Connect your AI assistant to Vitamin D Explorer — so it can answer, for your actual location and skin type, whether the sun can make vitamin D right now, how long you'd need, and which months of the year it's possible at all.
Generic advice says "get 15 minutes of sun". That answer is wrong most of the time: skin type I in London and skin type V in Madrid need completely different exposure, and above about 40° latitude there are months where synthesis is physically impossible no matter how long you stay out.
"I'm in Vilnius, skin type II. Can I make vitamin D today?"
"Which months of the year can I get vitamin D in London?"
"I was out 25 minutes at noon in Madrid, arms and legs bare — how much did I make?"
"When's golden hour in Lisbon on Friday?"
Related MCP server: WeatherAPI MCP Server
Most clients can connect to the hosted server directly, with no install at all — see getvitamind.app/connect for per-client steps. Use this package when your client only launches local commands.
{
"mcpServers": {
"vitamind": {
"command": "npx",
"args": ["-y", "vitamind-mcp"]
}
}
}That's the whole configuration. No API key, no account.
Six public tools, no account needed:
Tool | Answers |
| Find a city and its coordinates, in any of the app's six languages |
| Sunrise, sunset, solar noon, civil dawn/dusk, both golden hours, day length |
| The synthesis window for one day: minutes needed, best hour, UV peak |
| The whole year in one call: which months work, which don't |
| Whether right now is a good moment, from live UV and cloud data |
| What a session produced — IU made, and minutes until burning |
Four more read your saved profile, favourite cities and sun history if you sign in
(get_my_profile, get_my_cities, get_my_history, log_sun_session). Those need
OAuth, which this bridge does not implement — connect the account endpoint directly, or:
npx mcp-remote https://getvitamind.app/api/mcp-auth/mcpNot a lookup table. Every answer is computed from:
Solar geometry — NOAA declination and elevation formulas.
UV model — Madronich (2007) clear-sky UVI with van Heuklon ozone by latitude, longitude and season, plus an altitude correction (~8% per km — enough to change which months work for a city like Bogotá).
Vitamin D synthesis — Holick & Dowdy (2010), with MED by Fitzpatrick skin type (I-VI) and the Holick (1989) age factor. Sessions saturate: past roughly ⅓ MED you gain little and burn risk rises, and the tools say so.
Live weather — Open-Meteo UV index and cloud cover.
Threshold for any synthesis at all: UV index ≥ 3. Below that the answer is honestly "not today, consider supplementing" rather than a smaller number.
| Endpoint to bridge to. Default |
| Same, as an environment variable |
A stdio↔HTTP relay, and nothing more. It forwards JSON-RPC messages verbatim between your client and the hosted server, so new tools appear without a release here. All the vitamin D logic lives in the hosted server — deliberately, since a second copy of the model in this package would drift from the app that people actually use.
Estimates for healthy skin under clear-sky or forecast conditions. They ignore aerosols, ground reflectance, sunscreen and individual variation, and they are not a substitute for advice from a professional. Do not use them to plan an intentional burn.
App: getvitamind.app
Setup guide: getvitamind.app/connect
Main repository: JaviMaligno/vitamind
MIT
Estimate a sun session's outcome: 'I was (or will be) out N minutes — how much vitamin D did I make?' plus 'how long before I'd burn?' for the profile. Takes a start time (defaults to the day's best hour) and session minutes; returns estimated IU (with the physiological cap), average UV and clear-sky minutes-to-sunburn. Use for any 'how much did I get / can I get in X minutes' or 'how long without burning' question.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Age in years (synthesis declines with age); omit for adult baseline | |
| lat | Yes | Latitude in decimal degrees | |
| lon | Yes | Longitude in decimal degrees | |
| date | No | Date as YYYY-MM-DD; defaults to today | |
| minutes | Yes | Session length in minutes | |
| skinType | No | Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3 | |
| timezone | No | IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC | |
| startTime | No | Local HH:MM the session starts; defaults to the day's best hour | |
| elevationM | No | Ground elevation in metres (UV rises ~8%/km); default sea level | |
| exposedSkinFraction | No | Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and provides valuable behavioral details: it mentions the default start time ('defaults to the day's best hour'), the physiological cap on IU, and the specific outputs (IU, average UV, clear-sky minutes-to-sunburn). It does not claim to be read-only or destructive, but the description does not require additional disclosure beyond its actual function.
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 primary use case and example questions, then a concise summary of inputs and outputs. Every sentence earns its place without redundancy or unnecessary detail.
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 (10 parameters, multiple outputs), the description adequately connects inputs to outputs and explains the tool's role in the broader domain. It does not enumerate every parameter but the schema covers those details. The absence of an output schema is partially mitigated by listing the return values (IU, average UV, minutes-to-sunburn).
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 already provides 100% coverage with detailed descriptions for all 10 parameters, including defaults and meanings. The tool description adds context about the start time default and the output units, but does not significantly expand parameter semantics beyond what the schema offers. This matches the baseline for high schema coverage.
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 starts with a specific verb 'Estimate' and clearly identifies the resource as a 'sun session's outcome'. It distinguishes itself from siblings by focusing on per-session estimation of vitamin D production and sunburn time, with illustrative user questions. This makes the tool's purpose unmistakable.
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 states when to use the tool: 'Use for any how much did I get / can I get in X minutes or how long without burning question'. While it does not explicitly mention alternative tools, the clear usage context effectively differentiates it from siblings like get_vitamin_d_window or get_sun_forecast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether RIGHT NOW is a good moment for vitamin D synthesis at a location, using live Open-Meteo UV/cloud data when reachable (clear-sky model otherwise): current UV index, minutes needed now, and when today's window opens or closes.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Age in years (synthesis declines with age); omit for adult baseline | |
| lat | Yes | Latitude in decimal degrees | |
| lon | Yes | Longitude in decimal degrees | |
| skinType | No | Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3 | |
| targetIU | No | Vitamin D target per session in IU; default 1000 | |
| timezone | No | IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC | |
| elevationM | No | Ground elevation in metres (UV rises ~8%/km); default sea level | |
| exposedSkinFraction | No | Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals a key behavioral trait: it attempts to use live Open-Meteo UV/cloud data and falls back to a clear-sky model when unreachable. It also lists the main outputs, adding transparency about what the tool returns. It does not cover error handling or rate limits, but the core behaviors are well disclosed.
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 with no fluff. It packs the core question, data source fallback, and key outputs into a compact, front-loaded structure. Every clause contributes meaning, and the sentence is well-organized despite its length.
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 8 parameters and no output schema, the description covers the main purpose and gives a high-level list of outputs (UV index, minutes needed, window times). It does not specify the return structure or mention how parameters like age and skin type influence results, but the schema descriptions fill in parameter meaning. The description is sufficient for an agent to select the tool for a real-time status check.
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 baseline is 3. The description itself adds no parameter-specific semantics; it only mentions outputs in general terms. It does not discuss how parameters like age, skin type, or targetIU affect the calculation, but the schema already describes each parameter adequately.
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's purpose: assessing whether the current moment is good for vitamin D synthesis at a location. It mentions the data source (live Open-Meteo vs clear-sky model) and key outputs (current UV index, minutes needed, window times). This distinguishes it from siblings like get_sun_forecast and get_vitamin_d_window by emphasizing 'RIGHT NOW' and the live data aspect.
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 clear context: use when you need to know if now is a good moment for vitamin D synthesis. The 'RIGHT NOW' framing implies its niche compared to forecast/window tools, and it specifies the live-data and fallback behavior. However, it does not explicitly name alternative tools or when-not-to-use, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in user's current city and favorite cities with coordinates and timezones, ready to feed into the public tools. Requires OAuth (scope profile:read).
| 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 carry the behavioral load. It discloses OAuth scope (profile:read) and user-specific data, but does not describe return format, error cases, or pagination. Enough for basic transparency but gaps remain.
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, well-structured sentence that is front-loaded and efficiently communicates the tool's purpose, output, and auth requirement with 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 the simplicity of a zero-parameter read tool and no output schema, the description covers the essential aspects: what is returned and what authentication is required. It is complete enough for an agent to select and use it 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?
The tool has zero parameters, so the baseline is 4. The description adds meaning about the output, though parameter semantics are not applicable here.
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 signed-in user's current city and favorite cities with coordinates and timezones. This is specific and distinguishes it from sibling tools like get_my_profile or get_my_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?
The description implies a use case ('ready to feed into the public tools') but does not explicitly mention when not to use it or list alternative tools. This is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in user's sun history from the app's calendar: which recent days had viable sun, which they confirmed going outside, and their current streak. Requires OAuth (scope history:read).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many recent days to return; default 30 |
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 the tool returns historical data and requires OAuth. However, it does not explicitly state that it is a read-only operation or if it has any side effects. For a simple read tool, this is adequate but not thorough.
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, each earning its place: the first explains the purpose, the second states authentication requirements. No wasted words, and the most important information is front-loaded.
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 is simple with one optional parameter and no output schema. The description fully covers what the tool returns (history, streak) and its authentication needs. Given the complexity, it is complete.
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 schema covers 100% of parameters and includes a description for 'days' with default value. The tool description does not add any additional meaning beyond the schema, so baseline 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 tool returns the signed-in user's sun history from the app's calendar, specifying the data points (viable days, confirmations, streak). This sets it apart from sibling tools like get_my_profile or log_sun_session.
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?
It mentions the required OAuth scope (history:read), which is a key prerequisite. It does not explicitly state when to use vs alternatives, but the context of 'signed-in user' and 'history' naturally implies its use for personal historical data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in user's saved Vitamin D profile: skin type, exposed-skin default, age, target IU and their current city. Requires connecting with OAuth (scope profile:read). Call this FIRST for any personal question, then pass its values to the public tools instead of asking the user.
| 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 the burden. It discloses the OAuth scope requirement (profile:read) and notes the data is 'saved,' implying persistence. However, it does not mention potential errors, whether data is cached, or how authentication failure is handled. It adds useful context but leaves some behavioral gaps.
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 concise sentences. The first sentence immediately states what the tool returns; the second provides usage and authentication context. No filler, each sentence contributes meaningful information.
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 profile retrieval tool with no parameters and no output schema, the description covers the essential context: data contents, authentication requirement, and usage positioning. It doesn't mention return format or error behavior, but these are less critical given the simple nature and the presence of sibling tools for broader context.
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 zero parameters, and the schema coverage is 100% (trivially). Per the rubric, 0 parameters earns a baseline of 4. The description adds no parameter-specific semantics because none exist, which 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 this tool retrieves the signed-in user's saved Vitamin D profile, enumerating specific fields (skin type, exposed-skin default, age, target IU, current city). It distinguishes itself from sibling tools by positioning it as the first call for personal questions, with values passed to public 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 guidance is given: 'Call this FIRST for any personal question, then pass its values to the public tools instead of asking the user.' This clearly indicates when to use and provides context for alternatives (public tools), though it does not name specific sibling tools or explicitly state 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.
Sunrise, sunset, solar noon, civil dawn/dusk, morning AND evening golden hour, and day length (with day-over-day trend) for a location and date. Handles midnight sun and polar night. Pure sun times — for vitamin D questions use the vitamin_d tools instead.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude in decimal degrees | |
| lon | Yes | Longitude in decimal degrees | |
| date | No | Date as YYYY-MM-DD; defaults to today | |
| timezone | No | IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds useful behavioral context by noting it 'Handles midnight sun and polar night' and includes a 'day-over-day trend.' It does not explicitly state read-only behavior, but the 'get' verb and 'pure sun times' scope imply a safe calculation tool.
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 output details, no fluff. Every clause adds value, from the comprehensive list of times to the edge-case handling and usage pointer.
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 4 parameters and no output schema, the description fully covers what the tool returns, edge cases, and when to use it. The timezone parameter is well-covered in the schema, so no gap remains.
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 parameters are already well-documented. The description mentions 'location and date' but adds no extra meaning beyond the schema's parameter descriptions, meriting the baseline score.
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 lists specific outputs (sunrise, sunset, solar noon, civil dawn/dusk, golden hour, day length) and explicitly contrasts with vitamin D tools, making the tool's purpose unmistakable and differentiated from siblings.
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?
It clearly states when to use this tool vs. alternatives: 'Pure sun times — for vitamin D questions use the vitamin_d tools instead.' This provides an explicit exclusion and points to the correct sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The solar vitamin D synthesis window for ONE specific day at a location, for a personal profile: when UV is strong enough (index ≥ 3), the best hour, the clear-sky minutes needed to reach the target IU, and (with atTime) the minutes at the specific hour the user plans to go out. Returns synthesisPossible=false when the sun never gets high enough that day. Only for single-day questions — for months, seasons or 'when during the year', call get_vitamin_d_year instead of calling this once per date.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Age in years (synthesis declines with age); omit for adult baseline | |
| lat | Yes | Latitude in decimal degrees | |
| lon | Yes | Longitude in decimal degrees | |
| date | No | Date as YYYY-MM-DD; defaults to today | |
| atTime | No | Local HH:MM the user plans to go out — adds minutesNeeded and UV at that exact time | |
| skinType | No | Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3 | |
| targetIU | No | Vitamin D target per session in IU; default 1000 | |
| timezone | No | IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC | |
| elevationM | No | Ground elevation in metres (UV rises ~8%/km); default sea level | |
| exposedSkinFraction | No | Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details: it returns synthesisPossible=false when the sun never gets high enough, and it uses clear-sky assumptions. Since no annotations are provided, the description carries the burden, and it covers the key edge case and modeling context, though it doesn't detail the underlying calculation model further.
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 three sentences, front-loaded with the core purpose, and each sentence adds distinct value (what it returns, edge case, when not to use). No filler or 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 having no output schema, the description explicitly summarizes the return values (when UV is strong enough, best hour, clear-sky minutes, optional atTime minutes, and synthesisPossible=false). It also covers the single-day scope and sibling distinction, making it complete for selection and invocation.
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 already covers 100% of parameters with descriptions, so the baseline is 3. The description adds minimal parameter context beyond restating the atTime behavior that the schema already documents, providing no additional meaning or syntax 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 defines the tool as providing the solar vitamin D synthesis window for one specific day, listing what it returns (UV threshold, best hour, minutes needed, optional atTime calculation). It distinguishes from get_vitamin_d_year by explicitly stating the single-day scope.
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?
It explicitly states when to use the tool ('Only for single-day questions') and provides a direct alternative for other cases: 'call get_vitamin_d_year instead of calling this once per date.' This gives clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The WHOLE YEAR of solar vitamin D for a location in a single call. monthsWithSun lists every month with at least one viable day (season edges count as partial months, see byMonth[].viableDays); solidMonths lists months where most days work; exactViableSpan gives the exact season boundaries; summary carries per-year aggregates for comparing places. Use this for any question about months, seasons, winter/summer or 'when during the year can I…' — never probe individual dates with get_vitamin_d_window for that.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Age in years (synthesis declines with age); omit for adult baseline | |
| lat | Yes | Latitude in decimal degrees | |
| lon | Yes | Longitude in decimal degrees | |
| skinType | No | Fitzpatrick skin type 1 (very fair) to 6 (very dark); default 3 | |
| targetIU | No | Vitamin D target per session in IU; default 1000 | |
| timezone | No | IANA timezone like 'Europe/Madrid'. Strongly recommended — without it all times are UTC | |
| elevationM | No | Ground elevation in metres (UV rises ~8%/km); default sea level | |
| exposedSkinFraction | No | Skin exposed: 0.10 face+hands, 0.18 face+arms, 0.25 t-shirt+shorts (default), 0.40 swimsuit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explains the output structure and each field's meaning (viable days, solid months, exact season boundaries, aggregates). It does not disclose potential costs or data freshness, but covers the core behavior sufficiently.
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 focused sentences: first introduces the tool, second details output fields, third gives usage guidance. No wasted words; each sentence carries essential information.
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 description covers output fields and usage context well. However, with no output schema, the description could include more structural details (types, examples) to fully describe the complex return object, but it is still quite complete for an experienced user.
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 parameters are fully documented in the input schema. The description does not add new parameter-specific information beyond the schema, meeting the baseline for high coverage.
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 provides the whole year of solar vitamin D for a location, listing key output fields (monthsWithSun, solidMonths, exactViableSpan, summary). It distinguishes from the sibling tool get_vitamin_d_window by explicitly indicating when not to use that tool.
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 gives explicit guidance on when to use this tool ('any question about months, seasons, winter/summer') and when not to ('never probe individual dates'), directly naming the alternative tool get_vitamin_d_window.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Marks a day as sun-confirmed in the signed-in user's history calendar — use when the user says they went (or will have gone) outside for their sun. Defaults to today. Requires OAuth (scope history:write).
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Day to confirm, YYYY-MM-DD; defaults to today | |
| minutes | No | Minutes the user reports having spent in the sun (acknowledged, not stored) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that minutes are 'acknowledged, not stored', requires OAuth scope history:write, and defaults to today. This provides useful behavioral context beyond the schema.
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 three sentences, front-loaded with the primary purpose, and contains no unnecessary words. Every sentence adds significant 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 the tool has two optional parameters, no output schema, and no nested objects, the description covers essential points: purpose, usage trigger, authentication, and parameter behavior. Siblings are diverse, and this tool's role is clearly defined.
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 noting that date defaults to today and minutes are acknowledged but not stored. These details are not present in the schema descriptions and help the agent understand parameter behavior.
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 marks a day as sun-confirmed in the signed-in user's history calendar, with a specific verb and resource. It distinguishes from sibling tools (e.g., get_my_history, estimate_sun_session) by being a write operation for logging actual sun exposure.
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 context: 'use when the user says they went (or will have gone) outside for their sun'. It also mentions defaulting to today and OAuth scope. It does not explicitly state when not to use, but the 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.
Find a city in the app's database by name (any of the app's six languages works) and get its coordinates, IANA timezone and elevation — feed those into the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | City name, e.g. 'Madrid', 'London', 'Nueva York' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the tool's behavior: accepts city names in any of six languages and returns coordinates, timezone, and elevation. It does not describe error cases or read-only guarantees, but for a search tool this is adequate. No contradictions with annotations (none present).
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, focused sentence. It front-loads the verb and resource, then provides essential output details and usage context. Every clause is informative and no redundant wording is present.
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 simplicity (one parameter, no output schema), the description is complete for an agent to understand its role and output. It mentions the return values and integration with other tools. It could optionally detail return format or failure behavior, but those are handled by schema and reasonable inference. Overall, sufficient.
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 already has 100% description coverage with a clear example and format. The tool description adds the multilingual aspect ('any of the app's six languages works') and the purpose of the query, which enhances understanding but doesn't add significant syntax details beyond the schema. Baseline 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 'find' and the resource 'city in the app's database', and specifies the output (coordinates, IANA timezone, elevation). It distinguishes itself from sibling tools focused on sun/vitamin D by being the city lookup utility. The phrase 'feed those into the other tools' confirms its role as a prerequisite lookup.
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 when to use this tool: to obtain city data needed by other tools. It doesn't explicitly state exclusions or alternatives, but the context is clear given the sibling list. The instruction 'feed those into the other tools' provides practical usage direction.
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.0.1estimate_sun_sessionget_current_statusget_my_citiesget_my_historyget_my_profileget_sun_timesget_vitamin_d_windowget_vitamin_d_yearlog_sun_sessionsearch_cityScored across 10 tools
Each tool targets a distinct function: city lookup, sun times, vitamin D windows (daily/annual), current status, session estimation, and user profile/history. Descriptions explicitly differentiate overlapping areas (e.g., 'for vitamin D questions use the vitamin_d tools instead'). No ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case: get_my_cities, search_city, get_sun_times, get_vitamin_d_window, get_vitamin_d_year, get_current_status, estimate_sun_session, get_my_profile, get_my_history, log_sun_session. Predictable and clear.
10 tools is well-suited for the domain. The set covers location setup, sun data, vitamin D planning across timescales, current status, session estimation, and user management. No unnecessary tools, and the scope is focused.
The tool surface is comprehensive for vitamin D assistance: city search, sun times, daily/yearly vitamin D windows, current status, session estimation, and user profile/history. Minor gaps exist (no profile update or data deletion), but core workflows are covered.
Vitamin D synthesis calculator: sun position, UV, IU/min, time to dose, sunburn risk, daily window.
Know when the sun can make vitamin D where you are, for your skin type. Live UV data.
Elevation-corrected sun, moon, twilight, solar and tide data for any point on Earth
Where is it sunny? Monthly sunshine scores, temps, rain, UV and sea temp for 3,833 destinations.
