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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: paces are never pooled, classes below a minimum time are `gated` with their time stated, bests are sliding windows not instantaneous maxima, and cadence excludes standing. However, it says nothing about read-only vs mutating nature, failure modes, or how the many date/filter parameters change the scope of results.

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

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

It is front-loaded with what is returned, which is good, but the body drifts into essayistic reasoning ('a maximum selects for positive measurement error in a way a mean does not') and carries a stray '§6.0 the run's own description' artifact. Much of the caution text is valuable; some of it is prose that costs tokens without changing agent behavior.

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

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

An output schema exists, yet the description spends most of its length explaining return values it did not need to, while leaving 7 of 8 input parameters undefined. For a tool whose filtering behavior is driven by those parameters, the definition is asymmetric: rich on interpretation, thin on how to actually scope a call.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate — but it only documents `run` (run_id, activity_id or Garmin file id; empty means latest). The other seven (`last_n`, `cluster`, `start_date`, `end_date`, `run_type`, `direction`, `segment_id`) are left entirely unexplained, so their semantics remain invisible.

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 the concrete contents returned for a single run (average HR, three pace bases, windowed bests, run/walk/stand time, cadence), which is far more specific than a restatement of the name. It does not explicitly contrast itself with siblings like session_series or efficiency_factor, leaving the agent to infer that this is the per-run summary anchor.

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?

There is one piece of real routing guidance — that average HR is a baseline to be quoted as the level drift and efficiency deviate from, not a finding. That implies this tool is a starting point before the analytic siblings, but no alternative is ever named and no when-not-to-use condition is given.

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

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

With no annotations, the description carries the full burden and does well: it warns that run and walk are never pooled and explains why, and it discloses the DEM-coverage constraint plus the `n_runs_without_grade` counter for excluded runs. It omits any statement on read-only semantics, cost, or result shape, but the data-coverage caveats are exactly the kind of context an agent cannot get elsewhere.

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

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

Three short sentences, front-loaded with the operation, with zero filler — the pooling rationale earns its space by justifying the split. The leading '§6.0' reference is cryptic overhead but negligible.

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

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

An output schema exists, so return values needn't be explained, and the coverage caveat is handled well. But for a 7-parameter tool with zero schema descriptions, the description should say what the selection, cluster, direction, and date arguments do; that gap is material.

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?

Seven parameters at 0% schema description coverage (titles only) — last_n, cluster, end_date, run_type, direction, segment_id, start_date are all undocumented in both places. The description mentions `split_type` and `n_runs_without_grade`, neither of which appears in the input schema, so it adds confusion rather than meaning for the actual callable arguments.

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 metric (cadence), a specific bucketing (per 5% grade bin), a selection scope, and a grouping key (split_type). That is enough to distinguish it from siblings like grade_binned_pace, though it never names an alternative directly.

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

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

Usage is implied through 'over a selection' and the split_type grouping, and the 'never pooled' note tells the agent how results behave. However, there is no explicit when-to-use or when-not guidance relative to siblings such as grade_binned_pace, leaving the agent to infer the choice.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that ascent and descent are not comparable and that tau is excluded, but it does not state whether the operation is read-only, what permissions are needed, whether there are side effects, or other operational constraints.

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 short and front-loads the metric definition before the caveats. However, the repeated '§6.3' references are opaque to an agent that lacks the referenced specification, which slightly reduces 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?

The tool has 7 parameters, no schema descriptions, and no annotations, so the description needs to compensate substantially. It provides metric context and two important caveats, but it omits parameter semantics and when-to-use guidance, leaving the definition incomplete for 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 7 parameters with 0% schema description coverage, and the description explains none of them beyond a vague reference to 'direction' and 'selection.' Key parameters such as last_n, cluster, start_date, end_date, run_type, and segment_id are left completely undocumented in both the schema and the description.

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

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

The description identifies a specific metric: HR excursion across an effort, broken out by direction and constrained to a selection. It is clear enough to distinguish this from generic metrics tools, but it does not explicitly name or distinguish itself from closely related siblings such as segment_effort_drift or matched_terrain_drift.

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?

There is no explicit guidance on when to use this tool versus alternatives. The only usage-adjacent information is a caveat that ascent and descent are not comparable and that tau is never returned, which is interpretation guidance rather than selection 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the gate is computed against a live corpus, unreportable results are diagnostic-only, onset is confounded with run length, the earliest representable value is bounded by a 600 s pair separation, and dew point travels with every value for interpretability. What it does not clarify is what 'REFUSED' operationally means for the caller (empty result, error, or a flagged row).

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, which is good, and every paragraph is about something real. But the section-number jargon and the 'currently REFUSED' framing consume space without adding actionable meaning, and the Args block documents only one of eight arguments despite the space it takes.

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 needn't enumerate return fields, yet the gate/reportable/reason interpretation it does provide is genuinely necessary context for a tool whose output can be non-reportable. Against that, seven undocumented parameters and an unresolved 'REFUSED' status leave an agent guessing about 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?

Schema description coverage is 0% across 8 parameters, and the description documents only 'run' (run_id/activity_id/Garmin file id, empty = latest). The remaining seven — last_n, cluster, end_date, run_type, direction, segment_id, start_date — are left entirely to a bare schema, so an agent cannot infer filtering or scope semantics from the text.

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 quantity (the time in a run at which cardiac drift begins) but buries it under internal section references (§6.9, §6.7, §6.3) that mean nothing to an agent without the source documentation. It never differentiates itself from drift-flavored siblings like matched_terrain_drift or segment_effort_drift, and the phrase 'currently REFUSED' is ambiguous about whether the tool answers at all or just marks results non-reportable.

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 real interpretive guidance — do not quote the curve as a finding while gate.reportable is false, and read gate.reason to learn what would change that. But it says nothing about when to reach for this tool versus the other drift siblings, and the 'Empty means the latest run' note only covers one parameter. Usage is implied rather than routed.

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

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

With no annotations, the description carries the full behavioral burden. It discloses one meaningful trait — that matching uses segment identity rather than GAP because GAP is unvalidated — but says nothing about read-only vs mutation nature, cost, what happens with an empty selection, how defaults on the seven optional filters behave, or failure modes.

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

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

It is short and the metric definition is front-loaded, so there is little waste. But the spec-section citations (§6.8, §12.2) occupy space without conveying anything to an agent that cannot read the spec, making the text dense yet under-informative.

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 existence of an output schema excuses it from explaining return values. Everything else is missing: seven undocumented parameters at 0% coverage, no annotations, no precondition or exclusion guidance, and a rationale-heavy framing that leaves an agent unable to construct a correct call confidently.

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

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

Schema description coverage is 0% across seven parameters, so the description must compensate and largely fails. 'Over a selection' vaguely gestures at the filtering parameters (last_n, cluster, date range, run_type, direction, segment_id) but explains none of their units, formats, default semantics (empty string vs 0), or interaction.

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 phrase 'speed per heartbeat on segment-matched terrain' identifies the computed metric and its scope ('over a selection'), which is more than a restatement of the name. However, it never uses a verb like 'compute' or 'calculate', and the leading '§6.8' reference assumes the agent already knows the spec. The contrast with GAP-based matching hints at sibling differentiation but does not name an alternative 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?

'Matched by segment identity, NOT by GAP' is a methodological constraint on the computation, not guidance on when to invoke this tool. Nothing tells the agent when to pick this over matched_terrain_drift, segment_effort_drift, or basic_metrics, nor what preconditions (segment history, sufficient rides) are required.

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

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

With no annotations, the description carries the full burden, and it does disclose one important trait: run and walk are never pooled, with the rationale for why pooling misleads. It omits other key behavior — what empty-string/zero defaults mean (all data vs none), permission needs, and how a 'selection' is bounded.

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

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

Front-loaded with the core operation and tightly sized — two short sentences with no filler. The section-number prefix and slightly verbose second sentence cost a point.

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

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

An output schema exists so return values needn't be explained, but for a 7-parameter, annotation-free analytical tool the description leaves the entire parameter surface and the default/empty-value behavior unexplained. Only the non-pooling caveat is covered.

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?

Seven parameters at 0% schema description coverage, and the description explains none of them. It mentions a 'split_type' that is not even a parameter, and never clarifies run_type, direction, last_n, or the date/cluster filters, so it fails to compensate for the coverage gap.

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

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

States a specific computation (pace binned by grade, split by split_type) scoped to a selection, which is distinguishable from siblings like cadence_by_grade and hill_pace. The '§6.2' reference and the absence of a real verb keep it from being a crisp 5.

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

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

Usage is only implied: 'over a selection' hints at when it applies, and the run/walk warning explains interpretation rather than tool selection. No sibling is named as an alternative (e.g., when to choose this vs. hill_pace or cadence_by_grade).

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

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

With no annotations, the description carries the burden and does add substantive behavioral context: it explains that mean pace and best 30 s are different quantities, that a slow mean beside a fast best is not a contradiction, and that ascent-vs-descent comparisons are terrain-confounded. It does not explicitly state read-only behavior or side-effect profile, but for an analytics tool the non-obvious output semantics are well disclosed.

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

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

The description is front-loaded with purpose and structured with an Args section, and the interpretive caveats are relevant rather than filler. It is somewhat prose-heavy, but each paragraph serves a real comprehension 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?

The core output interpretation is covered, and an output schema exists, but the description is not complete for an 8-parameter tool with 0% schema description coverage: most filters are never explained. An agent can understand the headline metric but not how to correctly scope the query.

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

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

Schema description coverage is 0% across 8 parameters, and the description explains only `run` (run_id/activity_id/Garmin file id, empty means latest). It leaves `last_n`, `cluster`, `start_date`, `end_date`, `run_type`, `direction`, and `segment_id` entirely undocumented, so an agent must guess their 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 states a precise resource and scope: pace on every slope effort of one run, split by direction. It is clear what the tool computes, but it does not differentiate itself from siblings such as grade_binned_pace or segment-based 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 only guidance is interpretive: read comparable_ground.length_ratio before comparing directions. There is no explicit statement of when to choose this tool over siblings, nor any when-not-to-use or alternative-tool 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?

With no annotations, the description carries the full burden and does so unusually well: it discloses that HR is raw and never lag-shifted, that flags are reported but not applied, that runs with unresolved peak provenance are marked and never dropped, and that totals are re-reported under without_unresolved_peak. These are exactly the behavioral facts an agent could not infer from the schema.

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

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

The core statement is front-loaded and the key caveats are legible, but the prose is padded with emphatic asides and a rhetorical line about climbing versus flat running that consume space without adding callable information. The heavy capitalization and bold formatting also fight the reader rather than helping.

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 long enumeration of returned fields (run, date, offset, span, peak, 30 s window, flags, pace/grade/cadence) is largely redundant, while the 7 undocumented filter parameters are the real gap. For an 8-parameter query tool the description is complete on semantics of the data but incomplete on how to scope the query.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate. It documents only threshold (0 means the configured hr_above_default_bpm, and threshold_bpm in the result echoes the value used); last_n, cluster, start_date, end_date, run_type, direction, and segment_id are left entirely undefined.

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

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

States a specific resource and scope: 'Every contiguous excursion at or above a heart-rate threshold,' and explicitly frames the unit of return as an excursion rather than a record. That distinguishes it conceptually from row-per-reading tools, though it never names a sibling like time_above_hr or max_hr_over.

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 motivates the tool ('deciding whether a ceiling is demonstrated or merely recorded') and explains the threshold parameter's default, which implies when to reach for it. But it gives no explicit when-not guidance and does not say how it differs from the closely named time_above_hr or max_hr_over siblings.

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

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

With no annotations, the description does real work: it discloses that run_type filters are REJECTED, that rows report run_type as null labelled 'not collected', and that rows carry local_date. These are non-obvious behaviors an agent could not derive from schema or annotations. Gaps remain around permissions and limit edge behavior, preventing a 5.

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

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

The lead sentence front-loads purpose and ordering before the parameter block. The docstring-style 'Args:' formatting and the multi-line run_type explanation are somewhat verbose, but every clause conveys actionable semantics rather than filler.

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

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

An output schema exists, so return values need not be described, and the description covers filter interaction, ordering, and the notable run_type degradation. Minor gaps (pagination ceiling, whether results are truncated silently) remain for a 6-parameter query 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 coverage is 0%, so the description must carry all parameter meaning, and it does: date formats and inclusivity, the rejected run_type path, cluster special values (NO_GPS / OTHER) sourced from config, and the critical sport semantics ('empty' = running, 'any' = all sports). Only 'limit: maximum rows' is thin, but it is sufficient.

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 ('Corpus listing') plus ordering ('newest first') and scoping semantics ('All filters optional and AND-ed'). It never names the nearest sibling (list_segments) or explicitly says 'runs', so differentiation is left to inference, which keeps it below a 5.

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

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

Usage is implied by the sport/cluster semantics ('empty means running', 'a cluster name from config/athlete.yaml'), so an agent can infer when this tool applies. However, there is no explicit when-to-use/when-not guidance and no reference to alternatives such as list_segments.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies an unfiltered enumeration via 'every segment', but never states read-only behavior, side effects, ordering, or what 'reference run' means; the output schema covers return fields but not call behavior.

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?

A single sentence with no filler is appropriately concise, but the metaphor 'slope library' and unexplained 'reference run' make it cryptic rather than clearly front-loaded with an action.

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 list tool with an output schema, the description is almost sufficient: it signals complete enumeration and inclusion of reference-run intersection data. However, it does not clarify what 'reference run' means or how this differs from siblings like segment_history.

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 there are no parameter semantics to document. Baseline 4 is appropriate because the description need not compensate for any schema gaps.

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?

Identifies the resource (segments) and scope ('every segment'), but lacks an explicit verb and the phrase 'where the reference run meets it' is ambiguous. An agent can infer this is a list operation, but not precisely what a segment record represents.

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?

No when-to-use or when-not guidance is provided, and no alternatives are named among the many sibling tools such as segment_history. 'The slope library' weakly implies discovery, but the description does not say when to choose this over segment-focused siblings.

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

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

With no annotations, the description carries the behavioral burden well: it discloses pairing rules, distance and time tolerances, speed matching, exclusion of walking, and that users should inspect `applied_filters` and `excluded`. It does not state read-only or permission assumptions, but the operational filtering behavior is unusually well documented.

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 metric definition and remains relatively tight. It includes some internal section references and backtick field names that may be unnecessary noise, but every substantive sentence adds behavioral or selection context.

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

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

The output schema means return values need not be explained, and the description explains the metric's construction and exclusions well. However, for a tool with seven undocumented input parameters and no annotations, the description is materially incomplete for correct invocation because it provides no parameter guidance.

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 seven parameters with 0% description coverage, and the description does not explain any of them. Terms like `last_n`, `cluster`, `run_type`, `direction`, and `segment_id` are left entirely for the agent to infer, so the description fails to compensate for the schema gap.

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

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

The description states a specific metric and scope: HR drift on the same ground, expressed in bpm/hour, over selected runs. It explicitly distinguishes this quantity from `segment_effort_drift`, so an agent can tell which drift metric is being requested.

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 a clear usage condition: this is the substitute when the steady-effort gate in §6.4 fails. It also warns that `segment_effort_drift` is a different quantity and that neither is 'the' drift, which directly helps tool selection. The only weakness is reliance on an external section reference.

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

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

With no annotations, the description carries the full burden and does so well: it flags max_hr_recorded as a spike candidate selected for positive measurement error, discloses that §15.4-flagged records are excluded from the 30 s ceiling, states that run_type is null by design, and explains that declared_ceiling is reported but never corrected. It also documents the gated/refusal behavior of the comparison and names what it returns when refused, which is exactly the behavioral context structured fields don't supply.

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 first sentence is well front-loaded, but the body is long for a small result object and spends much of its length on emphasized editorial framing (ALL CAPS, bold, §-references) rather than new information. The core facts are present but padded.

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

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

An output schema exists, so return-value explanation is legitimately omitted, and the behavioral/semantic side of the result is thoroughly covered. What is missing is the input side: with seven undocumented optional parameters and no required ones, an agent lacks enough guidance to construct a meaningful selection, which is the one thing this tool cannot work without.

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?

Seven parameters with 0% schema description coverage, and the description never mentions any of them by name. It repeatedly refers to 'a selection' and 'IN THIS SELECTION' but never says which of last_n, cluster, start_date, end_date, run_type, direction, or segment_id define that selection or how they combine. For a tool whose entire output depends on the selection boundary, this is a significant compensation failure.

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 resource ('the highest heart rate in a selection') and states that it returns the producing run, then splits the result into two named measures (max_hr_recorded vs max_hr_30s). It is a clear verb+resource statement, but it never positions itself against siblings like delta_hr, hr_above, or basic_metrics, so an agent must infer that this is the peak-value tool rather than a distribution or threshold 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?

Usage context is implied rather than stated: 'Over easy runs the gap measures the selection, not the heart' is a caution about interpreting the result, not an instruction on when to call this versus delta_hr or hr_above. No explicit when/when-not/alternatives appear anywhere in the text.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: boundary interpolation rules, partial final units, gap flagging, running-only pace excluding stopped/walking time, HR averaging semantics, elevation null reasons, and that Garmin laps are never substituted. These are meaningful behavioral disclosures beyond the schema.

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

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

The description is front-loaded with the main output and then gives argument and behavioral details. It is longer and denser than ideal, with some repetition around Garmin laps, but most sentences add necessary semantic value for a complex splits tool.

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

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

Given the complex per-mile computation, two undocumented schema parameters, no annotations, and a present output schema, the description is complete enough for correct invocation. It covers parameter meanings, edge cases, and field semantics without needing to repeat the output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains both parameters: `run` accepts run_id, activity_id, or Garmin file id and empty means latest run; `unit` accepts "mile" or "quarter" with mile as default.

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 defines a per-mile (or quarter-mile) running-splits output with pace, HR, elevation gain/loss, and gait time, plus Garmin laps for cross-check. It is specific about the resource and computed fields, but does not explicitly name sibling tools or state how it differs from adjacent metrics 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?

Usage is implied by the description: per-mile running splits with cross-check against Garmin laps, and `run` empty means latest run. However, it gives no explicit when-to-use/when-not guidance and does not route the agent away from alternatives such as segment_history, session_series, or basic_metrics.

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

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

With no annotations, the description carries the full burden and does well: it discloses the critical behavioral trait (NEVER TOUCHES THE DATABASE, therefore responsive during a sync) and supplies an interpretation rule — a 'broken' result from another tool while write_locked is true indicates the lock, not corrupt data. Missing is any statement of side effects (none) or of what the tool itself returns on failure, but for a read-only probe the key traits are covered.

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

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

Three short sentences, each earning its place: what it reports, the key behavioral guarantee, and how to read failures from other tools. The framing as questions is slightly informal but front-loads the payload immediately.

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

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

An output schema exists, so return values need not be explained, and the description still names write_locked, one of the likely returned fields, tying it to diagnostic use. For a zero-parameter probe this is essentially complete; only an explicit statement of what the tool returns when the server is down would improve it.

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 the baseline is 4; there is nothing for the description to disambiguate.

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 frames the tool as three concrete questions it answers: liveness, running code version, and database lock state. That is a clear, specific health-probe purpose distinguishable from data-returning siblings like sync_status or basic_metrics, though it never explicitly states 'this is the health check, use it before/after X' or names a sibling it could be confused with.

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 real usage context: call it to verify the server is alive and to check whether a lock explains failures, and it explains that it 'answers during a sync' when other tools may not. It stops short of explicit routing (e.g. 'use this instead of sync_status when you only need liveness'), so it is strong but not a full when/when-not/alternative 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool 'presents only — it does not judge' and implies comparison against recent history, but it does not explicitly state read-only behavior, side effects, or other operational constraints.

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 short and front-loads the core purpose before its parameter note and reading guidance. The only inefficiency is the opaque '§16.2' reference and an Args section that covers just one of eight parameters.

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

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

An output schema exists, so return values need less description, but the tool has 8 parameters with 0% schema coverage and none are explained except `run`. For an agent to invoke it correctly, the description should clarify the roles of the other filtering and comparison parameters.

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 there are 8 parameters, so the description must compensate. It only explains the `run` parameter (accepting run_id, activity_id, or Garmin file id, with empty meaning latest), leaving last_n, cluster, end_date, run_type, direction, segment_id, and start_date undocumented in both schema and description.

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

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

The description clearly identifies a report for one run against its recent history, which is a specific resource and scope. However, it does not differentiate this tool from sibling metric-oriented tools like basic_metrics or session_series, and the internal label '§16.2' adds little external meaning.

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 output-reading guidance ('Read `notable` first, then `unenforced`') and states that eliminating causes is the caller's work, but it does not explain when to choose this tool over siblings such as basic_metrics or efficiency_factor. The post-run context is implied, not explicitly framed as 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?

With no annotations, the description carries the full burden and does disclose key behavior: effective n is the number of blocks, fewer than three blocks returns trend_status insufficient, and missing RPM is grouped separately. It does not cover auth/rate-limit behavior, but for an analysis tool the important statistical semantics are present.

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, but the project-history aside with section references (§6.9, §2.6) and 'same disease' does not help an agent select or call the tool. The all-caps emphasis and internal references add noise.

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

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

An output schema exists, so return shape need not be explained. However, with no annotations and 0% schema description coverage, the description leaves both parameters and usage relative to siblings unexplained, which is a substantial gap for a two-parameter analysis 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 coverage is 0% for both parameters, and the description never defines what match_rpm controls or how the resistance value is interpreted. It mentions matched resistance and RPM grouping, but does not explain the boolean toggle or default resistance=0.

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 states a specific analysis: HR at matched resistance over calendar time, described as the longitudinal cut. This is clear enough to distinguish it from aggregate/resistance tools, but it never names a sibling or explicitly says it returns a time series.

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 explains internal grouping behavior, but gives no guidance on when to use this tool versus time_in_resistance, ride_blocks, or other siblings. There are no stated exclusions or selection conditions.

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

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

With no annotations, the description carries the full burden and does so: it discloses HR-only recording, constant distance, athlete-recalled resistance/RPM/boundaries, provenance, machine_totals reliability, off-bike flagging, and unavailable-with-reason behavior.

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

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

Front-loads the resource and then uses short paragraphs for caveats; the length is justified by the data-quality disclosures. Minor verbosity but no wasted sentences.

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

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

Output schema exists, so return shape needn't be explained, and the description covers the unusual data limitations and unavailable case well. The missing parameter semantics is the main 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?

The sole parameter `run` has 0% schema description coverage and is never mentioned in the description. The description does not explain what run identifies or how to supply it.

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 it returns the stationary ride's blocks with HR summary, a specific resource and payload. It does not explicitly contrast with save_ride_blocks or resistance_history, so sibling differentiation is left implicit.

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?

No explicit when-to-use or when-not-to-use guidance, and no named alternative. The unannotated-ride behavior is a return contract, not usage 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?

With no annotations provided, the description carries the behavioral burden and does so richly: it states that walk protocol is not collected, `poolable_with_other_runs` is false, sub-120s blocks lack pace, and the measures are paired series rather than fitted slopes. It also warns that identical arithmetic can mean structure or willingness depending on what governed the walks.

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 purpose and important caveats, and much of the length is justified by the complexity. However, it includes dense internal references and rhetorical framing, while its Args section covers only one of eight parameters, making the structure uneven.

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

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

An output schema exists, so return values do not need full explanation in the description. But with no annotations, eight mostly undocumented parameters, and only partial usage guidance, an agent still lacks enough context to confidently use all filtering options.

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 there are eight parameters, but the description explains only `run`, including accepted ID types and that an empty value means the latest run. The other seven parameters (`last_n`, `cluster`, date bounds, `run_type`, `direction`, `segment_id`) are left 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 clearly states the tool computes run/walk cycle economics and explains the `purchase` and `decay` measures. It is specific but relies on internal labels like M3 and §17.2, and does not explicitly differentiate itself from sibling analytics tools.

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

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

The description gives interpretation caveats, such as reading `elapsed_at_*` before concluding causation and reading each run on its own. However, it does not explicitly say when to use this tool versus alternatives like `mile_splits`, `drift_onset`, or other pacing analytics.

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

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

With no annotations, the description carries the full burden and does so thoroughly: supersede keeps the previous revision, ambiguity is refused rather than resolved, start_min is rejected, raw_text is stored verbatim through revisions, and RPM is never collapsed to a midpoint. It also discloses validation against a declared ceiling and what is intentionally not stored.

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

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

The purpose is front-loaded, but the description runs long with philosophical asides such as the bronze-file analogy and repeated framing of what is not a field. Much of the content is valuable, but several sentences could be compressed without losing operational meaning.

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 no annotations and a rich behavioral surface, the description is complete: it covers required and optional payload contents, supersede semantics, block anchoring, resistance and RPM rules, raw text preservation, ambiguity rejection, and exclusions. An output schema exists, so return-value detail is appropriately omitted.

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

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

Schema coverage is 0%, so the description must compensate, and it does: payload is broken into required fields (run_id/activity_id, raw_text, blocks) and optional fields (events, machine_totals), supersede is explained as an argument beside the payload rather than a field inside it. Block entry structure and end-anchoring rules add meaning far 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 first sentence gives a precise verb and resource: 'Store one stationary ride's block structure.' It immediately distinguishes this tool from all siblings by declaring it 'THE ONE tool that writes athlete input,' making its unique write role 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?

It explicitly states when to use this tool and when not to use related fields: perceived effort is excluded in favor of session_load, athlete-recalled HR is excluded because the watch is authoritative, and parsing prose belongs to the chat at save time. These exclusions and alternatives leave little 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?

No annotations, so the description carries the full burden. It does disclose real behavioural traits — the gap normalisation amplifies short gaps (+10 bpm over 10 min reads as +60 bpm/hour), the value can be several times larger than matched_terrain_drift on the same run, and the agent should read applied_filters. That is meaningful, but it doesn't state freshness, data source, or what happens when no matched segment exists.

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

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

Front-loaded with the metric definition, then the formula caveat, then the routing advice. Prose is compact. The 'NOT §6.7 — a DIFFERENT quantity' line assumes internal spec knowledge and costs a sentence without adding interpretable meaning.

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

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

An output schema exists, so return values needn't be described. The description covers what the measure is, how it is scaled, and the caveat against presenting it as canonical drift. It falls short only on the seven undocumented parameters.

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?

Seven parameters with 0% schema description coverage, and the description explains none of them. last_n, cluster, run_type, direction, segment_id, start_date and end_date are all undocumented in both schema and prose. The mention of 'no split_type filter' hints at a filter dimension but doesn't clarify which parameter governs it.

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

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

Names a specific metric (effort-level HR drift on a matched segment) and states exactly how it is computed: whole effort averages paired with no speed match, normalised by the gap between effort starts. It is differentiated from its sibling matched_terrain_drift by naming it and describing the divergence. The 'NOT §6.7' framing adds ambiguity for an agent that doesn't know what §6.7 refers to.

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

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

Explicit routing: 'Use matched_terrain_drift unless you specifically want the slope-matched measure.' That tells the agent when to prefer the sibling. There is no guidance on the date/cluster/run_type filters or what conditions make this measure the right call beyond the slope note.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that segment ids come from `report` and are ordered by the reference run, but says nothing about read-only status, permissions, filtering behavior, date-range handling, or other operational traits beyond that single sourcing detail.

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 short and front-loads the concept, but '§6.6' and 'one slope' are cryptic, and the two sentences are under-specified for a seven-parameter tool. It avoids verbosity but does not use its brief space to convey the most necessary semantics.

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

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

The tool has seven parameters, 0% schema description coverage, and no annotations, so the description must do substantial work. It only covers the conceptual purpose and how to obtain a segment id; it leaves most parameter behavior and usage context unexplained, despite an output schema being present.

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

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

Schema description coverage is 0% with seven parameters. The description only indirectly clarifies `segment_id` by saying ids come from `report`; it adds no meaning for `last_n`, `cluster`, `start_date`, `end_date`, `run_type`, or `direction`.

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 phrase 'one slope, every traversal, over time — the trending primitive' suggests historical trend data for a segment, but it is metaphorical rather than a clear verb+resource statement. It does not explicitly say what is returned or distinguish this tool from sibling segment-related tools such as segment_effort_drift or list_segments.

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 one useful prerequisite: use `report` to find segment ids, and explains that ids are unrecognisable on their own. However, it gives no guidance on when to choose this tool versus other segment or history tools, and no exclusions or conditions.

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

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

With no annotations, the description carries the full burden and does it well: it discloses that unrated sessions are 'unavailable' with a reason and never priced at 0, that garmin_feel is shown but unused, that timer time (not moving time) is the basis system, and that selection sums may be lower bounds flagged by is_lower_bound. These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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

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

Front-loaded with the definition and an Args block, and every paragraph addresses a distinct behavioral risk. It is longer than most definitions but the density is justified by the number of pitfalls; the heavy all-caps emphasis is slightly noisy but not wasteful.

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

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

For a complex eight-parameter tool with no annotations, the description covers semantics, selection logic and aggregation caveats, and an output schema exists so return shape need not be spelled out (though it usefully names key summary fields). The only real hole is the undocumented direction and segment_id parameters.

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

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

Schema coverage is 0%, so the description must compensate; it documents the meaning, exclusivity and defaults of run, start_date, end_date, cluster, last_n and the run_type rejection in useful detail. However, two of the eight parameters, direction and segment_id, are never mentioned at all, leaving an agent to guess whether they apply to this tool.

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 specific metric, its source, its formula (Garmin RPE x timer minutes) and its unit (AU), so an agent knows exactly what this tool returns. It does not, however, distinguish itself from siblings such as session_series or basic_metrics, which also operate on sessions.

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

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

Clear operating rules for choosing one activity versus a selection, the explicit exclusivity ('Name a run OR a selection, never both'), the empty-means-latest default, and the run_type rejection. What is missing is when to reach for this tool instead of a sibling for related load/dose questions.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it explains null-distance bins, state-as-seconds semantics, elevation availability, dynamics absence reasons, per-field n, and flags coverage. These are exactly the behavioral traits an agent needs to interpret the payload correctly.

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

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

The purpose is front-loaded and the content is information-dense, but the description is very long, with section references, all-caps asides, and repeated caveats. It is useful but could be structured more tightly.

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

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

An output schema exists, so return values need not be explained, and the behavioral edge cases are well covered. However, with 0% schema description coverage and seven undocumented parameters, the definition is not complete enough for an agent to use all inputs confidently.

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

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

Schema description coverage is 0% across 9 parameters, and the description documents only run and include_dynamics. The other seven parameters (last_n, cluster, end_date, run_type, direction, segment_id, start_date) are left unexplained, so the description cannot compensate for the schema gap.

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

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

States a specific resource and granularity: the session as a 30 s binned series, intended for 'over the run' reasoning. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as mile_splits or basic_metrics.

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 phrase 'for over the run reasoning' implies when to use it, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling tools.

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

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

With no annotations, the description carries the burden, and it usefully discloses that the content is stable across runs and should be cached unless the spec changes. It does not explicitly discuss read-only behavior or side effects, but the load-once guidance provides strong operational 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?

Three short sentences front-load the purpose, usage timing, and caching rule with no filler. Every sentence adds useful 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?

The output schema presumably explains the returned brief, so the description need not enumerate return values. It covers purpose, usage timing, and stability, though it could be slightly more explicit about what kinds of measured findings are included.

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 there are no parameter semantics to explain beyond the baseline. The description appropriately avoids inventing parameter details.

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 positions this as a contextual primer rather than a metric-computation sibling: it provides a standing brief for interpreting results. It does not specify exactly what form the brief takes, but the distinction from the many metric tools is clear.

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 load it ONCE at the start of a conversation and to refetch only if told the spec changed. That gives both the when and the when-not, leaving little inference for 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?

With no annotations, the description carries the full burden and does so: it discloses runtime of minutes, an exclusive database write lock, why it cannot be awaited, append-only writes that never modify/move/rename/delete raw files, and per-step partial-failure semantics. It even pre-empts a false alarm — DEM-dependent steps being skipped is described as normal on a fresh install.

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: the first two lines give purpose, return value and the polling alternative. Each subsequent block covers a distinct failure mode, though the detailed field-by-field recounting of `steps`, `step_errors`, `problems`, `rejected` and `skipped_steps` partially duplicates what the existing output schema already conveys, and the all-caps emphasis is loud.

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 long-running, lock-holding job with no annotations, the description supplies everything an agent needs: async contract, polling target, write-scope guarantees, partial-failure interpretation, and the CLI-only escape hatch for stuck recordings. No material gaps remain.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No stray parameter claims are made.

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

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

Opens with a specific verb+resource ('Fetch new Garmin activities and process them') and immediately states the return contract ('Returns a JOB ID at once'). The asynchronous nature cleanly separates it from the sibling `sync_status`, which is explicitly named as the polling counterpart.

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

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

Explicitly routes the agent away from awaiting the call and toward `sync_status`, and warns that `confirm-file` is CLI-only so the agent should relay a command rather than hunt for a tool. Missing only a positive trigger ('call this when new recordings are on disk').

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

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

With no annotations, the description carries the full burden and does so well: it enumerates the state machine (queued, running with current step, done, failed with failing step), and explains that only DOWNLOAD failures fail the job outright while later-step exceptions surface inside a `done` job under `step_errors` with `clean: false`. That is exactly the kind of non-obvious behavior an agent could not infer from the schema. It stops short of noting polling cost, result persistence, or whether old jobs expire.

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 behavior and the empty-arg default are front-loaded in the first two sentences, with failure semantics following. Every clause is substantive, though the parenthetical "a Garmin outage and a corrupt file are different problems" is motivational color rather than operational instruction.

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

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

An output schema exists, so return structure needn't be restated, yet the description usefully names `step_errors` and `clean`. Combined with the documented states and default-job behavior, this is enough for an agent to call the tool correctly; only edge cases (invalid/expired job_id, polling guidance) are absent.

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 only parameter's schema is a bare `string` with `default: ""`, so the description's "Empty job_id returns the most recent" is the sole explanation of what the empty value means and what the parameter selects. That compensates for the near-total schema gap, though it doesn't say what an unrecognized job_id yields.

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 resource and read intent: the progress/status of a sync job, which cleanly separates it from the sibling `sync` (the trigger) and from analytical siblings like `report` or `session_load`. It does not explicitly name `sync` as the companion tool, so the differentiation is inferable rather than spelled out.

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?

"Empty job_id returns the most recent" gives concrete guidance on the parameter's default case, implying the intended poll-after-sync workflow. However, there is no explicit statement of when to call this versus `sync`, whether it should be polled repeatedly, or what happens with an unknown job_id — the usage is implied, not directed.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses timer-time weighting, that stopped time is deliberately not subtracted (with a rationale), that time is capped per record, and that corpus totals omit a run with open provenance. What it omits is the practical profile: read-only nature, pagination/size limits, and failure modes.

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 computation is front-loaded, but the block on timer-time weighting is discursive and the '§14e-bis' provenance reference is internal jargon an agent cannot resolve. Roughly a third of the text is rationale rather than operational instruction.

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

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

An output schema exists, so return values needn't be explained, and the metric's methodology is well covered. But for a 7-parameter tool with zero schema descriptions, leaving every filter and scope parameter undefined is a significant gap that the description should have closed.

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?

Seven optional parameters at 0% schema description coverage, and the description explains none of them — `cluster`, `direction`, `segment_id`, and `run_type` are completely opaque as to accepted values and effect. The only identifier mentioned, `thresholds_bpm`, is a result field, not an input. Names like `last_n` and `start_date` are inferable, which keeps this above a 1.

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

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

States a specific computation: time at or above each rung of the configured HR ladder, reported per run and corpus-wide, with the rungs exposed via `thresholds_bpm`. It even frames the analytical question it answers (repeated exposure at the top of the range vs. a one-off). It stops short of naming the sibling it differs from (`hr_above`, `max_hr_over`), so an agent must infer the boundary.

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 'THE QUESTION THE EXCURSION LIST CANNOT ANSWER' framing implies when this tool is the right choice, but it never names the alternative tool or states a selection rule. There is no explicit 'use this instead of X when...' and no prerequisites for calling it.

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

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

With no annotations the description carries the full burden, and it does add real behavioral context: results are a pure aggregation of stored blocks and are only as valid as the logged blocks. It stops short of saying what happens when no blocks are logged (empty result vs error) and gives no indication of scope across rides or any cost/size characteristics.

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 measure statement is short and front-loaded, but the leading '§18.2' is an opaque cross-reference that means nothing without the external document, and 'The same shape as time-in-zones' points at a tool that is not in the sibling set. Both sentences spend space on references the agent cannot resolve.

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

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

An output schema exists, so return values need not be explained, and the unit/granularity (0.5-turn bands, LOCAL week) is covered. The remaining gap is scope: with zero parameters the agent cannot tell whether this aggregates every stored ride block or only a default window, and the prerequisite relationship to save_ride_blocks/ride_blocks is only hinted at.

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 per the baseline this is a 4; there is nothing for the description to disambiguate. The schema is fully self-describing (empty object).

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 the measure precisely: minutes bucketed per resistance value and per 0.5-turn band, per LOCAL week, produced by "pure aggregation of stored blocks." That is a specific verb+resource+granularity. It does not, however, distinguish itself from actual siblings in the list (resistance_history, ride_blocks) — it instead compares to 'time-in-zones', which is not among the sibling tools, so the differentiation target is unverifiable.

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 clause 'the only ride read that rests on NO assumption beyond the blocks having been logged correctly' implies when to prefer it (when an assumption-free ride read is wanted, versus derived metrics like efficiency_factor or drift_onset), but that comparison is never made explicit. There is no stated when-not condition and no named alternative 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses that boundaries come from each activity's own file, that weeks spanning multiple boundary sets are reported as SPLIT rather than summed, that stops and flagged records are excluded, and that a 40s HR lag is applied. These are non-obvious traits that materially affect interpretation.

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

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

The main purpose is front-loaded, but the description is long and includes motivational context ('why the split matters') that could be trimmed. It is structured but not tight; several sentences explain interpretation rather than invocation.

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

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

For a tool with seven undocumented parameters and no annotations, the description is incomplete on the input side. It provides excellent behavioral and interpretive context, and the output schema covers return values, but the missing parameter semantics leave a critical gap for 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?

Schema description coverage is 0% and the description does not explain any of the seven parameters (last_n, cluster, end_date, run_type, direction, segment_id, start_date). An agent has no way to know what values to supply or how they affect the result.

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: time in HR zone split by gait (running vs walking vs standing). This is clear enough for an agent to distinguish it from a simple zone-total tool, though it doesn't explicitly name sibling alternatives.

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 explains why the gait split matters but gives no explicit guidance on when to use this tool versus alternatives like basic_metrics or time_above_hr. The only comparison is to Garmin's external metric, not to sibling tools in this server.

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