CGM hypo events

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral detail beyond those: window truncation by the provider, the caveat that 'No hypos' is only true for hours_covered, ADA level thresholds, and the recovery_time definition. It also includes a medical disclaimer. No contradiction with annotations; it enriches them significantly.

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 information-dense. It leads with the core purpose, then output fields, then provider caveats, and ends with the disclaimer. Each sentence earns its place — no fluff. The structure is logical, though the length might slightly challenge quick scanning. It's appropriately sized for the 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?

Without an output schema, the description fully specifies return values (event fields, totals, recommendations). It covers edge cases (window truncation, threshold interpretation, provider limits) and provides a safety disclaimer. For an agent to correctly call and interpret results, nothing essential is missing. This is as complete as it needs to be.

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 baseline is 3. The description adds clinical meaning to parameters (e.g., threshold_mg_dl as ADA Level 1, severe_threshold as Level 2) and clarifies that `window` is the requested span while observed_window reflects actual data. It also explains how response_format and privacy_mode affect output. This goes beyond the schema's plain descriptions, justifying a 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 opens with a precise verb-resource pair — 'Detect hypoglycemia events between `from` and `to` ISO dates' — and enumerates the exact output fields (started_at, severity, recovery_time_minutes, etc.). It clearly distinguishes this tool from siblings like cgm_glucose_window or cgm_time_in_range by focusing specifically on hypo events and their structure.

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 strong context for when to use it: it handles date ranges and outputs event arrays with thresholds. It also explains provider-specific behavior (12h cap on live reads) that affects interpretation. However, it never explicitly names alternative tools or states when NOT to use it, leaving the agent to infer from sibling names. A direct 'use this instead of X' would push it to 5.

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