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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it defines what 'before' means (next-oldest days WITH DATA, so gaps push the window older rather than empty), warns that the tool does not judge which window is better, and explains the ambiguous `coverage.window_satisfied: false` case with `coverage.more_available` as the disambiguator. That is genuine non-obvious behavior disclosure.

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?

Front-loaded with the core rule before the calendar-period exception, and every sentence carries information (format, precedence, gap semantics, coverage caveat). It is long, but the length is justified by the tool's conditional logic; minor repetition of 'quote' guidance.

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?

An output schema exists, so explaining return values is not strictly required, yet the description usefully frames them (mean/median/min/max plus differences, coverage block) with interpretation caveats. It is nearly complete for a complex tool, with the only real hole being the undocumented `fresh` and `partner` flags.

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 0%, so the description must carry all parameter meaning. It does well for `period`/`baseline` (exact 'YYYY-MM-DD..YYYY-MM-DD' format, open-end allowed) and `days` (ignored when windows are given), but `fresh` and `partner` are completely undocumented in both schema and description, and `series` is only implied. Two of six parameters are opaque, so this is partial compensation.

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?

Opens with a specific verb and resource ('Compare two periods of one series') and immediately distinguishes the two operating modes (newest `days` vs prior `days`, or two named windows). An agent can tell this apart from get_metric_trend or correlate_metric_series without opening the schema.

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 routes the agent: use `period`/`baseline` for calendar-style comparisons ('this semester vs the summer', 'before and after I started training') and fall back to `days` otherwise, with the precedence rule stated ('`days` is then ignored'). No inference required.

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 the safety profile (read-only, idempotent, non-destructive); the description adds real behavioral depth: missing days are dropped rather than interpolated or zero-filled, n_pairs can be smaller than either series, <3 shared days returns null with a reason, and it explains the counterintuitive coverage.window_satisfied=false case. This is exactly the context annotations cannot carry.

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?

Dense and front-loaded: the definition comes first, then lag semantics, then edge cases and output guidance. Every paragraph does work, though the output-handling instruction ('repeat its substance... do not translate r into a word like strong') is a style directive that lengthens the definition beyond strict tool-selection needs.

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?

An output schema exists, yet the description still explains the two fields an agent must reason about (caveat, coverage) and warns against misuse of window_satisfied, which is genuinely useful. It is nearly complete; the unexplained days/fresh/partner parameters are the only real 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?

Schema coverage is 0%, so the description carries the full burden, and it does well for lag_days (including negative semantics and the 'sleep dated by the morning it ends' nuance), series_a/series_b pairing, and since/until format. But days, fresh, and partner are never mentioned, leaving three of eight parameters undocumented anywhere.

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?

Opens with a precise verb+resource: 'Pearson r between two daily series, over days that have BOTH recorded.' That is unambiguous and clearly distinct from siblings like get_metric_trend or compare_metric_periods, which measure trends/period shifts rather than pairwise association.

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?

Gives a concrete use case and the exact invocation for it ('does a short night show up in HRV the day after' = sleep vs HRV with lag_days=1), plus the condition that produces null (<3 shared days). It does not explicitly name a sibling alternative or state when NOT to use it, which keeps it 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?

Annotations already declare `destructiveHint: true`, `readOnlyHint: false`, and `idempotentHint: false`, so the bar is lower. The description still adds substantial context beyond annotations: the entry is overwritten in the cloud, disappears from `get_symptoms` and the app, and the response carries `deleted_entry` so a mistaken delete can be logged again.

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?

Front-loads the core action and then layers conditions and caveats in a logical order. Every sentence adds useful information, though the description is slightly longer than strictly necessary and the parenthetical '(agent write)' is mildly redundant given annotations.

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 destructive single-entry tool, the description covers purpose, usage, alternatives, side effects, and a key restriction. It omits some edge cases such as auth requirements or behavior for a nonexistent `entry_id`, but an output schema exists and annotations already carry the destructive/idempotency profile.

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 is one parameter (`entry_id`) with 0% schema description coverage. The description does not define what `entry_id` is, where to obtain it, or its format; it only mentions `entry_id` incidentally in the `update_symptom` alternative. With low coverage, the description should compensate but does not.

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?

States a specific verb and resource: 'Erase one reported symptom that was logged by mistake.' It also scopes the tool to erroneous entries and explicitly distinguishes it from `update_symptom` and `log_symptom`, so an agent can route correctly without opening sibling schemas.

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?

Gives explicit when-to-use conditions (duplicate, wrong person, symptom they did not have) and an explicit when-not-to-use rule ('A symptom that simply ended is NOT deleted'), naming `update_symptom` as the alternative. It also states a hard limitation: Apple Health imports cannot be deleted here.

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 read-only/idempotent/non-destructive, but the description adds substantial behavior the annotations cannot: token cost per logged day, the `result_too_large` failure mode, filigree of the `coverage` block, and the critical `coverage.more_available` flag that warns against reporting a limit-shaped window as the true extent of history.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but front-loaded and largely earned by the tool's complexity and the near-empty schema. Some redundancy remains (two separate day-capping params, repeated coverage guidance), so it is dense rather than wasteful.

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 an output schema exists, return-value explanation is not strictly required, yet the description usefully explains the coverage/meals/items shape and the failure mode. It is nearly complete for a complex 5-param read tool, short only on the undocumented `fresh` parameter.

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 0% across 5 params, so the description must carry the load. It well explains `limit`, `since`/`until` (format and inclusivity), and touches `limit_days`, but `fresh` is never mentioned and `limit` vs `limit_days` is left ambiguous ('cap how many days return'), which is a real gap for a 0%-coverage 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?

Opens with a specific verb+resource: 'Decrypt daily food-intake logs locally (newest first).' An agent immediately knows this is a read of logged meals, distinct from the sibling writers log_food_entry/log_food_append and from get_strength_log which it referencing-crosses by date format.

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?

Gives clear in-tool routing: use `limit` for 'newest N logged days' vs `since`/`until` for a calendar window ('what did I eat in the first week of August'), and tells the agent to ask for fewer days on `result_too_large`. It does not, however, compare this tool against any alternative sibling (e.g. get_notes), so no explicit when-not 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 already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: HRV is measured sporadically (8-14 rows/day), history length depends on what the phone uploaded rather than a fixed window, and the coverage block must be read for oldest_available/more_available. The only gap is the unexplained `fresh` parameter's effect.

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?

Dense but front-loaded: the core scope lands in the first sentence, then granularity options, then caveats. Every sentence carries information, though the granularity bullet block makes it longer than strictly needed for a read tool.

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?

An output schema exists, yet the description still usefully explains row shape, column order, and the coverage block — appropriate for a data-returning tool. It is nearly complete for an agent's needs, missing only an explanation of what `fresh` does and what it changes.

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 0%, so the description must carry the load, and it does well for three of four parameters: granularity modes are fully defined, limit semantics (rows, default 168 ≈ 2-3 weeks) are clarified, and series is implied as HRV SDNN. `fresh` is never mentioned, leaving one parameter undocumented in both schema and description.

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?

States a specific verb (samples) and a precise scope: within-day samples for series that record multiple times per day (HRV). It explicitly distinguishes itself from get_metric ('For one number per day use get_metric'), so an agent can route between the two without reading schemas.

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?

Gives explicit when-to-use guidance for each granularity mode ('hourly' for how HRV moved through the day, 'raw' for per-sample rows) and names the alternative tool for daily aggregation. It also warns that limit counts rows not days, which prevents a common misuse.

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 readOnly/idempotent/non-destructive, but the description adds substantial context they cannot: the opt-in-only, on-device, never-re-exported sensitivity constraint, plus the return shape (samples + next-period prediction). The detailed `coverage` semantics, including the false-negative trap on `window_satisfied` and the `more_available` re-read instruction, is exactly the kind of behavioral disclosure annotations can't convey.

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 purpose is front-loaded, then structured into sensitivity, routing, and coverage-guidance blocks. It is longer than most definitions, but nearly every sentence (opt-in condition, partner routing, window_satisfied caveat, more_available rule) prevents a specific misinterpretation, so the length is largely earned.

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?

An output schema exists, so return values needn't be enumerated, yet the description still tells the agent how to interpret the `coverage` block correctly. Combined with the privacy and partner-routing context, an agent has everything needed to call this tool and report its results without misreading the window.

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 0%, so the description carries the load, and it does for two of three params: `partner` is explained directly and `limit` is explained through the extended 'limit-shaped window' discussion and the re-read-with-larger-limit instruction. `fresh` is never defined, leaving one undocumented parameter, which keeps this just under full marks.

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?

States a specific verb and resource ('Decrypt recent menstrual cycle data locally and predict the next period'), so an agent knows exactly what it returns before opening the schema. It is clearly distinguishable from siblings like get_symptoms or get_sleep_nights because it is the only cycle/period tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says the tool reads YOUR cycle by default and to pass `partner=true` when the cycle belongs to a partner. That is real routing guidance for the main ambiguity ('whose data'). It does not, however, describe when to prefer this over adjacent tools such as get_metric or get_symptoms, so it stops short of full when/when-not coverage.

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 read-only/idempotent/non-destructive; the description carries far more. It discloses that aggregation is computed server-side, that sum is refused on state measurements, the semantics of period_in_progress/clipped_by_window, partial:true exclusion from aggregates, excluded_days with reasons, missing days never zeroed, and the partner-sharing allowlist (sleep, water, weight only).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Long (~450 words), but front-loaded and organized into labeled blocks (series, days, aggregation/granularity, honesty guarantees, output shape, partner, siblings), and nearly every sentence carries operational content. It is on the verbose edge for a tool description, yet the density justifies most of the 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?

Despite an output schema existing, the description goes further by explaining the columns/rows table shape, the coverage block, and the more_available warning that prevents misreporting the extent of a user's history. For an 8-parameter, multi-mode tool with 0% schema coverage, 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 description coverage is 0%, so the description must compensate, and it does for series, days, since, until, aggregation, granularity and partner — including value formats ('YYYY-MM-DD'), defaults, enum-like options (avg/sum/min/max/latest/none; day/week/month/weekday) and interaction rules (days ignored when since/until given). The one gap is `fresh`, which is never explained anywhere, so coverage is strong but not complete.

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?

Opens with a specific verb+resource: 'Read any one-number-per-day health series: steps, resting HR, HRV, weight', and immediately draws the boundary against siblings (list_metric_series, get_sleep_nights, get_intraday, get_metric_trend, compare_metric_periods, correlate_metric_series). An agent can route to this tool without opening any other schema.

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 when-to-use rules: call list_metric_series first rather than guessing names; use days for 'newest N days that have data' versus since/until for a calendar window; pass the five activity series as a list to get a whole day in one call. It also states exclusions and redirects richer kinds (workouts, food, symptoms, cycle, profile, intraday, trends) to their own 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?

Annotations already carry the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the description's marginal value is its edge-case disclosure: arithmetic only, no threshold/band/verdict, and a null slope with a reason when fewer than 3 days exist. The coverage-block interpretation is useful but partially overlaps the 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?

Front-loaded with the core purpose, then parameter and output semantics in compact sentences. Dense but each sentence carries meaning; slightly long for a trend getter but no 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?

For a read-only trend tool with an output schema, the description supplies the edge-case and interpretation context an agent needs (density caveat, null-slope rule, coverage pairing). The gap is the two undocumented parameters, fresh and partner.

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 0%, so the description must compensate. It meaningfully explains series, days ('newest N days THAT HAVE DATA, not the last N calendar days') and since/until format, but leaves fresh and partner completely undocumented in both schema and description.

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?

States a specific computation and resource: 'least-squares trend for one daily series: slope per day, endpoints, spread.' This clearly distinguishes it from a raw-value sibling like get_metric. It stops short of naming an alternative (compare_metric_periods, correlate_metric_series) to route against.

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 gives condition semantics (series comes from list_metric_series; days vs since/until select different windows), which implies when each parameter applies. But there is no explicit when-to-use-this-vs-another-tool guidance, and no exclusions, so it remains implied rather than directive.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds substantial context beyond them: data stays on-device and is never re-exported, the text is SENSITIVE, and it gives detailed coverage-block semantics (days_covered, span_days, window_satisfied, more_available) that would otherwise mislead. It does not explain the 'fresh' parameter behavior, so not a full 5.

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 purpose and filter behavior are front-loaded, and each block earns its place. It is somewhat long due to the detailed coverage guidance and the red-flag warning, but that content is task-critical rather than padding.

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?

An output schema exists, so return values need not be restated; the description focuses on semantics and interpretation instead. It is thorough for a read tool but leaves the 'fresh' parameter and the exact enum formatting ('sleep' | 'menstrual' | 'mood' | 'general' vs the untyped schema) unaddressed.

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 0% across 4 parameters. The description compensates for partner (explains the about: 'partner' distinction) and target_kind (lists the valid kinds and the filter role), and touches limit indirectly via the larger-limit advice. However, 'fresh' is never explained, so the description only partially covers the undocumented 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?

States a specific verb and resource with scope: 'Decrypt recent free-text notes (day annotations) locally.' It also names the kind categories and the sibling write path (log_note/log_note_append), so an agent can distinguish this read tool from the logging tools without opening schemas.

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?

Gives clear usage context: default returns notes about YOU, partner=true returns notes about the partner, and 'Pass target_kind to filter.' It implies but does not explicitly state when NOT to use this versus alternatives like get_metric or correlate_metric_series, so it falls short of the top tier.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes well beyond that with size/budget warnings (~3k chars per night, 13k with include_timeline), the `is_in_bed_only` non-measurement trap, and coverage-block reporting rules — genuinely useful behavioral context. However, the volume of caveats is disproportionate to the tool's actual behavior, and many are output-interpretation guidance rather than invocation behavior, so it earns solid but not top marks.

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?

Front-loaded with purpose, then clearly delimited routing/returns/SIZE/semantics sections. The parenthetical aside about the tool's former self-description is editorial waste, but most of the length is load-bearing given the size-budget traps and the coverage-reporting contract.

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 6-parameter, 0%-coverage, read-only analytics tool, the description covers invocation parameters, the output shape (stage_intervals/stage_minutes/stage_vitals) despite an output schema existing, size budgets, data-absence semantics, and the coverage block's correct interpretation. Nothing an agent needs to call or interpret 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 description coverage is 0%, so the description carries the full load and does so for limit (newest N, default 2), since/until (exact 'YYYY-MM-DD' format, local day the night ENDS on, and how limit interacts with a window), include_timeline, and partner. Only `fresh` is left unexplained, which is a minor gap against five well-documented 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?

Opens with a specific verb+resource ('Per-night sleep stages with per-stage HR/RR') and immediately scopes it ('depth on a few nights'). It explicitly names and distinguishes both alternatives, `get_sleep_nights` and `get_metric`, so an agent can route correctly without opening any schema.

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?

Contains a dedicated routing block stating when to use this tool (one or two specific nights), when NOT to (anything spanning time, periods), and which sibling to use instead for each case. It even warns against a specific misinference ('do not conclude from THIS tool's two rows that only two nights exist').

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 establish read-only, idempotent, non-destructive behavior, and the description goes well beyond: it discloses approximate output size (~40k chars/year), that column names come once in `columns`, the `legend` flag semantics (`unworn` means never measured, not zero; `motion_inferred` should be excluded from averages), that null means 'not measured, never zero', and that `partner=true` reads a partner's shared data. This is exactly the operational context annotations cannot carry.

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?

It is a long description, but the load-bearing facts are front-loaded (one row per night, newest first, column layout) and the tool-selection routing and legend semantics are each stated once. The length is justified by the tool's complexity, though the schema/legend material is dense enough that it could be tightened.

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?

An output schema exists, yet the description still usefully explains the row/column shape and the `coverage` block (`days_covered` to quote beside averages, `more_available` before claiming history depth), which is high-value context for correct answer framing. Combined with the flag semantics and null rules, coverage is strong; the sole miss is the unexplained `fresh` parameter.

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 0%, so the description must carry the entire burden. It explains `limit` (newest N nights, default 120, 400 for everything), `since` (YYYY-MM-DD, inclusive, overrides guessing a limit), and `partner` (reads partner's shared sleep). However `fresh` is never mentioned anywhere in the description or schema, leaving one of four parameters completely undocumented.

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?

States the resource ('one compact row per night'), the ordering ('newest first'), and the enumeration of every returned column, giving an agent a complete picture of what the tool produces. The explicit 'Which sleep tool' section names the two sibling alternatives (get_metric, get_sleep_detail) and the condition that selects each, so the tool is separable from its siblings without opening any schema.

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?

Gives explicit when-to-use ('any span of time', 'period or a pattern: weekends vs weekdays, drifting bedtimes'), when-to-use-elsewhere (get_metric for precomputed arithmetic, get_sleep_detail for one or two nights), and parameter-level guidance for choosing between `since` and `limit`. Nothing about tool selection is left to inference.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: local decryption, owner's-sessions-only scope (no partner fan-out), duplicate_sessions already excluded from counts, and detailed `coverage`/`more_available` semantics with a warning not to misreport a limit-shaped window as full history. This is rich behavioral disclosure.

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?

Front-loads the core purpose and scopes return fields before the operational caveats. It is long and mostly earns its length given the coverage-safety warnings, though the `coverage`/`more_available` instruction block is dense enough to border on over-explanation.

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 an output schema existing, the description usefully explains the meaning of key return fields (exercise sets, total_volume_kg, duplicate_sessions, coverage block), which the schema alone would not convey. For a 3-param read tool it is complete enough to call correctly and interpret results 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?

Schema description coverage is 0%, so the description must compensate. It explains `limit_days` ('cap how many sessions return') and references `limit` indirectly ('re-read with a larger `limit`'), but never explains the `fresh` parameter at all, leaving one of three params undocumented in both schema and description.

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?

States a specific verb+resource ('Decrypt recent strength-training sessions locally') with ordering (newest first) and explicitly distinguishes itself from the sibling `get_workouts` by noting it carries exercise-level detail HealthKit's workout type cannot. An agent can pick this over `get_workouts` without opening a schema.

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?

Gives clear usage context: join `date` against sleep/HRV/weight for training-load analysis, and pass `limit_days` to cap results. It implicitly contrasts with `get_workouts` via the HealthKit remark, but never explicitly states when NOT to use it or names an alternative to prefer for non-strength data.

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 readOnly, idempotent, non-destructive behavior, but the description adds substantial context: sensitive on-device data, Apple Health opt-in requirements, partner reported episodes never reaching the caller, empty partner reported meaning 'not shareable', and coverage.more_available pitfalls. This far exceeds the safety profile provided by 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?

Front-loads the core purpose and uses structured bullets for complex source and coverage differences. However, it is very long and enumerates many return fields despite an output schema already existing, so it is not maximally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, sensitive tool with an output schema, it covers source distinctions, partner limitations, correction workflows, and coverage caveats well. The main omission is the fresh parameter, and some return-field explanation duplicates the output schema.

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 0%, so the description must compensate. It clarifies partner=true and references using a larger limit in the coverage warning, but it never explains the fresh parameter, leaving one of three parameters undocumented.

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?

States a specific verb ('Decrypt') and resource ('symptoms'), with scope 'grouped by data owner — both sources' and default/partner behavior. It also distinguishes correction paths by naming update_symptom/delete_symptom, so an agent can tell what this tool is for.

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?

Explains that it returns YOUR symptoms by default, that partner=true returns only a partner's Apple Health days, and that reported entries are corrected via update_symptom/delete_symptom. It lacks an explicit comparison to unrelated siblings like get_metric/get_notes, but gives clear usage context and alternatives for mutation.

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 cover readOnly/idempotent/non-destructive/closed-world, yet the description adds substantial behavior the structured fields cannot: every field may be null, `profile` is null when nothing was uploaded, the reply's `note` explains why, nulls must never be guessed, and the row is replaced in place so there is no upload timestamp indicating currency. It even clarifies that a profile is not a series and `coverage.days_covered` is 0 by construction.

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 purpose and the pre-requisite use case are front-loaded in the first two paragraphs, and each subsequent sentence carries a distinct constraint (null handling, no partner, non-series semantics, no upload time). No filler or restatement of the name.

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 an output schema present and no nested objects, the description need not describe return shapes, yet it still pre-empts the two most likely agent errors: treating a profile like a time series and hallucinating values for null fields. Nothing needed 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 description coverage is 0% and the sole parameter `fresh` is never mentioned, let alone explained (is it a cache bypass? a re-read?). The description compensates richly for output semantics but leaves the one input entirely undocumented, which is the reverse of what a low-coverage schema requires.

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?

States a precise verb and resource ("Read YOUR health profile") and enumerates the exact fields returned: biological sex, age, date of birth, height. It also differentiates from siblings that take a partner option by asserting this tool has none, so the agent can place it relative to get_metric/get_symptoms without opening a schema.

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?

Gives an explicit use condition: call it before anything depending on sex, age or height (BMR, HR zones, VO2 max bands, BMI). It also states a constraint (no partner option), which functions as a when-not. It stops short of naming a sibling alternative or a case where a different profile-ish tool should be preferred.

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 establish a safe read-only, idempotent profile, and the description layers on substantial non-obvious behavior: server-side decryption, the fact that the returned window is capped by `limit`, and the critical caveat that coverage.window_satisfied=false and coverage.more_available=true can mask older available history. This is exactly the kind of data-completeness behavior an agent cannot infer from structured fields.

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?

Front-loaded with purpose in the first sentence, then progressively narrower interpretation rules. The coverage guidance is dense and slightly repetitive ('Never report a limit-shaped window as the extent of their data' restates the more_available warning), but every block still carries actionable 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?

An output schema exists, so return values need no explanation, and the description nonetheless documents the coverage block's interpretation rules thoroughly. What's missing is the meaning of the `fresh` parameter and any routing versus the strength/metric siblings, which keeps it short of fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the load. It functionally explains `limit` (it truncates older days, and a larger value reveals more history) but never mentions `fresh` at all, leaving one of two parameters entirely undocumented anywhere.

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?

States a specific verb and resource ('Decrypt recent workout sessions') and enumerates the payload fields (type, duration, calories, distance), so the agent knows exactly what comes back. It also delimits scope by declaring workouts are never partner-shared, which separates it from the partner-aware siblings in this server.

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?

Gives clear context ('Reads YOUR workouts', no partner option) and detailed instructions on how to consume the result safely. It does not, however, say when to prefer this over adjacent siblings such as get_strength_log or get_metric, which is a real gap given the overlapping fitness-domain 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?

Annotations already declare the safe read-only idempotent profile, yet the description still adds real behavioral context beyond them: what `rows` counts, that `cumulative: true` series have routinely-partial newest values that must not be compared to completed ones, and that state measurements carry `false`. That partial-day caveat is exactly the kind of trap an agent would otherwise fall into.

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?

Front-loaded with the key instruction, then dense supporting detail where every paragraph (rows semantics, cumulative warning, sleep note, deliberate absences) earns its place. It runs long, but no sentence is 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?

An output schema exists so return values needn't be described, and the description still adds the useful semantics of the returned fields. The one real hole is parameter meaning — an agent can call it with defaults, but cannot knowingly use `fresh` or `partner` from this text.

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 0% and the description never explains the `fresh` parameter at all, nor defines what `partner` filters. `partner` is only obliquely implied by the example about 'a partner with 14 weigh-ins.' With two undocumented booleans, the description does not compensate for the schema gap.

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?

Opens with a specific verb+resource and scope: 'Every series, with how much data actually backs each one.' It explicitly distinguishes itself from get_metric (rows counted the way get_metric reads it), get_sleep_nights, and the richer-shape tools that are deliberately absent, so an agent can place it against siblings without opening any schema.

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?

Gives an explicit when-to-use imperative ('Call this BEFORE guessing a `series` name, and before concluding a kind is empty') and names the concrete alternative tools for the cases it excludes (get_sleep_nights for nights, 'their own tool' for workouts/strength/food/notes/symptoms/cycle). The routing is 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?

Far exceeds what annotations declare. It explains the merge behavior by meal name, that replaced_meals is always [] as a deletion receipt, that no note can be set, and the E2E encryption. Annotation destructiveHint=false is corroborated, not contradicted.

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?

Front-loads the core append semantics and the log_food_entry contrast, with clear paragraph separation. The photo-estimation paragraph is somewhat long and contains an editorial comment ('keep the photo-estimation paragraph above in sync') that is meta-instruction rather than tool guidance, slightly diluting focus.

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 a mutation tool with no param docs in the schema, this covers interaction semantics, parameter shapes, return value shape, failure modes, and side effects. Nothing an agent needs to invoke 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 0%, so the description must compensate—and it does thoroughly: date format 'YYYY-MM-DD', full meals object shape with every field, a concrete example, optional-field rules, accepted snake_case aliases, and photo-estimation heuristics. It adds far more meaning than the bare 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?

States a specific verb+resource (append meals to a day) and explicitly distinguishes from its sibling: 'Reach for log_food_entry ONLY when you intend the supplied meals to become the day's ENTIRE log.' The append-vs-replace semantics are 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?

Explicit when-to-use ('log the snack I forgot', 'add dinner to today', almost every follow-up write) and when-not-to-use (log_food_entry for full replacement). It even closes loopholes by explaining why note-setting is excluded. Nothing is left to inference.

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 destructiveHint=true, and the description goes well beyond that by naming exactly what is destroyed (any meal not re-sent), how the caller can detect it (replaced_meals in the result), the note=None vs note="" semantics, the deprecation status of merge, and that data is encrypted end-to-end. This is exactly the kind of context annotations cannot carry.

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?

It is long, but the length is justified: the destructive warning is front-loaded in caps before any detail, and each subsequent paragraph covers a distinct failure mode (accidental deletion, note clearing, date locality, photo estimation). The only waste is the leaked editorial note about keeping the photo paragraph in sync with log_food_append, which is boilerplate for maintainers rather than agents.

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 destructive, 4-parameter write tool with an output schema, the description covers the risks an agent needs to call it safely: replacement semantics, recovery via replaced_meals, note handling, and estimation guidance. Return-value shape is left to the output schema, which is the right division of labor.

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 0%, so the description must carry the full burden and does: date format and timezone semantics, the nested meals shape with a concrete example, which fields are optional, accepted snake_case aliases, and the non-obvious note=None behavior. merge is also explained as a legacy alias.

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 ('Log one day's food intake on the owner's behalf') plus the critical scope fact that it replaces the whole day rather than adding to it. It explicitly names the sibling it is not (log_food_append), so an agent can route correctly without opening either schema.

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 gives an explicit when-not rule with a stop condition ('If you meant to ADD to a day rather than replace it, STOP and call log_food_append instead; it cannot delete anything'), and explains the legacy merge=True path and why new callers should prefer the separate tool. Nothing about tool selection is left to inference.

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 destructiveHint=true, and the description goes well beyond that: it explains the one-note-per-(kind,day) model, that text becomes the ENTIRE contents, that existing text is silently deleted, the replaced_text recovery path, E2E encryption, and partner-account scoping. This is exactly the extra context a destructive tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the destructive warning, but the merge=True legacy explanation and the repeated deletion caveat make it longer than strictly necessary; still, each block targets a distinct failure mode so little is 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?

Covers read-back via get_notes, the replaced_text output field (so no separate return-value explanation needed), encryption, and partner isolation — complete for a destructive 5-param tool with an output schema.

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 0%, so the description carries full burden and does: date format ('YYYY-MM-DD', default today), kind values, text semantics (replaces, not appends), merge as a legacy alias, and partner=true meaning a note about the partner stored in the caller's own account.

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?

States a specific verb+resource ('Log a free-text note on the owner's behalf') and immediately distinguishes itself from siblings by naming log_note_append and log_symptom as the wrong destinations for certain content.

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 routes: narratives vs chat history, kind='mood' vs 'general', sleep/menstrual notes refused, add-intent should go to log_note_append, symptoms to log_symptom. When-to-use and when-not-to-use are both covered with concrete examples.

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 say readOnlyHint=false and destructiveHint=false. The description adds substantial behavioral context: it cannot delete existing content, `replaced_text` is always null as a 'receipt', it refuses sleep/menstrual notes, it is end-to-end encrypted before leaving the machine, and `partner=true` isolation semantics. This goes well beyond the 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?

It is long but front-loads the core append semantics, then layers distinctions and parameter notes. Every paragraph earns its place, though a few parentheticals could be tightened. The structure is logical and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, 0% schema description coverage, a mutation with no destructive annotation, and an output schema, the description covers everything an agent needs: what it does, what it refuses, how to read back via `get_notes`, parameter meanings, and return shape (same as `log_note`, `replaced_text` always null).

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 0%, so the description must carry parameter meaning, and it does: it explains `kind` values 'general' vs 'mood' and that sleep/menstrual are refused, `date` format is LOCAL 'YYYY-MM-DD' defaulting to today, `partner=true` records a note about the partner stored in your account and excluded from plain reads, and `text` is the appended line.

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 with scope: 'Add a line to a day's note WITHOUT erasing what is already there.' It immediately distinguishes itself from the sibling `log_note` by contrasting append vs. replace behavior, so an agent can select correctly without inspecting schemas.

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 gives explicit when-to-use (append to an existing note, the normal case of a second note of the day), when-not-to-use (`log_note` only when replacing the entire contents), and points to an alternative for symptoms (`log_symptom`). This is exactly the routing guidance needed among several sibling write 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?

Annotations confirm non-destructive, non-idempotent write, and the description adds substantial context beyond them: matching-name exercises get their sets appended, notes cannot be set (replace-only), auth/pairing requirement is documented, and encrypted end-to-end is 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?

Front-loaded with the core behavior and the sibling contrast. Slightly verbose in the encryption/auth paragraph, but every sentence carries information (the pairing requirement is actionable).

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?

Output schema exists and the description confirms `replaced_exercises` is always `[]`, explaining its semantic meaning. Auth prerequisites, side effects on existing data, and the note-field restriction are all covered — nothing important 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 0%, so the description carries full burden — and it delivers: `date` format ('YYYY-MM-DD' LOCAL calendar day) and full example of the `exercises` array structure with nested sets (weightKg/reps).

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?

States a specific verb and resource ('add exercises to a session') and clearly contrasts the behavior with the sibling `log_strength_entry` (append vs. full replace). An agent can immediately tell this apart from `log_strength_entry` and `log_food_append`.

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 names when to use this tool ('log the set I forgot', logging in installments) and when NOT to use it ('Reach for `log_strength_entry` ONLY when...'), even describing the consequence of the wrong choice (everything else deleted).

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 flag destructiveHint=true, but the description goes far beyond them: it explains exactly what is destroyed (unlisted exercises silently deleted), surfaces the replaced_exercises result field as a verification signal, documents note=None vs note="" semantics, and discloses encryption plus a bind/version prerequisite with remediation.

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?

Front-loads the destructive warning before any procedural detail, which is exactly right. It is long, and the merge=True parenthetical and the re-pair remediation could be trimmed slightly, but nearly every sentence conveys operational information an agent needs.

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 destructive 4-parameter write with a nested payload, zero schema coverage, and a sibling that does the opposite, the description covers deletion semantics, verification via replaced_exercises, parameter edge cases, and the auth prerequisite. 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 description coverage is 0%, so the description carries the full burden and does: date is the LOCAL calendar day in YYYY-MM-DD, exercises is given a concrete nested example, note=None preserves the existing note while note="" clears it, and merge's legacy behavior is explained.

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?

States a specific verb and resource ('Log one strength-training session') and immediately distinguishes itself from the sibling log_strength_append by declaring it REPLACES the day. An agent can tell the two tools apart without opening either schema.

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 when/when-not routing: 'If you meant to ADD to a day rather than replace it, STOP and call log_strength_append instead; it cannot delete anything.' It also explains the merge=True legacy path and why new callers should prefer the separate 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?

Annotations already declare destructiveHint=false and idempotentHint=false, but the description adds real context: it is strictly append-only ('cannot change or delete anything already recorded'), returns an entry_id to hand to update/delete, and is end-to-end sealed for the owner and machine. That is concrete behavior beyond the structured hints, with 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?

Front-loaded with purpose and the one-per-symptom rule, then organized field-by-field in visually scannable blocks using the exact parameter names. Given nine parameters and zero schema coverage the length is justified, though a few parenthetical asides (e.g. the trailing examples after the Apple Health list) could be trimmed.

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?

An output schema exists, so the description only needs to name the key return value, which it does ('entry_id ... and the entry as read back'). For a nine-parameter, 0%-schema-coverage mutation tool with no enums, the description closes every gap an agent would otherwise hit, including timezone handling and the do-not-invent severity/timing rules.

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 0%, so the description carries the full burden and does: it defines symptom_type naming conventions with merge rationale, supplies the severity enum (mild|moderate|severe|unspecified) that the schema lacks, and specifies ISO 8601 + UTC offset formats and edge-case defaults for onset_at, end_at, and date. It also constrains triggers to the user's own suspicion rather than invented causes.

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?

States a specific verb and resource ('Record one symptom the person reports') and immediately scopes the cardinality ('one call per symptom'). It explicitly distinguishes itself from log_note ('This is where ... goes, not a note') and names the sibling read/update/delete tools, so an agent can route without opening a schema.

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?

Gives explicit when-to-use rules ('Two symptoms at once are two calls'), explicit when-not ('not a note'), and names the alternatives with their conditions (update_symptom to add an end time later, get_symptoms to read, delete_symptom to remove). Routing is fully determined by the text.

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?

Goes well beyond annotations: it discloses upsert-in-place keying (dayID = body-{dayStart.epoch}), end-to-end encryption before data leaves the machine, the dual write destination (Vaultbeat cloud + MCP, conditionally Apple Health), and a corruption failure mode from double-entry. The 'overwrites' semantics align with destructiveHint=true and the replace-day title.

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 actionable content is front-loaded (units, params, upsert semantics) before the propagation details. It loses a point for changelog-style asides — dated stamps like '(agent write, 2026-07-21)' and the parenthetical about the pre-2026-07-28 docstring — that document history rather than guide invocation.

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 mutation tool with an output schema already present, nothing an agent needs is missing: constraints, date semantics, overwrite behavior, encryption, downstream destinations, and the Apple Health toggle dependency are all stated. Return-value details are correctly left to the output schema.

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 0%, so the description must carry the load and it does: `weight_kg` is constrained (positive, ≤500) and `date` is defined as a LOCAL calendar day in 'YYYY-MM-DD' with a stated default of today. Neither constraint appears anywhere in the schema itself.

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?

States a specific verb and resource with units and actor: 'Log the owner's weight (kg) on their behalf'. It also distinguishes itself from the read path by naming the sibling surface (`get_metric` series "weight_kg") where the written data appears, so an agent can route write vs. read without opening schemas.

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 covers when to use it (agent-side weigh-in logging), what happens on repeat calls ('re-logging the same day overwrites'), and the alternative interaction pattern to avoid ('do NOT tell them to re-enter it by hand in the Vaultbeat weight card'). It also names the prerequisite for Apple Health propagation and the exact UI path to enable 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?

Despite annotations covering the safety profile (destructiveHint=true, idempotentHint=false), the description adds critical behavior beyond annotations: overwrite semantics (note replaces rather than appends, triggers replaces the whole list), clearing conventions ('' and []), the read-back contract (returns previous plus entry as read back), and an edit restriction for Apple Health imports. This is exactly the extra context needed for a destructive, non-idempotent mutation.

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?

Front-loaded with the common call and its trigger, then layers overwrite, clearing, sourcing, and return semantics. Every paragraph earns its place, though it runs several dense sentences and could tighten slightly.

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 10-param, 0%-coverage destructive mutation with an output schema, the description covers the partial-update model, overwrite/clear rules, id sourcing, edit exclusions, and return shape. 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 0%, so the description must carry parameter meaning. It supplies the critical partial-update semantics ('only the fields you pass change; omitted ones keep their value'), explains entry_id sourcing, and defines special values ('' clears text/end_at, [] clears triggers). This is substantially more than the bare schema titles.

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?

States a specific verb (change fields) and resource (one reported symptom), clarifies it targets a single entry by entry_id, and differentiates from siblings like log_symptom and delete_symptom by noting it only modifies given fields.

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?

Gives concrete when-to-use examples ('when the person says it has stopped' → end_at, 'when it got worse' → severity) and explicitly excludes a case: symptoms imported from Apple Health cannot be edited here. Names the source tools for entry_id (log_symptom, get_symptoms).

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context: it performs a cloud round trip (latency warning), explains what each report section means, warns that a passing report does not clear the client side, and flags env_overrides_received as something to inspect. This is behavior the annotations cannot convey.

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?

Front-loaded with purpose, then cleanly sectioned with backticked field names (checks, capabilities, scope, binding). It is longer than typical, and some of the field-by-field explanation overlaps the output schema, but each section carries real diagnostic meaning rather than 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?

For a zero-arg diagnostic with an output schema and strong annotations, this is complete: it covers when to call it, what each result section means, how to interpret empty vs unchecked kinds, and the limits of a green report. An agent needs nothing else to invoke and interpret 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?

There are zero parameters, so the schema carries no parameter semantics to compensate for; baseline 4 applies. The description's detail about the report shape describes outputs (also covered by the output schema) rather than adding parameter meaning.

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?

States a specific verb (diagnose), an explicit resource (this Vaultbeat MCP install), and a concrete deliverable (which data types are unavailable). It is unambiguously distinguishable from the read/log siblings, which fetch data rather than test the install.

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?

Gives a precise trigger condition: 'Call this when a read tool returns nothing, or when anything fails, before telling the user their data is missing.' This routes the agent away from a specific failure mode. It does not name a particular sibling tool or state an explicit when-not, so it stops 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.