sync_garmin_data

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

Even without annotations, the description fully discloses behavior: it is incremental and chunked, each call syncs up to max_rounds (default 25, ~2-4 minutes), reports rounds_remaining, and guarantees permanence ('Nothing is lost between calls; every batch is permanent'). It also explains the unbounded nature of full=True without max_rounds and the skip behavior of include_health=False, covering side effects and performance.

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 moderately long but every sentence earns its place. It front-loads the main purpose, then logically covers incremental behavior, progress loop, permanence, full mode, and an alternative execution path. No filler or repetition, and technical details are compactly parenthesized.

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

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

Given the tool's complexity (sync with chunking, progress tracking, multiple modes) and the presence of an output schema (so return structure is covered), the description fully equips an agent to use the tool correctly across scenarios. It even addresses the batching loop and provides an out-of-band alternative, leaving no critical gaps.

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?

Despite 0% schema description coverage, the description adds rich semantics for all three parameters. full is explained as 'refetches already-cached rounds (least-recently-synced first)', max_rounds bounds the run and defaults to 25, and include_health controls the health pass. This goes beyond the schema's bare types and defaults, giving actionable meaning.

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

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

The description opens with a specific action: 'Pull golf data from Garmin Connect into the local cache, plus daily health...' This clearly identifies the resource (Garmin Connect data), the mechanism (sync to local cache), and the scope (golf rounds + health metrics). It distinguishes itself from siblings like list_rounds or get_round, which operate on already-cached data, by emphasizing the fetch-and-store behavior.

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

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

Provides explicit operational guidance: for full history, 'keep calling this tool until rounds_remaining is 0' with progress updates, and for very large backfills, recommends using `caddie-mcp sync` in a terminal. It also explains when to use include_health=False and full=True, giving clear context on how the tool should be invoked for different scenarios.

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