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

With no annotations, the description carries the full burden. It clearly discloses that this is a write operation ('Writes: books the selected menu'), specifies the return dict, and gives operational notes. It omits details like permissions and failure modes, but the core side effect is transparent.

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 compact and structured with Args, Returns, and Notes sections. The write nature is front-loaded, and every sentence adds relevant information with no redundancy.

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 write tool with no annotations and no output schema, the definition covers all parameters, the return format, and cross-tool prerequisites. The agent has enough to call it correctly.

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 0%, so the description must fully explain the parameters. It does: date_str format, meal_type allowed values, number's 1-based semantics tied to get_meals, and subdomain default. This adds meaning the schema completely lacks.

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 opens with 'Order/choose a meal' and clarifies 'Writes: books the selected menu for the date,' giving a specific verb and resource. It also distinguishes itself from siblings by naming get_meals as the read prerequisite and sign_off_meal as the cancellation alternative.

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?

It explicitly tells the agent to read `get_meals` first to obtain a valid `number`, and says to use `sign_off_meal` to cancel. This is clear context and an alternative, though it does not enumerate conditions for every sibling tool.

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

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

With no annotations, the description carries the full burden, and it succeeds: it discloses that this is a write operation that drops cache, affects the next lookup by forcing a refetch, and can clear all schools. The return shape is also described, giving a complete picture of side effects.

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 well-structured and efficient: purpose first, then usage trigger, then argument semantics, then return format. Every sentence earns its place without redundant filler.

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?

Even though there is no output schema, the description includes the return dict format. Combined with argument explanation and usage guidance, the description gives an agent everything needed to invoke the tool correctly and understand its consequences.

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 0% and the subdomain parameter has no schema description, but the tool description fully explains it: 'School whose cache to clear. Without it, clears ALL schools.' This adds critical meaning 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?

The description states a specific action and resource: it drops the local student data cache so the next lookup re-fetches from EduPage. This makes the tool's purpose unambiguous and clearly distinguishes it from read-only lookup tools like scan_students and find_student.

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?

Explicit trigger conditions are provided: call this after students are added/removed or when scan_students/find_student appears stale. It also warns about the default behavior of clearing ALL schools when subdomain is omitted, which is essential guidance for correct use.

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

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

With no annotations provided, the description correctly carries the full burden. It discloses the most critical traits: write capability ('treat as write-capable'), use of the active session, and that responses are raw text ('Parse the returned text yourself; fields are not pre-serialized'). It falls short only on error/edge-case behavior (e.g., network failures, non-2xx handling, auth expiry) which would be useful for a low-level tool.

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 summary line is front-loaded with the critical warning about write capability, followed by tight Args/Returns/Notes sections where every line earns its place. Though longer than minimal descriptions, the length is justified by the 0% schema coverage that forces parameter documentation into the description. No redundant text.

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 tool with no annotations and no output schema, the description covers all the essential operational context: what it does, all parameter formats, the return shape, session behavior, and the write risk. The only meaningful gap is absence of error/disaster behavior (what happens on network failure, invalid session, or non-2xx status codes), which an agent invoking raw HTTP should reasonably expect to know.

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%, so the description wholly compensates — and does so exceptionally. It documents all 5 parameters with meaningful detail: URL resolution rules ('resolved against https://<subdomain>.edupage.org'), allowed method values, body applicability, header JSON format with an example, and subdomain session semantics including its default.

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 ('Send a raw request to the Edupage server using the active session') and immediately flags the key behavioral caveat ('Can perform writes depending on the endpoint'). The Notes section explicitly frames this as the low-level fallback for endpoints not covered by dedicated tools, which clearly differentiates it from the 27 sibling tools without needing to compare 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?

Explicitly instructs when to use: 'Low-level escape hatch for endpoints not covered by the dedicated tools — prefer those when available.' This gives the agent a clear selection rule versus alternatives. It could name specific siblings, but the class of dedicated tools is well-understood and the general routing instruction is actionable.

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

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

With no annotations provided, the description carries the full disclosure burden and meets it: it states read-only behavior, search scope across schools, tier semantics, confidence sorting, and ambiguity handling. This is rich behavioral context beyond what the schema alone shows.

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 front-loaded with the core purpose, then organized into Args, Returns, and Notes with zero filler. Every sentence contributes either parameter meaning, return-shape detail, or usage guidance.

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 two-parameter read-only lookup with no output schema, this description is complete: it specifies the return dict and fields, explains matching tiers, and tells the agent how to use the result. No critical operational detail is missing.

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%, but the description fully compensates: `name` is explained with format variants including short forms, and `subdomain` is given a clear restriction and default behavior. This adds real meaning beyond the bare schema field names.

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 uses a specific verb ('Look up') plus resource ('student') and method ('tiered matching'), and states the read-only nature and multi-school behavior. This clearly differentiates find_student from broader listing tools like scan_students.

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?

It explains when subdomain should be used versus omitted, and advises using the returned student_id with get_student_timetable/get_day_summary for unambiguous lookups. It does not explicitly name sibling alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden and mostly succeeds: it discloses the discovery-first default behavior, the full=True escape hatch, and the section-isolation contract (a failed section returns {'ok': false, 'error': ...} without failing the report). It does not state auth/permission requirements or rate limits, leaving a small gap.

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 the core purpose and the section list, then bulleted conditions for each parameter mode; every bullet carries distinct routing information. The section enumeration is long but earns its place by telling the agent exactly what is aggregated.

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 no annotations and no output schema, the description does the necessary work: it explains return semantics (per-school child index vs full report vs logged-in account report) and the degradation behavior on section failure. It stops short of describing the concrete report schema, but given the isolation contract that is a minor omission.

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 0%, so the description must compensate, and it does for four of five params: date_str (default today), name/student_id (student selection, cross-school unless subdomain scopes it), subdomain (scoping), and full (full report per child instead of index). Only minor ambiguity remains, e.g. the exact name vs student_id precedence.

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 composite action (one-call daily school report for a date) and enumerates the exact sections it aggregates (timetable, substitutions, grades, meals, etc.). It explicitly distinguishes itself from the many sibling section tools by saying it 'composes the individual section tools' so the agent needn't fire 8-10 calls.

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 explicit branching conditions: with name/student_id it reports for that student; omitted for a parent it returns a lightweight per-school child index (discovery-first); omitted for student/teacher it uses the logged-in account; full=True builds the full report for every child. This is precisely the when-to-use/when-not guidance an agent needs against siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses read-only behavior, describes the return format (dict with subdomain and grades list), and explains the default behavior when parameters are omitted. It doesn't mention error handling or permission requirements, but for a simple getter this is adequate.

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 tightly structured with Args, Returns, and Notes sections. The purpose and read-only note are front-loaded, and every sentence adds value—no filler or repetition. It is concise while covering all essential aspects.

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?

Given the low complexity (3 optional parameters) and no output schema, the description provides everything needed to call the tool correctly: parameter explanations, return format, and default behavior. It also references a helper tool for resolving the school year, rounding out the context.

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 0%, yet the description fully compensates by explaining each parameter in the Args section: year with an example (2025 for 2025/26), term as 'FIRST' or 'SECOND', and subdomain with a default (active subdomain). This adds meaningful semantics beyond the bare schema properties.

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 states a specific verb ('Get') and resource ('grades') for a clearly scoped subject ('the logged-in student'), and explicitly labels the operation as read-only. This distinguishes it from sibling tools that handle timetables, meals, or student scans without ambiguity.

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?

It provides concrete usage context: notes that omitting year and term returns the current gradebook, and points to get_school_year to resolve the current school-year start. While it doesn't explicitly list when not to use it or compare against alternatives, the default behavior and helper guidance give the agent clear direction.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly. It discloses read-only safety, the guaranteed shape of the response, handling of unpublished slots as None, and the endpoint fallback behavior. This goes well beyond a basic summary and gives the agent accurate expectations.

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 well-structured with a front-loaded purpose, then Args, Returns, and Notes sections. Every sentence adds necessary information, and the formatting makes it easy to scan. Despite its length, nothing is wasted.

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?

The description is complete for this tool's complexity. It has no annotations or output schema, so the description covers return values, parameter defaults, edge cases for unpublished meal slots, fallback behavior, and integration with related meal tools. An agent has everything needed to call it correctly.

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%, but the description fully compensates. It documents both parameters with format and defaults: date_str as YYYY-MM-DD defaulting to today, and subdomain as the school to query defaulting to the active subdomain. This adds meaning the schema lacks entirely.

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 starts with a specific, unambiguous statement: 'Get the meal menu for a date.' It further clarifies the resource and behavior by listing the five meal slots and explicitly marking the operation as read-only. This clearly differentiates it from sibling mutation tools like choose_meal and sign_off_meal.

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 provides clear usage context by noting the return data is usable with choose_meal and sign_off_meal, implying when to fetch before acting. Read-only status signals not to use it for modifications, though it does not explicitly name alternatives or state when-not-to-use cases.

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

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

No annotations are present, so the description carries the behavioral burden. It explicitly states 'Read-only', documents the return shape, and notes the empty-list behavior. This covers the key behavioral concerns for a simple read tool, though it doesn't mention error cases or authentication requirements.

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 compact and well-organized with clear Args, Returns, and Notes sections. Every sentence adds value, and the most important facts are front-loaded in the first sentence.

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 tool with two optional parameters and no output schema, the description is complete: it documents defaults, input format, return structure, empty-list behavior, and a complementary sibling. Nothing essential is missing for an agent to invoke it correctly.

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 fully compensates: date_str is given the YYYY-MM-DD format and a default of today, and subdomain is explained as the school to query with a default of the active subdomain. Both parameters become unambiguous.

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 names a specific verb and resource ('Get teachers missing on a date'), states the default date, and explicitly marks it as read-only. It is clearly distinct from sibling tools like get_timetable_changes, and the purpose is immediately comprehensible.

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 provides clear usage context: optional date and subdomain defaults, and pairs with get_timetable_changes for the full substitution picture. It doesn't explicitly list when not to use it, but the pairing note gives an agent a concrete way to combine it with an alternative.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool is read-only, uses cached data, and that the cache can be refreshed by clear_student_cache. It also explains account-type visibility differences and the relationship to scan_students, going well beyond a simple operation statement.

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 organized into Args, Returns, and Notes sections, each earning its place. The key behavior is front-loaded, and the alternative guidance is compactly presented in the Notes. No redundant or filler content.

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-optional-parameter tool with no annotations and no output schema, the description is remarkably complete: it explains purpose, visibility rules, caching behavior, return shape, related functions, and how this tool differs from its sibling. An agent has everything needed to select and invoke it correctly.

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%, but the description compensates by explaining the only parameter, subdomain: 'School to query (defaults to the active subdomain).' This adds meaningful semantic context beyond the bare string type, though it does not specify the exact format or expected value shape of a subdomain.

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 opens with a specific verb and resource: 'Get the students visible to the logged-in account.' It clearly communicates the scoped visibility (children/classmates) and differentiates itself from the school-wide get_roster sibling.

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 notes explicitly state when to prefer this tool over get_roster and what each alternative provides: get_my_students shows your own children/classmates, while get_roster lists the whole school. It also names related operations like switch_to_student and get_student_timetable.

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

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

With no annotations, the description carries the full burden and it does so well: it states 'Read-only', specifies the return shape as a dict with date, subdomain, and lessons, and notes default behaviors. It does not discuss errors or authentication requirements, but the 'logged-in user' phrasing and read-only nature make the behavioral profile clear enough.

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 neatly organized into Args, Returns, and Notes with no filler. Every sentence contributes either parameter details, return contract, or sibling routing, and the most important scope information is front-loaded.

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 simple two-parameter read-only getter with no output schema, the description covers the input format, defaults, return structure, and sibling alternatives. Nothing essential is missing for an agent to select and invoke this tool correctly.

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 0%, so the description must fully compensate, and it does. date_str is defined with format and default, and subdomain is defined with its default and meaning. This is complete parameter documentation.

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 states a specific verb and resource: 'Get the timetable for the logged-in user on a date.' It is clearly differentiated from siblings through notes that explicitly name get_student_timetable, get_timetable, and get_next_week_timetable, so an agent can distinguish this tool without opening 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?

Usage is explicit: it is for the logged-in user on a single date, with defaults explained. The Notes section gives concrete when-not-to-use guidance and names the alternative tools for another student, for teacher/class/room/range, and for next week.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly labels the operation as 'Read-only' and describes the output as a serialized ringing with type and time. This gives the agent confidence about side effects and expected results, though it doesn't mention error behavior or timezone handling.

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 tightly structured with a one-line purpose, clearly separated 'Args', 'Returns', and 'Notes' sections. Every sentence adds value, including the useful pointer to get_periods. No filler or redundancy exists.

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 simple read-only tool with two optional parameters and no output schema, the description covers the essential context: what the tool does, how to call it, what it returns, and how it relates to the sibling get_periods. It lacks edge-case details like handling of past dates or timezone implications, but these are not critical for basic invocation.

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%, so the description must compensate entirely. It does so by giving each parameter a one-line explanation with default values: date_time_str is 'ISO datetime to search onward from (default: now)' and subdomain is 'School to query (defaults to the active subdomain)'. This fully compensates for the empty 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?

The description states a specific verb ('Get'), a precise resource ('the next school-bell ringing'), and the exact information returned (type and time). It also distinguishes itself from the sibling tool get_periods by describing its scope as the next single ringing versus the full schedule.

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 'Args' section explains how to use the tool, including defaults for date_time_str and subdomain, giving clear operational context. It also points to get_periods for the full bell schedule, suggesting an alternative for a different need, though it doesn't explicitly state 'use this when you only need the next ringing'.

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

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

With no annotations, the description carries the full burden and handles it well by stating 'Read-only', specifying grouping by weekday, describing the return dict structure, and listing weekday abbreviations. It also discloses that subdomain defaults to active subdomain, which is important invocation behavior.

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 front-loaded with the core purpose and organized into Args, Returns, and Notes. Every element adds operational value without repetition.

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?

There is no output schema or annotation support, yet the description covers scope, auth context, parameters, return shape, weekday codes, and sibling routing. This is complete enough for an agent to invoke the tool correctly.

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?

The schema only declares a subdomain string with a default, but the description adds meaning: 'School to query (defaults to the active subdomain).' Since schema description coverage is 0%, this is necessary and sufficient for the sole optional parameter.

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 opens with a specific verb and resource: 'Get the Mon-Fri timetable for next week for the logged-in user, grouped by weekday.' It also names sibling tools in the notes, distinguishing when get_my_timetable and get_timetable are appropriate instead.

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 Notes section explicitly routes alternatives: 'For the logged-in user on a single day use get_my_timetable; for any target ... over a range use get_timetable with end_date.' This gives clear when-not-to-use guidance so an agent can select this tool correctly.

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

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

No annotations are supplied, so the description takes on the behavioral disclosure burden. It clearly labels the operation as 'Read-only', explains the default subdomain behavior, and describes the return dictionary, covering the main behavioral facts an agent needs. It does not discuss auth or error conditions, but for a simple read-only lookup these are not critical gaps.

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 compact, front-loaded summary followed by a structured Args/Returns/Notes breakdown. There is little waste; the only slight flaw is the informal return notation using {'starttime', 'endtime'}, which is minor and does not undermine comprehension.

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 one-optional-parameter, read-only query with no output schema, the description supplies the essential information: what is returned, the shape of the return value, and the default behavior. The cross-reference to get_next_ringing_time adds useful integration context. No critical missing information remains.

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?

The input schema provides only the property name 'Subdomain' with no description, so the description is the sole source of parameter meaning. The Args section explains that subdomain selects a school and defaults to the active subdomain, which fully compensates for the 0% schema description coverage.

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 opens with 'Get the bell schedule (periods with start/end times)', which names a specific action and resource. The parenthetical clarifies the output granularity and implicitly separates it from the live-time sibling get_next_ringing_time, and the Notes line makes that relationship explicit.

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?

It states the tool's purpose clearly and notes that it should be combined with get_next_ringing_time for live timing, giving an agent context on where this fits. It does not explicitly list exclusions or alternative tools, so it stops short of the top score.

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

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

With no annotations at all, the description carries the behavioral burden. It explicitly states the tool is read-only and describes the return shape as a dict keyed by roster name with an example, which goes beyond minimal disclosure. It does not cover auth or rate limits, but for a read-only roster lookup the provided transparency is strong.

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 well-organized with clear Args, Returns, and Notes sections. Each sentence contributes either parameter semantics, return behavior, or routing to alternatives, with no filler.

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?

Given only two parameters, no output schema, and no annotations, this description is complete: it documents all parameter values, default behavior, return shape, read-only nature, and important relationships to sibling tools. An agent has everything needed to select and call this tool correctly.

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%, so the description must fully compensate, and it does. Every roster_type option is explicitly listed with its meaning and former tool name, and subdomain is described as the school to query with a default to the active subdomain.

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 begins with a specific verb and resource, 'Get a school roster', and immediately enumerates the exact roster types: students, teachers, classes, classrooms or subjects. The inline values and formerly-named tool references make it easy to distinguish this from related roster tools.

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 Notes section explicitly tells the agent when to prefer alternatives: use get_my_students for students visible to the logged-in account, and use find_student for a single student lookup. It also explains how returned IDs connect to get_timetable and switch_to_student, giving clear contextual routing.

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

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

No annotations are provided, so the description carries the full burden. It explicitly discloses 'Read-only', clarifies the default subdomain behavior, and states the return format. It could add error or authentication context, but for a trivial read operation this is sufficient transparency.

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 compact and front-loaded with the core purpose, then uses a clear Args/Returns structure. Every sentence adds distinct value without repetition or filler.

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?

Even though there is no output schema, the description provides the exact return dict format and explains the only parameter's behavior. For a one-parameter, read-only getter, nothing essential is missing.

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%, so the description must compensate. It defines 'subdomain' as 'School to query' and specifies it 'defaults to the active subdomain', adding meaningful semantics beyond the bare string type and null default in the 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?

The description uses a specific verb 'Return' with a clear resource 'current school year (starting year)' and explicitly states 'Read-only'. This precisely distinguishes the tool from its siblings and leaves no ambiguity about its function.

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 when to use the tool (when the current school year is needed) and explains the subdomain parameter, but it does not explicitly compare against sibling tools or state when not to use it. For a simple getter with no close sibling overlap, this is acceptable but still mostly implicit guidance.

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

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

No annotations are provided, so the description carries full burden. It clearly states read-only, describes the multi-school one-result-per-school behavior, parent child-agent resolution without session switching, and the return summary when multiple schools are searched. This is richly transparent.

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 well-organized with Args, Returns, and Notes sections. It front-loads the core purpose and terse behavior, then packs parameter semantics and parent-specific behavior into clearly labeled blocks without repetition or fluff.

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?

Covers invocation parameters, defaults, return format, and parent behavior. Minor gap: it doesn't state what happens if neither name nor student_id is supplied or if no student is found, but the description is otherwise sufficient for correct invocation given the lack of an output schema.

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 0%, but the description documents every parameter with meaningful detail: name accepts first/last/full, student_id is the preferred person_id, date_str uses YYYY-MM-DD with default today, and subdomain restricts to one school. This fully compensates for the schema's lack of descriptions.

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+resource: 'Get a student's timetable by first/last name OR person_id' and identifies itself as read-only. Distinguishes from sibling get_my_timetable by noting the parent/child handling, so an agent can immediately tell which timetable tool to use.

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 to get_my_timetable for the caller's own timetable and recommends student_id from find_student/get_my_students for unambiguous lookups. Also explains the multi-school search behavior and the subdomain restriction, which helps the agent decide when to supply subdomain.

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

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

No annotations are provided, so the description carries the full burden. It explicitly declares 'Read-only.' and thoroughly details return structure, edge cases (parent vs student/teacher, allowlist behavior), failed logins, and environment variable flags. This is transparent and goes beyond the basics.

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?

Although lengthy, the description is well-structured with clear sections (Purpose, Args, Returns, Notes) and front-loads the core purpose. Every sentence adds value, covering complex return semantics and usage notes without redundancy. The detail is justified given the tool's rich output.

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 no output schema, the description fully explains the return values and their nuances, including conditional behavior, environment variables, and integration with sibling tools. It covers all information an agent needs to correctly interpret results and decide next actions.

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?

The tool has zero parameters, so there is nothing for the description to clarify beyond the schema (which is trivially 100% covered). Per instructions, a baseline of 4 is appropriate when there are no parameters, and the description does not need to add parameter-specific meaning.

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: 'List the school subdomains available to the logged-in account and the server's session status per school, plus overall login state.' It specifies a distinct verb and resource, and differentiates from siblings by noting it replaces the former auth_status/user_id tools. This makes its purpose unambiguous.

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 explicitly tells when to use it ('Use this instead of the former auth_status / user_id tools') and provides actionable follow-up steps: passing discovered subdomains to login_all and handling two_factor_pending with two_factor_finish. This is clear contextual guidance that distinguishes it from alternatives.

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

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

With no annotations, the description carries the full burden and does so well. It declares 'Read-only,' describes the return shape with an example, notes that date_from only matters for history, and explains that missing categories yield empty lists. These are meaningful behavioral details beyond the raw schema.

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 well-organized into Args, Returns, and Notes. Each section adds necessary information: parameter semantics, return contract, and edge-case behavior. The mention of formerly separate tools is useful context, and the alternative get_day_summary is clearly highlighted.

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 tool with no output schema and no annotations, the description is complete enough for an agent to call it correctly: it defines all parameters, explains the return format, notes the read-only nature, and points to the more appropriate sibling for whole-day summaries. No critical information is missing.

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%, but the description fully compensates. It explains every parameter: category values with defaults and meanings, date_from format ('YYYY-MM-DD') and scope, and subdomain behavior including the default. This is more informative than an enum-based schema would be.

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 opens with a specific verb and resource: 'Get EduPage timeline notifications, filtered by category.' It also enumerates the distinct category values and explicitly references former tool names, making the tool's scope easy to distinguish from siblings like get_day_summary.

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?

It explicitly states when to prefer an alternative: 'For a whole-day report ... prefer get_day_summary — one call.' It also implies when this tool is appropriate by categorizing event types and noting that missing event types return empty lists, which helps an agent decide between timeline-specific queries and the summary endpoint.

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

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

With no annotations provided, the description carries the full burden. It clearly states 'Read-only', explains the two return shapes (single-day vs. range keyed by date), defaults for date_str, and the empty-lessons behavior for days without published data. It also notes that date_str is ignored when end_date is given, providing complete behavioral context.

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 well-structured with sections for Args, Returns, and Notes. It front-loads the purpose, then provides details in a scannable format. Despite length, every sentence adds value and avoids redundancy – an optimal structure for a complex multi-mode tool.

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?

Given the tool's complexity (5 parameters, two return shapes, sibling differentiations) and the absence of both annotations and output schema, the description covers all necessary aspects: parameter semantics, defaults, edge cases (empty lessons), and tool alternatives. Nothing an agent needs to correctly invoke and interpret the tool is missing.

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 0%, so the description must explain every parameter. It does: target_type enumerates allowed values, target_id links to get_roster, date_str specifies format and default plus interaction with end_date, end_date defines range behavior, and subdomain defaults to the active one. All five parameters are clearly defined beyond their schema names.

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 states a specific verb 'Get', a resource 'timetable', and enumerates valid target types (teacher, student, class, classroom). It precisely differentiates from siblings like get_my_timetable and get_student_timetable by naming them and their intended use cases.

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 explicitly instructs when to use alternatives: 'For the *logged-in user's own* timetable prefer `get_my_timetable`; for a student by name/id use `get_student_timetable`.' It also mentions `get_next_week_timetable` for a whole-week plan, leaving no ambiguity about tool selection.

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

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

With no annotations, the description carries the behavioral burden and it does disclose the key traits: read-only, empty list when nothing changed or school publishes none, and return shape. It does not detail errors/auth/rate limits or what 'serialized substitutions' looks like, but the core call behavior is transparent.

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 organized into clear Args/Returns/Notes sections, front-loads the core purpose, and every sentence adds information. It is compact despite covering defaults, return values, and sibling routing.

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?

There is no output schema, so the description supplies the return contract (dict with date, subdomain, changes, empty-list behavior), which is sufficient for invoking and interpreting the result. Combined with usage alternatives, the context is complete for selecting this tool correctly.

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 0%, so the description must carry parameter meaning; it fully does. date_str gets format YYYY-MM-DD and default today, and subdomain gets 'School to query' and default active subdomain, adding real semantics beyond the bare 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?

The first sentence names a specific verb+resource: 'Get substitution/timetable changes for a date' with a default of today and explicitly labels it read-only. The Notes section differentiates it from get_student_timetable/get_timetable, which are for one student's plan, so an agent can distinguish it from siblings.

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?

It gives explicit when-to-use context: pair with get_missing_teachers for the full substitution picture, and use get_student_timetable/get_timetable instead for a single student's daily plan. The read-only marker and date/subdomain defaults further clarify when it can be used.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses that login writes/replaces the server-side session, that EDUPAGE_SUBDOMAINS acts as a strict allowlist, that 2FA may be pending, and that environment-variable-based automatic login happens at startup.

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 long but organized into clear sections (Args, Returns, Notes), with the core purpose front-loaded. Some details about environment variable fallbacks could be considered extra, but they are directly relevant to correct invocation and the structure prevents confusion.

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?

Given the tool has five parameters, no annotations, and no output schema, the description covers all necessary context: parameter semantics, return values, side effects, related tool routing, and 2FA follow-up. Nothing an agent needs to call this correctly is missing.

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%, so the description must document parameters, and it does. Each parameter is explained with defaults, fallback environment variables, and method-specific requirements, including the special role of session_id and when subdomain is optional.

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 opens with a specific verb and resource: 'Log in to Edupage for a school' and clearly states the behavioral effect: 'establishes (or replaces) the server-side session for that subdomain.' It also distinguishes itself from the sibling login_all by noting that one call logs into one school while login_all handles several.

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 gives explicit when-to-use guidance through method options: 'credentials', 'auto', and 'session', each with conditions. It explicitly points to login_all when multiple schools are needed and mentions two_factor_finish for the 2FA continuation case, plus explains the EDUPAGE_SUBDOMAINS allowlist behavior.

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

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

With no annotations, the description takes on the full transparency burden and does well: it labels the call as 'Writes', says it establishes or replaces sessions, explains per-entry failure reporting, and documents the EDUPAGE_SUBDOMAINS allowlist refusal behavior. It does not cover all side effects (e.g., rate-limit implications or complete session-destruction semantics), but the key mutation and failure behavior is disclosed.

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 well organized with Args, Returns, and Notes sections; the most important facts (batch scope and session-write behavior) are front-loaded. Every included sentence adds value, and the bullet-style notes make the failure and 2FA behavior easy to parse.

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?

Given no output schema and no annotations, the description covers parameter fallbacks, return shape, per-entry errors, allowlist enforcement, and 2FA next step. It falls slightly short by not explaining the meaning of `active_subdomain` or how the returned `two_factor_required` field connects to `two_factor_finish` parameters, which a caller would need to fully complete the flow.

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 0%, so the description is the only source of parameter meaning. It explains comma-separated formats, per-school cardinality, and fallback to environment variables for every parameter. The only weakness is the ambiguous 'or a single one' phrasing, which does not fully define whether one username/password applies to all schools or only to a single-school call.

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 opens with 'Log in to one or more schools in a single call', which names the exact verb, resource, and batch scope. It further distinguishes itself from the sibling `login` by saying schools should be added one at a time with `login`, and it clarifies the side effect: establishing or replacing server-side sessions.

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?

It gives a clear alternative in Notes: 'Add schools one at a time with `login`' and instructs to finish 2FA with `two_factor_finish`, which tells the agent when the sibling tools are appropriate. It does not explicitly spell out 'use this for bulk login, use `login` for a single school', but the intended usage is strongly implied.

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

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

With no annotations, the description must disclose behavioral traits. It only states 'Writes:' and mentions the return dict, but it does not discuss side effects, whether ratings are overwritten, authentication requirements, error handling, or any constraints. This is minimal disclosure for a mutation tool.

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 concise, with a clear top line ('Rate a meal. Writes:...') and a structured Args/Returns layout. Every sentence provides needed information; there is no fluff or redundancy. It is well-organized and front-loaded.

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 simple write operation with no annotations and no output schema, the description covers all parameters and the success return, but it lacks details about error conditions, whether existing ratings are overwritten, or any required context like being logged in. These gaps could lead an agent to misuse the tool.

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?

The schema has zero descriptions (0% coverage), so the description fully compensates. It provides specific semantics for every parameter: date_str format (YYYY-MM-DD), meal_type enum ('snack' | 'lunch' | 'afternoon_snack'), quality and quantity ranges (1-5), and subdomain default (active subdomain). This adds essential meaning beyond the bare types in the 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?

The description clearly states the tool's purpose: 'Rate a meal. Writes: submits quality/quantity ratings for a date and meal type.' This is a specific verb (rate) and resource (meal), and it distinguishes itself from sibling tools like get_meals (retrieval), choose_meal (selection), and sign_off_meal (sign-off) by focusing on rating.

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: it is for rating a meal, but it does not explicitly state when to use it over alternatives or mention any prerequisites (e.g., must be logged in). It does not say 'Use this when you want to submit ratings' or exclude other meal-related operations, so guidance is only implied, not explicit.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses that the tool is read-only, uses cached data to avoid redundant API calls, and varies behavior by account type (parent versus student/teacher). It also documents the exact return format and the one-entry-per-student-per-school rule.

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 well-structured and front-loaded: the core purpose and scope appear first, followed by behavioral notes and return format. Every sentence earns its place, and the notes section cleanly separates alternative-tool guidance from cache behavior.

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?

Even though there is no output schema, the description provides the full return dict shapeeding, the 'total' key, per-account behavior, and cross-school duplication. It also covers cache semantics, configuration influence, and related tools, leaving no significant gap for an agent to call it correctly.

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?

The tool has zero parameters and 100% schema coverage, so the schema is complete by construction; the description is not required to explain parameter meaning. It still adds useful context around the output and scope, which is appropriate for a zero-parameter tool.

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 states a precise verb and resource ('Discover all students visible to the logged-in account') and defines the scope via the discovery configuration or all schools when unset. It also distinguishes the tool from get_my_students by explicitly mentioning the same view but restricted to the active subdomain.

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 names concrete alternatives and their appropriate conditions: get_my_students for the active subdomain only, and clear_student_cache to refresh the cached data. This gives an agent clear routing guidance without needing to inspect other tool schemas.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the write operation ('Writes'), the non-empty body constraint, and the exact return format ({'sent': True, 'timeline_id': <id>}). It does not mention potential error conditions or side effects beyond the core write, but for a simple send operation this is adequate. No contradiction with annotations exists (none present).

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 well-structured with a clear main sentence, an Args section, Returns, and Notes. Every sentence adds value: the main verb, parameter details, return format, and source guidance. No fluff or redundancy. The critical information (write behavior and parameter constraints) is front-loaded.

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 tool with no output schema and no annotations, the description covers all necessary context: what it does, parameter semantics, where to obtain recipient IDs, default behavior, and return format. There is no missing information an agent would need to invoke it correctly. The only minor gap is absence of error scenarios, but that is not critical for a simple send operation.

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?

The schema provides only type/title with no descriptions (0% coverage), so the description must fully compensate. It does: each parameter (recipient_id, body, subdomain) is explained, including the expected format for recipient_id and the default for subdomain. This goes well beyond the schema and gives an agent everything needed to construct valid arguments.

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 action: 'Send a message to a recipient' and specifies the resource and effect: 'Writes: posts a new message on the recipient's timeline.' This distinguishes it from read-oriented sibling tools (e.g., get_timeline, get_grades) and clearly conveys its write nature. The verb and object are specific and unambiguous.

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 provides practical guidance on sourcing recipient IDs via get_roster or get_my_students, and notes the subdomain default. It does not explicitly state when to avoid this tool, but given no competing messaging sibling exists, the context is clear enough. It could be slightly more explicit about when this tool is the appropriate choice, but it's not misleading.

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

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

With no annotations, the description carries the burden and it does disclose that this is a write operation that releases the booking, and that the result has ordered=False. It does not cover edge cases like already-cancelled meals or auth requirements, but the core mutating behavior is explicit.

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 tightly structured with a one-line purpose, args, and returns, and contains no filler. Every line adds necessary invocation or outcome information.

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 simple cancellation tool with no annotations or output schema, it provides sufficient invocation details and the return shape. Minor gaps, such as error behavior and whether cancellation can be repeated, keep it from being fully complete.

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 0%, yet the description documents every parameter: date_str format and meaning, the meal_type allowed values, and subdomain defaulting. This fully compensates for the schema's lack of descriptions.

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 opens with a specific verb and resource: 'Cancel an ordered meal for a date,' which immediately distinguishes it from meal selection/rating/listing siblings like choose_meal, rate_meal, and get_meals. The action and target are unambiguous.

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?

It clearly states the trigger: cancel a previously ordered meal on a specific date. It does not explicitly name sibling alternatives or exclusion conditions, but 'cancel an ordered meal' provides enough contextual guidance to select it over get_meals/choose_meal.

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

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

With no annotations provided, the description carries the full burden, and it does so well by disclosing the write-like side effect: 'changes which account subsequent tools operate as.' It also describes the return value shape, clarifying that switching back yields `{'switched_to_parent': True, 'user_id': ...}`. A small gap remains around error behavior when not in a parent-active session, but the core behavioral contract is clearly stated.

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 tightly structured with a one-sentence summary, a Writes note, an Args section, a Returns section, and a short Notes section. Every line earns its place, and the most important information about side effects and pairing is front-loaded.

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 simple one-parameter, no-output-schema tool, the description covers purpose, side effects, return type, parameter semantics, and the companion tool. An agent has enough information to call it correctly and know what will happen. No critical behavioral detail is missing.

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%, so the description must compensate, and it does. The only parameter, `subdomain`, is explained as 'School whose session to restore (defaults to the active)', adding meaningful semantics beyond the bare schema title 'Subdomain'. The default behavior is also clarified, which is valuable for a non-required parameter.

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 'Switch the session back to the parent account', identifying the exact verb and resource, and immediately qualifies it with '(parent accounts only)'. It is also distinct from the sibling `switch_to_student`, so an agent can tell which direction the session switch operates.

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 explicitly says to pair with `switch_to_student` and notes it is 'only relevant after a parent session was switched to a child.' This gives clear when-to-use guidance and implicitly warns against using it in other contexts, which is strong framing for the agent.

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

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

With no annotations, the description carries the full burden. It explicitly discloses the stateful side effect—'Writes: changes which account subsequent tools operate as'—and explains how to revert. This makes the mutation behavior clear to the agent.

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 tightly organized into Args, Returns, and Notes. The main purpose is front-loaded, and every section earns its place without redundancy or filler.

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?

The description covers purpose, parameters, return value, side effects, reversion, and a relevant alternative. The only notable gap is that, although student_id and name are described as alternatives, it never explicitly states that at least one is required—especially since the schema marks all parameters optional.

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%, but the description fully compensates: student_id is defined as the child's person_id from get_my_students, name is positioned as a fallback when student_id is omitted, and subdomain is documented with its default. All three parameters gain meaningful semantics.

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 opens with a direct verb and resource: 'Switch the session to a student account (parent accounts only).' It then clarifies the operative effect: subsequent tools act as that student. This clearly distinguishes the tool from siblings like switch_to_parent and get_student_timetable.

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?

It states the parent-only precondition and explicitly names the alternative for a common case: prefer the stateless get_student_timetable when only a timetable is needed. It also tells the agent how to undo the switch using switch_to_parent.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses that the tool writes by completing the pending flow, describes polling behavior when no code is given, explains the timeout, and notes the caller can call it again later. This goes well beyond a minimal description.

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 well-organized into purpose, arguments, and return value. The trigger condition is front-loaded, and every section earns its place without redundant filler.

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?

Despite having no output schema or annotations, the description covers success return fields, pending status, polling mechanics, and retry guidance. It provides all operational details needed to invoke this tool correctly.

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%, so the description must fully explain each parameter. It does: code's optionality and direct-use behavior, subdomain's default, and poll_seconds' timeout and retry semantics. This fully compensates for the bare 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?

The description opens with a specific verb and resource: 'Finish a pending 2FA login,' and clarifies it 'completes the pending auth flow.' This clearly distinguishes it from sibling tools like login by tying it to a prior two_factor_required response.

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 explicitly states the trigger condition: 'Only needed after a `login` that returned `two_factor_required: True`.' This gives an unambiguous when-to-use signal and prevents premature invocation.

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