fitbit_trends

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

With no annotations available, the description carries the full burden of behavioral disclosure. It discloses that the tool auto-syncs from the local cache if stale, implying potential network or cache side effects. It also details return values per data type and notes that compare ignores other date parameters. It lacks error-handling or permission details, but overall it is transparent.

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 longer than a typical two-sentence summary but is well-structured with a one-line overview, an Args section, a Returns section, and a final note. Every sentence adds value, especially the detailed parameter options and per-data-type outputs. It is front-loaded with the core purpose and uses clear formatting, though it could be slightly tightened.

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 tool with 5 optional parameters, a complex compare feature, and 13 data types with varied output fields, the description covers parameter semantics, return values, and cache-sync behavior. It even provides examples for compare and date formats. It omits edge cases like invalid dates or empty data, but the presence of an output schema and the description's thoroughness make it sufficiently complete.

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 input schema provides zero parameter descriptions (0% coverage), so the description's 'Args' section is essential and fully compensates. It defines data_type and period options with defaults, start/end date formats, and the compare format with examples. Every parameter is semantically described, including the behavior that compare overrides others.

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, 'Analyse trends in cached Fitbit data,' then elaborates on computing averages and totals over time. It clearly distinguishes itself from sibling fitbit_get_* tools by explicitly stating it is not for raw data and by listing supported data types. This makes its purpose unambiguous.

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 provides clear guidance on when to use the tool for aggregated trends and explicitly notes 'Not for raw data - use fitbit_get_* tools instead,' naming the alternative. It also explains the compare feature and how it overrides period/start_date/end_date, giving users context. However, it stops short of describing specific scenarios beyond the raw-data exclusion, so it is not a full 5.

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