generate_timetable

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description usefully reinforces that this is a planning-only operation that neither enrolls nor writes an ACORN timetable. It adds solver semantics and the one-plan-per-term grouping, but says nothing about how a result is shaped or any limits on plan size.

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?

Roughly five sentences, each carrying distinct information: purpose first, then per-field meaning, then the negative scope caveat. No filler or restated title.

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 single-argument tool with no output schema and clear annotations, the description covers purpose, inputs, and what it does not do. It is slightly thin on what the returned plans actually contain (sections, times, identifiers), which is the one thing only the description could supply.

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?

With only one top-level parameter and low coverage in the reported schema descriptions, the description compensates well: it explains that each plan maps to one term, that activity_types are section types (Lecture/Tutorial/Practical), that preference is early/balanced/late, and that blocked_times use weekday names with 24-hour HH:MM values. Some of this restates schema enums/patterns, but the grouping and clock-format meaning go beyond the raw schema.

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: asks the university's solver for conflict-free lecture, tutorial and practical sections. It also carves out a clear boundary against siblings ('This does not enroll students or write an ACORN timetable'), which separates it from save_timetable and retrieve_timetable without opening their schemas.

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?

Gives an explicit input dependency ('course_id values come from get_course_details') and a negative scope statement ruling out enrollment/timetable writing. It stops short of naming save_timetable as the follow-up step for persisting a generated plan, so the alternative is implied rather than stated.

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