get_wellness_data

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

With no annotations provided, the description carries the behavioral disclosure burden. It does so well by revealing that standard fields are returned by default, that include_all_fields=True extends to custom fields, that athlete_id and api_key optionally fall back to .env values, and that dates default to a 30-day window. It does not mention error behavior or rate limits, but it adequately describes what the tool does at invocation time.

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 sized and well-structured: a purpose sentence, a sentence about behaviors, and a logical Args block. The Args lines repeat parameter names from the schema but add valuable default and format context, so nothing is wasted. It could be slightly tighter, but it remains readable and front-loaded with the core function.

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 five all-optional parameters and an existing output schema, the description supplies enough to call the tool correctly: parameter defaults, credential sources, date formats, and the field-scoping flag. There is no need to describe return values because the output schema exists. Minor omissions like invalid-input handling do not impede correct invocation.

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 is the sole source of param meaning. It fully compensates by documenting all five parameters in the Args section, adding format specifics (YYYY-MM-DD), default values (30 days ago, today, False), and the .env fallback for credentials. This is exactly the semantics an agent needs beyond raw JSON schema.

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 verb and resource: 'Get wellness data for an athlete from Intervals.icu.' It then enumerates the content domains (training metrics, vitals, sleep, subjective scores), which clearly separates it from sibling tools focused on activities, events, gear, and custom items. There is no ambiguity about what this tool does.

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 establishes a clear use context: whenever an agent needs wellness data for an athlete. It also gives practical guidance on the include_all_fields flag, explaining when to set it to True. It does not explicitly name alternative tools or state when not to use it, but the semantics of 'wellness data' are distinct enough among the siblings to provide clear direction.

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