Reimport Samsung Health Export from Watch Folder

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

The description goes well beyond annotations by disclosing that caches are cleared on promotion, that check_only is read-only, and that promotion requires explicit user intent. It also specifies what file types are considered newer (SamsungHealth folder, *.csv, *samsung*health*.zip), adding concrete behavioral context.

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

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

Four sentences with the main action front-loaded, followed by mode-specific behavior and comparison to the Android bridge. Dense but every sentence adds critical information; no 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?

Despite no output schema, the description covers the full workflow: what gets scanned, what qualifies as newer, what happens on promotion, cache clearing, check_only behavior, and the alternative Android path. All three optional parameters are accounted for contextually, making the tool's behavior predictable.

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 covers force and check_only descriptions, and the description adds meaning by explaining check_only's effect ('only report what would happen without promoting') and tying force to the explicit-intent requirement. response_format is not explained but has an enum and default, so the baseline is 3 with slight improvement to 4.

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

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

The description clearly states the tool re-scans a watch folder for newer Samsung Health exports and promotes them to the active export, clearing caches. It distinguishes itself from siblings by explicitly naming it as the cross-platform recurring-refresh path and separating it from the Android Health Connect bridge.

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 explains when to use the tool (recurring refresh via watch folder) and provides an exclusion: the native Android Health Connect bridge is separate and needs an Android device. It also clarifies the role of check_only as read-only inspection and the explicit-user-intent requirement for promotion.

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