Vitamin D Explorer

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It transparently describes the output (months with sun, season span, viable days, ranking) and the shared axis capability. However, it does not explicitly state read-only nature or any authentication requirements.

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: first sentence states purpose with example, second lists outputs and distinguishes from sibling. Every sentence earns its place, front-loaded with key 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?

Given the tool's moderate complexity (5 parameters, comparison, no output schema), the description is quite complete: it explains purpose, outputs, and provides usage guidance. Could optionally mention read-only nature, but overall adequate.

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 minimal parameter insight beyond the schema, though the example query helps contextualize the 'places' parameter. No additional value for other parameters.

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 compares vitamin D year of 2-5 places side by side, gives an illustrative example query, and distinguishes itself from the sibling tool get_vitamin_d_year by noting that only this tool can draw years on a shared axis.

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 recommends using this tool instead of calling get_vitamin_d_year once per city, providing clear when-to-use guidance. The example query also helps contextualize usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains the tool shows a form and returns values back to the conversation, and that it updates live. It does not state whether the tool has side effects (e.g., saves profile permanently) but given no annotations, the description still provides sufficient transparency for a configuration form.

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 somewhat verbose but front-loads the core purpose. Every sentence adds value; however, it could be slightly more concise without losing clarity.

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, no output schema, and no annotations, the description is highly complete: it explains what the tool does, when to use it, what parameters affect live updates, and how to use the results. There is no obvious gap.

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?

While schema description coverage is 100% (baseline 3), the description adds meaning by highlighting the four main values (Fitzpatrick, skin fraction, age, target IU) and explaining that lat/lon/timezone/placeName enable a live UV estimate. This goes beyond the schema's brief 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 explicitly states the tool shows an interactive form for the four key values (Fitzpatrick skin type, fraction of skin exposed, age, target IU) with live updates of minutes needed. This clearly distinguishes it from siblings that assume these values are already known.

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 guidance: use when values are unknown, when the user wants to change them, or instead of asking for them one at a time. It also instructs to pass the returned values to other tools afterwards.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses important behaviors: it explains that missing records mean no measurement, not insufficient sun, and states the OAuth scope requirement. It also mentions the calendar rendering behavior. This goes well beyond what structured annotations would provide.

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 compact, with four sentences covering key aspects (what it returns, date coverage, missing-data caveat, auth). It is front-loaded, but the 'from'/to' inconsistency is a structural flaw that prevents a perfect score.

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 the main data points returned, the missing-data semantics, and auth. However, without an output schema, it leaves the exact return structure ambiguous, and the 'from'/'to' reference conflicts with the actual parameter. It is reasonably complete for a simple tool but has notable 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?

The description references 'from' and 'to' parameters, but the schema only defines a 'days' parameter. This is contradictory and confusing, detracting from the schema's own clear description of 'days'. The description adds no value here and actually introduces inconsistency.

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 sun history from the app's calendar, including viable sun days, confirmed going-outside days, and current streak. It distinguishes this from siblings like get_sun_forecast (future) and get_current_status (current) by explicitly focusing on historical calendar 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 context on when this tool is relevant (for signed-in users' history) and highlights a key caveat about missing records, but it does not explicitly name alternatives or say when not to use it. The usage is implied rather than clearly differentiated from sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the transparency burden. It does disclose that the tool uses the 'live Open-Meteo forecast' and lists per-day output fields, which is useful. However, it does not explicitly mention that the operation is read-only, has no side effects, or clarify network/error behavior, leaving some behavioral traits implicit for a forecast 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?

The description is two tightly written sentences. The first sentence packs the core purpose and output summary; the second provides usage context, example questions, and the explicit sibling alternative. Every word contributes, with no redundant 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?

Given the lack of an output schema, the description compensates by enumerating the return fields (peak UV, cloud cover, synthesis window, minutes needed, bestDay) and by explaining the multi-day use case. The schema comprehensively covers all parameters, so the description need not repeat them. Minor gaps remain around timezone handling consequences and potential error cases, but the overall context is sufficient for an agent to select and call this tool 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?

All 9 parameters have comprehensive schema descriptions covering ranges, defaults, units, and special roles (e.g., timezone). The tool description itself adds little parameter-specific meaning beyond 'a location' and 'NEXT FEW DAYS', so the schema carries the parameter documentation burden and earns the baseline score of 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 identifies the tool as a multi-day vitamin D sunshine forecast for a location, explicitly listing the computed outputs (peak UV, cloud cover, synthesis window, minutes needed, bestDay). It further distinguishes itself from the sibling get_vitamin_d_window by highlighting the multi-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?

The description provides explicit usage guidance: 'Use this for any question spanning several days', followed by concrete examples ('which day this week should I go out'). It also directly names the alternative approach and says 'instead of calling get_vitamin_d_window once per date', making the tool-choice decision unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It disclosesspecific behavioral details of the return structure: monthsWithSun includes partial months via byMonth[].viableDays, solidMonths is defined, exactViableSpan gives season boundaries, and summary holds per-year aggregates. This adds meaningful context beyond 'returns data', though it does not explicitly state read-only semantics (implied by 'get').

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, each earning its place: the opening states the tool's purpose, the middle explains the return fields, and the closing gives usage guidance. There is no filler or repetition of schema details.

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 (9 params, no output schema), the description covers the essential context: what the call returns, how to interpret field semantics, and when to use it vs. an alternative. It provides enough to select and invoke the tool correctly without needing to infer behavior from sibling tools.

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 documents all 9 parameters. The description adds no new parameter-specific semantics beyond mentioning 'for a location', which is redundant with lat/lon. The baseline of 3 applies because the schema does the heavy lifting.

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 a whole year of solar vitamin D data for a location, with a specific verb ('get') and resource ('year'). It distinguishes from the sibling tool get_vitamin_d_window by explicitly contrasting year vs. individual dates.

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 provided: 'Use this for any question about months, seasons, winter/summer or "when during the year can I…"' and it names the alternative with direction 'never probe individual dates with get_vitamin_d_window for that.' This is a clear when-to-use and when-not-to-use statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully discloses behavior: it explains the effects of each 'confirmed' value, notes that 'minutes' are acknowledged but not stored, mentions the default date, and states the OAuth scope requirement. This goes beyond the schema and gives the agent a clear picture of side effects and permissions.

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 purpose, then covers values, defaults, and auth. Every sentence adds necessary information without waste.

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 write operation with full schema coverage and no output schema, the description is complete. It explains purpose, parameter semantics, default behavior, and auth requirements. No significant gaps remain.

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 description doesn't need to add much. It does restate the default for 'confirmed' (true) and the non-storage of 'minutes', but these are already in the schema. The description adds no new parameter semantics beyond what structured schema provides, warranting 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 clearly states the tool's function: 'Sets a day's answer in the signed-in user's history calendar.' The verb 'Sets' and resource 'day's answer in history calendar' are specific. It distinguishes from siblings (e.g., get_my_history reads, update_my_profile modifies profile) by targeting the sun session log specifically.

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 for when to use this tool: to log a day's sun session answer. It explains the three allowed values and defaults. It does not explicitly name alternative tools or exclusion criteria, but the purpose is unambiguous enough for an agent to infer appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the OAuth scope (history:write), states that it only changes location and not other details ('whether they went outside that day is untouched'), and clarifies it stops assumption. This is strong, though it could mention whether existing location data is overwritten or merged.

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 four sentences, front-loaded with the core purpose, then usage guidance, parameter hints, and scope/permissions. 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 tool's complexity (5 params, optional combinations, no output schema), the description covers purpose, when to use, parameter relationships, side effects, and auth. It is sufficient 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 coverage is 100%, so baseline is 3. The description adds meaning by explaining the from/to range concept and the mutually exclusive cityId or lat/lon options, which is not fully captured in the schema. This adds value beyond the field 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 verb and resource: 'Records where the signed-in user was over a range of past days.' It also differentiates from siblings by explaining it corrects assumed history, which get_my_history marks with `locationAssumed`.

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 it when the user corrects a stretch' and references get_my_history as the detection mechanism. It also gives alternatives for parameters (cityId from search_city or lat/lon), providing clear context for when to use this tool versus others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses the write operation, the specific writable fields, OAuth requirement, and that the saved values affect later calls. It does not mention error conditions or idempotency, but covers key behavioral traits 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?

Two sentences, front-loaded with the main purpose. No wasted words. The second sentence efficiently clarifies scope and auth. Excellent structure.

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 optional parameters, no output schema, and no annotations, the description covers the essential context: purpose, writable fields, auth, and persistence behavior. It lacks mention of what happens if all parameters are omitted, but overall it is sufficient for a simple update 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% with good descriptions for each parameter. The description adds context that these fields constitute the 'synthesis profile' and clarifies that null for age means adult baseline. This adds value 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 verb 'Save' and the resource 'signed-in user's synthesis profile' with specific fields. It explicitly distinguishes from siblings by noting what is NOT writable (favourites, cities, history), making its scope precise.

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 (to persist profile values for future calls) and implicitly when not to (for updating cities/favourites). It also mentions the required OAuth scope. However, it could more explicitly name alternative tools for non-profile updates.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.