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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description goes well beyond annotations by revealing non-obvious behavior: 'Before' means next-oldest days with data, a gap makes the earlier window older rather than emptier, and `previous.first_day`/`previous.last_day` should be quoted. It also discloses the `coverage` block and explicitly says the tool does not decide which window is better, which is valuable behavioral context for an agent.

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 dense but every sentence earns its place: the main operation is front-loaded, the gap semantics follow, the return summary is next, and the coverage caveat closes the important behavioral notes. There is no filler or repeated schema content, and the line breaks guide the reader through distinct concepts.

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 4-parameter analytical tool with an output schema and safety annotations, the description is unusually complete: it explains window selection, gap behavior, returned statistics, non-judgment, and the coverage block. The main gap is the absence of any explanation of `fresh` and `owner`, though both have defaults and the required `series` parameter is reasonably inferable from the prose. Overall, it is sufficient for confident default invocation and interpretation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does give context for `days` through 'newest `days` days' and implies `series` through 'of a series.' However, `fresh` and `owner` are never mentioned or explained, leaving the agent without enough information to use those parameters deliberately. Because half the parameters are undocumented in both the schema and description, the compensation is incomplete.

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

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

The description opens with a specific verb and resource: 'Compare the newest `days` days of a series against the `days` before them.' This clearly distinguishes the tool from siblings like get_metric_trend or correlate_metric_series by describing a two-window comparison of a single series. The added statements about returned statistics and the absence of a judgment also reinforce what the tool is and is not.

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

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

The description gives useful interpretational guidance, such as how to treat gaps and how to read `coverage.window_satisfied: false` as a shorter history rather than a missing kind. However, it never explicitly says when to choose this tool over an alternative like correlate_metric_series or get_metric_trend, nor does it state a clear exclusion condition. The intended usage is implied by the operation described, but alternative selection is left to the 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 discloses key behaviors beyond the annotations: missing days are dropped (not interpolated or zero-filled), n_pairs is usually smaller than either series, fewer than 3 shared days returns null with a reason, and the result carries a caveat about causation. It also explains how to interpret coverage.window_satisfied: false. This is rich behavioral context that the annotations (readOnlyHint, idempotentHint, destructiveHint) do not provide.

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 well-structured with clear paragraphs and front-loaded purpose. It is longer than a typical description, but every sentence carries meaningful guidance about interpretation, caveats, and output fields. The only minor issue is that it could be slightly more compact, but the density of useful information justifies the length.

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

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

Given the tool's complexity (statistical correlation with missing-data handling, output caveats, coverage blocks), the description is remarkably complete. It explains the null condition, the caveat field, the coverage block, and how to interpret the results. The output schema exists, so return values are already structured, and the description adds the interpretive context an agent needs to use the result correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's lack of parameter documentation. It does explain the meaning of n_pairs and coverage fields in the output, but it does not explicitly describe the parameters series_a, series_b, days, fresh, or owner. However, the tool's purpose is so clearly stated that the meaning of series_a and series_b is obvious, and days/fresh/owner are common patterns. The description adds value by explaining output semantics, but it leaves some parameter details to inference.

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

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

The description opens with a precise statement: 'Pearson r between two daily series, over days that have BOTH recorded.' This names the statistical method, the resource (two daily series), and the scoping rule, which clearly distinguishes it from siblings like get_metric_trend or compare_metric_periods. The title 'Correlate two series' is expanded with enough specificity that an agent can select it correctly.

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 explains when to use this tool: when you need a Pearson correlation between two daily series, and it warns about the consequences of missing days and small sample sizes. It also tells the agent to quote n_pairs, coverage fields, and the caveat, and to avoid translating r into words like 'strong'. This is strong usage guidance that goes beyond a simple definition.

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, idempotent, and non-destructive annotations, the description discloses rich behavioral details: one entry per day, newest first, the coverage block semantics, the meaning of more_available, and the warning not to report a limit-shaped window as the data extent. This adds substantial value and does not contradict 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 detailed but every sentence earns its place. It is front-loaded with the core purpose, then adds usage and interpretation guidance. The structure is logical and not bloated, though the emoji and dense coverage explanation could be streamlined without losing 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?

Given the complexity (coverage block, pagination, owner filtering) and that an output schema exists, the description covers the tricky parts well. It leaves `fresh` unexplained, but that parameter is likely a cache-bypass flag that the agent may infer from the name. Overall, it is highly complete for its complexity.

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 explain parameters. It explains `owner` (prefix filter) and `limit` implicitly through the coverage discussion (re-read with a larger limit), but `fresh` is entirely unmentioned. This is a partial coverage of a three-parameter tool, so a 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 (Decrypt) and resource (recent daily activity rings) and lists the exact metrics (steps, active energy kcal, exercise minutes, stand hours, distance km). This clearly distinguishes it from sibling tools like get_water_intake or get_weight_trend, so an agent can pick it without ambiguity.

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

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

It gives explicit guidance on filtering by owner and how to interpret the coverage block, which are key usage contexts. It does not explicitly name alternatives, but the purpose is so specific that the intended use is obvious; the coverage caveat also tells when to re-read with a larger limit.

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 read-only and idempotent; the description adds substantial behavioral detail beyond them: hourly sample cadence, partial-day rows looking real but being short proportionally, `incomplete: true` exclusion from averages, the coverage block semantics, and warnings about `more_available` and `oldest_available`. It also explicitly warns against quoting a `limit`-shaped window as the full history. No contradiction 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 long but densely informative, and the key purpose is front-loaded before the caveats. Every warning addresses a plausible failure mode, so the length is mostly justified. It could be tightened slightly, but it does not waste words on 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 the output schema exists and the annotations cover safety, the description covers nearly everything an agent needs: kcal units, hourly cadence, daily aggregation, incomplete-row exclusion, coverage fields, and the more_available/oldest_available re-reading behavior. The only notable omission is the `fresh` parameter, which is not described anywhere.

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

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

Schema description coverage is 0%, so the description must compensate. It gives good semantics for `owner` (filter by person) and `limit` (increasing it retrieves older days), but never explains `fresh`, which is a real parameter. Without schema descriptions, that remaining gap prevents full parameter understanding.

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: 'Decrypt recent basal-energy-burned samples (Apple Watch BMR estimate, kcal).' It clearly scopes the metric to basal energy/BMR rather than total energy or activity, which distinguishes it from related siblings like get_total_energy_burned and get_activity. The title reinforces the purpose.

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 operational guidance: how daily aggregation works, how to filter by person with `owner`, how to handle incomplete rows, and how to re-read with a larger `limit` when `coverage.more_available` is true. It does not explicitly state when to prefer this tool over alternatives, but it provides strong context for common use cases and caveats.

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?

Although annotations already declare `readOnlyHint: true` and `destructiveHint: false`, the description adds valuable behavioral context: it explains the decryption happens locally (privacy implication), that the tool returns an optional `coverage` block with semantics for interpreting incomplete history, and warns against misreporting data extent. This goes well beyond the annotation hints, adding nuanced behavior about pagination and coverage.

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 well-structured with clear paragraph breaks: it starts with the core purpose, then details the data structure, and concludes with the important `coverage` guidance. Every sentence contributes practical value—there is no filler or repetition. The guidance on interpreting `coverage` is critical and 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 tool's complexity (nested structure with optional nutrition data, variable coverage), the description is thorough. It explains the data shape enough for an agent to sum or estimate, covers the `coverage` block semantics, and addresses pagination with `more_available`. Although there is an output schema, the description clarifies nuances not obvious from the schema alone.

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 explicitly mentions `limit_days` as a way to cap the returned days, which adds semantics beyond the schema (which only lists it as an optional integer). However, the other two parameters (`fresh` and `limit`) are not described in the text. Since schema coverage is 0%, the description should ideally cover all parameters, but the primary parameter (`limit_days`) is addressed, earning a 4.

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

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

The description opens with an unambiguous statement of purpose: 'Decrypt recent daily food-intake logs locally (newest first).' The verb 'decrypt' plus the specific resource ('food-intake logs') makes the tool's function immediately clear. It distinguishes itself from siblings like get_notes and get_weight_trend by focusing on the food-log domain.

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 'Owner's own days only,' which is a clear scoping constraint. It also provides explicit instructions on how to use the 'coverage' block: quote `coverage.days_covered` for averages, watch for `window_satisfied: false`, and re-read with a larger limit when `more_available` is true. This level of operational guidance is exceptional.

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, idempotent, and non-destructive; the description adds substantial behavioral detail: rolling windows, data source (Apple Watch sampling rate), backward-compatibility alias, coverage block semantics, and the `more_available` flag with explicit instructions not to misreport the limit-shaped window as full history. It even retracts a prior equivalence claim, showing careful disclosure.

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

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

The description is long but exceptionally well-structured: purpose front-loaded, granularity explained in a bulleted block, a warning callout, and a dedicated coverage section. Every sentence adds value for a complex tool; it is as concise as the complexity allows, though it could trim minor redundancy in the coverage section.

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

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

The description covers all critical operational aspects: window sizes, record counts, sampling patterns, alias behavior, coverage fields, owner sourcing, and the warning about comparability. Combined with the output schema (present) and annotations, an agent has everything needed to call the tool correctly and interpret results.

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?

With schema description coverage at 0%, the description must compensate. It thoroughly explains `granularity` (two modes with exact routing), `owner` (source and format), and `limit` (impact on data extent via `more_available`). However, the `fresh` parameter is not addressed, leaving a small gap; the detailed treatment of the other three parameters still earns a high score.

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

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

States a specific verb and resource ('Decrypt recent HRV (SDNN in ms)') and immediately differentiates the two granularity modes. The tool's role among siblings (e.g., get_resting_hr, get_metric_trend) is clear because HRV is a distinct metric.

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 when to use hourly vs raw ('hourly for trend/aggregate answers... raw only when you need per-sample precision'), warns that averages are NOT comparable across granularities, and explains how to source the owner prefix from other tools. This goes beyond vague context into actionable routing.

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, idempotentHint, and destructiveHint, so the description need not repeat them. It adds substantial context: data sensitivity and on-device storage, the meaning of coverage fields, and the pitfall of misinterpreting limit-shaped windows. This goes well beyond annotations, making the tool's behavior very transparent.

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 relatively long but densely packed with useful information. It is structured into clear paragraphs: purpose, sensitivity, and coverage instructions. The front-loading of purpose and the use of the 🔴 emoji to flag a critical warning are effective, though the length could be trimmed slightly without losing 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?

Given that an output schema exists to document return values, the description focuses on what the schema cannot convey: sensitivity, coverage interpretation, and the limit pitfall. It covers all major behaviors an agent needs to call the tool correctly, including how to handle partial history. 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?

With schema description coverage at 0%, the description must explain parameters. It clarifies `owner` (filter by person) and `limit` (controls how many days are fetched, and interacts with `more_available`). However, it never mentions the `fresh` parameter, leaving it unexplained. This is a notable gap, so a 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 opens with 'Decrypt recent menstrual cycle data locally and predict the next period,' which clearly states a specific action and resource. It also mentions returning recent samples plus a prediction, distinguishing it from sibling get_* tools like get_weight_trend or get_sleep_detail. The purpose is unambiguous and unique.

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

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

The description provides explicit guidance on using the `owner` prefix for filtering and explains how `limit` affects coverage with `more_available`. It does not explicitly state when to use this tool versus alternatives, but the unique domain makes that implied. It offers clear instructions on handling the coverage block, which is more than minimal.

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, idempotent, and non-destructive. The description adds substantial behavioral detail: days select data-bearing days not calendar days, results are arithmetic-only, fewer than 3 days yields a null slope with a reason, and coverage fields indicate sparse history. This goes well beyond the annotations.

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

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

The description is longer than average but almost every sentence adds operational value, with important caveats front-loaded after the core definition. Minor redundancy around 'arithmetic only' and 'no threshold, band or verdict' prevents a perfect score.

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

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

With an output schema present and annotations covering safety, the description handles return semantics, edge cases, and coverage interpretation well. It is missing guidance for fresh and owner, which leaves some ambiguity for an agent calling the tool with non-default values.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It thoroughly explains series and days, but leaves fresh and owner entirely unexplained. Since two of four parameters receive strong semantic guidance and the other two receive none, it is partially compensating.

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 and resource: 'Least-squares trend for one daily series: slope per day, endpoints, spread.' It also clarifies scope ('one daily series') and what it does not provide ('no threshold, band or verdict'), which distinguishes it from comparison and correlation 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 gives clear context about series selection and day-window semantics, and the 'one daily series' wording implies when this tool is appropriate. However, it never explicitly names alternatives such as compare_metric_periods or correlate_metric_series, nor does it state when not to use this tool.

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

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

The description far exceeds what annotations convey: it reveals the decryption behavior, teaches the semantics of the coverage block (days_covered is distinct days not row count, window_satisfied:false means shorter history, more_available:true means older data exists), and warns against reporting a limit-shaped window as the extent of the data. These are precisely the non-obvious misinterpretation traps annotations cannot express.

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

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

The purpose is front-loaded in the first sentence, and every subsequent sentence carries non-obvious operational value; the 🔴 marker draws attention to the most critical caution. It is dense, and the final sentence somewhat restates the more_available rule, but no sentence is wasted.

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 medium-complexity tool with an output schema, the description thoroughly covers the failure-prone behaviors: coverage interpretation, limit truncation, and re-read strategy. An agent has everything needed to call it correctly except an explanation of the `fresh` parameter, which is the one notable gap.

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

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

With 0% schema description coverage, the description must compensate, and it gives `owner` a clear role (person filter) and `limit` nuanced truncation semantics (small values leave older decryptable days behind; larger values recover them). However, `fresh` (boolean, default false) is never mentioned, leaving one of three parameters entirely unexplained.

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 states a specific verb-resource pair ('Decrypt recent daily mindfulness summaries') and names the exact fields returned (session count, total minutes). Among roughly thirty sibling getters covering sleep, HRV, water, food, weights, and workouts, this is the only mindfulness-specific reader, so an agent can disambiguate it immediately.

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 operational guidance within the tool ('Use `owner` prefix to filter by person', re-read with a larger `limit`), but it never explicitly states when to choose this tool over an alternative or when not to use it. Selection is implied by the tool name and domain 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 goes well beyond the annotations. It discloses that the tool decrypts data locally, that the data is sensitive free text, that it is never re-exported, and that it carries a coverage block with specific fields that must be interpreted in particular ways. It also warns against reporting a limit-shaped window as the extent of the data, which is a behavioral trap the agent would otherwise fall into. The annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent with the description, and the description adds substantial 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?

The description is dense and information-rich, with the most important facts front-loaded: what the tool does, that it is sensitive, and the key fields. The coverage block explanation is lengthy but necessary because it prevents a specific misinterpretation. It earns its length, though it could be slightly tightened by moving the 'SENSITIVE free text' warning after the first sentence without losing clarity.

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 tool's complexity (sensitive data, coverage semantics, filtering, and a large sibling list), the description is remarkably complete. It explains the return value's coverage block, how to interpret it, how to filter, and what not to do. The output schema exists, so the description doesn't need to enumerate return fields, but it explains the non-obvious parts of the output. An agent has everything it needs to call this tool correctly and interpret its results.

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 input schema has 0% description coverage, so the description must compensate. It explains target_kind by listing the kinds ('sleep' | 'menstrual' | 'mood' | 'general') and how they are authored, which adds meaning beyond the schema's bare anyOf string/null. It also explains limit in the context of coverage.more_available and first_day, giving it semantic weight. The fresh parameter is not explicitly explained, but the description's focus on decryption and local processing implies its purpose. This is strong compensation for a schema with no descriptions.

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

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

The description opens with a specific verb and resource: 'Decrypt recent free-text notes (day annotations) locally.' It clearly distinguishes this from sibling tools by explaining that notes are free-text day annotations, that they are decrypted locally, and that they are sensitive. It also names the kinds of notes and how they are authored, which differentiates it from log_note and other get_* 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 tells the agent when to use this tool and how to use it: pass target_kind to filter, join against same-day metric data for pattern analysis, and re-read with a larger limit when coverage.more_available is true. It also gives clear guidance on how to interpret coverage fields, which is essential for correct usage. It does not explicitly name alternatives, but the sibling list is large and the description's specificity about notes vs metrics makes the usage context 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 already indicate readOnly, idempotent, and non-destructive. The description goes well beyond that by explaining the `coverage` block semantics: how to interpret `days_covered`, `span_days`, `window_satisfied`, and `more_available`. It warns about the pitfall of treating a limit-shaped window as the full data extent and instructs to quote `oldest_available` as the true start. This is rich behavioral detail that adds significant value 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 front-loaded with the core purpose, then introduces the coverage block. It uses a paragraph break to separate the primary function from the detailed coverage guidance. While the coverage section is lengthy, it is dense with necessary caveats and actionable instructions. The formatting with bold and emojis aids readability, and every sentence contributes to correct usage. It could be slightly trimmed but remains appropriately concise for the complexity.

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

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

The description covers the essential output structure (per-day records and average), the coverage block, and edge cases around data availability. An output schema exists, so return-value details need not be spelled out. The only notable gap is the `fresh` parameter, which is left undefined. Given the tool's moderate complexity and the presence of annotations and output schema, the description is nearly complete but misses one parameter's semantics.

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 has 0% description coverage, so the description must compensate. It explains `owner` (filter by person) and `limit` (indirectly via 're-read with a larger `limit`'), but does not explain the `fresh` parameter at all. Since one of three parameters is completely unaddressed, and the other two are only partially described (limit's exact semantics of window size are implied rather than explicit), the description only partially compensates for the schema's lack of documentation.

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 the tool's function: 'Decrypt recent resting heart rate samples (bpm). Returns per-day records plus average over the window.' It names the specific metric (resting heart rate) and the output structure (per-day records and average), distinguishing it from sibling metric tools like get_hrv or get_wrist_temp. The verb 'decrypt' is specific and the resource is unambiguous.

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

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

The description provides clear usage context for the owner parameter ('Use `owner` prefix to filter by person') and gives detailed guidance on interpreting the coverage block, including when to re-read with a larger limit. However, it does not explicitly mention alternative tools or state when NOT to use this tool versus siblings like get_hrv or get_metric_trend. The name and title are self-explanatory, but explicit routing to alternatives is missing.

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 signal readOnly, idempotent, and non-destructive behaviorchery. The description adds substantial behavioral context beyond that: the ~1-2k character per-night size, the ~13k character per-night risk of include_timeline, the exact meaning of is_in_bed_only, the coverage block semantics, and the owner-blending pitfall. It also alerts agents to the limit-shaped window trap.

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

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

The description is long, but it is well-structured with section headers, clear bullets, and prioritized warnings. The core purpose and tool-selection guidance are front-loaded, and every major section adds necessary operational safety or selection value. The brief historical note explains why the description was corrected, which is useful context for agents.

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

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

For a tool with output schema present, annotations, and four optional parameters, the description is nearly complete: it covers selection, ownership filtering, size constraints, special-value semantics, and coverage behavior. The only notable gap is the unspecified 'fresh' parameter, which prevents full completeness at the highest level.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains limit (defaults, size implications, raising for trends), owner (prefix, discovery via vaultbeat_doctor, blending risk), and include_timeline (raw samples, size, when to use). However, the 'fresh' parameter is never mentioned, leaving one parameter unexplained.

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

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

The description opens with a precise verb-resource-scope statement: 'Per-night sleep stages with per-stage HR/RR — depth on a few nights.' It clearly distinguishes this tool from vaultbeat_sync_sleep and explicitly cautions against treating this tool as a broad sleep analysis 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 explicit when-to-use guidance: use this tool for deep dives on one or two nights, and vaultbeat_sync_sleep for periods, trends, and averages. It also tells agents not to infer only two nights exist from this tool's default limit, which is a clear exclusion and alternative-related instruction.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: local decryption, newest-first ordering, no partner fan-out, and detailed coverage-block semantics including more_available, oldest_available, and the warning not to report a limit-shaped window as data extent. No contradiction 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 long but dense; every sentence adds either scope, output-shape guidance, or a coverage warning that would otherwise be unguessable. It front-loads the core purpose in the first sentence and keeps advanced warning details at the end.

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 tool's coverage-block complexity and 0% schema coverage, the description is remarkably complete: it covers return contents, coverage meaning, limit interaction, and interpretation pitfalls. The only minor omission is the 'fresh' parameter, which is optional with a default and does not prevent correct use.

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?

With 0% schema coverage, the description carries parameter documentation. It explicitly explains limit_days ('cap how many sessions return') and gives practical meaning to limit through the coverage discussion ('your limit left behind', 're-read with a larger limit'). However, the 'fresh' parameter is never explained, so parameter coverage is strong but incomplete.

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 names the exact resource ('recent strength-training sessions'), the operation ('Decrypt'), the processing location ('locally'), and ordering ('newest first'). It also distinguishes the tool from siblings by saying HealthKit's workout type cannot carry this exercise-level detail and noting it is owner-only.

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: it is for manually logged Vaultbeat strength sessions, owner-only, and says to join date against sleep/HRV/weight for training-load analysis. It implicitly contrasts with HealthKit workout data and write siblings, but it never explicitly names an alternative tool (e.g., get_workouts) or states a when-not-to-use condition, so it falls short of a perfect 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 mark the tool read-only, idempotent, and non-destructive, and the description adds substantial beyond-that context: local decryption, on-device-only handling with no re-export, per-owner grouping, severity values, and detailed coverage semantics for days_covered, span_days, window_satisfied, more_available, and oldest_available. It also warns against reporting a limit-shaped window as the full history.

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

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

Front-loaded with a clear one-sentence purpose, then organized into SENSITIVE and coverage blocks. It is long, but nearly every sentence carries necessary caveats for sensitive health data; minor redundancy like 'Decrypt... locally' versus 'Stays on-device' keeps it from a perfect score.

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 rich output schema and read-only annotations, the description thoroughly covers return structure, owner grouping, privacy constraints, and coverage edge cases. The main gap is the undocumented 'fresh' parameter, which an agent cannot resolve from either the schema or the description.

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?

With 0% schema description coverage, the description must compensate for both parameters. It meaningfully explains limit's role in truncation and re-reading older data, but it never defines limit's units or scope, and 'fresh' is not mentioned at all. This is partial compensation for one of two parameters.

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

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

Opens with a specific verb and resource: 'Decrypt recent HealthKit symptom days locally, grouped by data owner.' This clearly states what the tool does and distinguishes it from sibling health getters by naming HealthKit symptoms and the owner-grouped output shape.

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 does not explicitly say 'use this when...' or name alternatives/exclusions, so routing is mostly implied by the tool name and symptom subject. It does provide useful context about opt-in availability and coverage caveats, but an agent comparing it to sibling tools like get_menstrual_cycle or get_wrist_temp gets no direct guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds substantial behavioral detail: excluded day categories, one-directional error from incomplete days, coverage semantics, and how more_available affects reported history. This goes far beyond what the annotations provide.

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 front-loaded with the core definition, but it is very long and repeats concepts like coverage, exclusions, and quoting guidance across multiple sentences. The emoji warning and repeated operational instructions add verbosity; it could be tightened substantially without losing key 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?

Given the tool's complexity, the description covers the crucial runtime semantics: exclusions from averages, coverage blocks, pagination via more_available, and diet-target interpretation. The missing 'fresh' parameter and the 'limit' naming inconsistency prevent full completeness.

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?

With 0% schema description coverage, the description must explain parameters; it does explain days/last N days and owner prefix. But it never mentions the 'fresh' parameter, and it refers to a 'limit' parameter that does not exist in the input schema, presumably meaning 'days', which can confuse an agent.

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 retrieves TDEE as 'basal + active per day, last N days' from Watch measurements. It clearly distinguishes itself from siblings like get_basal_energy by emphasizing the total-energy scope and the per-day breakdown plus average.

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?

Strong usage guidance is present: quote average_tdee_kcal for diet targets, check basal_incomplete before quoting a single day, and interpret coverage.window_satisfied:false as a shorter history. However, it never names sibling alternatives or explicitly states when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds rich behavioral detail: it explains the coverage block fields (days_covered, span_days, window_satisfied, more_available), warns about limit-shaped windows being misreported as full history, and clarifies that the data is decrypted. This goes well beyond the annotations.

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

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

The description is well-structured in three paragraphs: core purpose and reference ranges, coverage block semantics, and the more_available warning. It front-loads the key information and each sentence adds value. It is longer than average but the complexity of the coverage behavior justifies the length.

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

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

Given there is an output schema (not shown) and annotations cover safety, the description covers the essential behavioral context: sparsity, limit behavior, owner filtering, coverage interpretation, and the warning about limit-shaped windows. The only gap is the 'fresh' parameter, which is not explained. Overall it is highly complete for a get-metric 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?

Schema description coverage is 0%, so the description must compensate. It explicitly explains owner ('filter by person') and limit (sparsity recommendation, effects on coverage), but does not address the 'fresh' parameter at all. With 3 parameters and no schema descriptions, missing one param's semantics is a notable gap, though it partially compensates for two.

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?

Clearly states the tool decrypts recent VO2Max samples from Apple Watch cardiorespiratory fitness, provides units and reference ranges, and notes the sparsity. It is distinct from sibling get_* tools by explicitly describing the unique coverage block and limit semantics, so an agent can differentiate it from get_resting_hr or get_hrv.

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?

Provides concrete usage guidance: recommends a limit of 30 given sparse data, explains how to filter by owner, and instructs how to interpret coverage fields (e.g., window_satisfied false means shorter history, more_available true means older data exists). It doesn't explicitly name alternatives or exclusions, but the metric-specific naming and detailed context make the intended use 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?

The annotations already mark this as read-only and idempotent, and the description adds substantial behavioral context: local decryption, per-day vs row semantics, the `coverage` block, the meaning of `window_satisfied: false`, and the `more_available` / `oldest_available` caveat. This goes well beyond what annotations provide.

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 dense but front-loaded with the core purpose, followed by return format, owner filtering, and coverage caveats. Each section earns its place, though the coverage warning is repeated and could be tightened slightly.

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

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

For a three-parameter tool with no schema-level descriptions and an output schema available, the description covers output shape, owner sourcing, and the critical coverage edge cases. The only meaningful gap is the undocumented `fresh` parameter, which keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains `owner` thoroughly and `limit` well enough to understand it controls the window and that larger values access older days. However, `fresh` is never mentioned, leaving one of three parameters undocumented.

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

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

The description uses a specific verb and resource: 'Decrypt recent daily water intake locally and compute the average.' It also states the return shape (per-day entries, refill count, container volume, derived liters, and average) which makes the tool's purpose unmistakable and clearly distinct from sibling metric getters.

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, actionable context: this is the tool for recent daily water intake and averages, and it explains how to obtain the `owner` prefix from `vaultbeat_status` or `vaultbeat_doctor`. It does not explicitly name alternatives or exclusions, but the unique resource and filtering guidance provide enough direction for an agent to select it correctly.

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 read-only, idempotent, and non-destructive. The description goes far beyond that by disclosing local decryption, the `coverage` block's exact semantics, the meaning of `window_satisfied: false`, and the caveat that `more_available` may require a larger `limit`. This is rich behavioral context that annotations do not provide.

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

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

The description is long but every sentence adds operational value. It is front-loaded with the tool's purpose, then returns, then parameter guidance, then the critical coverage warning in its own paragraph. The emphatic 'Never report a `limit`-shaped window...' sentence reinforces a high-stakes user-facing mistake without padding.

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

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

An output schema exists, so the description need not restate the full return shape, and it already covers owner sourcing, limit truncation, coverage semantics, and goal handling. The only material gap is `fresh`, which is optional but completely unexplained; otherwise an agent has nearly everything needed to call this 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?

With 0% schema description coverage, the description carries the burden, and it largely delivers: `owner` is sourced and explained, `limit` is tied to `first_day` and `coverage.more_available`, and `goal_kg` is connected to distance-to-goal output. However, `fresh` is never mentioned in the description, so one parameter remains semantically opaque.

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 names a specific verb and resource: 'Decrypt recent body-weight records locally and compute the trend.' The rest of the description elaborates exact outputs (per-day entries, OLS weekly rate, distance to goal), making it obvious this is the weight-trend tool rather than one of the many sibling metric getters.

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 operational guidance for when parameters are relevant, especially `owner` ('take it from `vaultbeat_status` ... or `vaultbeat_doctor`') and `goal_kg` ('when `goal_kg` is given'). It does not explicitly contrast this tool with siblings such as `get_metric_trend` or `list_metric_series`, so alternative/exclusion guidance is missing, but the context is otherwise 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 already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial non-obvious behavior: the coverage block semantics, how to interpret `coverage.window_satisfied: false`, and the warning about `limit`-shaped windows not representing true data history. This goes far beyond the structured annotations and prevents a realistic 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?

The core purpose is front-loaded in the first sentence, followed by a short parameter tip and then a detailed coverage block. The coverage block is essential but fairly long; the emoji and explicit formatting make it scannable. It is not overly padded, though a bit verbose for such a small parameter set.

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 of the coverage block and the presence of an output schema, the description covers the main pitfalls thoroughly and explains how to report data extent correctly. The only noticeable gap is the `fresh` parameter, which is undocumented in both schema and description. Overall, it is nearly complete for an agent to call and interpret the result correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain `owner` ('filter by person') and `limit` (it leaves older days behind and can be increased to retrieve them), which adds real meaning beyond the raw schema. However, `fresh` is never described, leaving one of three parameters without semantic context.

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, 'Decrypt recent workout sessions (type, duration, calories, distance),' identifies a specific verb and resource with the key fields returned. It is clear and distinct from siblings like get_activity, but it does not explicitly name an alternative or contrast its scope, 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 only usage guidance is 'Use `owner` prefix to filter by person,' which is a parameter tip, not guidance on when to choose this tool over alternatives such as get_activity or get_strength_log. There is no when/when-not language, no prerequisites, and no mention of alternative tools, so the description provides little decision support.

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, idempotentHint, destructiveHint, and openWorldHint, but the description adds substantial behavioral context beyond these: the absolute vs delta distinction, the legacy field naming, the coverage block semantics, window_satisfied, more_available, and the instruction to re-read with a larger limit. It also clarifies that samples are one per night and owner filtering is available. No contradiction 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 long but well-structured: it opens with the core purpose, then warns about the absolute-vs-delta pitfall, then details the coverage block and interpretation rules. Each section adds necessary information for a complex tool with coverage semantics. It is front-loaded and not redundant, though it could be trimmed slightly for the less-critical warnings. Overall, it earns its length.

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

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

For a tool with three optional parameters, no schema descriptions, and a rich output schema (not shown), the description is remarkably complete. It explains the main semantic trap (absolute vs delta), the coverage fields and their meanings, the concept of more_available, and the correct way to report history. The only gap is the 'fresh' parameter, but that is a minor omission given the overall depth. An agent can call this tool correctly and interpret its results without further information.

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 the parameters. It indirectly explains 'limit' (affects how many samples are returned, can be enlarged) and 'owner' (used as a prefix to filter), but it does not mention 'fresh' at all. Given that the schema provides no descriptions, the coverage is incomplete, though the hints about limit and owner are helpful. The score reflects the partial compensation.

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

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

The description states a specific verb and resource: 'Decrypt recent sleeping wrist temperature samples — ABSOLUTE °C.' It clearly distinguishes absolute skin temperatures from baseline deltas and mentions the legacy field-name misnomer, leaving no ambiguity about what data is returned. The scope (sleeping wrist temperature) is unique among sibling tools, which are mostly other metrics or logging actions.

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 explicit guidance on when to use the tool and how to interpret results: it explains that baseline deviation must be derived manually, it instructs to quote coverage.days_covered and coverage.span_days, and it warns about not reporting a limit-shaped window as the full history. It does not explicitly name alternative tools for temperature, but the usage context is clear and actionable. The only missing piece is a direct 'when not to use' statement.

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=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: the list excludes certain richer-shape kinds and explains why (flattening them would answer a question you did not ask), plus it signals the return includes units. The behavior of omission is disclosed, which goes 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?

Every sentence earns its place. The first sentence states the core purpose with units. The second gives a precise call-timing directive. The third explains a non-obvious exclusion behavior and routes to siblings. No filler, and the most important usage guidance is front-loaded immediately after the 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?

For a zero-parameter, read-only enumeration tool with an output schema present, the description covers purpose, timing, exclusions, and sibling routing. The output schema presumably documents the exact fields, so the description doesn't need to repeat return structure. Nothing needed for correct invocation is missing.

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

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

The tool takes zero parameters, so schema coverage is trivially 100%. The description adds value by explaining what the returned data will contain (series names and units) and which kinds are intentionally missing. While there are no parameters to document, the description compensates by clarifying the semantics of the returned enumeration.

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: 'List every series the trend / compare / correlate tools accept, with units.' It clearly names the sibling tools that consume this list, which distinguishes it from all the get_* / log_* siblings whose resources it catalogs. An agent can tell exactly what this tool is for.

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

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

The description gives explicit usage timing: 'Call this BEFORE guessing a series name.' It also explicitly names alternatives and exclusion criteria: series with richer shape (sleep stages, workouts, strength sets, food, notes, symptoms, cycle) are deliberately absent and should be read with their own get_* tools. This is clear when-to-use and when-not-to-use 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?

The description goes well beyond the annotations: it explains the append semantics, the merge behavior for matching meal names, the guarantee that nothing is deleted, the always-empty replaced_meals receipt, the inability to set the day's note, and end-to-end encryption. It also discloses the persistence of estimated nutrition values and the risk of confident wrong estimates. This is rich behavioral context that annotations (which only say readOnlyHint=false, destructiveHint=false) do not provide.

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

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

The description is long but every paragraph earns its place: append semantics, sibling routing, parameter shapes, photo estimation guidance, and the note-field limitation. The photo-estimation paragraph is somewhat tangential to the tool's core mechanics but is relevant because this tool persists estimates. The structure is front-loaded with the most critical semantic (append, not replace).

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 2-parameter tool with 0% schema coverage, the description is complete: it covers both parameters, the return shape, the deletion guarantee, the sibling distinction, and the persistence implications. The output schema exists and the description references its shape ('same shape log_food_entry returns'), so return values need no further explanation.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains date as the LOCAL calendar day 'YYYY-MM-DD', and gives a full shape for meals with an example. It also documents that everything but food is optional, that snake_case aliases are accepted, and that estimated nutrition should go into structured fields. This fully compensates for the empty 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 opens with a specific verb and resource ('Add meals to a day WITHOUT touching what is already logged') and immediately distinguishes itself from the sibling log_food_entry. It clearly states the append semantics and names the exact use cases ('log the snack I forgot' / 'add dinner to today').

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 when to use this tool vs log_food_entry: use this for appending, use log_food_entry only when the supplied meals should become the day's ENTIRE log. It also explains what this tool cannot do (set the day's note) and routes that to log_food_entry. This is explicit 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?

Even though annotations already set destructiveHint=true, the description adds crucial behavioral detail: this tool silently deletes any meal not re-sent, merge=True behaves like log_food_append, note=None preserves the existing note, and the call is encrypted end-to-end. It also warns about the replace-vs-append mistake and what the result's replaced_meals field means.

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 front-loaded with the critical deletion warning and organized into focused paragraphs. It is longer than strictly necessary, and the maintainer note about keeping photo-estimation copy in sync is noise for an agent, but nearly every other sentence adds operational 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?

Given the destructive nature and four parameters, the description is remarkably complete: it covers all parameters, the exact deletion semantics, the alternative tool, merge behavior, note handling, output's replaced_meals, photo-estimation pitfalls, and persistence of nutrition values. An agent has everything needed to invoke it safely and correctly.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter semantics. It thoroughly explains date as 'LOCAL calendar day, YYYY-MM-DD', gives the meals structure with an example, documents note=None behavior vs. note="", and clarifies the merge parameter. It even covers optional item fields and snake_case aliases, going well beyond the bare schema.

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

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

The description states a specific action and resource: 'Log one day's food intake on the owner's behalf' and the title adds 'replaces day'. It explicitly contrasts itself with log_food_append, so an agent can distinguish the destructive replacement behavior from appending without opening the sibling 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 when-to-use vs. when-not-to-use guidance: 'If you meant to ADD to a day rather than replace it, STOP and call log_food_append instead'. It also explains the merge=True alias and directs new callers to the separate tool, leaving no ambiguity about the preferred alternative.

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?

Even though annotations already set destructiveHint=true, the description goes far beyond that: it states one note per (kind, day), that text becomes the entire contents, that overwritten notes are silently deleted, and that replaced_text reveals the deletion. It also discloses merge=True compatibility, refusal of iOS-authored sleep/menstrual notes, end-to-end encryption, and how to recover a destroyed note.

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

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

The description is long but the destructive behavior makes the length justified. It is front-loaded with the core action, then immediately warns about deletion with a bold callout. Subsequent paragraphs each add independent value: alias behavior, recovery instructions, symptom use-case, date semantics, and encryption. The structure keeps high-risk information prominent.

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 tool's destructive semantics, 4 parameters, 0% schema coverage, and output schema, the description covers everything an agent needs: purpose, parameter semantics, when to choose the sibling, deletion consequences, recovery via merge=True, output meaning, and privacy. Nothing material is missing.

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

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

Schema description coverage is 0%, and the description fully compensates. It explains kind values (mood vs general), date as LOCAL calendar day YYYY-MM-DD with default today, text as replacing the entire note, and merge=True as equivalent to log_note_append. It even clarifies the output field replaced_text. Every parameter and the key return value gets meaningful semantic context.

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 states a specific action and resource: "Log a free-text note on the owner's behalf (agent write)." It also differentiates from siblings like log_note_append and get_notes by describing the note-taking role and the kind values it supports. The description makes it unmistakable what this tool does.

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 tells when to use this tool versus log_note_append: "If you meant to ADD to a day rather than replace it, STOP and call log_note_append instead" and "For symptoms, use log_note_append." It also warns that new callers should prefer the separate visible tool over the buried merge=True flag. This is exemplary when-to-use 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 are sparse (all flat false hints), so the description carries the burden and fully delivers: it discloses append-only semantics, the inability to delete existing content, refusal of sleep/menstrual kinds, the always-null replaced_text receipt, end-to-end encryption, and consequence of repeat calls (second write is normal, not an error). This goes well beyond what annotations 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?

Key behavior is front-loaded in the first sentence, and the structure flows from behavior to usage to parameters to return shape. It is somewhat long and the 'nausea at noon, dizziness at night' narrative is illustrative rather than strictly necessary, but every sentence does contribute usage, parameter, or behavioral value, so the length is mostly earned.

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

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

For a 3-parameter write tool with barren schema (0% coverage), this description is complete: it covers selection (vs log_note), all parameters with formats and defaults, constrained kinds and refusals, return-value semantics via replaced_text, and security. The output schema exists, so not restating the full return shape is appropriate.

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

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

Schema coverage is 0% and the schema is just typed titles with no descriptions, so the description must compensate and does: text is the line to append, date is the local calendar day in YYYY-MM-DD with today as default, and kind is fully documented with 'general' and 'mood' semantics plus the refused values. Every parameter is meaningfully explained.

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

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

The description names a specific verb and resource ('Add a line to a day's note') and immediately states the critical distinguishing scope: it appends WITHOUT erasing existing content. It explicitly contrasts with the sibling log_note and even names the exact condition under which log_note is the right choice, so an agent can disambiguate 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?

Gives explicit when-to-use guidance ('USE THIS FOR SYMPTOMS'), explains the recurring-write rationale with a concrete example, and states when NOT to use it (use log_note only when the text should become the entire note). It also enumerates allowed kind values and notes which kinds are refused, leaving nothing to inference.

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

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

Beyond the annotations, the description discloses detailed behavioral guarantees: it cannot delete anything not sent, matching exercise names append their sets, it deliberately cannot set the session note, `replaced_exercises` is always an empty list as a no-deletion receipt, data is encrypted end-to-end, and it requires a bind made after the agent write path shipped. This is substantially more behavioral context than the annotations alone provide, and there is no contradiction.

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

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

The description is long but every section earns its place: core behavior, usage guidance, parameter semantics, exclusions, result receipt, and binding prerequisite. It is front-loaded with the most decision-critical information first, and the details are grouped so an agent can quickly extract what it needs.

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

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

The description is complete for a complex mutation tool with minimal input schema. It covers the operation semantics, the exact sibling distinction, parameter formats, the session-note limitation, return-shape behavior, security/encryption, and a concrete bind-version prerequisite for older sessions. Since an output schema exists, the description does not need to detail the full return structure.

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?

With 0% schema description coverage, the description fully compensates by defining `date` as the local calendar day in YYYY-MM-DD format and `exercises` with a concrete example showing `name` and nested `sets` containing `weightKg` and `reps`. It also explains the matching rule by `name`, which is essential behavioral semantics for the main 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 opens with a specific verb and resource: 'Add exercises to a session WITHOUT touching what is already logged.' It explicitly distinguishes itself from `log_strength_entry`, explaining that this tool appends while the sibling replaces the day's session, so an agent can select it correctly without opening schemas.

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

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

The description gives explicit when-to-use scenarios ('log the set I forgot', 'logging a session in installments') and an explicit when-not-to-use rule: reach for `log_strength_entry` only when the supplied exercises should become the ENTIRE session and everything else deleted. It also covers the session-note edge case and directs the agent to the correct sibling for that operation.

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 destructiveHint=true and readOnlyHint=false, but the description goes far beyond: it warns that unsent exercises are silently deleted, explains the replaced_exercises field in the result, details note=None behavior, and discloses end-to-end encryption and binding requirements. This is exactly the kind of 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?

The description is long but every sentence earns its place. The critical deletion warning is front-loaded, the alternative tool is named immediately, and subsequent paragraphs explain merge, note, date, exercises, encryption, and binding. No filler; the density is justified by the destructive risk.

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

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

For a destructive write tool with encryption and binding prerequisites, the description covers all operational aspects: deletion semantics, merge behavior, note handling, input formats, security, and re-pairing steps. It even references the result field and sibling tools. An agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 0%, so the description must fully document parameters. It does: date format 'YYYY-MM-DD', exercises structure with a concrete example, note=None leaves existing note (pass note='' to clear), and merge=True behaves like the append tool. Every parameter is explained with behavioral nuance.

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 logs one strength-training session, and immediately differentiates it from log_strength_append which adds without deleting. The phrase 'replaces day' in the title and the explicit warning make the destructive nature unambiguous. An agent can instantly tell this tool from its 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?

Explicitly instructs when to use this tool vs. log_strength_append: 'If you meant to ADD to a day rather than replace it, STOP and call log_strength_append instead'. Also explains merge=True compatibility and advises new callers to use the separate tool. No ambiguity remains.

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?

Building on annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=false), the description discloses what gets destroyed (same-day entry overwritten via dayID 'body-{dayStart.epoch}'), the always-on storage path (Vaultbeat cloud + MCP), conditional Apple Health sync gated by an iOS toggle, end-to-end encryption, and the trend-corruption failure mode. It deepens the annotations rather than repeating or contradicting them.

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

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

Purpose is front-loaded and the layout (params → behavior → warnings) is logical, with nearly every sentence earning its place. The deduction is the closing historical note about the 2026-07-28 docstring revision — self-referential documentation history that an agent does not need and that slightly muddies the date timeline.

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 write tool with destructive overwrite and external Apple Health side effects, the description covers parameter constraints, defaults, storage destination, sync conditions, the corruption failure mode, and the exact user-facing instruction to give. Since an output schema exists, not explaining return values is acceptable, and nothing an agent needs to invoke or reason about 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?

Schema description coverage is 0%, so the description carries the full burden for both parameters. It supplies constraints (weight_kg must be positive and ≤500), format and meaning (date is a LOCAL 'YYYY-MM-DD' day), and the default behavior (today) — all absent from the bare schema.

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

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

The opening sentence 'Log the owner's weight (kg) on their behalf' names a specific verb, resource, unit, and acting party, and the title 'Log weight' reinforces it. The body references get_weight_trend as the read counterpart, so an agent can distinguish this write tool from its sibling log_* tools 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?

The description gives explicit usage semantics: same-day upsert-in-place overwrite behavior and a default date of today. It also gives an explicit when-not instruction — do NOT tell the owner to re-enter the weight manually, because double-entry corrupts the trend line — plus the correct alternative (enable the 'Allow AI to update Apple Health' toggle), routing the agent's behavior precisely.

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 goes far beyond the annotations, disclosing that the tool performs a cloud round trip, that it is slower than the local-only status tool, and that its report has three distinct parts: checks, capabilities, and scope. It also transparently explains the tool's limitations—it cannot inspect the client's config, environment variables, or launch arguments—and warns that a green report does not clear the client. This is rich behavioral context that annotations alone would not provide.

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?

Although the description is long, it is efficiently structured with clear sections for `checks`, `capabilities`, and `scope`, and each sentence adds distinct value. The first sentence states the core purpose, and the later paragraphs elaborate without redundancy. The length is justified by the nuance required to prevent false conclusions about missing data.

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

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

The description is complete for a diagnostic tool of this complexity: it explains the trigger conditions, the output structure, the meaning of each result section, the limitations, and the relationship to the sibling status tool. An output schema exists, so return-value detail is not required, but the description still provides enough context for an agent to interpret the results correctly. 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 tool has zero parameters, so the schema carries no parameter burden and the description need not explain any. The baseline for zero-parameter tools is 4, and nothing in the description contradicts or complicates that. The description even clarifies what the tool does not cover, which is more than necessary for parameter 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?

The description opens with a specific verb and resource: 'Diagnose this Vaultbeat MCP install, and report which data types are unavailable.' It clearly distinguishes the tool from siblings by contrasting it with `vaultbeat_status` and by framing it as the diagnostic tool to run when reads fail. This is more than a restatement of the title.

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 states exactly when to invoke: 'Call this when a read tool returns nothing, or when anything fails, before telling the user their data is missing.' It also names an alternative (`vaultbeat_status`) and gives the preference rule: use status for a quick liveness check because doctor is slower. This is explicit, actionable 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?

The description goes far beyond the annotations by explaining the semantic meaning of 'pending' as positive evidence, the endpoint's pollID lookup behavior, and the destructive consequence of rerunning bind. It also explains why a long run of 'pending' is not staleness, which is critical for correct agent behavior. No contradiction 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 front-loaded with purpose, uses a clear bulleted status list, and bolds the terminal condition. It is long, but every sentence earns its place by conveying diagnostic or action-guiding information that prevents a destructive mistake.

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

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

The description covers all statuses, terminal behavior, user-facing instructions, and the most likely misinterpretation. Since an output schema exists, not describing the return format is acceptable. The description is complete for safe and correct invocation.

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

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

There are zero parameters, so the schema carries no explanatory burden. The description adds useful operational context (pollID lookup, statuses, polling behavior), but no parameter-level detail is needed.

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

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

The description opens with a specific verb and resource: 'Check whether the user has scanned the QR code and authorized this server.' It then defines the three possible statuses, making the tool's function concrete. It clearly distinguishes itself from vaultbeat_start_binding by saying 'Call this after vaultbeat_start_binding.'

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 guidance is explicit and actionable: call it after start_binding, keep polling while pending, stop on expired, and never rerun bind while pending. It also names the correct alternative for expired states and explicitly tells the agent what not to do ('Do not send them to check the network, reinstall this server, or run diagnostics').

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

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

Beyond the annotations, the description clarifies exactly what is and is not invalidated: an open QR is invalidated, but existing credentials keep working until a scan lands. It also discloses the historical behavior before 2026-08-11, preventing an agent with stale knowledge from silently unbinding a user.

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 front-loaded with the core purpose, and every paragraph earns its place: the QR-rendering warning prevents a real failure mode, the return/poll guidance completes the workflow, and the historical note prevents dangerous misuse.

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

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

The description covers the full binding flow, output usage, fallback behavior, and safety nuances. It is slightly incomplete only because it leaves `server_name` unexplained, though the schema default makes this a minor gap.

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

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

Schema description coverage is 0%, and the description never mentions the only parameter, `server_name`. The schema's title and default give some hint, but the tool description itself adds no meaning about what value to pass or how it is used.

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

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

The description opens with a specific verb and object: 'Initialize a binding session', then specifies what the call does (generates a keypair if needed) and what it returns (a QR payload). It clearly differentiates itself from vaultbeat_poll_binding by positioning itself as the start of the flow.

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 call vaultbeat_poll_binding after the user scans, gives a concrete fallback command (`uvx vaultbeat-apple-health bind`) when QR rendering fails, and explains that this call does not disturb an existing binding. The 'when to use' and 'what to do instead' guidance is direct 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond annotations: it guarantees no private keys or server tokens are exposed and that the state is local. This is meaningful behavioral disclosure without contradiction.

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

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

The description is a single sentence, front-loaded with the action and resource, followed by a brief security caveat. Every word earns its place with no redundancy.

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 tool with a full annotation set and an output schema, the description fully explains what it returns and what it deliberately omits. Nothing an agent needs to call it correctly is missing.

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

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

With zero parameters, the baseline is 4. The description does not need to explain inputs, and it correctly focuses on the return value and security properties.

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 uses a specific verb ('Return') and resource ('local Vaultbeat binding state'), and further clarifies what it does NOT expose (private keys or server tokens). This clearly distinguishes it from siblings like vaultbeat_start_binding and vaultbeat_poll_binding, which deal with establishing or polling bindings.

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 context is clear: this is a read-only status check. However, the description does not explicitly state when to prefer this over alternatives such as vaultbeat_poll_binding or vaultbeat_doctor, nor does it give exclusions. The usage 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?

The description adds substantial behavioral context beyond the annotations: local decryption, a 10-minute cache with `fresh=True` forcing a cloud round trip, output-size overflow behavior, the `is_in_bed_only` interpretation trap, and the `coverage.more_available` caveat about limit-shaped windows. Despite mentioning 'side effect' and 'force a sync,' it does not contradict the readOnly/idempotent/non-destructive annotations because those actions are retrieval/cache refreshes, not data mutations.

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

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

The description is long, but the tool is complex and full of easy-to-miss traps, so most sentences earn their place. It is front-loaded with the core purpose. A slight deduction is warranted because some phrasing, such as 'which is a large share of real calls' and the extended overflow narrative, could be trimmed without losing essential guidance.

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

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

Given the tool's complexity, the lack of required parameters, and the presence of an output schema, this description is unusually complete. It covers return blocks, per-day selection priority, owner filtering, cache semantics, output-size failure mode, coverage interpretation, and the in-bed-only semantic trap. There is no important calling consideration left to the agent to discover.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it succeeds for all four parameters: `limit` is tied to raw blob count and rough time span, `owner` is sourced from specific sibling tools with a warning about mixing partners, `fresh` is tied to the cache, and `summary_only` is explained in terms of returned fields and output size. This is far more than the raw schema provides.

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

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

The description opens with a specific verb-plus-resource statement: 'Fetch encrypted Vaultbeat sleep records, decrypt them locally, and return per-day primary session summaries matching the iOS app's display.' It clearly distinguishes this tool from get_sleep_detail, which is explicitly named as the tool for raw night-level details. The name and title alone would not convey this, so the description adds real 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?

Usage guidance is explicit and actionable. It says to use `owner` filtered from `vaultbeat_status` or `vaultbeat_doctor`, describes the consequence of omitting it, explains when to pass `fresh=True`, and tells the agent to prefer `summary_only=True` when only the side effect is wanted. It also routes night-level needs to get_sleep_detail, giving a clear alternative.

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