list_workouts

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it states ordering (newest first), output format (compact summaries with field list), filtering semantics (inclusive dates, local time, case-insensitive substring), default limit, and the special `part_of` attribute for multisport events. It also explains how to link to detail tools, leaving no hidden behavior.

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 front-loaded with the core action and output fields, then efficiently covers parameters in a compact block, followed by a special-case note and routing instruction. Every sentence adds value—there is no filler or redundancy. The structure is logical and easy to scan, making it both concise and informative.

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 four parameters, an output schema, and no annotations, the description is fully complete. It covers all parameter behaviors, output characteristics (including swim-specific fields), special cases (multisport legs), and cross-tool usage. The output schema already defines the return structure, so the description needn't repeat it; nothing an agent needs to call the tool correctly is missing.

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 schema provides zero descriptions, so the description must fully document parameters. It does so comprehensively: from_date/to_date are defined as optional ISO YYYY-MM-DD bounds (inclusive, local time), sport is a case-insensitive substring filter with examples, and limit is the max items with default 30. Every parameter's meaning, format, and default are spelled out, exceeding what the schema alone could convey.

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 precise verb and resource: 'List workouts, newest first, as compact summaries'. It enumerates the exact fields returned, making the tool's scope unmistakable and distinguishing it from detail tools like get_workout_detail or aggregation tools like summarize_workouts. The phrase 'compact summaries' also clarifies the level of detail, leaving no ambiguity about what the 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 explicitly instructs the agent to use the returned `trackid` with get_workout_detail / get_workout_track for further detail, effectively routing the user to the appropriate sibling tools. It also notes special handling for multisport legs, which guides correct usage. While it doesn't explicitly contrast with every sibling, the mention of detail tools and the emphasis on listing makes the intended use clear.

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