Garmin Local Archive

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 the path-dependent behaviour (live path applies a 30-day default plus a 'note' field; the SQLite-cached path actually taken returns an empty result with no note when dates are omitted) and frames it as deliberate rather than a bug. It omits error conditions, permissions, and result shape, but the gotcha disclosure is genuinely valuable.

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 content is front-loaded, but the body is padded with a versioned changelog entry and internal call-path references (mcp_map.get_archive_metadata(), metadata_map.py, mcp_sql.get_metadata_range(), _route_query()) that belong in code comments, not a tool docstring. The actual invocation-relevant rule is buried inside that machinery discussion.

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

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

For a 3-parameter read tool with no output schema, it covers parameter semantics, defaults, and a non-obvious empty-result edge case, which is most of what an agent needs. Residual gaps are the unexplained non-stats kind return values, which are not inferable from the schema or annotations.

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 is the only source of parameter meaning and it delivers: it lists every legal `kind` value (none present in the schema) and fully specifies date_from/date_to as inclusive ISO YYYY-MM-DD, including per-kind applicability and default behaviour. It does not explain what the less obvious kinds (e.g. 'capability_config', 'token_log') actually return.

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 resource ('archive-state metadata') and enumerates the artefact kinds selectable via `kind`, with an explicit gloss on the most common one ('stats' = coverage/quality overview for size/health questions). It does not differentiate itself from siblings like query_raw or query_health, which is the main gap.

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 guidance for one kind ('use this for "how big/healthy is my archive" questions') and states which kinds date_from/date_to applies to versus which four ignore it. However it never says when to prefer this tool over the sibling query_* tools, so routing guidance is only partial.

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 exist, so the description carries the full burden. It does disclose the result shape ('fields' nested name list plus an additive 'units' dict) and that the change is backward-compatible, which is real behavioral context. However, it says nothing about read-only safety, rate limits, or caching, and a large share of its behavioral text is version-scoped changelog material rather than invocation-relevant 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?

The first two sentences are tight, front-loaded, and exactly what an agent needs. The following paragraph is over half the definition and is largely internal engineering notes ('v1.7.1.6', 'mcp_context.py's _resolve_context_bundle()', 'FIELD_UNITS in mcp_field_registry.py') that consume space without helping selection or 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?

With no output schema, the description takes on the job of explaining the return shape and does so (nested {domain:{source:[...]}} plus a flat {field:unit} map). Purpose, usage trigger, and the lone parameter are all covered, so an agent can call this correctly; only the exhaustive domain list 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% and the single 'domain' param is undocumented in the schema, so the description must compensate. It does: null/omitted yields a full overview, and it supplies three concrete narrowing values ('health', 'context', 'fit'). It stops short of enumerating the complete valid domain set, so the agent must still infer whether other values are legal.

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

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

The opening sentence states a specific verb+resource ('List all queryable fields') plus its organization ('grouped by domain and source'). It implicitly distinguishes itself from the query_* siblings by being the metadata/introspection call, but it never names an alternative, so it stops short of a clean 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?

'Use this first if the set of available fields is unknown' gives an explicit triggering condition, and the follow-up tells the agent how to call it (omit domain for a full overview, pass health/context/fit to narrow). There is no statement of when NOT to use it or which sibling to prefer once fields are known.

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 and does disclose genuinely useful traits: unknown-field detection with three ordered outcomes, transparent alias/bundle auto-resolution surfaced via _meta.field_resolved_from/_meta.field_used, and the guarantee that valid-field results are unchanged. That is substantial disclosure about error semantics and silent-rewrite prevention, even if the delivery is changelog-shaped.

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 dominated by session-by-session release notes (v1.7.1.3 through v1.7.1.12), internal class/file references (mcp_sql.get_context_range(), clients/mcp_sql.py, NOTES_v1.7.1.12.md) and duplicated logic explanations that add no value for an agent. Only the first two sentences are agent-facing; the remaining bulk is noise and is not front-loaded around caller needs.

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

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

There are no annotations, no output schema and 0% schema coverage, so the description must carry everything. It does cover return shapes ({"date","value"} vs {"date","series"}) and field-resolution behavior well, but it omits date-format expectations, the 'resolution' parameter semantics, and any read-only/permission context. Partially complete but with clear gaps for a 4-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 compensate for all four parameters. It thoroughly covers 'field' (aliases, bundles, series suffix), but date_from/date_to formats are never specified and the 'resolution' parameter (default 'daily', and how it relates to the '_series' shape) is never tied back to the schema. Two of four parameters remain semantically 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 opening sentence gives a clear verb+resource+scope: 'Query external context data (weather, pollen, air quality) for a field over a date range. Fans out across all sources that recognize the field.' That is enough to distinguish it from query_fit_activities or query_raw, though it never explicitly contrasts itself with sibling query_health beyond a passing mention of its domain. The purpose is buried under heavy version-history prose.

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 never states when an agent should choose query_context over query_health, query_raw, or list_available_fields. It explains internal resolution mechanics at length but offers no when-to-use / when-not-to-use context, leaving the routing decision entirely to the caller's 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 it actually discloses meaningful behavior: transparent typo auto-resolution surfaced via _meta.field_resolved_from, three distinct unknown-field error outcomes with did_you_mean behavior, the sleep_score fan-out and its _meta marker, and the 'unit' key added to every returned field. Deeper operational traits (auth, limits, date formats, payload size bounds) remain unstated, but the error-handling 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?

The vast majority of the text is an internal changelog: version numbers (v1.7.1.1, v1.7.1.6, v1.7.1.9), session dates, source file and function names, and references to markdown planning documents. Only the first paragraph and the sleep_score/alias paragraphs serve the calling agent; the rest does not earn its place and pushes critical guidance far from the front.

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

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

For a 4-parameter, no-output-schema, no-annotation tool, the description covers error behavior and the multi-field result shape ({'garmin': {field: {...}}}) well enough that an agent knows what comes back. It still omits practical invocation basics — date string format, maximum range, and expected response size — which matter more here than the retained release 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?

Schema coverage is 0%, so the description must compensate. It does explain the resolution parameter in depth (daily vs intraday, per-field restrictions, and that it is currently a no-op for routing) and the semantics of valid/aliased/unknown field values. But date_from and date_to — two of three required parameters — are given no format, range, or inclusivity guidance at all.

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 gives a specific verb, resource and scope ('Query Garmin health data ... for a field over a date range') with concrete field examples, and it explicitly separates this domain from query_context's domain. However, the purpose is buried under version-history noise, and the distinction from sibling tools like query_fit_activities or query_raw is never stated.

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 tells the caller to pass a field name matching the desired resolution and to consult list_available_fields(), and it implies query_context is the tool for other domains. But there is no explicit statement of when to choose query_health over query_fit_activities/query_raw/query_context, and no prerequisites or exclusions beyond the routing aside.

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 entire behavioral burden. 'Raw, unprocessed' hints that results aren't aggregated, but there is no mention of permissions, caching (a sibling is refresh_cache, suggesting data may be stale), rate limits, or result volume for a raw archive query. This is a meaningful gap for a data-heavy read tool.

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

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

Two sentences, front-loaded with the core action and followed by the parameter caveat. Slight redundancy in 'raw, unprocessed,' but nothing else is wasted.

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

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

For a 4-parameter tool with 0% schema coverage, no annotations and no output schema, the description leaves too much unspecified: no date format, no field-name convention, no statement of what raw records look like. An agent can guess the shape but cannot call this reliably without trial and error.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain domain and supplies the enum values ('health', 'fit', 'context') that the schema does not declare, which is genuine added value. But field, date_from and date_to receive no format, naming convention, or discovery hint (e.g., pointing at list_available_fields).

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 raw, unprocessed archive data for a passthrough field over a date range'), which tells the agent exactly what the tool returns. It implicitly differentiates from the domain-specific siblings (query_health, query_context, query_fit_activities) by explaining that domain narrows the scope. The term 'passthrough field' is jargon that isn't defined anywhere.

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 note that domain 'restricts the query to one domain... omit to search all domains' gives real usage guidance for that one parameter. However, it never states when to prefer this tool over the sibling query_health/query_context/query_fit_activities, nor prerequisites for calling it. Usage 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 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.