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

Beyond the readOnlyHint annotation, the description discloses substantial behavioral context: state meanings, device-specific data availability, the empty-result caveat, plain wall-clock time semantics, a capped span due to collapsed intervals, and the exact shape of the return value. This goes well beyond what annotations provide and contains no contradiction.

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 long but every paragraph earns its place: core definition, device coverage, key distinction from insulin amounts, use cases, time semantics, and return shape. It is front-loaded with the central concept and uses structure and emphasis to keep important caveats scannable. No redundant filler.

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 that there is no output schema, the description thoroughly compensates by explaining exactly what will be returned: per-state minutes/percentages and an intervals array with state, start, end, and minutes. It also covers crucial edge cases such as empty results for unsupported devices, the non-UTC time caveat, and the difference between states and units. Nothing essential is missing for correct 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?

Schema description coverage is 100%, so the input schema already documents start, end, and includeIntervals in detail. The description reinforces the wall-clock caveat and mention of includeIntervals, but it does not add significant parameter-level meaning beyond what the schema provides. A 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's purpose with a specific subject ('the pump's automated-delivery algorithm'), resource ('basal over time'), and a precise set of states (normal, suspend, max, limited). It also explicitly differentiates itself from get_daily_insulin by clarifying these are states, not insulin amounts, leaving no ambiguity about what the tool does.

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 provides explicit use cases ('investigate lows', 'rebound patterns', 'how hard the system is working', 'whether excursions coincided with limited mode'), a direct alternative for basal units ('use get_daily_insulin'), and warns against treating empty results as normal for non-Omnipod devices. This is strong 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.

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

Beyond the minimal annotations (readOnlyHint=false, destructiveHint=false), the description discloses file creation, browser opening, downsampling behavior with a `downsample` object, the fallback `html` field, and the critical instruction not to reproduce the chart in the response. It also clarifies the wall-clock time caveat and return fields. No contradiction exists between description and annotations.

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 long but well-structured and front-loaded: the core purpose and differentiation appear first, followed by multi-day behavior, data resolution, and response handling. Each section is functional, though some redundancy with schema descriptions exists (e.g., resolution details are repeated). Still, it is not padded—every section addresses a real agent decision point.

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 no output schema, the description enumerates the return fields (ranges, dayCount, unit, pointCount, bolusCount, filePath, openAttempted, downsample, html) and explains their conditions. It also covers edge cases: falling back when browser open fails, how to handle downsampling, and the policy about not emitting the chart as an artifact. An agent has everything needed to call the tool correctly and respond appropriately.

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 detailed parameter explanations (including wall-clock caveat, resolution semantics, and ranges usage). The tool description reinforces these but does not add new parameter-level meaning beyond the schema. This is the expected baseline for a fully self-documenting 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 opens with a specific verb and resource: 'Generates a clinical-report-style glucose chart... saves it to a file, and opens it directly in the patient's default web browser.' It also explicitly differentiates from get_chart_series with 'USE THIS instead of get_chart_series whenever the patient wants to SEE a chart,' making its scope unambiguous.

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 when-to-use guidance: 'USE THIS instead of get_chart_series' for visual charts, and explains when to use `ranges` versus start/end, and when to offer `resolution` choices. It also defines the fallback scenario for `openAttempted: false`, so an agent knows exactly how to route behavior.

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?

Annotations only indicate readOnlyHint: true现实，但 description 补充了关键行为细节: returns data not a picture, gives specific rendering instructions, warns against typical auto-chart pitfalls, explains time axis handling with ready-made xAxis object, and clarifies time and unit conventions. This goes far beyond the annotation, giving the agent implementation-level transparency.

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 lengthy, with many paragraphs dedicated to x-axis handling and rendering instructions, which are highly relevant but could be condensed. However, it is well-structured with clear headers (X-AXIS, HOW TO RENDER IT) that front-load critical information. While every sentence earns its place given the tool's complexity, the verbosity may reduce readability. It's not overly concise but is efficiently organized.

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, with no output schema, the description comprehensively covers what is returned (unit, points, events, xAxis), how to interpret each field, and how to render them correctly. It addresses common mistakes (index axis), provides alternative use cases, and specifies time/unit conventions. Nothing essential is missing for an agent to call and use the 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?

Schema coverage is 100% for all three parameters, including detailed descriptions for start/end emphasizing wall-clock time and maxPoints with default/range. The description adds context on usage (e.g., maxPoints 200-400 is ample) and reinforces time semantics, though the schema already covers most meaning. It provides value beyond the schema by clarifying how parameters affect output granularity and cost.

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 'chart series', specifying it returns downsampled glucose data with min/max bands and bolus markers for charting. It explicitly differentiates from sibling tools like get_glucose and get_chart_html, noting it returns data, not a picture, and is for plotting graphs versus numeric inspection.

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 tells when to use this tool: whenever the patient wants a graph or chart of glucose over a window, or for illustrating 'what a good/bad day looked like'. It contrasts with get_glucose, reserving that for close-up numeric inspection. It also instructs to render the data as a chart and avoid built-in shortcuts that misplot the x-axis, providing clear behavioral guidance.

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?

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: the most recent day may be flagged provisional if still today and not finalised, and all dates are wall-clock (device-local) days. It also clarifies that the bolus figure is pre-aggregated by Glooko, which is a behavioral nuance beyond the annotation. It does not describe pagination or error behavior, but for a read-only data retrieval tool this is solid.

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-structured: a one-sentence summary, a usage paragraph, a provisional-data note, and a return-shape paragraph. Every sentence earns its place, and the most important scoping information is front-loaded. It is detailed but not bloated.

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 read-only tool with two fully documented parameters and no output schema, the description covers the return shape, the source, the provisional flag, and the wall-clock semantics. It also addresses the key distinction from sibling tools. Nothing an agent needs to call it correctly is missing.

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 thoroughly. The description adds value by explaining the wall-clock semantics and the 'Z' format artifact, which is critical for correct usage. It also clarifies that timestamps returned are likewise wall-clock. This goes beyond the schema's own caveats and reinforces the key semantic trap.

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 states a specific verb and resource: it returns Glooko's own per-day insulin totals (basal, bolus, combined total) plus a window aggregate. It clearly distinguishes itself from sibling tools by noting that bolus here is Glooko's pre-aggregated daily figure, while other tools use event-level aggregation. This is a precise, non-tautological definition.

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 says when to use this tool: when you want device-reported daily totals, e.g., a day-by-day basal/bolus table or total daily dose per day. It also names alternatives (get_diabetes_summary, get_trend) for event-aggregated bolus, and notes that basal is only available from Glooko, so this tool and those share the same basal source. This is strong routing guidance.

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 annotations declare readOnlyHint=true, and the description aligns with that while adding substantial behavioral context: device-specific coverage limitations, confirmed-empty results for CamAPS FX + Ypso Pump, wall-clock rather than UTC time semantics, and the caution that empty results do not mean no changes occurred.

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-structured with labeled sections and every sentence earns its place. It front-loads the core purpose, then adds coverage caveats, usage guidance, time semantics, and return shape 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?

Given the moderate complexity, absent output schema, and read-only annotations, the description covers what the tool returns, how timestamps are represented, device coverage limitations, and how to interpret results. An agent has enough context to select and invoke the 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?

Schema description coverage is 100%, and the input schema already thoroughly documents both start and end parameters, including the wall-clock caveat and inclusivity. The tool description reinforces these points but does not add significant parameter 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 identifies the tool as returning pod/site changes and CGM sensor changes as timestamped events in two separate lists. The resource and output shape are specific and distinguish this from the sibling glucose, insulin, and trend 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?

The description gives strong context for when to use this tool: to check whether unexplained glucose disruption aligns with a recent pod/sensor change, and explicitly warns against asserting causation. It does not name alternative sibling tools, but the use case is clearly delineated.

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?

Beyond the readOnlyHint annotation, the description discloses important behaviors: fixed-size aggregates regardless of window length, uncapped cheap calls, wall-clock time semantics, explicit ranking tie-breakers, and the basal/bolus calculation rule. This is substantial and consistent with annotations.

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 front-loaded with purpose and usage guidance, followed by a useful tip and a detailed returns section. It is longer than average, but the density is justified by the tool's rich output; each section 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, so the description carries the full burden of explaining return values. It enumerates all result groups (reportRange, glucoseControl, glucoseExtremes, bestWorst, insulin, bolusArchitecture, carbs, settings) and clarifies timezone, ranking, and metric semantics. This is complete for a complex summary 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 input schema has 100% coverage with detailed descriptions for all five parameters, including the wall-clock caveat and unit override behavior. The description reinforces these semantics but does not add significant new parameter-level 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 states a specific verb/resource and explicitly positions the tool as 'the single best starting point for any overview question'. It also clarifies scope ('no matter how long the span') and distinguishes it from more granular siblings like get_trend or get_daily_insulin.

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 clear usage guidance: use for overview questions, and use a deliberately wide call as an orientation step before drilling into a specific period. It does not name sibling tools explicitly, but the when-to-use instruction is strong enough to guide an agent.

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?

Beyond the readOnlyHint annotation, the description discloses critical behavioral details: time is plain wall clock (not UTC), glucose values are in configured units, the 92-day cap, and the meaning of delivered vs programmed (interruption flag). It also outlines the response structure and setting context. This transparency is exceptional and far exceeds what annotations alone 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 lengthy but well-organized, front-loading the core purpose then progressively detailing usage, constraints, and return object. Every sentence adds substantive information without redundancy. While it could be tightened, the structure is logical and aids comprehension, earning a 4 rather than a 5 for its verbosity.

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 (3 parameters, 2 required, rich return object) and the absence of an output schema, the description is highly complete. It explicitly enumerates the return fields, explains the interruption flag, override semantics, and the settings context object, and covers constraints like the 92-day cap and time-zone handling. Nothing an agent needs to call it correctly is missing.

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 detailed descriptions for all three parameters, including time-zone caveats and valid class enum values. The description adds extra strategic value by recommending the classes filter to 'keep the response small,' which enriches usage semantics beyond the schema. With 100% schema coverage, this goes above the baseline 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 states a specific purpose: return every bolus in the window, enriched with contextual data (CGM, settings, overrides) to judge dose correctness. It clearly distinguishes itself from siblings by emphasizing enrichment and analysis use cases, making it easy for an agent to select this tool over alternatives like get_split_bolus_log or get_daily_insulin.

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 use-case guidance: 'Use it to investigate insulin stacking, bolus-calculator accuracy, interrupted deliveries and user overrides.' It also advises on the classes filter to keep responses small. However, it does not explicitly mention when NOT to use it or contrast it with sibling tools, which would make the guidance fully complete.

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?

Beyond the readOnlyHint annotation, the description discloses critical runtime behavior: the 21-day cap on raw points, the plain wall-clock time semantics (explicitly not UTC), and that values follow the configured unit. It also previews the return shape, which is especially valuable given there is no output 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 longer than average but well structured: a one-line summary, then the band selector explanation, then usage boundaries and caveats, then the return format. Every section adds operational value, though a small amount of repetition with the schema's parameter descriptions keeps it from 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?

For a tool with no output schemathor, the description provides a complete mental model: what the tool returns, the cap, timezone handling, unit behavior, and how it relates to sibling tools. An agent has enough information to call it correctly and interpret the response.

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% parameter description coverage, so the baseline is 3. The description does reinforce the meaning of 'band' and explains the value of filtering, but it largely restates what the schema already documents rather than adding new parameter-level semantics.

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 opens with a specific statement: 'Individual timestamped CGM readings for a window', clearly identifying the resource and the operation. It further distinguishes itself from sibling tools by noting it returns raw points rather than downsampled chart series or aggregate statistics.

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 usage direction: use 'low'/'high' to pull only excursions without thousands of normal readings, and 'all' for the full trace. It also names concrete alternatives—get_chart_series for wide charts)Skip until get_diabetes_summary or get_trend for aggregates—so an agent knows exactly when to choose another tool.

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?

Beyond the readOnlyHint annotation, the description discloses a non-obvious behavioral trait: hours are the device's wall-clock hour, not UTC, and must be presented as-is with no conversion. It also explains how data is pooled across the window and what fields the returned rows contain. This adds real value over the annotation.

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?

Every sentence earns its place: core aggregation method, usage scenarios, the critical UTC/wall-clock warning, and the return shape. The structure is front-loaded and there is 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?

With no output schema, the description appropriately lists the output row shape (byHour array, fields, wall-clock 'HH:00') and unit semantics. It is missing details such as whether hours without readings are omitted or zero-filled and the exact scale/data types of timeInRange, timeLow, and timeHigh, which may be needed for correct interpretation.

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%, and the schema already documents all five parameters with detailed caveats (ISO format, wall-clock quirk, overrides). The description only reiterates that glucose values are in the configured unit, which the schema already covers, so the baseline 3 is correct.

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 states exactly what the tool does: it pools Time In Range and average glucose by clock-hour across the whole window, with a concrete example ('every reading that fell in the 07:00 hour on any day is combined into one 07:00 row'). This is a specific verb/resource/aggregation, clearly distinct from raw glucose retrieval or generic trend 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?

The description gives explicit when-to-use guidance: circadian questions, recurring high/low-at-certain-time patterns, dawn phenomenon, and evening highs. These are concrete use cases, but it does not explicitly say when not to use the tool or name alternatives (e.g., get_trend, get_glucose), so it stops at 4.

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?

Annotations already declare readOnlyHint=true, so safety is known. The description goes beyond by clarifying time is device-local wall clock (not UTC), glucose units follow configuration or override, and returning specific arrays (glucoseTimeline, associatedBoluses). This adds useful behavioral context without contradicting annotations.

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-structured: scope first, then usage, then conventions, then return shape. Every sentence earns its place, with no fluff or repetition. It is detailed but efficient.

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 explicitly lists the return fields (targetEvent, unit, glucoseTimeline, associatedBoluses), satisfying return expectations. The two parameters are fully explained in schema. For a focused read-only analysis tool, nothing critical is missing.

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% – both eventTimestamp and units already have detailed descriptions covering wall-clock time, optional override, and unit enums. The description adds some usage context (how to find the event time) but does not materially extend parameter semantics beyond what the schema provides, 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 states a specific verb/resource: a focused analysis window around a single meal bolus event, exactly 30 minutes before and 3 hours after the timestamp. It clearly distinguishes itself from 'pulling whole days' and relates to the sibling get_enriched_bolus_log for finding the event, making its 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?

It explicitly says when to use it ('judge a post-meal excursion and how well a dose worked') and even gives a prerequisite workflow: find the event time via get_enriched_bolus_log, then pass it here. This is strong usage guidance that differentiates it from day-level or historical 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?

Beyond the readOnlyHint annotation, the description reveals critical behavior: it contains NO real values, only fabricated placeholders, and reportHash is an opaque integrity token not meant for the patient. It also openly describes the confirmation gate and warns against substituting judgment. No contradiction with annotations exists.

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 front-loaded with the core privacy guarantee and then the critical usage gate, and it is well structured with a return summary. It is longer than average due to safety-critical repetition, but nearly every sentence earns its place. A small amount of redundancy could be trimmed without losing meaning.

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 parameters, no output schema, and only a readOnly annotation, the description carries the full burden of explaining the tool. It completely specifies the returned fields, their semantics, how to use them in the follow-up call, and the confirmation requirement. An agent has everything needed to call it correctly and safely.

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 there are no parameter semantics to clarify. The description appropriately explains the outputs that matter for the next call, including requiredPhrase and reportHash. This matches the 0-parameter baseline of 4.

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 builds a discovery report and is step 1 of 2 for contributing to the schema registry. It explicitly differentiates itself from submit_registry_contribution and from the many read-only data retrieval siblings. The verb 'Builds' plus the resource and step context make the purpose unambiguous.

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 an explicit, detailed usage flow: show the full entries verbatim, obtain the patient's exact typed phrase, then call submit_registry_contribution with confirmationPhrase and reportHash. It also states what not to do, such as proceeding on a paraphrase or 'yes', and names the next sibling to call. This is exceptionally clear guidance.

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?

Beyond the readOnlyHint annotation, the description discloses important behavioral caveats: effective timestamps are device-local wall-clock time rather than true UTC, per-segment 'from' times are pump-schedule clock-hours, glucose values use the configured unit, and results are chronological. It also spells out the return shape, which is especially valuable because no output schema is provided.

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 front-loaded with the core definition, followed by use-case context, critical caveats, and a clear return summary. Every sentence carries necessary information and there is no filler or redundant restatement of the title.

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 no output schema, but the description compensates by fully describing the returned settings array and its nested profile segments. Combined with the input schema, the timezone caveats, and the readOnlyHint annotation, an agent has everything needed to invoke the tool correctly and interpret its 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 description coverage is 100%, so the schema already fully documents the start and end parameters, including the wall-clock caveat and inclusivity. The description reinforces the timezone concept but does not add substantial new parameter-level meaning beyond the schema, so the baseline 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 states the exact verb and resource: retrieve pump setting changes effective during a time window, in chronological order, including DIA, max basal rate, and time-segmented target/ISF/carb-ratio profiles. It clearly differentiates this from sibling tools by focusing on settings history and active-at-a-time semantics.

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 context for when to use it: establish which settings were active at a given time before judging a bolus or excursion, or inspect how settings changed over a long span. It does not name exclusions or specific sibling alternatives, but the usage context is clear enough to route an agent correctly.

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?

Annotations only declare readOnlyHint=true, but the description adds critical behavioral context: the 92-day cap, wall-clock vs UTC time handling, the pass-through of durationString without parsing, and the interpretation of null/0 stats as a normal result for closed-loop users (not an error). This significantly enriches beyond the annotation.

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?

Well-structured: opens with the purpose, then details the data shape, moves to use cases, and finishes with caps and return format. Each sentence adds value; no redundancy. Though slightly long, the complexity of the tool justifies it.

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 exists, so the description fully compensates by enumerating the exact return fields (window, stats, boluses) with sub-fields and their null/0 behavior. It also explains durationString. The description gives everything an agent needs to correctly interpret results and decide on 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?

Schema description coverage is 100% — both start and end parameters have thorough descriptions including timezone caveats and inclusivity semantics. The tool description adds no extra parameter-level information; it's all covered in the schema. Thus, the baseline of 3 applies.

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 states a specific resource (split/extended bolus log) with explicit scope (only boluses with an extended-delivery portion, excluding normal single-shot doses) and differentiates it from a general bolus log. It directly addresses the sibling get_enriched_bolus_log by clarifying what makes this tool unique.

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 use cases: 'see whether/how often splitting is actually used' and 'whether the split ratio correlates with post-meal control' with a concrete pairing recommendation (get_meal_window_analysis). Also imposes a hard cap of 92 days, informing agent decisions on window size.

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?

Beyond the readOnlyHint=true annotation, the description discloses that each bucket is computed independently from raw readings ('not by averaging averages'), explains the insulin aggregation rules (bolus summed from events, basal from Glooko's per-day totals), and details the observedDays and coverage percentage for trust assessment. This provides substantial behavioral context that is not captured by the annotation.

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 front-loaded with the purpose, then the computation method, and finally the return structure. It is longer than typical but appropriate given the tool's complexity (8 parameters, intricate aggregation logic). Each sentence adds value, and there is no redundancy or filler.

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 thoroughly enumerates the return structure, including conditional fields (basalUnits only when Glooko daily data exists) and trust metrics. It also explains edge cases like 'when Glooko daily data exists' and the wall-clock time convention. An agent has all necessary information to invoke and interpret results 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 input schema has 100% coverage, so parameters are already documented. The description adds interpretive value by explaining how mode affects bucket division (calendar vs. fixed), how insulin rules apply 'same as elsewhere,' and the meaning of the returned aggregates. It does not restate schema descriptions but enriches the conceptual understanding of parameter effects.

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 computes glucose, insulin, and carb aggregates split into time buckets for period-over-period questions. It explicitly names the resource (aggregates), the action (trend over any timeframe), and the context ('how have things changed month by month over the last year'). It also differentiates from summary calls by emphasizing single-call multi-bucket retrieval.

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 to 'Prefer this over making many separate summary calls for a multi-period comparison,' which clearly indicates when this tool should be used. It does not mention specific sibling tools or when not to use it, but the alternative suggestion and the uniqueness of the bucketed approach are adequate for an agent to select it appropriately.

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?

Annotations already mark this as destructive (destructiveHint=true) and not read-only. The description goes far beyond that by detailing the full gating sequence: exact-match phrase check, independent second privacy scan, content-integrity hash check, writing to schema-registry/, and the fallback behavior when `gh` is missing or PR fails, including local verification and clear reporting. It also clarifies that it does not trust earlier redaction, adding significant behavioral context beyond the annotation.

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?

Although the description is lengthy, every sentence adds necessary detail about the gating sequence, fallback, and error handling. It's front-loaded with the step and prerequisite, and the structure is logical (prerequisite → action → checks → outcome). No filler or redundancy; the length is justified by the tool's complexity.

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 is highly complete for a complex destructive tool: it covers inputs, prerequisites, detailed behavioral checks, and failure scenarios. The only gap is that it doesn't describe the return value or response format, and there's no output schema to compensate. For a submission tool, an agent might need to know what it returns (e.g., PR URL, status), but the description's thoroughness elsewhere makes this a minor omission.

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 for both parameters is 100%, and the schema descriptions already state exactly what each parameter must be (verbatim reportHash and the patient's own typed phrase). The tool description reiterates that requirement but doesn't add new meaning beyond the schema. Thus, a baseline score of 3 is appropriate per the rubric.

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: it's step 2 of a two-step process to submit a schema registry contribution, explicitly naming the exact inputs (confirmation phrase and reportHash) and the action (write and submit). It distinguishes itself from the get_registry_contribution_report sibling by framing it as the follow-up step.

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 clearly defines when to call this tool: after the patient has reviewed the report IN FULL and typed the exact confirmation phrase. It also conditions the call on having the reportHash and phrase. While it doesn't explicitly state when NOT to call, the prerequisites are unambiguous, and there are no alternative submit tools among siblings, so the context is clear. A slight bump to 5 would require explicit exclusions or alternatives, which aren't present.

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