gym-ops MCP server

Overview Schema Source Related Servers Discussions Admin

get_class_occupancy

Read-onlyIdempotent

Check how full group classes were between two dates, per slot and overall, to identify peak hours and attendance trends.

Instructions

How full group classes were between two dates, per slot and in aggregate.

Use this for questions about attendance, busy or quiet times, peak hours, or how a class type is performing. Returns:

totals: slots, capacity, check-ins, and occupancy_pct over the whole range;
by_class: the same per class type;
by_weekday_hour: the same per (weekday, start hour), sorted busiest first, so the first rows are the peak times;
slots: each class slot chronologically (start time in local gym time, coach, capacity, check-ins), capped at 200 rows; truncated is true if cut. occupancy_pct = check-ins / capacity * 100, rounded to one decimal.

Dates are inclusive, YYYY-MM-DD, at most 366 days apart. Classes run Monday-Saturday. Valid class_name values: HIIT, Spin, Yoga, Pilates, Boxing, Strength.

If no class slots match, the result also has available_range ({"from": ..., "to": ...}): the first and last dates that have any class slots. Retry with dates inside it rather than concluding there were no classes.

Input Schema

TableJSON Schema

Name	Required	Description
`end_date`	Yes	Last day to include, YYYY-MM-DD (inclusive). Must be >= start_date.
`class_name`	No	Only include this class type. Omit for all classes.
`start_date`	Yes	First day to include, YYYY-MM-DD (inclusive).

Output Schema

TableJSON Schema

Name	Required	Description
`slots`	Yes	Chronological; capped at 200.
`by_class`	Yes
`end_date`	Yes
`truncated`	Yes	True if `slots` was cut at 200 rows.
`class_name`	Yes
`start_date`	Yes
`total_slots`	Yes
`occupancy_pct`	Yes
`total_capacity`	Yes
`total_checkins`	Yes
`available_range`	No	Present only when no class slots fall in the requested range: the first and last dates that have class slots. Retry with dates inside it.
`by_weekday_hour`	Yes	Sorted busiest first (highest occupancy_pct).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already establish a safe read-only, idempotent operation; the description goes beyond by disclosing the 200-row cap with truncated flag, inclusive date semantics, the 366-day maximum span, and the available_range fallback when no slots match. This gives the agent accurate expectations for edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but densely structured: purpose first, then return sections, then parameter constraints, then the empty-result edge case. Every block earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with multiple return sections, a truncation rule, and an empty-result fallback, the description covers all behavior an agent needs to call it accurately. The output schema plus this description leave no important gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema documents all three parameters, so baseline is 3; the description adds meaningful constraints beyond it—inclusive date bounds, a 366-day maximum span, class schedule, and retry guidance via available_range. It does restate the class_name enum values, but overall it adds value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States exactly what it computes—group class occupancy between two dates—and specifies the granularity (per slot and aggregate). It clearly distinguishes itself from the member/payment sibling tools, so an agent can select it without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use-case guidance: questions about attendance, busy/quiet times, peak hours, and class type performance. It doesn't name negative cases or alternatives, but the sibling tools are obviously unrelated and the positive triggers are specific.

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

Deploy Server