Hydrate several recent Strava activities

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

With no annotations, the description carries the transparency burden. It discloses that the operation is 'Write-only' and explains the execution model: 'hydrates one activity at a time and reports every outcome.' It also notes a dependency on athleteId. It does not mention idempotency, rate limits, or failure semantics, but still provides meaningful operational context beyond a bare verb.

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?

Two sentences with no filler. The critical qualifier ('Write-only targeted batch enrichment') is front-loaded, and each clause contributes distinct information: selection modes, execution model, outcome reporting, and prerequisite. The unexplained 'Catence' term is the only minor blemish.

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 7-parameter tool with no output schema and no annotations, the description covers selection modes and prerequisite but leaves semantics of limit and refresh unaddressed. It also does not warn against using this tool for single-activity hydration or indicate whether it is long-running and how that relates to sibling status tools. An agent would still have open invocation questions.

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 had to compensate. It successfully links the 'explicit list' mode to activityIds and the 'bounded date/sport window' mode to startDate/endDate/sports, and highlights athleteId as required. However, it leaves limit and refresh undefined, providing only partial compensation for the schema gap.

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 names a specific verb ('hydrate') and resource ('recent Strava activities'), and explicitly characterizes the operation as 'targeted batch enrichment', distinguishing it from its singular sibling hydrate_strava_activity. It also identifies the two selection modes (explicit list vs bounded date/sport window), making the tool's purpose unmistakable.

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?

It provides a concrete prerequisite ('Requires athleteId from list_athletes') and tells the agent how to choose between an explicit list and a date/sport window. It does not explicitly name the singular alternative or list exclusions for when not to use this tool, so it loses a point.

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