Get school events

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

Annotations indicate readOnlyHint=true and openWorldHint=true, and the description aligns: it's a read-only operation. The description adds context about the data source ('as announced on the timeline') and the scope of event types, which is not captured in annotations. It doesn't mention pagination or partial results, but the description's detail about event categories helps.

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 a single sentence, but it's dense. It front-loads the primary concept (school calendar events) and then lists specific event types. It doesn't waste words, though the sentence is somewhat long. The information about timeline and involved parties is useful, so the length is justified.

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 read-only retrieval tool with no required parameters and a good output schema (implied by 'has output schema: true'), the description is fairly complete. It covers the date range logic, event categories, and included details (subject, teachers, classes). The main gap is the 'student' parameter semantics, but since the tool is likely used in a context where the student is implied, this is acceptable.

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%, and the description only explains start_date and end_date defaults (today and +30 days). It doesn't clarify the optional 'student' parameter – how the student is identified (an ID? name?) or whether defaulting to null implies the current student. The description fails to compensate for the low schema coverage, leaving two of three parameters under-documented.

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 clearly states the tool's purpose: retrieving school calendar events (exams, trips, holidays, etc.) for a student within a date range. The specific verb 'get' and resource 'school events' are unambiguous. It distinguishes itself from siblings like get_timetable and get_homework by focusing exclusively on calendar events as announced on the timeline.

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?

The description implies usage: when a user asks about school events, exams, or holidays between dates. It doesn't explicitly state when not to use it or mention alternatives like get_timetable (for schedule) or get_substitutions (for changes). However, the event type list provides some context that this is for broader events rather than daily schedules.

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