get_workout_details

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

With no annotations, the description carries the full burden and discloses substantial behavior: the response can exceed 200k characters, slim mode strips specific fields, media fields are always stripped, coaching text truncates to max_text_chars, and team resolution falls back to the user's primary team. It also explains server-side team resolution when program_id is provided. No contradictions exist.

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 three purposeful paragraphs: overview, usage/team resolution, and slim-mode details with an alternative. Each sentence carries operational information—response size, defaults, fallbacks, and alternatives—so the length is justified and the core purpose is front-loaded.

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 6-parameter tool with no output schema, the description is remarkably complete: it specifies input provenance, output contents and size, default behavior, truncation, and a targeted alternative. It also warns about a concrete risk (raw response >200k chars) that affects agent decisions. The only minor omission is cache_bust semantics, which does not substantially hurt usability.

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 compensate, and it covers 5 of 6 parameters: program_workout_id provenance, program_id/team_id relationship, slim behavior, and max_text_chars truncation. cache_bust is the only parameter left unexplained, but it is a minor boolean flag and all required/main parameters are given clear semantic context.

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 workout details for a specific program workout,' and enumerates the included content (exercises, prescribed vs. logged sets, coaching notes). It also distinguishes from sibling tools by tying to get_workout_history and directing single-exercise needs to get_exercise_detail.

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 explicitly instructs to pass the program_workout_id from get_workout_history, explains the trade-offs between program_id and team_id, and names get_exercise_detail as the alternative when only one exercise's per-set data is needed. It also tells when to use slim=True versus slim=False based on response size and context-window constraints.

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