Garmin Local Archive

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

With no annotations, the description carries the full behavioral burden, and it does so for the important part: it defines the detection semantics (single-day outliers vs. streaks of 5+ consecutive days relative to a baseline average) and notes streaks can fire even when no single day is an outlier. It omits operational traits such as whether results are computed live or cached, and any sensitivity/threshold configurability, which keeps it short of 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?

Front-loaded with purpose, then output taxonomy in a single follow-on sentence with no filler. The parenthetical streak definition is dense but earns its place by teaching the agent a non-obvious detection rule.

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

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

There is no output schema and no annotations, so the description's explanation of the two finding kinds is genuinely necessary and good. However, the three required parameters remain completely unspecified (field naming and date format), which an agent needs in order to call the tool correctly.

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

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

Schema description coverage is 0% and all three parameters (field, date_from, date_to) are undocumented. The description only obliquely implies field is 'one health field' and says nothing about date_from/date_to format or range semantics, so it only partially compensates for the coverage gap.

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

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

States a specific verb and object ('Find days where one health field broke from its own recent pattern') and immediately distinguishes itself from detection-adjacent siblings like baselines, gaps, and correlate by naming the two finding types it produces. An agent can tell what this tool returns without opening the schema.

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

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

Usage is implied rather than stated: the outlier/streak examples show when the tool is useful ('catching a slow drift, e.g. a gradually rising resting heart rate'), but there is no explicit when-to-use-this-vs-baselines-or-gaps routing and no excluded case. Minimum viable guidance for a tool with several overlapping 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?

No annotations are provided, so the description carries the full burden. It does disclose the analytical model (rolling 90-day window, mean ±3 standard deviations) and that it is a read/query operation, but it says nothing about permissions, cost, handling of sparse data, or whether results are precomputed vs. computed on demand.

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 tight sentences with the core definition front-loaded and no filler. The parenthetical '(mean +/- 3 standard deviations)' earns its place by defining the reference range; the second sentence is slightly long but carries the routing 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?

With no output schema and no annotations, the description does well to explain what the result conceptually contains (baseline plus reference range), but omits return shape details (sample counts, SD, per-metric structure) and the operational facts an agent needs for a 3-required-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 description coverage is 0%, so the description must compensate for all three undocumented parameters. It clarifies that 'field' is a health field and that the date pair defines a window, but gives no field naming convention (despite the list_available_fields sibling), no date format, and no constraints such as whether the range is capped by the 90-day baseline.

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 (Query) plus a precisely defined resource: the rolling 90-day baseline and mean ±3 SD reference range for one health field. It also names the sibling it contrasts with (query_health) and the scoping constraint (one field, one date range), so an agent can distinguish it without opening the schema.

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

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

Gives explicit when-to-use guidance (to see what 'normal' looks like recently, or paired with query_health to compare against the person's own history rather than a fixed threshold) and names the alternative tool. It stops short of stating when not to use it or when other siblings like anomalies or correlate are the better fit.

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 and no output schema, the description carries the full behavioral burden and does so well: it discloses the two returned coefficients, their [-1, 1] range, the meaning of Pearson vs Spearman (linear vs monotonic, outlier robustness), and that an overlap count is returned. It omits any note on permissions, rate limits, or behavior when sample sizes are too small.

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

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

Front-loads the core operation, then the lag semantics, then the return values. Every clause adds information, though the parenthetical explanations in the lag sentence are slightly dense. No filler or restatement of the name.

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

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

For a 5-parameter, no-output-schema statistical tool, the description covers operation, parameter semantics, and return values adequately. The remaining gap is field-name/date-format discovery and minimum-sample behavior, which an agent may need before invoking successfully.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It fully specifies lag_days (bound -7 to +7, default 0, direction of shift), and covers field_a/field_b ('two fields, health or context, any combination') and the date range implicitly. It does not state the accepted field-name or date-string formats.

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 statistical verb+resource ('Measure how closely two fields move together over a date range') and gives concrete examples (stress vs pollen, resting HR vs sleep duration). This is clearly distinguishable from siblings like baselines, anomalies, and query_health, which return values rather than relationships.

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 clear via worked examples and the lag_days use case ('does X today predict Y a few days from now'), giving the agent a good sense of when this tool applies. It does not, however, name which sibling to use instead when the agent merely wants raw values (query_health/query_context) or how to discover valid field names (list_available_fields).

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. It does disclose the key behavioral trait that domain='fit' is non-functional, and defines gap semantics (never synced vs synced-but-empty/failed), which is genuinely useful. However, it says nothing about return shape, permissions, or reliability limits, leaving real gaps for a read-style tool with zero annotation coverage.

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

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

Three sentences, front-loaded with the core purpose, followed by domain caveats and the gap definition. Minimal waste; the parenthetical is slightly awkward but earns its place by preventing a doomed 'fit' call.

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

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

Covers purpose, domain semantics, and gap definition, but with no output schema and 0% parameter coverage, the description omits date format and any hint of what the returned list looks like. Adequate but with clear omissions for a 3-required-param tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does document the domain enum values and the fit degradation, which is real added value the schema lacks. But the two date parameters (date_from/date_to) get no format or syntax guidance despite being bare 'string' types, leaving 2 of 3 params under-specified.

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

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

States a precise verb+resource: 'List days with no usable data over a date range,' and goes on to define what a gap is. This clearly differentiates the tool's function from sibling query tools, though it never names an alternative sibling the way a 5 would.

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 (find uncovered days), and the note that domain 'fit' always degrades to 'domain not yet available' is a useful when-not caveat. But there is no explicit statement of when to choose this over anomalies, baselines, or query_health, nor any stated prerequisites.

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: silent empty results when date_from/date_to are missing (no error, no default range), dates ignored for other kinds, log payloads of several hundred KB, token_log never exposing token contents, and an error on unknown kind. These are exactly the non-obvious behaviors an agent needs.

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 purpose followed by a clean bulleted kind list, so it is easy to scan. It is somewhat long and mildly repetitive — the log kinds are re-listed once in the bullet list, again in the date-requirement sentence, and again in the size warning — but each repetition carries a distinct constraint, so the cost is small.

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?

No output schema exists, yet the description documents the response envelope ({"data": ..., "error": None}) and the error behavior for unknown kinds. Combined with complete parameter semantics and the size/date caveats, an agent has everything required to call this correctly.

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

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

Schema coverage is 0%, so the description must compensate — and it does. It defines the full domain of 'kind', gives ISO 'YYYY-MM-DD' inclusive semantics for date_from/date_to, and states precisely which kinds require both dates and which ignore them. Nothing about the three parameters is left ambiguous.

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

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

States a specific verb+resource ('Read archive-state metadata') and then enumerates every accepted 'kind' with a concrete description of what each returns (stats, device_table, quality_log, source_api_log, token_log, capability_config, log kinds). This is far more than a name restatement and clearly separates it from siblings like query_health or gaps.

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 guidance: 'Use this for "how big/complete/healthy is my archive" questions', and 'prefer "stats" for overview questions'. It also gives the when-not/no-op condition — the log kinds silently return empty without both dates — and warns to request only needed days because logs are large.

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 discloses that 'fit' returns an empty list, that an unknown domain silently returns no fields rather than erroring, and that narrowing by domain produces a much smaller result. These are non-obvious edge-case behaviors an agent would otherwise have to discover by trial.

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

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

Front-loaded with purpose and trigger, then parameter behavior, then return shape — a sensible order. It is dense and slightly long, but every clause carries operational information (edge cases, units, _series naming convention), so little is wasted.

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

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

There is no output schema and no annotations, yet the description fully documents the return payload (domains, metadata_kinds, fields, units) and the _series naming convention. Nothing needed to call or interpret this tool is missing.

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

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

Schema coverage is 0% — the domain parameter has no description or enum in the schema — so the description must compensate, and it does: omit domain for the full overview, pass 'health' or 'context' to narrow, and the special-case 'fit' returns empty. This is richer than the schema by a wide margin.

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 ('List the queryable fields') plus the grouping dimension ('by domain and source'). It explicitly differentiates from siblings by noting that query_raw's fields are excluded and named elsewhere, and it names query_health and query_context as the consumers of the output.

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

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

Gives an explicit trigger ('Call this first when the exact field name for query_health or query_context is unknown') and names the sibling it does not cover (query_raw). No ambiguity about when to reach for this tool versus the query 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 present, the description carries the full burden and does so well: it discloses that resolution is accepted but ignored, that unknown/ambiguous fields return an error with a did_you_mean list, that typos are auto-resolved with _meta.field_resolved_from/field_used, and that an empty range yields empty values rather than an error.

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 action is front-loaded in the first sentence, routing guidance follows immediately, and the second paragraph is a dense but purposeful set of edge-case behaviors. No sentence is filler.

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

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

With no output schema and no annotations, the description still covers error behavior, resolution metadata, and empty-result semantics, which is exactly what an agent needs to call and interpret this tool correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it defines the field parameter's naming conventions (category names, _series suffix meaning intraday timeseries vs one value per day), the ISO YYYY-MM-DD inclusive format for date_from/date_to, and the no-op nature of resolution.

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

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

The description names a specific verb and resource ('Query external context data (weather, pollen, air quality) for one field over a date range'), and explicitly contrasts itself with query_health and list_available_fields. An agent can distinguish it from every sibling without opening a schema.

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

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

It gives explicit routing rules: use query_health for Garmin body data, and call list_available_fields first when the field name is unknown. Both the alternative tool and the condition that selects it are stated, leaving nothing to inference.

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

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

With no annotations, the description carries the full burden and does add genuinely non-obvious behavior: the call succeeds with a clean 'not available' result and never errors. That prevents an agent from misreading a placeholder as real data. It still omits auth requirements, what an invalid field returns, and how resolution affects output.

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

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

Two short sentences, zero filler. The core purpose leads and the availability caveat, which is the single most decision-relevant fact, follows 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?

For a low-complexity, 4-parameter query tool with no output schema, the description adequately covers the behavioural quirk but leaves parameter formats (field naming, resolution values, date format) undocumented in both schema and text. An agent could call it successfully but not interpret the arguments well.

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 schema documents nothing and the description must compensate. It covers the 'field' and date-range parameters implicitly but says nothing about 'resolution' (default 'daily'), its allowed values, or the expected date format, leaving the coverage gap half-filled.

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

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

The description states a specific verb and resource ('Query FIT activity data for a field over a date range'), which is concrete and distinct from sibling names like query_health or query_raw. It does not explicitly contrast itself with those siblings, so it loses the top tier, but the purpose is unambiguous.

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

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

It discloses an important negative condition — the tool is not yet functional (FIT pipeline v1.8) and returns a placeholder rather than an error. However, it never names an alternative (e.g., query_raw) for an agent that actually needs this data now, so routing guidance is implied rather than explicit.

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 discloses that resolution is accepted but ignored, that unknown/ambiguous fields error with a did_you_mean list, that typos/aliases are auto-resolved via _meta.field_resolved_from/field_used, and that empty ranges return empty values rather than errors. It stops short of explicit read-only/permission statements, but the behavioral disclosure is unusually rich.

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

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

Front-loaded with purpose and routing before the denser parameter semantics. Every sentence earns its place, though the parameter block is dense enough that it reads as one long paragraph rather than being cleanly separated.

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

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

With no output schema, the description still explains the return shape: per-field 'unit', empty values for no-data ranges, and _meta resolution fields. Combined with the error semantics, an agent has all it needs to call and interpret results.

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

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

Schema coverage is 0%, so the description must compensate for all 4 parameters — and it does: field naming conventions ('_series' = intraday timeseries vs plain = one value per day), the multi-field sleep_score behavior, ISO YYYY-MM-DD inclusive dates, and the ignored resolution param. This meaning exists nowhere else.

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 (Query) and resource (Garmin health data: heart rate, sleep, stress, body battery, steps) over a date range, and distinguishes itself from siblings query_context (weather/pollen/air quality) and list_available_fields. An agent can tell exactly which tool to pick without opening any schema.

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

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

Explicitly routes alternatives: 'Use query_context instead for weather, pollen and air quality; call list_available_fields first if the exact field name is unknown.' When-to-use and when-to-use-elsewhere are both stated concretely.

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 discharges it: read-only and non-mutating ('does not change the archive'), no units provided and interpretation left to the caller, auto-correction of near-miss field names surfaced via _meta.field_resolved_from/field_used, error semantics with did_you_mean, and domain rejection. It also discloses result-shape edge cases (missing day = no entry, stored-but-empty = raw null), which is more than the schema or any annotation would reveal.

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

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

Purpose and the query_health routing are front-loaded in the first two sentences, and the remaining blocks (field list, date semantics, resolution behavior, result shape) are each load-bearing rather than filler. It runs long and the parenthetical field-to-counterpart mapping is dense, but nothing is redundant with structured data, so the size is justified.

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

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

For a 4-param, no-output-schema tool, the description covers everything an agent needs: valid fields, date format and inclusivity, the single valid domain, resolution and error behavior, and the exact response envelope with null-vs-absent semantics. Nothing material is left to inference.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for all four parameters: field is fully enumerated with an explicit caveat that these names are absent from list_available_fields, date_from/date_to are specified as ISO YYYY-MM-DD and inclusive, and domain is constrained to 'health' with the error behavior spelled out. This adds substantial meaning the bare schema lacks.

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

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

States a specific verb and resource ('Query archived Garmin data as stored in raw/') plus the scope constraint (no value extraction, only fields the processed tools cannot reduce to a daily value). It names the sibling it is not (query_health) and explains why the raw path exists, so an agent can distinguish it from query_health and list_available_fields without opening either schema.

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

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

Explicitly routes the agent: 'Use query_health instead whenever the data you need exists there', then names the three fields with processed counterparts and the exact target fields. It also states when the tool is inappropriate (fields that reduce to a daily value) and warns that its field names are NOT listed by list_available_fields, which prevents a common misuse.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that the call blocks until the sync finishes, that it may take a long time on a large pending delta, and that it reuses the startup sync path. It omits any concurrency concern (e.g. what happens if a sync is already running) and any indication of what the call returns.

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 action and its trigger are front-loaded in the first sentence, with blocking behavior last. It is slightly longer than needed — the em-dash aside about backfill/recheck could be tightened — but every sentence carries real information.

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

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

For a parameterless, annotation-free maintenance call with no output schema, the description covers the essential agent-facing facts: what it does, when to invoke it, and that it blocks. It does not say what happens on failure or whether the call is idempotent, which are minor gaps for a zero-arg tool.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing in the schema for the description to clarify or compensate for.

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 gives a specific verb and resource — "Manually trigger a SQLite cache sync against the archive" — and frames it as the manual counterpart to the sync the server runs at startup. This is the only maintenance action among the query_* siblings, so an agent can distinguish it without opening a schema.

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

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

It states the triggering conditions precisely: use when a sync, backfill, or recheck has just run and results may be stale. It does not explicitly say when to avoid calling it (e.g. during normal operation, or that query tools are the alternative), so it stops short of full when/when-not/alternatives guidance.

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