get_activity_streams

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

No behavioral disclosure beyond the mechanics of the data: there is no statement of whether the tool is read-only, what permissions it requires, what errors occur for an invalid activity_id, or whether calls are rate-limited. The description does explain what the return value contains (one array per field, means, unit strings, nulls for empty buckets, missing_fields), which is valuable, but for a tool with no annotations at all, it leaves the operational characteristics largely undisclosed.

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 definition is front-loaded with the essential statement ('Downsampled per-second data of one Activity') and sustains a tight chain of semicolon-separated clauses without repetition. It is dense and slightly run-on with nested parentheses, but every sentence carries 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?

It covers the return shape well enough without an output schema: how arrays are nested, how missing fields are reported, and how empty buckets are nulled. It still omits the shape of the missing_fields container itself and any failure modes or limits, which matters for a five-parameter read tool with no 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 100%, so the schema supplies the baseline. The description adds real meaning: it defines buckets as resolution_sec_used-second means starting from start_sec, notes that the last bucket may be shorter, and fixes units per field (W, bpm, rpm, m/s, m, m). It also explains the 500-point cap and the behavior when a finer resolution is requested. That goes beyond the schema's field-level text.

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 operation and resource: downsampled per-second data for one Activity, taken from its Activity file. It also describes the value of the result: chart it or reason about it. It does not name sibling tools such as get_window_stats or get_activity_intervals, so an agent must still infer why it should choose streams over aggregates.

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 phrase "to chart or reason about" only implies the intended use (time-series visualization) without stating when to use this tool versus get_window_stats or get_activity_intervals. No exclusions or prerequisites are given, so selection 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.