Skip to content

STARS: Room schedules MCP tools

Service overview · CLI reference · All MCP tools · Data types

Room schedules

Inputs are required only where marked. A required output field may still be null if its type allows it. See data types for nested objects.

stars_find_available_rooms

Find rooms with no known published undergraduate teaching throughout a day/time interval and every requested teaching week. Covers all indexes from both full-time and part-time schedules, including all lesson types. Filters select room type inferred from venue code, venue text/prefix, excluded rooms or observed lesson types. Unknown conflicting schedules are excluded. Only teaching-observed rooms are returned; this does not establish occupancy, access, capacity or availability against graduate classes, exams or other bookings. Times are Singapore time and weeks are semester teaching weeks. Omit weeks for a conservative whole-term check. Follow has_more with offset.

Find a teaching-observed room with no known scheduled undergraduate classes throughout a requested interval.

Inputs: academic_year, semester, and window with day, start_time, and end_time. Optional window.teaching_weeks selects semester teaching weeks, from 1–20; the room must be free in every selected week. Omitting weeks checks every published meeting conservatively across the term. window.buffer_minutes, default 0 and maximum 120, requires additional teaching-free time before and after the interval. The interval plus buffer must fit in one day.

Optional filters:

Field Meaning
room_types tutorial_room, seminar_room, lecture_theatre, laboratory, or other, inferred from venue labels
venue_contains Case-insensitive literal text within a normalized venue code
venue_prefixes Any matching code prefix, such as LHN, LHS, SPMS, or S4
exclude_venues Exact venue codes or equivalent normalized aliases to omit
used_for_lesson_types Require observed use for any listed lesson type, such as TUT or LAB

All lesson types still block availability, regardless of filters. limit is 1–100, default 20; offset defaults to 0. refresh: true reloads the complete shared teaching snapshot.

Returns: room codes, inferred types, observed aliases/lesson types, free_from/free_until teaching-free bounds on that day, total match_count, and pagination. A free_until of 24:00 is the end of the day, not a building opening-hours statement. Conflicting unknown days, times or teaching weeks exclude a room and contribute to excluded_uncertain_count; known clashes contribute to excluded_busy_count.

The first lookup fetches two public schedule pages concurrently: a blank-course search for full-time offerings and another for part-time offerings. Every published index/session is checked; no course-by-course crawl, course-description lookup or vacancy request is needed. Both pages must parse successfully before results are returned. The normalized snapshot is shared with room timetable lookups, cached for NTU_CACHE_TTL_SECONDS, and bounded to four terms.

Only recognizable room labels actually observed in teaching are candidates. Online, placeholder, date-like, course-reference and unrecognized venue labels are excluded. Common punctuation, quotation and tutorial-number variants are merged conservatively; multi-room cells block each independently observed component. Unknown raw venue text is retained in room timetable results. Coverage reports course/index/lesson counts, courses without published indexes, observed room count, excluded venue-label count and unplaced lesson count. Empty official index tables remain missing data; they do not establish that a course has no classes.

{"academic_year":2030,"semester":1,"window":{"day":"WED","start_time":"14:00","end_time":"16:00","teaching_weeks":[7],"buffer_minutes":10},"filters":{"room_types":["tutorial_room","seminar_room"],"venue_prefixes":["LHN","LHS"]}}

Inputs

Field Type Required Details
academic_year integer Yes minimum: 2000; maximum: 2100
semester 1, 2, "S" Yes —
window RoomWindow Yes —
filters RoomFilters or null No default: null
limit integer No minimum: 1; maximum: 100; default: 20
offset integer No minimum: 0; default: 0
refresh boolean No default: false

Output

Field Type Required Details
academic_year integer Yes —
semester string Yes —
source_url string Yes —
retrieved_at string Yes —
cached boolean Yes —
coverage RoomCoverage Yes —
availability_basis "no_known_scheduled_teaching" No default: "no_known_scheduled_teaching"
window RoomWindow Yes —
match_count integer Yes —
offset integer Yes —
has_more boolean Yes —
rooms array of AvailableRoom Yes —
excluded_busy_count integer Yes —
excluded_uncertain_count integer Yes —

Unknown fields are not accepted.

stars_get_room_schedule

Get all published undergraduate course/index lessons using one observed room, including full-time and part-time offerings. Accepts a venue code or returned alias. Shared lessons carry all associated index numbers. Optional day, teaching weeks and overlapping time interval filter the result; uncertain lessons remain included. Missing weeks/times are unknown. Paginate with offset/limit and has_more. This is teaching data, not room bookings or actual occupancy.

Retrieve the courses and indexes using a room, from the same complete full-time/part-time undergraduate teaching snapshot.

Inputs: venue, academic_year, semester. Optional day, teaching_weeks, and both start_time/end_time restrict the result to potentially overlapping lessons. Unknown timing/week data remains included rather than being silently discarded. limit is 1–100, default 50; offset defaults to 0. refresh reloads the shared snapshot.

Returns: the canonical venue and aliases, inferred room type, observed lesson types, and paginated sessions. Shared sessions are grouped with every associated index in indexes. Course codes and indexes remain strings. Sessions retain teaching weeks, unusual remarks, raw day/time values and original venue labels when they differ from the enclosing room. An unidentified venue returns an error rather than an empty or apparently free timetable.

{"venue":"TR+7","academic_year":2030,"semester":1,"day":"TUE","teaching_weeks":[7]}

These tools report no known scheduled undergraduate teaching, not guaranteed room availability or occupancy. Graduate classes, exams, private bookings, closures and access restrictions are outside coverage. Room types are inferred from names; capacities, equipment, accessibility and opening hours are not supplied by this source. Bare TR/LT codes do not establish North/South Spine or a building location; use MazeMap for verified location information.

Inputs

Field Type Required Details
venue string Yes minimum length: 1; maximum length: 80
academic_year integer Yes minimum: 2000; maximum: 2100
semester 1, 2, "S" Yes —
day "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN" or null No default: null
teaching_weeks array of integer or null No default: null; minimum items: 1; maximum items: 20
start_time string or null No default: null; pattern: ^(?:[01]\d\|2[0-3]):[0-5]\d$
end_time string or null No default: null; pattern: ^(?:[01]\d\|2[0-3]):[0-5]\d$
limit integer No minimum: 1; maximum: 100; default: 50
offset integer No minimum: 0; default: 0
refresh boolean No default: false

Output

Field Type Required Details
academic_year integer Yes —
semester string Yes —
source_url string Yes —
retrieved_at string Yes —
cached boolean Yes —
coverage RoomCoverage Yes —
room RoomIdentity Yes —
session_count integer Yes —
offset integer Yes —
has_more boolean Yes —
sessions array of RoomLesson Yes —

Unknown fields are not accepted.