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?

Goes well beyond the destructiveHint=true annotation by disclosing the full cascade: immediate removal from get_state_of_mind, next-sync removal from the iPhone app, cloud content overwrite for all shared readers, and Apple Health sample deletion. It also notes the deleted_entry payload enabling re-logging and the apple_health source restriction — rich 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?

Front-loaded with the core intent and the when-to-use condition, then layered with consequences. Slightly long, but nearly every sentence adds distinct operational value (cascade effects, return payload, source restriction).

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 enumerated, yet the description still flags the deleted_entry payload. Combined with the usage exclusions, cascade effects, and source restriction, an agent has everything needed to invoke this destructive 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 0% and the description never explains the entry_id parameter or where to obtain it. It references related structures (get_state_of_mind, source values) but does not add semantics for the single required parameter, so the schema underspecification is only partially compensated.

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 state of mind'), scopes it as an agent write, and immediately distinguishes the intent from the sibling log_state_of_mind. An agent can identify the operation 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 states the only valid use case (an entry that should never have existed — duplicate, wrong reading, wrong person) and names the alternative behavior ('To record that a feeling changed, log a new one'). It also gives an exclusion: apple_health-sourced records 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so safety is covered structurally. Beyond that, the description discloses propagation timing (vanishes from get_symptoms immediately, from the app and other readers after the next iPhone sync), a version-dependent side effect on earlier update_symptom copies, and the returned deleted_entry payload that allows re-logging. This is unusually rich behavioral context that annotations cannot express.

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 core decision (when to delete vs. not) and the alternative are front-loaded before the sync-propagation detail. The long parenthetical about app 1.3.0 and sealed copies is dense but does describe a real behavioral caveat, so it earns its place even if 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?

For a destructive tool with an output schema, this covers the destructive scope, the path to recover a mistaken delete, the sibling to use instead, and a hard exclusion (Apple Health imports). An agent has everything needed to decide and invoke correctly; return values need not be explained further given 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% for the single entry_id parameter, so the schema does not define it. The description references entry_id by name in the sibling example but never states what identifies it, its format, or how to obtain it (presumably from get_symptoms). It adds partial context but does not fully compensate for the coverage 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?

States a specific verb and resource ('Erase one reported symptom'), constrains scope ('that was logged by mistake'), and explicitly carves out the boundary against the nearest sibling by naming update_symptom as the tool for symptoms that ended. An agent can distinguish this from log_symptom and update_symptom 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 cases (duplicate, wrong person, symptom they did not have), an explicit when-NOT case ('a symptom that simply ended is NOT deleted'), the alternative to use instead with exact call syntax (update_symptom(entry_id, end_at=…)), and an additional exclusion (Apple Health imports cannot be deleted here). 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 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?

Goes well beyond the readOnly/idempotent/closed-world annotations: states data stays on-device and is never re-exported, flags the content as SENSITIVE free text, and warns about the coverage-block semantics (days_covered vs row count, window_satisfied ambiguity, more_available meaning days older than first_day exist). This is exactly the behavioral 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?

Front-loaded with the core purpose and every section (kinds, partner scope, coverage warnings) adds decision-relevant information, so the length is largely earned. Structure suffers from awkward mid-sentence line breaks and some density, but there is little true 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, yet the description still explains the coverage block an agent must quote correctly and the more_available trap that prevents misreporting history extent. Combined with the kind taxonomy and partner scoping, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning and largely does: it enumerates the target_kind values and their provenance, defines partner=true, and implies limit's role via the 'limit-shaped window' warning and 're-read with a larger limit'. The fresh parameter is never explained, which is the one 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?

States a specific verb and resource ('Decrypt recent free-text notes (day annotations) locally') and immediately distinguishes itself from siblings by explaining that mood notes live in get_state_of_mind and new notes are written via log_note/log_note_append. An agent can tell exactly what this tool retrieves and what it does not.

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 routing context: pass target_kind to filter, use partner=true for partner-authored/partner-about notes, read legacy mood notes here but write no new ones. It stops short of a crisp when-to-use-vs-alternative rule (e.g. no explicit 'use get_notes vs get_state_of_mind when...'), but the implicit guidance is strong.

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 establish the safe-read profile (readOnly, idempotent, non-destructive, closed world), and the description goes well beyond them: it flags the data as SENSITIVE, states it stays on-device and is never re-exported, discloses the `result_too_large` failure mode with its size math, and explains the `coverage` block, `window_satisfied`, and `more_available` semantics so the agent does not misreport history extent. This is unusually rich behavioral context.

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?

Purpose is front-loaded and the dense body is mostly load-bearing (window semantics, coverage interpretation, size limits). It is long and occasionally repetitive — the coverage/more_available guidance restates itself across several sentences — but almost every line changes how the agent should call or interpret the 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, so return shape needn't be spelled out, yet the description still supplies the interpretive context an agent needs (per-record fields, per-owner daily tallies, the warning not to treat a record-less day as neutral, and how to quote `count` and `coverage` beside averages). For a multi-source, paged, sensitive read tool this is complete.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does so for four of five params: `since`/`until` format and inclusivity, `limit`'s conditional application, and `partner`'s sharing precondition. The `fresh` parameter is never mentioned in either the schema or the description, leaving one 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?

States a specific verb and resource ('Decrypt recent states of mind') with an immediate gloss of what the resource means ('how the person felt'), and distinguishes itself from the write path by naming `log_state_of_mind` and `delete_state_of_mind` as the tools for recording/removing. An agent can separate this read tool from its siblings 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?

Explicitly covers when to use the default page (newest 100), when to switch to a `since`/`until` window ('how was I in March', data older than the default page), how `limit` interacts with a window, how to page around the ~130-record result cap, and the condition for `partner=true`. It also routes removal to `delete_state_of_mind`. 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 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 establish a safe read (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: sensitive on-device data never re-exported, partner sharing semantics ('empty reported means not shareable, not none logged'), coverage-block caveats, and the warning that each list is cut independently by `limit`. This is exactly the behavioral depth the dimension rewards.

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 bulleted structure to separate the two data sources, with the load-bearing limit caveat at the end. It is dense and long, but nearly every sentence carries actionable information; only the repetitive coverage-block explanation 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?

Output schema exists, yet the description still supplies the interpretive schema the agent needs: field-level meaning, count semantics (days vs episodes), the coverage quotation rule, and the limit-trap warning. For a sensitive, multi-source, share-gated tool, nothing essential to correct invocation 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 all parameter meaning. It richly explains `partner=true` and the per-list `limit` behavior (including the 'one day can return one report' warning), but `fresh` is never mentioned, leaving one of three parameters 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 and resource ('Decrypt recent symptoms locally, grouped by data owner') and immediately distinguishes the two sources (Apple Health 'days' vs self- 'reported' episodes). An agent can tell it apart from log_symptom/update_symptom/delete_symptom, which are explicitly named as the write/delete path.

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?

Clear context: it routes corrections/removals to update_symptom/delete_symptom, explains that imported days are edited in Apple Health, and defines the partner=true scope. It lacks an explicit 'use this when...' trigger and does not explain the `fresh` flag's role, so it stops short of full when/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 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 already flag destructiveHint=true, but the description goes far beyond: it explains the one-note-per-(kind, day) model, that text becomes the ENTIRE contents and prior text is silently deleted, that replaced_text in the result signals an unintended destruction, and that content is end-to-end encrypted before leaving the machine.

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?

Purpose and the destructive warning are front-loaded and the prose is organized into scannable blocks, but it is long and repeats itself — the replace-vs-append danger is stated in the warning, again in the merge paragraph, and again in the replaced_text paragraph.

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, five-parameter write tool this covers everything an agent needs: routing to siblings, destruction semantics, date format, partner isolation, read-back path via get_notes, and recovery guidance. An output schema exists, yet the description still usefully calls out the one field that matters (replaced_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 coverage is 0%, so the description carries the full burden and does: date format and default, kind default and the only accepted value, text's replace-not-append semantics, merge's back-compat behavior, and partner's storage/isolation semantics. All five parameters are given meaning beyond their bare names.

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 up front ('Log a free-text note on the owner's behalf') and immediately narrows scope: only kind='general' is written. It explicitly names what this tool is not (log_state_of_mind, log_symptom, log_note_append), 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?

Explicit when-to-use and when-not-to-use rules: feelings go to log_state_of_mind, symptoms to log_symptom, additive writes to log_note_append, and kind='mood'/sleep/menstrual/day notes are refused. It even explains the routing mechanism (separate tool vs buried flag) and which is visible to the owner.

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 annotations, the description clearly discloses that the tool appends and cannot delete existing content, that `replaced_text` is always `null` as a receipt of no deletion, and that data is encrypted end-to-end. It also explains the `partner=true` storage and visibility model in concrete terms, which is valuable behavioral context not captured by 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?

The definition is front-loaded with the key append-versus-replace distinction, and the remaining paragraphs add useful routing and behavioral context. It is longer than typical, but most of the length is justified by the number of sibling tools and the non-obvious partner/encryption semantics.

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 an output schema, so the description need not fully document return values, but it still notes that `replaced_text` is always `null` here. Combined with the explicit alternative-routing guidance and complete parameter explanations, an agent has enough information to call this tool correctly without opening sibling schemas.

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: it defines `date` as a local calendar day in `YYYY-MM-DD` format, explains `kind="general"` as the default and only writable kind while refusing `kind="mood"`, and fully specifies `partner=true` versus default behavior. It also makes clear that `text` is appended as a new 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 and resource: it appends text to a day's note without erasing existing content. It also explicitly distinguishes this append behavior from `log_note`, which replaces the note, so an agent can choose correctly without inspecting 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 explicit when-to-use and when-not-to-use guidance, including telling the agent to use `log_note` only when replacing the entire note and to use `log_symptom` for symptoms. It further routes feelings to `log_state_of_mind`, explains the `kind="general"` default, and clarifies partner-note 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 declare non-read-only, non-destructive, non-idempotent; the description adds the append-only guarantee ('only ever adds'), the iPhone write gate that is off by default, the app-version caveat for the mood calendar, the returned `entry_id`, and the encryption/partner-sharing implications of `note`. That privacy warning about who can read `note` is exactly the kind of context structured fields 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?

Purpose and trigger come first, then per-parameter guidance, then a caveats paragraph — a sensible front-loaded order with no filler sentences. It is long, and the multi-line example and encryption sentences are dense, but nearly every line carries operational information an agent would otherwise get wrong.

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?

A seven-parameter write tool with a 0%-coverage schema, a 0% description deficit would be fatal here, and none exists; return values are backed by an output schema and are nevertheless summarized (`entry_id` plus the entry as read back). Write-gating, privacy of `note`, and the delete counterpart are all present, leaving nothing essential to inference.

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 seven parameters — and it does: valence gets the -1..+1 scale plus Apple's seven-region mapping and an anti-dramatisation rule, labels and associations get controlled vocabularies with a 'leave it empty rather than guess' rule, kind gets both allowed values with their meanings, and logged_at/date get concrete ISO formats and a 'do not invent an hour' constraint.

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 concrete verb+resource ('Record how the person says they feel, as Apple Health's State of Mind') and anchors it with realistic utterance examples that map directly to the trigger condition. It is trivially distinguishable from `get_state_of_mind` (read) and `delete_state_of_mind` (remove a mistaken one), both of which are named.

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 when to use ('when they tell you how they feel'), why it matters ('people rarely open an app to log a feeling'), the cadence ('one call per feeling'), and the corrective path via `delete_state_of_mind`. It also points to `get_state_of_mind` for reading back, covering the alternative-selection burden completely.

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 the annotations (destructiveHint=true, readOnlyHint=false): same-day upsert-in-place with the dayID scheme, end-to-end encryption before data leaves the machine, the Apple Health sync side effect gated by a default-OFF iOS setting, the hard refusal condition when the setting is off, and the corruption risk of duplicate entry. This is exactly the behavioral context annotations cannot express.

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 action and parameter semantics before the longer environmental caveats, so the critical path is readable first. It is longer than the two-parameter schema strictly requires, and internal details like 'dayID = "body-{dayStart.epoch}"' add length without helping the agent decide or call.

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 same-day upsert with an output schema already present, the description covers everything an agent needs: the mutation and its overwrite behavior, the prerequisite iOS setting, the failure mode and required error handling, and the read path. Nothing material 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 carry the load and does: weight_kg is kilograms, positive, ≤500; date is a LOCAL calendar day in 'YYYY-MM-DD' format defaulting to today. Both parameters are given units, format, bounds, and default semantics that the raw schema lacks.

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: logging the owner's weight (kg) on their behalf, with the title additionally marking it as a day-replacing write. It is clearly distinguishable from siblings such as log_strength_entry, log_food_entry, and log_symptom 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-not guidance: when no iPhone has the Apple Health setting on, the write is refused, the agent should pass the error on and not retry until the user acts. It also names the correct alternative path (read via get_metric 'weight_kg', phone syncs to Apple Health) and forbids the wrong workaround (re-entering by hand in the Vaultbeat weight card).

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.