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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered; the description adds that it books a menu for a date and documents the prerequisite read. It does not discuss reversibility or what happens on a repeat call (relevant given idempotentHint=true), so it is strong but not exhaustive.

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-loads the one-line purpose and write semantics, then uses tidy Args/Returns/Notes sections. No sentence is filler; each adds invocation-relevant detail.

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 Returns block supplies the response shape, and the Notes cover the key prerequisite and the cancel path. For a 4-param mutation tool with annotations already disclosing safety, nothing an agent needs to call it 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 carries the full burden, and it does: date_str format (YYYY-MM-DD), the enumerated meal_type values, the meaning of number (1-based choice among chooseable menus with a pointer to get_meals), and the subdomain default. Every parameter is explained 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?

States a specific verb and resource ('Order/choose a meal') and immediately clarifies the write semantics ('books the selected menu for the date'). It is clearly distinguishable from the sibling read tool get_meals and the cancel tool 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 Notes section gives explicit ordering guidance ('Read get_meals first for the date to pick a valid number') and names the alternative for the opposite action ('To cancel, use sign_off_meal'). Both when-to-use and alternative routing are covered.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds the concrete behavior: it drops the local cache so the next lookup re-fetches from EduPage. This explains the side effect precisely – a local, non-destructive mutation – which the annotations alone do not convey. Also documents the return shape.

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-loads the action and effect, then gives scope and the crucial default behavior, then return format. Every sentence adds necessary information without padding.

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?

Complete for a single-parameter mutation tool with no output schema. It covers the side effect, default scope, triggers, and return keys. Minor deduction because there is no output schema and the description still supplies the return shape, which is helpful but could be considered beyond strict necessity; however, nothing critical 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 carry the full parameter burden. It does: 'subdomain: School whose cache to clear. Without it, clears ALL schools.' This is essential because omitting subdomain triggers a global cache clear, a high-impact behavior not evident from the bare 'string/null' 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?

Uses a specific verb+resource ('Force refresh of cached student data') and clarifies it is a cache write, not a read. Distinguishes clearly from siblings like scan_students and find_student by naming them as stale-data indicators.

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 says when to call it – after students are added/removed, or if scan_students/find_student seems stale. No ambiguity about appropriate timing relative to the read tools.

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?

Annotations declare destructive/openWorld/write-capable, and the description reinforces rather than merely repeats them by disclosing the text-only constraint, the 60000-char cap being tool-imposed, the inability to page through truncated bodies (EduPage ignores Range), and that the caller must parse text themselves. These are non-obvious behaviors beyond the annotations.

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 purpose, then Args/Returns/Notes blocks — well-organized and mostly waste-free. It is long, and the opening 'treat as write-capable' line lightly overlaps the destructiveHint annotation, but the length is largely justified by the 0% schema coverage.

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?

No output schema exists, yet the description fully specifies the return dict (status_code, content_type, bytes, text, truncated) and the meaning of `text`/`bytes`, plus the truncation and binary limitations. Nothing an agent needs to call it 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 carry the burden — and it does: it documents url path resolution against the subdomain host, method values 'GET'/'POST', data as the POST body, headers as a JSON string with a concrete example, and subdomain defaulting to the active session.

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 explicitly distinguishes itself from the dedicated sibling tools ('prefer those when available'), which is exactly the differentiation an agent needs to choose this escape hatch over the ~30 named 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?

Gives explicit when-to-use (endpoints not covered by dedicated tools), when-not (binary bodies go to download_attachment, prefer dedicated tools), and what to do when truncated (narrow the request or use download_attachment). Alternatives and exclusion conditions are named, not inferred.

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?

Goes well beyond the annotations: discloses non-overwriting with a ' (1)', ' (2)' suffix, that bytes are written raw and unmodified, that bad/expired tokens return HTTP 404 while an unauthenticated school page returns HTTP 200 with a login page (and both raise rather than write), and the 5 s request-timeout ceiling. That is exactly the destructive/auth/failure context an agent cannot get from the readOnly/destructive/openWorld hints.

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 action and the write warning, then cleanly sectioned into Args/Returns/Notes. It is long and repeats itself somewhat (the 'any authenticated attachment, not just homework' point appears twice), but nearly every sentence carries operational 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?

Despite having no output schema, it lists the returned dict keys ({'saved_to','bytes','source_url','name'}) and covers defaults, filename derivation from content-disposition, error modes, and a timeout limitation. Nothing needed to invoke it 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 coverage is 0% (only titles, no descriptions), so the description carries the full burden and does so for all four parameters: `url` (absolute vs. school-relative path with the exact form `get_timeline` returns), `dest_dir` (default `<tempdir>/homework`, auto-created), `filename` (illegal characters stripped, always lands directly in `dest_dir`), and `subdomain` (defaults 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?

Specific verb + resource: 'Download one attachment from the school to disk. Writes: creates a local file.' It explicitly distinguishes itself from siblings by being the only tool that returns a binary attachment intact, noting that `custom_request` refuses one and pointing at `get_timeline`/`get_homework_material` as the sources of valid URLs.

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 a real gating rule ('the only tool in this server that writes to disk ... call it only on request') and clarifies that school/login pages are not valid input, which steers the agent away from misuse. It stops short of an explicit when-to-use-X-instead-of-Y routing statement, but the contrast with `custom_request` supplies most of that context.

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?

Beyond the annotations (which already declare read-only, idempotent, open-world), the description discloses cross-school search scope, the four-tier matching semantics, confidence-based sorting, and the anti-guessing ambiguity policy. This is rich behavioral context an agent cannot infer from structured fields.

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?

Purpose is front-loaded and the Args/Returns/Notes structure is easy to scan. Slightly verbose — 'Read-only' restates the annotation, and the sections add length — but nearly every line carries useful information, so waste is minimal.

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 still documents the return shape (results list with name, student_id, class_id, subdomain, tier, confidence) and tier definitions, plus downstream usage. Nothing needed to call it 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 coverage is 0%, so the description carries the full burden, and it does: name accepts first/last/full and short forms like 'Novák V.', and subdomain restricts to one school with default meaning all logged-in schools. Both parameters are fully explained beyond the bare schema types.

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 (look up), resource (student), and mechanism (tiered matching by first/last/full name). The scope statement about searching ALL logged-in schools without a subdomain further distinguishes it from siblings like get_my_students and 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?

The Notes section tells the agent to reuse a student_id from results with get_student_timetable/get_day_summary for unambiguous lookups, and explains that ambiguous matches surface all candidates. No explicit exclusion against alternative lookup tools, but context is clear.

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?

Annotations already carry readOnly/idempotent/non-destructive/openWorld, so the description adds meaningfully beyond them: it discloses that every section is isolated and a failure yields {"ok": false, "error": ...} without failing the whole report, that ambiguous names surface all candidates rather than guessing, and that full=True costs one section sweep per child. These are non-obvious behavioral traits well past what the annotations convey.

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 promise, then well-sectioned bullets. It is somewhat long, with the discovery-first logic restated in both the body and the args list, but given five undocumented parameters and a complex composite operation the length is largely earned.

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 complex composite tool with no output schema and 0% schema coverage, the description supplies parameter meaning, routing rules, partial-failure semantics, and cross-school scoping. No output schema exists so return-value detail is not owed, and nothing an agent needs to invoke it 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?

With 0% schema description coverage the description must carry the full burden, and it does: date_str format (YYYY-MM-DD, default today), name (first/last/full, ambiguity behavior, ignored when student_id is set), student_id (preferred person_id, cross-school unless scoped), subdomain (default active), and full (parent-only behavior and cost). All five parameters get semantics the bare schema 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?

States a specific verb and resource ('One-call daily school report for a date') and enumerates exactly what it aggregates (timetable, grades, meals, absences, events). It also distinguishes itself from siblings by explaining it composes the individual section tools like get_grades and get_meals, so an agent can tell it apart without opening any schema.

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 when-to-use framing ('what happened yesterday at school' / 'what's coming tomorrow') and the alternative it replaces ('you don't need to fire 8-10 calls'). It then spells out the conditional routing: name/student_id present → specific student; omitted → discovery-first index for parents; full=True for the full multi-child report; omitted as student/teacher → logged-in account.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so 'Read-only' is redundant. However the description adds genuine behavioral context beyond annotations: omitting year+term yields the current gradebook, and subdomain defaults to the active subdomain.

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?

Args/Returns/Notes sections are front-loaded with purpose first and every line conveys usable information. Minor redundancy in restating 'Read-only' that annotations already cover, but no padding overall.

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 supplies the return shape ({'subdomain', 'grades': [...] with subject, teacher, percent}), documents defaults, and cross-references get_school_year. An agent has everything needed to invoke and interpret the call.

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 carries the full burden and does: it explains `year` semantics with a concrete example (2025 for 2025/26), supplies the enum-like `term` values ('FIRST' or 'SECOND'), and documents `subdomain`'s default. Nothing about the three params is left ambiguous.

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 states a specific verb and resource scoped to the logged-in student ('Get grades for the logged-in student'), which cleanly separates it from the timetable, meal, and roster siblings. Scope (own grades, not arbitrary students) is 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 tells the agent the default behavior ('When both `year` and `term` are omitted returns the current gradebook') and routes to a sibling ('Use `get_school_year` to resolve the current school-year start'). There is no explicit when-not-to-use, but the selection logic is clear.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: invalid/expired ids yield an actionable error rather than a stack trace, and an enabled student upload area is rendered as a literal placeholder string. These are non-obvious traits not derivable from annotations.

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?

Well front-loaded with a one-line summary before the Args/Returns/Notes blocks, and every sentence earns its place. It is somewhat verbose with a fairly long Returns enumeration, but the structure aids scanning rather than padding.

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 compensates by spelling out the returned dict keys and the attachment shape ({'name','url'} with absolute URL). Combined with the discovery notes and error behavior, an agent has everything needed to call and use the result 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 carries the full burden and does so: `superid` is the material id sourced from `additional_data.superid` of a timeline notification, and `subdomain` selects the school session with an explicit default. Both parameters get meaning beyond their bare 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 opening line states a specific verb+resource+scope ('Full body text and attachment list of one homework/assignment material') and immediately distinguishes it from the timeline sibling by noting the timeline carries only a short summary. An agent can tell exactly what it retrieves without opening the schema.

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 the agent: discover ids via `get_timeline(category='homework')`, and prefer `get_day_summary` for a whole day of homework. It also names the downstream tool (`download_attachment`) that consumes the returned URLs, giving clear when/when-not 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?

Beyond the annotations (which already declare read-only/idempotent/non-destructive), the description adds meaningful behavior: all five slots are always returned with unpublished ones set to None, and it discloses the fallback path from the personal ordering endpoint to the public canteen widget. This is exactly the kind of context the annotations cannot convey.

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 single-sentence purpose, then cleanly separated Args/Returns/Notes sections. No filler; every line (including the None-for-unpublished detail) earns its place.

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 supplies the return shape ({date, subdomain, meals{...}}) and the note about the menu fields usable with downstream tools, so an agent knows both how to call it and what it gets back.

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 carries the full burden and does: date_str is documented as YYYY-MM-DD defaulting to today, and subdomain as defaulting to the active subdomain. Both parameters get format and default semantics absent from 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?

States a specific verb and resource ('Get the meal menu') plus the scoping dimension ('for a date'), and routes the agent to the downstream siblings that consume the result ('choose_meal' / 'sign_off_meal'). An agent can distinguish this read tool from the meal-mutation siblings without opening any schema.

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 positions the tool as the read entry-point whose output feeds choose_meal/sign_off_meal, giving implied usage context. However it never states an explicit when-not or prerequisite (e.g., that you must fetch meals before choosing), so it stops short of a full 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' in the description is largely redundant. It does add real behavioral context, though: the exact return dict shape and the empty-list edge case when no teacher is missing. No permission or auth details are given.

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 one-line summary followed by Args/Returns/Notes sections that map cleanly to what an agent needs. Section headers add mild length but no filler sentences; every line earns its place.

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 compensates by documenting the return dict keys and the empty-result case, plus defaults for both optional params. Only missing element is any note on permissions or error behavior, which is minor for a read-only lookup.

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 carries the full burden and does so well: date_str format 'YYYY-MM-DD' with default today, and subdomain defaulting to the active subdomain. Without this text the bare anyOf strings would be ambiguous.

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 ('Get teachers missing on a date'), with the default date behavior clarified. It is clear what the tool returns, though it doesn't differentiate itself from siblings beyond the pairing note with get_timetable_changes.

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?

Explains when this applies (default today, active subdomain) and explicitly points to get_timetable_changes for the full substitution picture. No when-not guidance, but the context is sufficiently clear for a simple read 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful non-obvious traits: results are served from cache, refreshed via clear_student_cache, and visibility varies by account type (school homepage parsing). It stops short of rate limits or pagination notes, but the caching and visibility disclosure is substantial.

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-loads the core purpose in the first sentence, then structures Args/Returns/Notes cleanly. The Returns block is justified because there is no output schema, though the section labels add some verbosity for a one-param 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?

With no output schema, the description supplies the return shape ({'subdomain', 'students': [...]}) and names downstream tools (switch_to_student, get_student_timetable) that consume the person_id. Visibility rules, caching lifecycle, and alternatives are all present, leaving nothing essential 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 carries the load for the single parameter. It documents 'subdomain: School to query' and its default ('defaults to the active subdomain'), which the schema's bare title/default does not explain. This is more than baseline for a 0%-coverage param.

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 the students visible to the logged-in account') and immediately scopes it by account type (parent vs student/teacher). It explicitly distinguishes itself from get_roster and scan_students, so an agent can route without opening any schema.

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?

Provides explicit when-to-use guidance: prefer get_my_students over get_roster to see *your* children/classmates, versus get_roster(roster_type='all_students') for the whole school. It also names the maintenance siblings (clear_student_cache, scan_students), covering the alternatives and their conditions.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description's 'Read-only' is redundant with those annotations, though it adds useful default behavior ('default today', 'defaults to the active subdomain') and a return structure. With annotations carrying the safety profile, the added behavioral context is modest.

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 action and then uses clear Args/Returns/Notes sections. It is appropriately sized for a tool with two optional parameters and three sibling alternatives, and every section carries useful 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?

The description supplies the return dict structure despite no output schema, documents both optional parameters, and routes to all relevant sibling tools. Combined with annotations covering safety and openness, an agent has everything needed to 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 compensate. It documents both parameters: date_str as YYYY-MM-DD defaulting to today, and subdomain as the school to query defaulting to the active subdomain. It covers format and default meaning but does not describe valid subdomain values or edge cases.

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 ('Get the timetable for the logged-in user on a date') and explicitly distinguishes the tool from its siblings by scope. An agent can identify exactly which timetable variant this is without opening the schema.

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 names alternatives and the conditions that select them: another student → get_student_timetable, teacher/class/room or date range → get_timetable, next week for yourself → get_next_week_timetable. Nothing is left to inference.

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?

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description's 'Read-only.' largely restates that. It does add non-redundant behavior: the search starts from the given datetime or now, the school defaults to the active subdomain, and the return payload is described. Missing handling for time zones/no-more-ringings keeps this from a 5.

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 purpose sentence is front-loaded, followed by tight Args/Returns/Notes blocks with no filler. Every line either documents a parameter, the return shape, or the sibling relationship.

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 supplies the return shape (serialized ringing with type and time), both parameter meanings and defaults, and a pointer to get_periods. It is essentially complete for a two-optional-param read tool, with only edge cases (no ringing after the given time, time-zone semantics) unaddressed.

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 carries the full burden and does so: date_time_str is documented as an ISO datetime searched onward from (default: now) and subdomain as the school to query (defaults to active subdomain). Both parameters gain meaning absent from the bare schema, though the ISO format variant/time-zone expectation is unspecified.

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 ('get the type and time of the next school-bell ringing') and enumerates the two return values (type: break/lesson, time). It also names the sibling get_periods as the source of the full schedule, so an agent can separate the two without opening either schema.

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 the agent to get_periods for the complete bell schedule, which implies this tool is for the single next ringing. That is clear contextual guidance, but there is no explicit when-not condition (e.g., what happens when no further ringing exists on the given date).

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by disclosing the exact return shape and the weekday key convention ('Po','Ut','St','Št','Pi'), which is non-obvious domain 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?

Front-loaded with the core purpose in the first sentence, then clearly separated Args/Returns/Notes sections. No filler; each block earns its place.

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 supplies the return dict structure, weekday format, and sibling routing, which is nearly everything an agent needs. Minor gaps remain (no error/permission behavior), but for a read-only single-param tool this is close to 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 description coverage is 0%, so the description must carry the parameter meaning. It explains that `subdomain` is the school to query and, importantly, that it defaults to the active subdomain — a default behavior the bare schema (default: null) does not convey.

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 with full scope: 'Get the Mon-Fri timetable for next week for the logged-in user, grouped by weekday.' It also implicitly distinguishes itself from the two timetable siblings that handle single-day and target/range queries.

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 the agent: use `get_my_timetable` for the logged-in user on a single day, and `get_timetable` with `end_date` for any target over a range. When-to-use and alternatives are fully spelled out.

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?

Annotations already declare readOnly, idempotent, and non-destructive, so the extra 'Read-only.' line repeats structured data. But the description adds genuine value beyond annotations by disclosing the return structure ({'periods': [{'starttime','endtime'}]}) and cross-tool composition. No behavioral gaps of consequence remain.

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 purpose sentence, then clearly delineated Args/Returns/Notes sections. Every line earns its place and there is no filler. Slightly more verbose than a single-line ideal but structurally clean.

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 appropriately documents the return shape, and with a single optional parameter it explains the default. An agent has enough to call and consume the result correctly; only minor gaps around alternative-tool selection remain.

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 does: 'subdomain: School to query (defaults to the active subdomain)' explains both the semantic (school selector) and the default behavior, which the schema only shows as default=null without explanation.

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 with clarifying scope: 'Get the bell schedule (periods with start/end times).' The parenthetical disambiguates it from timetable siblings. It names get_next_ringing_time as a companion but doesn't explicitly differentiate from other schedule tools like get_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?

The Notes section gives a useful composition hint ('Combine with get_next_ringing_time for live bell timing'), which implies intended usage. However, it does not state when to prefer this over alternatives like get_timetable, nor any when-not conditions. Usage is only 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return shape (a dict keyed by roster name) and how returned IDs are consumed downstream, which goes beyond the structured annotations.

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?

Well-structured with Args, Returns, and Notes sections, and front-loaded with the core purpose. The repeated 'formerly ...' annotations for each roster type add useful disambiguation but make the block slightly longer than strictly necessary.

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 a two-parameter tool with 0% schema description coverage, no output schema, and only basic annotations, the description is complete: it documents both parameters, specifies the return format, and points to related tools for adjacent operations.

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 carry parameter meaning, and it does. roster_type is fully documented with each allowed value and its exact meaning, and subdomain is explained with its default behavior.

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 (Get) and resource (school roster) and enumerates the exact roster types available. It also names the sibling tools it supersedes (formerly get_students, etc.), so an agent can distinguish it from related tools 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?

The Notes section explicitly routes the agent to alternatives: prefer get_my_students for students visible to the logged-in account, and use find_student for name lookup. It also explains how returned IDs feed get_timetable and switch_to_student, giving clear when-to-use context.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's 'Read-only' line is largely redundant. It does add the return shape ({'school_year': <int>, 'subdomain': ...}), which is genuinely useful since no output schema exists, but it says nothing about caching, staleness, or auth.

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?

Purpose is front-loaded in the first line, followed by clean Args/Returns sections. Slight redundancy in restating 'Read-only' from the annotations, but overall tight and well-organized.

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-parameter read tool with no output schema, the description supplies the return shape and the parameter default, which is everything an agent needs to call it and consume the result.

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 carries the burden, and it does: it explains subdomain means 'School to query' and that it 'defaults to the active subdomain'. That clarifies defaulting behavior the schema's bare null default does not.

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 ('Return the current school year (starting year)') and even disambiguates the value semantics by defining school year as the starting year. None of the sibling tools offer this, so an agent can route to it unambiguously.

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 implied by the getter nature and the note that subdomain 'defaults to the active subdomain', but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. Adequate minimum-viable coverage for a simple read.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds material context beyond that: multi-school search scope, one result per school for multi-school students, the query/matched_schools summary, parent child-resolution without session switching, and subdomain defaulting to all logged-in schools.

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 purpose and scoping caveat, and the Args/Returns/Notes structure aids scanning. It is on the long side and some notes restate preference for student_id already covered in Args, but each block still carries 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?

No output schema exists, and the description compensates by describing the return dict shape and the multi-school summary variant. With no required params, the zero-parameter case is handled by documenting optional-key defaults, leaving no gap for correct 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 carries the full burden — and it does: name formats, student_id as person_id with a cross-reference, date_str as YYYY-MM-DD with a today default, and subdomain semantics. Every parameter is disambiguated.

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 ('Get a student's timetable') plus the two lookup keys, and explicitly distinguishes itself from get_my_timetable and get_timetable by naming the alternative for one's own schedule. An agent can route correctly without opening the schema.

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 when-to-use rules: prefer student_id (unambiguous, sourced from find_student/get_my_students), use get_my_timetable for your own timetable, and explanatory behavior for parent logins. Alternatives and edge conditions are spelled out rather than 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: live-discovery via the profile page for parent accounts vs fallback for student/teacher/unauthenticated, the allowlist effect of EDUPAGE_SUBDOMAINS, and the semantics of failed_logins (blocked login attempts, pending 2FA). This is substantive disclosure, not a restatement of the annotations.

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 purpose and cleanly sectioned into Args/Returns/Notes, so it is easy to scan. However the Returns block is dense and somewhat over-explained (e.g. repeated allowlist caveats in both subdomains and schools), which is more than strictly necessary.

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 must document the return shape, and it does so thoroughly: subdomains, per-school session fields, active_subdomain, failed_logins, and env_*_set. Given the role-dependent branching behavior, this level of detail is exactly what an agent needs to interpret results 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?

Zero parameters means baseline 4. The description reinforces that no arguments are taken and explains that the result is determined entirely by active credentials and EDUPAGE_SUBDOMAINS, which is useful framing beyond the empty schema, but there is no parameter syntax to clarify.

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: 'List the school subdomains available to the logged-in account and the server's session status per school.' It explicitly enumerates what is returned (subdomains, session status, login state) and points back to the tools it supersedes ('Use this instead of the former auth_status / user_id tools'). An agent can distinguish it from the login/switch siblings without opening the schema.

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 names the alternatives and the conditions that select them: use login_all to connect to a discovered subdomain with no session, and use two_factor_finish when two_factor_pending is True. It also instructs replacement of the deprecated auth_status/user_id tools. When-to-use is explicit rather than inferred.

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?

Annotations already cover readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and the description redundantly restates 'Read-only'. The added value is real behavioral context: the return shape, the keying by category name, and the fact that a school not publishing an event type returns an empty list rather than erroring. It stops short of pagination or limit behavior, so a 4 rather than a 5.

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 one-line summary, then Args/Returns/Notes blocks that each earn their place. Length is justified by the seven category values, and no sentence is 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 no output schema, the description supplies the return shape and key, the empty-list edge case, per-category semantics, the date_from constraint, the subdomain default, and the sibling alternative. An agent has everything needed to call this 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 carries the full burden and does: it documents the full enumerated set of category values with defaults, specifies date_from's YYYY-MM-DD format and its conditional relevance, and states subdomain defaults to the active subdomain. Nothing in the schema is left unexplained.

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 EduPage timeline notifications, filtered by category') and immediately differentiates the scope from siblings by naming get_day_summary as the whole-day alternative. An agent can distinguish this from get_timetable, get_grades, and the category-specific former tools without opening any schema.

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 enumerates every category value with its meaning, marks 'recent' as the default, ties date_from to category='history' only, and gives a named alternative (get_day_summary) with the condition that selects it. When/when-not and alternatives are all present.

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?

Beyond the readOnly/idempotent annotations, the description discloses default behaviors (date_str defaults to today, subdomain defaults to active), precedence rules (date_str ignored when end_date is set), range semantics, and edge-case handling (days with no data return an empty lessons list). It also maps the tool to the former get_timetable_range.

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, then organized into Args/Returns/Notes sections with no wasted sentences. It is longer than strictly minimal (the Returns block restates shapes the caller could infer), but every part is informative and scannable.

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 compensates by documenting both return shapes and the empty-day case, and it covers all five parameters, defaults, and sibling routing. An agent has everything needed to call and interpret 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 carries the full burden and does: it enumerates target_type's allowed values, states target_id's provenance (as returned by get_roster), documents date_str's format/default and its precedence against end_date, explains end_date's inclusive range keying, and notes subdomain's 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 (Get) and resource (timetable) plus the exact target scope (teacher, student, class, classroom) and temporal scope (date or range). It is immediately distinguishable from siblings like get_my_timetable and get_student_timetable, which it names.

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 the agent: prefer get_my_timetable for the logged-in user, get_student_timetable for a student by name/id, and get_next_week_timetable for a whole-week plan. Conditions and alternatives are stated, not 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the leading 'Read-only.' mostly restates structured data. The description does add real behavior beyond annotations: the today/active-subdomain defaults and the fact that an empty list is the normal no-change signal, which prevents the agent from misreading an empty response as an error.

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 one-line summary followed by clean Args/Returns/Notes sections, with no wasted sentences. Minor redundancy between the summary's 'Read-only' and the annotations, but every block earns its place.

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 supplies the return shape ({'date','subdomain','changes': [...]}) and the empty-list case, plus the sibling routing an agent needs. Nothing required to call or interpret this tool 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 carries the full burden and does so: date_str is documented as YYYY-MM-DD with a today default, and subdomain as the school to query defaulting to the active subdomain. Both of the two params gain format and default semantics absent from 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 first sentence names a specific verb ('Get') and resource ('substitution/timetable changes') plus the scope ('for a date, default today'), and the Notes distinguish it from get_student_timetable / get_timetable. An agent can tell it apart from the other timetable siblings without opening any schema.

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?

Notes explicitly route the agent: pair with `get_missing_teachers` for the full picture, and use `get_student_timetable` / `get_timetable` for a single student's plan. Both the alternative and the condition that selects it are stated, leaving nothing to inference.

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?

Annotations only cover the safety profile (readOnly=false, idempotent=true). The description goes well beyond, disclosing that each call adds/replaces a subdomain's server-side session, that EDUPAGE_SUBDOMAINS acts as a strict allowlist with refusals, and that 2FA may need two_factor_finish to complete.

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 one-line purpose and write semantics, then cleanly sectioned into Args/Returns/Notes. Despite its length, every line conveys non-derivable information (env fallbacks, allowlist behavior, 2FA handoff) rather than restating the schema.

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?

Although there is no output schema, the description documents the return dict (logged_in, subdomain, user_id, role, 2FA-pending) and the follow-up tool for 2FA. For an auth tool with five optional params and no required fields, this is complete enough to invoke 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?

With 0% schema description coverage the description must carry the full burden, and it does: all five params are documented, including env-var fallbacks for username/password/subdomain and the required session_id value when method='session'. The method enum values are fully explained even though the schema declares no enum.

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 ("Log in to Edupage for a school") and immediately scopes the side effect ("establishes (or replaces) the server-side session for that subdomain"). It clearly differentiates from the sibling login_all by noting that tool handles multiple schools in one call.

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 enumerates the three mutually exclusive authentication strategies ('credentials', 'auto', 'session') with the condition that selects each, and names login_all as the alternative for multi-school login. It also advises preferring EDUPAGE_USERNAME/EDUPAGE_PASSWORD for auto-login at startup.

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?

Annotations already cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), yet the description adds real behavioral context beyond them: it discloses that sessions are established OR REPLACED per subdomain, that EDUPAGE_SUBDOMAINS acts as a strict allowlist with per-entry refusal, and that failures are reported per-entry rather than aborting the call.

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 a one-sentence purpose, then organized into Args/Returns/Notes sections where each block is functional. It is somewhat long, but the length is driven by needed fallback and failure semantics rather than padding.

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 supplies the return shape ({'results': [{subdomain, ok, user_id, role, two_factor_required}], 'active_subdomain': ...}) plus per-entry error handling, allowlist behavior, and required follow-up calls. Nothing an agent needs in order to invoke or interpret this 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 description coverage is 0%, so the description carries the full burden and does so thoroughly: it documents the comma-separated format for all three params, the positional alignment rule ('one per school (or a single one)'), and the environment-variable fallback for each (EDUPAGE_SUBDOMAINS/USERNAME/PASSWORD).

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 ('Log in to one or more schools in a single call') and immediately declares the write nature of the operation. The batch/multi-school scope is explicit, which is what separates it from the single-school sibling `login`.

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 route the agent to the right alternatives: `login` for adding schools one at a time and `two_factor_finish` for completing pending 2FA. However, it never states the inverse condition explicitly (e.g. 'prefer login when only one school is needed'), so the routing is implied rather than fully spelled out.

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?

Annotations already declare the write/destructive/idempotent nature, and the description adds the return format and parameter details. However, it does not elaborate on what 'destructive' means (e.g., overwriting an existing rating) or confirm idempotency, so it adds only modest context beyond annotations.

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 a clear summary and then structured into Args and Returns sections. It is appropriately sized for a 5-parameter tool with no schema descriptions, though 'Writes:' is slightly redundant with 'Rate a meal'.

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, the description provides the return shape, and it documents all parameters thoroughly. It could mention overwrite behavior or permissions, but with annotations covering safety and a clear action, it is largely 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 description coverage is 0%, so the description carries the full burden. It defines all five parameters with format and meaning: date_str as YYYY-MM-DD, meal_type with enumerated values, quality and quantity as 1-5 scales, and subdomain defaulting to the active subdomain. This is thorough.

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: 'Rate a meal' and clarifies it writes quality/quantity ratings for a date and meal type. It does not explicitly differentiate from sibling tools like choose_meal or sign_off_meal, but the purpose is clear.

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?

There is no guidance on when to use this tool versus alternatives such as get_meals, choose_meal, or sign_off_meal. The description only implies usage through the name and action, leaving the agent to infer.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered structurally. The description adds real value beyond them: it uses cached data to avoid redundant API calls, and it clarifies the return shape and how results differ for parent vs student/teacher accounts (one entry per student per school).

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 purpose, then structured Args/Returns/Notes sections; every block earns its place. It is slightly longer than strictly necessary given the Notes section repeats the sibling relationship, but there is 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?

With no output schema, the description carries the return-format burden and does so explicitly (dict with students list of name/student_id/class_id/subdomain and a total). Scope, caching behavior, and account-dependent return semantics are all covered, so 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?

The tool takes zero parameters, and the description goes beyond the empty schema by explaining WHY there are no args — scope comes from EDUPAGE_SUBDOMAINS and login role, both environment/login state rather than per-call input. That is exactly the justification an agent needs to avoid hunting for nonexistent inputs.

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 (discover/scan) and resource (students), plus the precise scope: all students visible across the configured EDUPAGE_SUBDOMAINS discovery scope. It explicitly differentiates from the sibling get_my_students by noting that tool returns only the active subdomain, so an agent can distinguish the two 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?

Gives clear usage context: read-only, scope fixed by environment/role, and names the alternatives get_my_students (same view for active subdomain) and clear_student_cache (refreshes). It does not spell out an explicit when-not-use rule, but the contrast with get_my_students effectively signals the selection condition.

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the destination of the write (recipient's timeline) and the non-empty body constraint, but says nothing about irreversibility, visibility to the recipient, or rate limits for a destructive write.

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-loads the action and its side effect, then uses tidy Args/Returns/Notes sections where each line carries information. Slightly verbose in structure, but no sentence 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?

With only three parameters, no output schema, and no enums, the description covers what an agent needs: all three arguments, the return shape ({'sent': True, 'timeline_id': <id>}), and where ids originate. Only the absence of failure/error behavior keeps 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 description coverage is 0%, so the description must compensate, and it largely does: it gives the recipient_id format and concrete examples ('Student123'/'Teacher456') plus its source tool, states body must not be empty, and explains that subdomain defaults 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?

States a specific verb+resource ("Send a message to a recipient") and immediately clarifies the effect: it posts onto the recipient's timeline. This cleanly separates it from read-oriented siblings like get_timeline and get_roster, so an agent knows it is a write tool without opening the schema.

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 only implied: the Notes tell the agent where recipient ids come from (get_roster, get_my_students), which is a useful precondition, but there is no explicit statement of when to use this tool versus alternatives or when not to use it.

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?

Annotations already declare the write/destructive/idempotent/openWorld profile, so the bar is lower, and the description adds real context by stating "Writes: releases the booking" and showing the returned state {'ordered': False}. It does not mention permission/auth requirements or what happens if no booking exists, so it stops short of full disclosure.

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 action and write semantics, followed by compact Args/Returns blocks; every line is informational. The fragment "Writes: releases the booking" is slightly telegraphic, but 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?

With no output schema, the description helpfully specifies the return dict, and it documents all three parameters. The gaps are error/edge-case behavior (meal not ordered, invalid date, permission failure) rather than anything needed 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 schema exposes meal_type as an unconstrained string, so the description carries the full burden — and does: it supplies the YYYY-MM-DD format, the exact allowed meal_type values ('snack'|'lunch'|'afternoon_snack'), and the subdomain default behavior. This is essential information present nowhere else.

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 gives a specific verb ("Cancel") and resource ("an ordered meal"), scoped by date, which disambiguates the otherwise opaque name sign_off_meal. This reads clearly as the inverse of the sibling choose_meal, so an agent can route without opening a schema.

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 implied: you cancel a meal that was previously ordered for a given date. However, there is no explicit when/when-not guidance, no statement of prerequisites (e.g., a booking must already exist), and no named alternative such as 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?

Annotations already declare readOnly=false and idempotent=true, but the description adds meaningful context beyond them: the write's actual effect ('changes which account subsequent tools operate as') and the return payload. It doesn't cover failure modes (e.g., calling when not switched), which keeps it short of a 5.

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?

Well-structured with labeled sections (purpose, Writes, Args, Returns, Notes) and the core purpose front-loaded. Slightly longer than strictly necessary, but each section adds usable 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?

There is no output schema, so the 'Returns' section is genuinely useful. The description covers the write effect, the sibling relationship, the argument, and the return shape. Only error/precondition-failure behavior is left unspecified.

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 carry the param. It explains the single 'subdomain' arg as 'School whose session to restore' and its default behavior ('defaults to the active'), matching the null default. Clear and sufficient for one 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?

States a specific verb and resource ('Switch the session back to the parent account') with a clear scope qualifier ('parent accounts only'). An agent can distinguish it from switch_to_student without opening either schema.

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 names the paired alternative ('Pair with `switch_to_student`') and the precondition that selects it ('only relevant after a parent session was switched to a child'). The 'parent accounts only' qualifier also acts as an exclusion, leaving little to inference.

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?

Description discloses the key behavioral trait — this is a stateful write that changes which account subsequent tools operate as — plus the revert path. It also explains the student_id vs name fallback and the subdomain default. Annotations (idempotentHint=true, destructiveHint=false) already cover safety, so remaining gaps are minor.

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 purpose in the first clause, then Args/Returns/Notes sections. Slightly verbose with the Returns dict, but the structure is clear and every section earns its place for a stateful 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 no output schema, the description supplies the return shape, the stateful side effect, the sibling alternatives, the revert path, and parameter fallback logic. An agent has everything needed to call this correctly without opening other tools' docs.

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 the load — and it does, explaining student_id (person_id from get_my_students), name as fallback when student_id is omitted, and subdomain defaulting to the active subdomain. Uses of name (first/last/full) are clarified as the child's name, though the accepted string format isn't fully pinned down.

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 action (switch session to a student account) with the precondition (parent accounts only). Distinguishes itself from siblings like get_student_timetable and switch_to_parent by clarifying it changes the operating account context for subsequent 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?

Explicitly says when to use it (parent accounts switching to a child) and when not to (prefer stateless get_student_timetable for timetable-only needs), and names switch_to_parent as the revert. This is exactly the routing guidance an agent needs.

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?

Goes beyond the annotations by disclosing the pending-auth completion semantics, the code-vs-poll branching, the poll timeout fallback ('the caller can call `two_factor_finish` again later'), and the concrete success return shape. The write/idempotent profile in annotations is consistent with, and supplemented by, this detail.

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 action and precondition, then organized into Args/Returns sections, so it is easy to scan. Slight redundancy between the title sentence and 'Writes: completes the pending auth flow' keeps it short of maximal conciseness.

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 3-param auth tool with no output schema and sparse annotations, the description supplies the precondition, per-parameter semantics, branching logic, timeout handling, and an explicit return contract. Nothing an agent needs to call it 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?

With 0% schema description coverage, the description carries the full burden and does: `code` is explained as a directly-used verification code that switches behavior, `subdomain` defaults to the active subdomain, and `poll_seconds` defaults to 60 and only matters when `code` is absent. Every parameter's meaning and interaction is covered.

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 ('Finish a pending 2FA login') and immediately clarifies the write nature of the operation. It is clearly distinguishable from the sibling `login` tool by its focus on the post-login confirmation step.

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 states the triggering condition: 'Only needed after a `login` that returned `two_factor_required: True`.' It also explains the fallback path when no code is supplied and that the tool may be re-invoked after a poll timeout, covering when and how to use it.

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