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

The annotations already indicate readOnlyHint=true and idempotentHint=true, so safety and idempotence are covered. The description adds useful behavior beyond the annotations: it excludes the event day from both sides when anchor is used, and it says the tool reports how many days it excluded when excludeTravelDays is set. That gives an agent a solid model of aggressive time and side effects.

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 cosrne and front-loaded: it immediately states the operation and result, then gives the two input patterns. No sentence is wasted; it delivers the vervalue in two sentences. The long second sentence with parentheticals adds a little cost but still earns its place.

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

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

Given no output schema, the description does summarize the output shape: each aggregate plus change/percent change and, when excluding travel days, the number excluded. Combined with sibling semantics and annotation safety profile, this is reasonably complete, but it could drive lightly about metric values and required period constraints for the min agent.

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 overall schema describes some parameters, but coverage in the schema is only 40%; the description partially compensates by explaining the anchor/periodA/periodB relationship and the 'exclude the event day' nuance. However, it doesn't describe metric options or the exact date range semantics for periodA/periodB (boundary inclusivity, same length requirement). It thus adds meaningful but incomplete semantics over 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 operation: 'Compare a metric between two arbitrary date periods (A vs B)' and describes the result as each aggregate plus raw change and percent change. It is distinct: it compares period aggregates, and the sibling list contains no other true period-to-period comparison tool, so an agent can tell when to choose this 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?

The description gives clear context for use: explicit periodA/periodB for arbitrary periods, or anchor-based 'before/after' comparisons around a registered event. It does not mention alternatives among siblings or explicitly say when not to use this tool, so it stops just 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?

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?

The description adds substantial behavioral context beyond annotations: it reveals the `coverage` block with real firstDate/lastDate/days, warns to verify long windows, clarifies that `aggregate` is computed over the full range even when points are rolled up, and mentions segmentBoundaries for point events. These are meaningful nuances that annotations (readOnly, idempotent) do not cover.

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?

Only three sentences: purpose first, then critical behavioral warnings, and a final note about segmentBoundaries. Every sentence contributes value, and the most important caveats are front-loaded after the core purpose.

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

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

Given the complexity (7 params, nested object, no output schema), the description covers essential pitfalls: the coverage block, aggregate behavior with rollups, and event segments. It explains partial return structure but leaves some details (error behavior, exact format of points) to inference. Still, it is reasonably complete for a read-only tool without an output schema.

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

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

Schema coverage is 86%, so most parameters already have descriptions. The tool description does not add per-parameter semantics beyond the schema; it focuses on general behavior and result structure. The baseline of 3 applies since the schema handles the heavy lifting, and the description's behavioral notes (e.g., aggregate over full range) are more about operation than 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?

The description states a precise verb and resource ('Get values for a metric (or all metrics) over an optional date range, with an aggregate') and even labels itself 'The core data-retrieval tool,' which conveys its role. However, it does not explicitly differentiate from siblings like get_trends or compare_periods, leaving potential ambiguity about which tool covers which analytical task.

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?

Calling itself 'the core data-retrieval tool' implies it is the general-purpose retrieval endpoint, but there is no explicit guidance on when to prefer siblings, what user scenarios warrant get_trends vs. this, or exclusions. The guidance is implied 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?

Beyond the readOnly and idempotent annotations, the description reveals critical behavioral context: the source file is replaced every hourly run, making the tool a live snapshot rather than a stable historical archive. It also discloses the available:false failure mode and the setup guidance that accompanies it, giving the agent accurate expectations.

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, informative sentences cover the core functionality, the source/version, the critical replacement behavior, the appropriate alternative tool, and the edge-case return value. The most identifying information is front-loaded ('current hour-by-hour window') and no waste or repetition exists.

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

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

For a tool with one optional parameter and no output schema, the description conveys the necessary context: what it returns, when to use it, and how to handle early no-data situations. The remaining details about metrics or format are already in the schema or via sibling tools like list_metrics.

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 parameter 'metric' is already fully documented in the input schema with an example and an explicit 'omit for all metrics' rule. The description adds no supplementary semantics for the parameter, so the schema fully covers parameter meaning. Baseline 3 is appropriate.

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

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

The description states exactly what the tool returns: the current hour-by-hour window's each metric's hourly points plus its latest value. It distinguishes the tool from get_health_metrics by explicitly saying it is a live within-day view, not history, which resolves ambiguity among 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?

It explicitly says to use get_health_metrics for day-level questions, framing get_intraday as the tool for live intraday data. It also calls out the no-data-yet condition and explains that the tool returns available:false plus setup guidance, so the agent knows when the data pipeline is not ready.

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 indicate read-only and idempotent behavior, so the description's job is light. It adds useful context about what information the status call returns and that it serves as a connection check, which helps the agent understand expected behavior beyond the annotations.

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

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

The description is a single concise, information-dense sentence. It front-loads the purpose ('Health check'), lists the return contents, and gives the usage hint without unnecessary wording.

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

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

With no parameters, no output schema, and read-only annotations, this description fully equips an agent to call the tool correctly and understand what it will receive. Nothing important is missing for the task of selecting and invoking this tool.

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

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

The tool takes zero parameters, so there are no parameter semantics to document. The description compensates by explaining what the no-argument call returns, which is the only relevant guidance needed here.

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

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

The description clearly identifies this as a health-check tool and specifies exactly what it reports: data source, counts of metrics/workouts, optional context files, and most recent data date. It is clearly distinguished from sibling tools that retrieve specific data or insights.

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 instructs the agent to call this tool first to confirm the bridge is connected. This provides a clear decision rule for when to use it, and no alternative or exclusion is needed given it is the startup/connectivity check.

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?

The description discloses non-obvious behavioral traits: sessions are attributed to the waking day, split nights appear as multiple sessions with the same day, and timestamps include the local UTC offset. These go well beyond the readOnly and idempotent annotations, giving the agent a precise model of how results are shaped and time-zone sensitive. No contradictions exist with annotations.

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

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

The description is three sentences, tightly packed with functional and behavioral details. It front-loads the core purpose then expands on subtle behaviors. Every clause earns its place, and there is no fluff or repeated 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 retrieval tool with no output schema, the description explains the session clustering and timezone handling. However, it does not mention the list of returned fields, ordering, or pagination. Despite the strong behavioral context, the absence of an output schema means the agent still lacks a complete picture of the result shape.

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 documents all three parameters with inclusive explicit date range semantics (YYYY-MM-DD) at 100% coverage. The description only references them generically as filters, adding no new details beyond what the schema states. Thus the baseline score of 3 is appropriate.

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

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

The description states a specific verb, resource, and scope: 'Clustered sleep sessions from health-sessions.json with {start, end, day} filters.' It clearly distinguishes this tool from siblings like get_workouts or get_health_metrics by focusing on sleep sessions and their clustered/aggregated nature. The additional context about waking-day attribution and split nights makes the tool's uniqueness explicit.

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 on when the tool applies: it filters sleep sessions by start/end/day, and aligns with the daily cache's sleep_analysis. However, it does not explicitly name alternative tools or say when not to use it, leaving some inference to the agent. The clear domain coverage earns a 4 rather than 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?

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?

Annotations already declare readOnly and idempotent hints; the description adds substantial beyond-schema detail: start/end range semantics, ascending sort order, how unknown types pass through, and the available:false semantics that distinguish an untouched dataset from an empty one. These are exactly the edge behaviors an agent needs to reason about correctly.

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, information-dense, and front-loaded with the tool's core purpose before moving into filters and edge cases. Every sentence contributes unique, non-redundant 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?

Despite having no output schema, the description covers source, filter behavior, ordering, overlap semantics, unknown types, and the absence of a meaningful available:false result. This is sufficient for an agent to confidently select and invoke the tool.

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

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

The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful extra context by explaining that range filters allow overlap matching and by reinforcing that the type parameter is open to new app-defined types.

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 lists logged context events from health-events.json, enumerates the event types, and covers future types. This makes the tool clearly distinguishable from the metric, workout, and sleep siblings 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?

It gives clear context for when to use it — whenever a list of context events is needed — and describes the optional filters. It does not explicitly call out sibling alternatives or exclusion conditions, but the context signals and type enumeration make the target use case obvious.

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.