get_published_workouts_range

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

Annotations already cover read-only, idempotent, non-destructive, open-world behavior, and the description adds real context beyond that: one list read per day, detail requests scoped to the requested class, per-day available/unavailable status, a classNamesInRange summary, and a trust warning that source content is untrusted. The only weak spot is the cryptic '%RM enrichment matches get_published_workouts for today and later' clause, which is not self-explanatory.

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?

Front-loaded with verb, resource and range, then the sibling comparison, then output and trust notes — a sensible escalation. It is dense but every sentence carries information; minor cost is jargon like '%RM enrichment' that assumes prior context.

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?

With annotations, full schema coverage and an output schema already present, the description covers the remaining gaps an agent needs: when to prefer it, the 14-day bound, how each day is reported, the classNamesInRange helper, and the untrusted-source caveat.

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 coverage is 100%, so the baseline is 3; the description lifts it modestly by framing what the date range is typically used for ('today, a given weekday, or this week') and by restating the omit-vs-pass rule for className in operational terms. It does not add format or validation detail beyond the schema, so it stays below the top mark.

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?

States a specific verb and resource ('Retrieve published workouts of one exact className') plus the exact scope ('every gym-local date in an inclusive range of up to 14 days'). It also names the sibling it supersedes (get_published_workouts), so an agent can distinguish it without opening either schema.

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?

Explicitly routes the agent: 'Prefer this over repeated get_published_workouts calls' with the reason (one read per day, details only for the requested class). The className rule — omit for the gym-configured class, pass only when the account holder names a class — is a clear when-to-use condition.

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