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

Adds substantially beyond annotations: exact file written, explicit statement that Apple Health and app-owned files are untouched, read-only visibility in the app, the returned id prefix, idempotency fallback rules, and three distinct refusal conditions including passphrase sealing.

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, then constraints, then return value, then failure modes — a sensible order. Dense but every clause carries information; the file-path clause is slightly verbose but justified by the safety point it makes.

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

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

With no output schema, the description still specifies the return shape (stored event with agent-prefixed id). Mutation side effects, idempotency, and failure modes are all covered, so an agent can call it safely without further context.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra by explaining the idempotency fallback (same date/type/title/endDate when no clientEventId is supplied), which the schema does not state. Range-vs-point event semantics are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource ("Log a context event") with concrete examples (medication start, habit change, visit, trip) that map onto the type enum. Clearly a write-side counterpart to list_events/remove_event in the sibling set.

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 clear trigger ("the user tells you about") and an explicit precondition ("Ask the user before logging anything they did not state"). Refusal conditions (demo mode, unwritable folder, encrypted export without passphrase) are enumerated, though no sibling tool is named as an alternative for reading these events back.

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 safety (readOnlyHint, idempotentHint, openWorldHint=false), so the description's job is to add context — and it does: the event day is excluded from both sides, and the answer contains aggregate, change, and percent change. It stops short of noting how missing data or partial periods are handled.

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

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

Two dense sentences that front-load the core comparison and then the anchor shortcut; nearly every clause earns its place. The nested parentheticals make it slightly harder to scan than a truly crisp definition.

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

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

With no output schema, the description helpfully sketches the return values, and the anchor semantics are covered. The gap is the required metric argument: an agent still doesn't know what strings are legal or whether it must call resolve_metric first.

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 only 40%, so the description must compensate. It explains the anchor-vs-periodA/periodB tradeoff and the event-day exclusion well, but the required 'metric' parameter is documented nowhere — no valid values or pointer to list_metrics/resolve_metric — and excludeTravelDays is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — 'Compare a metric between two arbitrary date periods (A vs B)' — and even states the shape of the answer (each aggregate plus the change and percent change). It does not name a sibling such as get_trends or correlate_metrics to sharpen the boundary, which keeps it below a 5.

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 two clear invocation modes: pass periodA/periodB explicitly, or pass anchor {eventId, days} for the 'before/after question'. That is real usage guidance, but it offers no exclusions or comparison against alternatives like get_trends or correlate_metrics.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important quirks: r is withheld below 10 aligned pairs, the function returns both means, and the answer always carries an association-not-causation caveat. It also clarifies lag orientation clearly. This is exactly the kind of behavioral information an agent needs and cannot infer from 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?

Three concise, information-dense sentences. Every sentence contributes: the first defines the operation, the second explains the lag and return values, the third provides the necessary interpretation caveat. There is no filler or repetition of schema 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?

For a read-only correlation tool, the description covers the key computation, lag behavior, return fields, sample size threshold, and the contextual caveat. Its main omission is clear default behavior for unlimited or unspecified start/end windows, and it does not describe how alignedPairs is structured. Given there is no output schema, slightly more return-format exposure would make it 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?

The description adds useful meaning beyond the schema: it explains lag direction, default value, and relationship between aligned daily values. It also identifies the roles of metricA and metricB. Schema coverage is about 60%, and the description compensates for the missing metricA/metricB descriptions, though it does not elaborate on start/end bound semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific operation with a clear verb and resource: 'Pearson correlation between two metrics' daily values.' This is distinct from sibling tools like get_trends or compare_periods because it focuses on pairwise correlation rather than trend direction or period comparison.

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

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

The correlation intent is clear, and the lag semantics are explicitly explained, but the description does not state when to prefer this over alternatives like get_trends, compare_periods, or list_metrics. The decision context is implied rather than explicit, and no exclusions or alternative tools are named.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail beyond those: the phase-label rule, the derived-not-predictive nature, and the observed-midpoint method. It also discloses that no ovulation estimate is made, which is important for an agent considering this tool for health data interpretation.

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

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

The description is a compact, information-dense two-sentence definition. It front-loads the core purpose and source, then adds necessary behavior constraints and parameter behavior. Each sentence earns its place with no filler, though the organization could be slightly tighter.

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, zero-required-parameter tool with no output schema, the description covers the important context: input semantics, default behavior, derivation source, and the exact output dimensions. The return values are sufficiently described at a high level (day-in-cycle and phase label) to make the tool usable.

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

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

The schema description coverage is 100% for the single date parameter, and the description enriches it further: the date is optional, it applies to a single day, and the default behavior returns per-day context for the last cycle. This gives the agent a complete understanding of parameter behavior beyond the bare YYYY-MM-DD schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (user-logged period starts), a specific output (day-in-cycle and phase label), and the source file (health-cycles.json). It also distinguishes itself by explicitly noting it is derived from logged periods only and never predictive, which separates it from potential ovulation or prediction tools even without naming them.

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

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

The description gives a clear context for use: it is for cycle context based purely on logged period starts, and it explicitly excludes predictive or ovulation-estimation use cases. It does not explicitly name sibling tools or provide direct when-to-use-alternative language, but the scope and exclusions are strong enough to guide an agent.

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

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

Goes far beyond the readOnly/idempotent annotations: it defines exactly how staleness is judged (core files only, never the intraday file), the threshold precedence (default 26, HEALTH_STALE_AFTER_HOURS, maxAgeHours), and every state value including the non-obvious stale_copy and manifest_behind cases. It also discloses side-adjacent behavior such as embedded campaign-labeled links and the 'advisory only' caveat for sessions_last_night.

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, but the body is a dense single paragraph that mixes threshold rules, state enumeration, return-field inventory, and link/campaign behavior. Every clause is arguably informative, yet the lack of structure makes it harder to scan than it needs to be.

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

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

There is no output schema, and the description compensates by naming the returned fields (state, age_hours, as_of, last_data_date, data_lag_days, stale_files, manifest_behind, sessions_last_night, icloud) and explaining the ambiguous ones. Edge cases such as no export found and manifest-behind-data are covered, leaving nothing essential for a correct call unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: the precedence chain between maxAgeHours, the 26-hour default, and the environment variable, plus the note that the rule mirrors the `status --max-age` cron gate.

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, agent-relevant purpose: reporting how current the exported files are so the agent can decide whether to trust results. This is unmistakably distinct from sibling read tools like get_structured_export or query_health_data, and the follow-on rules elaborate on the same single job rather than blurring it.

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 decision context ('decide whether to trust what you read or ask the user to refresh') and a concrete reuse instruction ('Cheap: call it again before a long analysis'). It stops short of naming alternatives or explicit when-not conditions, but the intended call pattern is clear.

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; the description adds substantial behavior the agent could not infer: coverage block with firstDate/lastDate/days, aggregate always computed over the full range even when points are rolled up, segmentBoundaries for single-metric answers, readings capped at 150 with readingsOmitted, and recomputed_at/recompute blocks for backfilled days.

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 in the first two sentences, which is good. But the remainder is a dense run-on covering coverage, aggregations, segmentBoundaries, blood-pressure readings, recompute blocks in one paragraph — the readings/recompute detail could be tightened or split so the calling-critical facts stand out.

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

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

With no output schema, the description correctly carries the return-shape burden and does so thoroughly for a 7-param tool with a nested filterDays object. It stops short of describing empty-range behavior or what happens when filterDays matches zero days, which a data-retrieval tool's consumers would want.

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 high (86%), so the baseline is 3; the description earns above that by clarifying that aggregate is computed over the full range regardless of rollup, and that multi-year ranges degrade to monthly points rather than truncating. It adds little on filterDays or metric naming beyond the schema, but the rollup/aggregate semantics are genuinely new.

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?

First sentence states a specific verb and resource — get metric values over an optional date range with an aggregate — and the second sentence positions it as 'the core data-retrieval tool'. It never names or contrasts with plausible siblings such as query_health_data, get_trends, get_intraday, or get_structured_export, so an agent can't distinguish them from this text alone.

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?

Usage is only implied: 'check coverage before trusting a long window' and 'use single-metric to get segmentBoundaries' are hints rather than explicit when/when-not rules. No alternative tool is named, and there is no statement about when to prefer query_health_data or compare_periods over this.

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/closed-world, but the description adds material behavior the agent cannot infer: the file is REPLACED on every run, the window spans yesterday 00:00 to now (48h), older exports cover today only with no Min/Max, and discrete metrics pack hour Min/Max beside the mean. These are exactly the non-obvious traits that change how a result should be read.

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 payload and tightly packed with no filler, but the clauses chain into long, semicolon-heavy sentences that take effort to parse. Slightly long for one resource, though essentially every clause carries distinct information.

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

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

With no output schema, the description does the work of describing the return shape (t, v = hour's value, Min/Max for discrete metrics) and the degraded/empty responses. Combined with the window and replacement semantics, an agent has enough to call and interpret results correctly.

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

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

Schema coverage is 100% and the single parameter's own description already says 'Omit for every metric in the window.' The description implies filtering via 'each metric's hourly points' but adds no syntax, naming convention, or resolution guidance beyond the schema (e.g. use resolve_metric for names). Baseline 3 applies when the schema carries the load.

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 ('hour-by-hour window' of 'hourly points' with latest value) sourced from named automations (health-intraday.json, app 1.4+). It explicitly distinguishes itself from get_health_metrics, the day-level sibling, so an agent can route 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?

Names the alternative ('use get_health_metrics for day-level questions') and the condition that selects it, plus the boundary case that this is a live recent view, not history. It also describes the empty-state path ('Returns available:false with setup guidance when no hourly automation has delivered yet'), which tells the agent how to interpret a failure.

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

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

With readOnlyHint/idempotentHint already covering safety, the description adds meaningful return semantics: what stale_copy means, that supported is null when the cache cannot tell, and that the app links carry fixed campaign attribution. It stops short of describing what a disconnected bridge looks like in the response, which is the key thing the 'call this first' advice is meant to detect.

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 lead 'Health check:' is well front-loaded, but the rest is one long run-on sentence with nested parentheticals that packs freshness, recompute and URL attribution into a single breath. Every clause adds information, yet the structure makes it harder to scan than a short bulleted list would.

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

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

There is no output schema, so the description must carry return-value meaning, and it does so for the freshness and recompute blocks plus the app links. What is missing is the failure/disconnected state, the one behavior an agent calling this as a pre-flight check most needs to interpret.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-arg tool applies. The description correctly asks for no inputs.

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 ('Health check') and enumerates exactly what the result contains: data source, metric/workout counts, context files, latest data date, freshness block, recompute summary and app links. It does not, however, distinguish itself from the sibling get_freshness, which appears to cover overlapping freshness information.

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?

'Call this first to confirm the bridge is connected' gives an explicit trigger and ordering, which is strong guidance for the agent. It never says when to prefer the sibling get_freshness instead, so the overlap with that tool is left unresolved.

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

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

The annotations establish read-only and idempotent behavior, and the description genuinely adds behavioral value: it discloses the presentFields list and, crucially, warns that an absent field must not be interpreted as a negative value. This semantic caveat goes well beyond annotation signals and helps the agent avoid a dangerous misinterpretation.

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?

Three short sentences, each earning its place: the resource scope, the return shape, and the semantic caveat. No fluff, no redundancy, minimum well-organized and front-loaded.

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

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

With no params and no output schema, the description correctly explains both what the returned fields are and what the extra presentFields list means. The 'absent does not equal none' caveat closes the main path for user surprise/misuse. Nothing required to call or interpret this tool is missing.

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

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

The tool takes no parameters, so there is no schema coverage burden. The description correctly focuses on the return payload, which is the only remaining semantic surface. It receives a baseline 4 for handling the zero-parameter case well.

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 names a specific action ('get') and a clear resource ('health-profile.json' shared context fields), and distinguishes that resource from sibling tools by spelling out exactly what data is returned (conditions, medications, goals, allergies, notes). No ambiguity about what the tool operates on.

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

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

The description clearly defines the narrow scope—context fields explicitly opted into sharing—so an agent can infer when this tool is relevant. However, it does not state when not to use it or explicitly contrast it with sibling tools such as get_health_metrics or get_cycle_context. Usage is implied rather than spelled out.

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 read-only/idempotent profile, the description adds real behavioral context: duplicate nights from older app versions are collapsed into the longer session and counted in `collapsedDuplicates`, split nights appear as separate sessions sharing a day, and timestamps carry the local UTC offset. These are non-obvious output behaviors an agent could not infer from annotations.

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

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

Front-loaded with the core purpose and filters, then layered with behavioral detail. It is dense and mostly earns its sentences, though it reads as a run of separate caveats rather than a structured hierarchy.

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

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

With no output schema, the description must carry return-value semantics, and it does: collapsedDuplicates, separate sessions for split nights, manualInBed:true provenance, and timezone-offset timestamps. An agent has enough to interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns extra credit by explaining that filters operate on the WAKING day and why split nights share a day. That adds interpretive meaning beyond the schema's terse 'A single waking day' phrasing.

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 resource (clustered sleep sessions from health-sessions.json) and its filters {start, end, day}, which is more precise than the name alone. It does not name or differentiate against siblings like query_health_data or get_intraday, so an agent gets the what but not the routing signal.

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 implies the tool's niche by explaining the waking-day attribution and that it matches the daily cache's sleep_analysis, but there is no explicit 'use this when / use X instead' guidance for choosing between this and the other health-data tools. Usage is inferred rather than stated.

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

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

The description discloses pagination behavior, including nextCursor/cursor, and warns about large results. Since annotations already mark this as read-only and idempotent, no contradiction exists and no hidden mutation or side effect is suggested.

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?

Three short sentences, each with a distinct purpose: describing what it returns, explaining pagination, and providing usage advice. There is no redundant wording or unnecessary context.

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

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

There is no output schema, so the description should have provided a clearer picture of the returned JSON shape; it only says 'clean structured JSON' and mentions nextCursor. Pagination, date range, and metrics guidance are covered, but the actual output format remains under-specified.

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 property descriptions cover most parameters, so the baseline is already appropriate. The description does not add much semantic value beyond the schema: cursor behavior, limit, and granularity are already described in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence clearly describes the tool's deliverable: clean structured JSON for chosen metrics and a date range. It is distinct enough from analytics-oriented siblings like get_trends or compare_periods, though it does not explicitly name an alternative or scope how it differs from query_health_data.

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

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

The description gives concrete usage guidance: name metrics and a date range, and avoid bare calls over a full history because they return a lot of data. It provides a clear practical context but does not explicitly say when to choose this tool over a sibling.

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 convey read-only and non-destructive behavior. The description adds useful behavioral context beyond annotations: windowSatisfied can be false when not enough history exists, and comparisons then run over less data than requested. It also discloses that segmentBoundaries lists logged point events in the span.

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

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

The description is compact and front-loaded, opening with the main action and expected outputs. It adds technical details about windowSatisfied and segmentBoundaries without excessive filler. It is slightly dense but every sentence contributes semantic value.

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

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

There is no output schema, so the description carries the burden of explaining return data, which it does well: change, percent change, direction, daysAvailable, windowSatisfied, and segmentBoundaries. It does not fully address possible error/precondition cases or clarify metric validity, but for a read-only idempotent trend tool the essentials are present.

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 67%, with window and excludeTravelDays already documented in the input schema. The description adds a general 'N-day window' concept but does not explain the required metric parameter or add meaning for excludeTravelDays beyond the schema. It compensates only partially for the undocumented metric parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it compares the most recent N-day window against the prior N days for a metric and returns change, percent change, and direction. This distinguishes it from more generic query tools, but it does not explicitly contrast it with the closely named sibling compare_periods, so it stops short of full sibling differentiation.

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

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

The usage context is implied rather than stated: an agent can see it is meant for window-over-window trend comparisons. However, there is no explicit guidance about when not to use it, when to prefer compare_periods or get_health_metrics instead, or what prerequisite conditions apply.

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

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

Annotations already mark it read-only and idempotent, and the description adds meaningful behavioral detail: records are returned exactly as stored, optional newer keys may be absent, nothing is fabricated, and the summary applies over all matches. This is precisely the extra non-obvious behavior agents benefit from.

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

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

The description is long enough to capture filters, pagination, caching behavior, optional fields, and summary semantics, but every clause contributes. The core query action and paging semantics are front-loaded.

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 5-parameter read-only tool with no output/output schema, this description covers the important call/response semantics: which filters are allowed, how pagination works, what shape the records take, and what the summary provides. Nothing essential is missing.

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

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

The schema already describes all five parameters with examples, defaults, and format. The description restates them compactly and adds only marginal grouping/narrative value, so it earns the baseline 3 for a schema with high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete action ('Query'), a specific resource ('the workouts cache'), and enumerates filters and pagination. The scope is clearly workout data, which distinguishes it from sibling metric/trend/period tools.

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

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

The description gives clear context: this is for querying raw cached workout records within date/activity/filter bounds with pagination. It does not explicitly name alternatives or when not to use it, so it falls short of a full 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 readOnly/idempotent annotations: discloses the merge of health-events.json with health-events-agent.json, that every event carries a source of "app" or "agent", the ascending sort order, and the available:false shape when neither file exists. That is exactly the kind of provenance and empty-state context 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-loads what the tool returns, then provenance/merge, then filters, then ordering, then the empty-state caveat. Dense but every clause carries information an agent needs; nothing is redundant.

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

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

With no output schema, the description carries the return-value burden and does so: source field, sort order, and available:false. Combined with the filter overlap rule and the empty-result interpretation, an agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the optional {type, tag, start, end} set is described as filters and the range rule 'a range event matches a window it overlaps' explains behavior the schema does not. It does not detail date format or default window, but the schema already supplies YYYY-MM-DD.

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?

Names a specific verb (list) plus the concrete resource: logged context events across a named set of types. The enumerations (medication starts, habit changes, doctor visits, shift blocks...) make it unmistakable, and it explicitly distinguishes its contents from the sibling add_event by noting agent-logged events.

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

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

Explains filter semantics and the overlap rule, and gives the important interpretive caveat that an empty result means nothing was logged/exported rather than nothing happened. It does not explicitly route the agent against alternatives like query_health_data or get_structured_export, so it falls 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 mark this as readOnly and idempotent, so no safety contradiction exists. The description adds useful context about the listing including unit, day count, and date range, which goes beyond raw annotation data.

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

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

Two sentences with no filler. The main action and return content are front-loaded, and the usage guidance is immediately 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?

For a zero-parameter discovery tool, the description fully covers what the agent needs: what will be listed, what fields are included, and when to use it. Sibling tool context supports the discovery-to-query flow, and nothing critical is missing.

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

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

The tool has zero parameters, so parameter semantics are inherently simple. The description clarifies what the returned listing contains, which is useful given no output schema is present.

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 identifies a specific action (list), a clear resource (every available Apple Health metric), and the exact information included (unit, day count, date range). It clearly distinguishes this as a discovery tool from sibling querying tools.

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

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

The description explicitly states when to use this tool: 'discover metric names before querying.' This gives clear usage context and implies this is a prerequisite step rather than an analysis tool, though it does not explicitly name alternatives.

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 readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so the read-only and idempotent nature is established. The description adds one important behavioral fact: results are scoped to whatever data is currently in the file, and users should check list_metrics for the amount of history available. It doesn't explain routing behavior in detail (e.g., how ambiguity is handled), but the additional context about the underlying file scope is useful.

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

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

The description is a single, efficient passage that front-loads the core purpose and then adds practical usage guidance. No words are wasted; the routing concept, the preference for alternatives, and the prerequisite call are all packed into two sentences.

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?

In the context of a simple one-parameter tool with handers that mark it read-only and idempotent, the main missing pieces for an agent would be the shape of the structured results and any question formatting limits. The instructions to check list_metrics and set expectations on available history partially fill the context gaps, and the description does not need to explain return values due to a lack of an output schema summary line. Still, the absence of any return-format hint keeps it from a 5, but against the overall simplicity it's fairly 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 compensate for parameter meaning. The description does explain the question parameter's role by saying pass a question and get routed structured results, which is some semantic content. But it doesn't give examples, constraints, or format guidance for a well-formed question, leaving the parameter meaning incomplete despite a 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this tool takes a natural-language question and returns routed structured results, and identifies it as a convenience tool with a specific purpose. It also explicitly distinguishes it from the specific tools by referring to them as alternatives, which helps differentiate it from siblings.

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

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

The description explicitly says to prefer specific tools when possible, and instructs calling list_metrics first to check the data history before using this tool. This gives an explicit usage context and a clear prerequisite. It doesn't list specific alternatives by name or state when-not conditions in detail, but the guidance provided is concrete and actionable.

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 destructive, non-readonly, idempotent, and closed-world, but the description adds real context beyond them: the target file, the source-restriction refusal path, the demo/write-permission refusals, and the observable no-op message when an id is already gone. This is unusually complete for a destructive tool.

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

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

Front-loaded with the action and target file, and every sentence carries actionable constraint or refusal information. The prose is dense and the parenthetical provenance note is slightly compressed, but there is 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?

Given a destructive, idempotent, single-parameter tool with no output schema, the description covers target storage, eligibility, refusal conditions, and no-op behavior. An agent has enough to call it correctly and predict failure modes.

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

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

The single id parameter already has 100% schema description coverage, so baseline is 3. The description adds provenance semantics by tying accepted ids to add_event/list_events and identifying agent-prefixed ids, which is useful validation context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (remove an event) plus the exact backing store (health-events-agent.json) and the provenance link to add_event. It is unmistakable against siblings like add_event and list_events.

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 which events are removable (agent-logged ids, source 'agent' in list_events) and which are refused (iOS app events), and adds preconditions: demo mode and non-writable folders are refused. That is a clear when/when-not contract with the alternative behavior named.

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 cover the safety profile (readOnly, idempotent), but the description goes well beyond them: percentages are 0-to-1 fractions, unit variants come with exact conversion formulas, ambiguous multi-metric words return candidates, and a different measure (RMSSD vs SDNN) is refused rather than guessed. It also discloses that per-source attribution is only present when exports carry src/by, which is genuine 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 and accepted inputs are front-loaded and every sentence carries information, but the closing sentence about source attribution and merged-across-sources semantics is long and somewhat peripheral to the lookup job, making the whole denser than necessary.

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

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

There is no output schema, yet the description fully describes what comes back (canonical metric, unit, unit variants with formulas, whether the export holds it) plus conversion, ambiguity and refusal behavior. An agent has everything needed to select and invoke 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?

Schema description coverage is 100%, so the baseline is 3; the description still adds value by explaining the conversion pairing ('Pass {value, unit} to convert one value, e.g. 180 lb to kg') and the refusal rule for unknown units, beyond what the schema states. It does not add format constraints on `name` that the 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?

The opening sentence states a precise verb and resource: 'Look a metric name up in the canonical naming and unit table.' It then enumerates accepted input forms and return contents, making it clearly distinguishable from siblings like list_metrics or get_health_metrics 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 names which siblings accept the same aliases (get_health_metrics, get_trends, compare_periods, get_structured_export, correlate_metrics) and notes that other tools require the export's own names, which tells the agent when resolution is needed. It stops short of an explicit directive ('call this first when the name is ambiguous'), so it is clear context rather than 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.