set_fit_download_dir

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

No annotations are provided, so the description carries the behavioral burden. It discloses persistence, the exact config file location (~/.garminconnect_fit_config.json), the environment variable override, and the downstream effect on downloads. It does not discuss overwrite behavior or error cases, but for a simple configuration setter this is sufficient.

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 compact and well-structured: a clear purpose sentence, then persistence and configuration details, then the single argument explanation. Every sentence adds value, with no filler or repetition.

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 one-parameter setter, the description covers the main behavior, persistence location, environment override, and relationship to download_activity_file. An output schema exists to cover the return value. The only minor gap is that it does not mention whether the directory must already exist or how invalid paths are handled.

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 only lists a 'path' string with no description, so the parameter documentation in the tool description is essential. The description explains that path is a directory where .fit/.gpx/.tcx/.csv files are saved and even gives a practical tip about passing the current working directory. This fully compensates for the 0% schema coverage.

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: 'Set and persist the default directory for downloaded activity files.' It clearly distinguishes itself from the many getter and setter siblings by focusing on the download directory configuration, and it names the related download_activity_file 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?

The description gives clear context by explaining that download_activity_file will use this directory 'without asking again,' so an agent knows this tool is meant to configure a persistent download location. It does not explicitly list when not to use it or alternatives, but the intended usage is unambiguous among the sibling tools.

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