get_power_duration_curve

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly discloses that the tool downloads multiple FIT files, may take 30-60 seconds, filters by activity type, and returns provenance (activity and date) for each best. It could be more transparent about edge cases like missing power data or invalid activity types, but it covers the main cost and behavior well.

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 organized into clear sections: purpose, durations, practical FTP guidance, a performance warning, and parameter docs. Every sentence adds value—nothing is filler. The most important scoping and behavior information is front-loaded before the parameter details.

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 the output schema exists, the description correctly focuses on process and usage rather than return fields. It covers durations, FTP interpretation, latency, and parameters. Missing context is relatively minor: what 'season' means, how 'recent' is defined beyond num_activities, and behavior when there is insufficient power data. These are gaps but not crippling.

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 must fully document parameters. It does: num_activities is explained as 'Number of recent activities to analyze' with default 20 and max 50, and activity_type is explained as the filter with default 'cycling'. This adds meaning beyond the bare schema, including the max constraint not present in the 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 season-best Power Duration Curve across recent activities.' It then explains the computation pipeline (downloads FIT files, computes best mean maximal power) and return value (season bests with activity and date). This clearly distinguishes it from sibling tools like get_activity_power_in_timezones and get_cycling_ftp by describing its unique output and process.

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 for when this tool is useful, especially the practical tip to use the 20-minute best × 0.95 as an FTP estimate without a formal test. It also warns about the 30-60 second latency, letting the agent judge against faster alternatives. However, it does not explicitly name sibling alternatives or state when not to use this tool.

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