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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile needs no restatement. The description adds that results are aggregates ('counts') combined with full per-entry detail including date, lesson and remark, plus active measures such as detention — useful return-shape context, though nothing on latency, permissions or volume.

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?

A single dense sentence that front-loads the resource scope and then the contents; every clause carries information. The em-dash enumeration is long but readable and free of 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 usefully itemizes what comes back (counts, per-entry date/lesson/remark, active measures), which is what an agent needs to decide if this answers the question. The leerlingId requirement when multiple children are linked is covered by the schema, not the description, which is acceptable but leaves a small gap.

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 100%, so the schema already documents both parameters and the periode enum values. The phrase 'school year (or current grading period)' loosely glosses the periode choice but adds no syntax or default beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource scope (absence and registration records) and enumerates the record types returned: unexcused/excused absence, late, removed from class, homework not done, materials missing, plus active measures. That is enough to tell it apart from siblings like homework or grades, though the head is a noun phrase with no explicit retrieve verb.

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 tool is framed as the source of attendance/registration data for a school year or grading period, which hints at when to call it. There is no explicit when-not-to-use guidance and no named alternative (e.g. homework for assignments vs. absence for missed homework).

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, covering the safety and side-effect profile. The description adds useful context that these are platform-originated announcements with a publication window, but it does not describe return format, ordering, or pagination behavior. With annotations carrying the safety profile, this is adequate but not rich.

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?

Two sentences, front-loaded with the resource identity and immediately followed by sibling routing. Every clause earns its place and there is no repetition of annotation or schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only list tool with no output schema, the description supplies enough context to call it correctly and understand what it returns conceptually (platform announcements with publication windows). It does not specify exact response fields or ordering, which is a minor gap in the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly does not invent parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and scope: Somtoday-wide platform announcements (landelijke mededelingen), such as maintenance notices, including their publication window. It also explicitly distinguishes this from school news and personal messages, so an agent can identify the 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?

It gives explicit routing guidance by naming the alternatives: use `news` for school news and `messages` for personal messages. The when-to-use condition is clear and the exclusions are directly stated.

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 read-only, idempotent, non-destructive behavior, so the description's job is to add context. It does so usefully by disclosing what is returned and, importantly, that submitted files and teacher reactions are not returned because they are only visible to the student in Somtoday.

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?

Two dense sentences with the core scope front-loaded and the return/exclusion details following. No wasted framing and no repetition of schema or annotation fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with full schema descriptions, full annotations, and no output schema, the definition is complete: it explains the resource, the returned content, and the important visibility limitation. Nothing an agent needs in order 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 100%, and the schema documents both `toekenningId` and `leerlingId`, including the multi-child requirement for `leerlingId`. The description adds no parameter-specific meaning beyond that baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies a single hand-in assignment as the resource and enumerates what the detail contains (instruction text, learning goals, files, links, window, status, late flag, group). The word 'One' implicitly distinguishes it from the sibling `assignments` list, but no sibling is named explicitly.

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: this is the detail view for one assignment, likely after obtaining a `toekenningId` from `assignments`. The description does not explicitly state when to use it instead of `assignments`, `homework`, or `study_material`, and it provides no prerequisite guidance beyond the schema.

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 and idempotent, but the description adds substantial behavior: exact Dutch status meanings, teLaat is true only for an open past-deadline item, default hiding of inleveringenVerwacht 0 with count in verborgenZonderInlevering, and duplicate merging with duplicaatToekenningIds. It also clarifies that empty attachments means nothing was attached and that lesmateriaal is only a flag, not a separate material 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?

The description is dense but front-loaded: the resource and returned fields come first, then usage options. It is somewhat run-on and packs multiple behavioral details into a single paragraph, but each clause carries operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and four optional parameters, the description is complete enough for correct invocation: it explains returned status values, attachment handling, duplicate merging, hidden-item counting, and the handoff to assignment_detail.

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 100%, so baseline is 3. The description adds useful meaning beyond the schema, particularly around status=open behavior, includeNoHandIn, and dedupe semantics with duplicaatToekenningIds; it does not explain leerlingId, which the schema already documents.

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 resource ('All hand-in assignments') and enumerates the returned fields (window, status, teLaat, description, attachments, links). It also distinguishes itself from assignment_detail by telling the agent to use toekenningId with that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit behavioral choices: status=open vs default, includeNoHandIn=true to keep past-due no-digital-hand-in items, dedupe=false to list near-duplicates separately. It also names the routing condition to assignment_detail.

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?

The description says check=true renews the token, which is a state-changing operation, while annotations declare readOnlyHint=true. This is a direct contradiction because token renewal can write updated credentials to the keychain or file. The useful disclosure that tokens are never returned does not resolve that conflict.

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?

Two tight sentences front-load the status content and then explain the optional renewal behavior. There is little waste, and the parenthetical storage locations are useful.

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 covers the main return content: whether a session exists, where it is stored, and the last renewal outcome. It does not specify the default value of check or error/no-session edge cases, but it is mostly complete for a one-parameter status tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the check parameter is already documented in the schema. The description repeats the renewal and API-call behavior without adding format, default-value, or side-effect details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and scope: Somtoday session storage status, storage location, and last token renewal outcome. It is concrete enough that an agent can distinguish it from identity or data-fetching siblings such as whoami.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a condition for the check parameter, but does not explain when to use auth_status instead of siblings like whoami, nor when not to use it. Usage is implied rather than explicitly routed.

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 behavior. The description adds real value by enumerating the shape of the returned data (profile, school, placement, portal sections), which matters because there is no output schema. It does not mention auth requirements or empty-result behavior, keeping it below 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?

One sentence of content plus one routing sentence, with the return contents front-loaded and the sibling pointer last. No filler, though the first sentence is a dense run-on of field lists.

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 burden of explaining return values, and it does so by listing the categories of data returned. Combined with annotation coverage of the safety profile, an agent has enough to call and interpret it; only edge-case behavior (empty lists, permissions) 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies the call is unfiltered for the authenticated context.

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?

Names the resource (linked children) and enumerates precisely what it carries: profile fields, school data, current placement, and visible portal sections. An agent can distinguish it from 'whoami' without opening either schema, though the description lacks a leading verb such as 'Retrieve'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to the alternative: 'Use whoami when you only need leerling ids.' That is clear decision guidance. It does not state broader exclusions (e.g. when a parent context is unavailable), so it falls short of full when/when-not coverage.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful nuance that answers are recorded in the portal and cannot be changed here, but it does not describe return structure, ordering, or what an empty response means.

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?

Two short sentences, front-loaded with the resource name and parenthetical translation, followed by the read-only constraint. 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?

For a zero-parameter read-only tool with no output schema, the description does enough: it explains what a consent item is, gives an example, and states the constraint on mutation. It could say more about the shape of the returned consent list, but nothing critical to calling 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?

There are no parameters, so the baseline is 4. The description correctly says nothing about inputs, matching the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (consents set in the portal) and clarifies each item carries a recorded answer, with an example ('use of photos'). It does not explicitly distinguish itself from nearby siblings such as signing_requests or signing_document, so it falls short of a 5.

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 tool clearly serves to retrieve consent answers, and 'answers cannot be changed here' hints that changes happen elsewhere. However, it names no alternative tool or portal workflow, and gives no explicit when-to-use or when-not-to-use 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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds real value beyond them: host restriction, size cap, and the return-shape rule (extracted text for PDF/text/HTML/CSV/JSON, metadata otherwise), which matters since no output schema exists. Error behavior (rejected host, oversized file) is not described.

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?

Two densely packed sentences with no filler; the source-of-URL scoping and the hard constraints are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description covers what it accepts, what it will refuse, and what it returns. Only failure/error semantics are left implicit.

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 100% and the single parameter has its own description that nearly duplicates the parenthetical in the tool description. The description adds no format or syntax detail beyond what the schema provides, so baseline 3 applies.

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?

Opens with a specific verb and resource ('Read an attachment') and names the exact source of the URL (homework, assignments, study material, messages). No sibling tool fetches files, so differentiation is implicit rather than stated, which keeps it just short of a 5.

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 concrete preconditions for use: only https Somtoday file hosts and a 10 MB maximum. It does not name an alternative tool or explain when not to call it, but no competing tool exists in the sibling set.

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, openWorld, non-destructive, so the safety profile is covered. The description adds the one behavior beyond the schema: it reports when the child has no exam dossier yet, which tells the agent how to interpret a sparse result rather than assuming missing data. The required leerlingId condition for multiple children is documented in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph, front-loaded with the dossier scope and its contents, then the usage routing. It is compact and every clause earns its place, though the parenthetical jargon (PTA/SE) and packed list of returned items make it a touch dense to parse in one read.

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 does the work of explaining what comes back: per-subject averages, individual results, upcoming tests, and test-type averages. The only gap is that it does not mention result shape or ordering, but for a read-only overview that is minor.

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 100%, so both parameters (examenjaar defaulting to latest, leerlingId required with multiple children) are fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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 resource (school-exam dossier, PTA/SE) and enumerates exactly what it returns: per-subject SE average, all SE results, upcoming tests, and test-type averages. This is clearly distinguishable from the sibling grades_latest, which it names and contrasts.

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 to use this for exam-year progress and upcoming SE tests, and names the alternative (grades_latest with dossier=examen) with the condition that selects it (only the newest SE results). Both a when-to-use and a when-to-use-something-else are given.

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 openWorld, so safety is covered. The description adds a real behavioral trait beyond that: results are truncated at 30 and are limited to the newest progress-dossier entries, which tells the agent to expect partial data. It stops short of saying whether the averages are computed over the capped set or the full set.

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?

One front-loaded sentence establishes what it returns, then a single routing sentence covers all four alternatives. No filler, no repetition of the tool name as content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must describe the return value — and it does, naming both the capped result list and the per-subject averages. The only remaining ambiguity is the statistical scope of those averages, which is a minor gap for a summary tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single leerlingId parameter is documented there, including the multi-child requirement. The description adds nothing about the parameter, so this sits at the baseline the schema coverage earns.

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 ('Quick grade summary') plus the exact content returned: newest progress-dossier results capped at 30 and per-subject averages. The limits ('capped at 30', 'per subject') let an agent distinguish it from the four named sibling grade 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 routes to alternatives with the condition that selects each: grades_latest for more or exam results, grades_overview for a full school year, subject_grades for one subject in depth, exam_grades for the PTA/SE dossier. Both when-to-use and when-to-use-something-else are stated.

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 read-only/idempotent safety, so the description correctly spends its words on behavior instead: default 50 / max 1000, paged results, the dossier=examen variant, and that a next publication moment may be included. It stops short of describing ordering ties, page-token mechanics, or what an empty result looks like.

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?

Three dense sentences with no filler, but the most decision-relevant sentence ('Use this for...') is placed last, and the opening field enumeration delays the purpose. Slight reordering would make it stronger.

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 field list (subject, column, grade, weight, test type, period, date, remarks, resit) does necessary work, and paging plus sibling routing round it out. Missing only the multi-child leerlingId caveat and error/empty-case behavior.

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 already 100%, yet the description still adds meaning the schema lacks: dossier=examen maps to school-exam (SE) results, and paging behavior for limit. It does not mention leerlingId at all, relying on the schema for the multi-child requirement.

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 establishes the resource and ordering ('Newest results first') and enumerates the returned fields, and a later sentence explicitly contrasts it with grades and subject_grades. It's clear enough to pick without opening the schema, but the core purpose statement is buried in a field list rather than stated up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: 'Use this for "what grades came in recently"' with two named alternatives and the condition that selects each ('short summary with averages' vs 'all columns of one subject'). 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 declare readOnly/idempotent/non-destructive, and the description adds real context: the default fallback to the current placement and the fact that it returns historical years. It doesn't discuss response size, ordering, or pagination for a potentially large whole-year payload, which is the main remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: payload first, default/override second, routing to alternatives last. No redundant restatement of the tool name and 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?

No output schema, but the description compensates by listing exactly what the result contains (subjects, per-period results, report grades, weights, remarks). Combined with the routing guidance and the documented default, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the default-current-placement behavior and the concrete '2025/2026' format for schooljaar. leerlingId's conditional requirement is only in the schema, not repeated in prose, keeping it just short of a 5.

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 concrete verb+resource (full grade overview per school year) and enumerates the payload: every subject, results per period, report grades, weights, remarks. It explicitly names sibling tools (subject_grades, grades_latest) and the scope each covers, so an agent can differentiate 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 explicit when-to-use ('whole-year report view or earlier years') and when-to-use-else ('subject_grades for one subject, grades_latest for recent results'). The schooljaar parameter's alternate-year behavior is also framed as a usage cue.

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 this as a read-only, idempotent, non-destructive, open-world call. The description adds useful behavioral detail beyond that: grouping by day, default range of today plus 6 days, a maximum of 42 days, and attachment behavior including empty bijlagen/externeMaterialen and the lesmateriaal flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then layers in return fields, date limits, and attachment behavior. It is dense but mostly earns its length; the closing clause about there being 'no separate material call' is the least clear and slightly muddies an otherwise efficient structure.

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 complex, multi-field read tool with no output schema, the description does a good job explaining what is returned and how attachments and deadlines are represented. It is not fully complete because it omits explicit sibling routing and contains a potentially misleading statement about material calls, but it covers the essential behavior an agent needs.

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 100%, so the schema already documents all four parameters. The description adds meaningful semantics for the date parameters by stating the default range and the 42-day maximum, though it does not add anything about leerlingId beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the resource and scope: every studiewijzer item for a date range, grouped by day, including hand-in deadlines. It is specific about the returned fields, but it does not explicitly differentiate itself from sibling tools such as assignments or study_material.

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 phrase 'What to do and learn on which day' and by the default date range, but there is no explicit statement of when to use this tool instead of assignments, assignment_detail, or study_material. The note about download_attachment and the claim that 'there is no separate material call' gives some routing guidance, though the latter is potentially confusing given the study_material sibling.

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, open-world access, so the safety profile is covered. The description adds value annotations cannot: it explains what the returned lesson fields mean (ROOSTERTOETS/EXAMEN marks a test, uitgevallen=true means cancelled) and explicitly delineates what is excluded from the response. No auth or rate-limit context, but little more is needed for a read.

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?

Three tight sentences with no filler: scope first, then field semantics, then the exclusion/redirect. Every sentence carries information an agent needs.

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 two optional params, full schema coverage, and no output schema, the description carries the return-value burden and does so partially – it explains lesson type and cancellation but not the overall response shape (e.g. holiday field placement, ordering). Adequate 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 coverage is 100% – the date default (tomorrow), the ISO pattern, and the leerlingId requirement when multiple children are linked are all documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, so baseline 3 applies.

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 resource and scope: the timetable for exactly one Amsterdam date, plus a holiday flag. It also pre-empts confusion with the homework tool. It does not, however, distinguish itself from the sibling `schedule` tool, which an agent could plausibly pick instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent away from this tool for homework and test topics: "call homework for the same date." Clear usage context, but no statement of when this tool (versus `schedule`) is the right choice, and no prerequisites mentioned.

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, but the description adds a genuinely useful guarantee not in annotations: 'Never marks anything as read', which is the key worry for a read of unread messages. It also states ordering ('newest conversations') and what the thread view contains. It stops short of pagination or auth behavior, so not 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?

Dense but front-loaded: the read-only purpose and returned fields come first, then filters, then thread mode, then sibling routing. Every clause carries information, though the final sentence is long enough that parallel structure would aid scanning.

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 listing both the list-view fields and the thread-view contents (text, sender, recipients, attachments). With zero required parameters and all filters explained, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description still adds meaning by clarifying that zoek/ongelezen are filters over the listing and that conversatieId comes 'from a previous messages call' and switches to full-thread mode, which is a workflow detail the schema alone doesn't 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 the specific verb and resource ('Somtoday messages (berichten), read-only') and enumerates the returned fields (subject, sender, date, unread flag, preview), plus the thread-expansion mode. It explicitly differentiates from siblings news and announcements, so an agent can pick it 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 routing: use this for personal messages from teachers/school, school-wide news goes to news, Somtoday-wide notices to announcements. It also tells the agent how to escalate from list to thread ('Pass conversatieId for the full thread') and how to filter (zoek, ongelezen).

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 tool is read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context beyond annotations: ordering (newest first), return format (text), and inclusion of an unread count. It does not cover pagination behavior, but the limit parameter and annotations make this a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with scope and return behavior, followed immediately by sibling differentiation. Every phrase 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?

For a simple read-only list tool with one optional parameter, no output schema, and strong annotation coverage, the description provides everything needed: what is returned, ordering, audience, and which sibling tools to use instead.

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 sole parameter, limit, is fully described in the schema with its default and constraints. The description adds no additional meaning about the parameter, but with 100% schema coverage the baseline score of 3 is appropriate.

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 specifies the exact resource: news items published by the school to all parents, ordered newest first, returned as text with an unread count. It also distinguishes this tool from sibling tools like messages and announcements by scope and audience.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes the agent away from this tool for personal conversations (use messages) and platform-wide notices (use announcements). This gives clear when-to-use-this versus when-to-use-alternatives 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?

"Read-only; nothing is booked" adds real value beyond the annotations: in a parent-evening domain an agent might reasonably assume slot booking, and this explicitly forecloses it. The annotations already cover readOnly/destructive/idempotent, so the description is correctly focused on the non-obvious consequence rather than restating them.

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?

Three short sentences, front-loaded with the resource and its contents, then the id-omission rule, then the safety note. Nothing is padding; every clause carries information an agent needs.

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 one optional parameter, full schema coverage, rich annotations, and no output schema, the description covers both lookup modes and the no-side-effect guarantee. It doesn't hint at what the response shape looks like in the message-search case, which is the only remaining gap.

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 100% and the single id parameter is already documented in the schema with the same omit-to-search behavior. The description restates that behavior without adding format or example detail, so it hits the baseline rather than exceeding it.

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?

It names a specific resource (parent evening / ouderavond) and enumerates what it exposes: invitation, time slots and chosen teachers. It's clear enough that an agent can tell it apart from the sibling list, since no other sibling covers parent evenings, though the verb is implied rather than stated ("details").

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?

"Without id, finds invitations linked in your messages" gives an explicit routing rule between the two invocation modes, with the schema-backed id path as the alternative. It stops short of naming other tools or stating when not to call it, but the mode selection is unambiguous.

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 value on top: the 42-day cap, the default window, the guarantee that every day has an items array (empty on free days), and the filtering rule that routine 'Inschrijving in orde.' notices are dropped while real warnings are kept. That filtering surprise is exactly the kind of behavior an agent could not infer elsewhere.

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 resource, followed by the field inventory, then the two operating constraints (default window, maximum). Dense but every clause carries information an agent would otherwise have to discover empirically.

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-shape burden and does so thoroughly for a read-only query tool. The only remaining gap is its relationship to the `lessons` sibling and any ordering/pagination behavior.

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 100% and each parameter already carries a description, including the Amsterdam timezone for `date` and the multi-child requirement for `leerlingId`. The description adds only the default range values, which is a modest supplement, so the baseline 3 applies.

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?

Names a specific resource (timetable) with an explicit enumeration of what each day contains (lessons, tests, appointments, changes, cancellations, attachments, holidays). It is clearly distinct from grades/messages siblings, but the overlap with the `lessons` sibling is never addressed, so an agent cannot tell from this text alone which one to pick.

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 concrete operational context: defaults to today plus 6 days, and a hard maximum of 42 days. However, it offers no guidance on when to prefer this over `lessons`, `homework`, or `parent_evening`, and no stated exclusions.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the meaningful behavioral distinction that omitting paginaId returns per-child contact data while supplying it returns a single page, but it says nothing about pagination, volume, or whether a page list is itself returned on the first 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?

Three short sentences, front-loaded with what the tool returns, then the parameter behavior, then sibling routing. Every sentence carries distinct information with no repetition of 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?

There is no output schema, so the description must convey return shape, and it does so at a high level (contact data per child; page topics and documents). It stops short of describing the fields of the contact data or the page list itself, which leaves a modest gap for a no-parameter list 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 100%, so the baseline would be 3, but the description goes beyond the schema by explaining the effect of the parameter: a single page with its topics and documents. It also clarifies provenance of the id ('page list of a previous school_info call'), reinforcing the two-call sequencing pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource clearly - school contact data per child plus published information pages - and distinguishes the two modes (list vs single page). It is weakened by the absence of an explicit verb (fetch/read) and by the cryptic phrase 'contact data per child', but an agent can still tell what it returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the activation condition for the parameter ('Pass paginaId for one page with its topics and documents') and explicitly routes to siblings for adjacent needs ('Use teachers for staff and children for mentors'). No explicit statement of when not to use it, but the alternatives are named.

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, it discloses important behavior: the tool returns extracted text capped at 10 MB, requires login, is not a downloadable file URL for `download_attachment`, and is generally available only after signing. These are operational details an agent needs and they do not contradict the read-only, non-destructive 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 the core action and stays compact. Each detail, including the return type, login requirement, sibling-tool distinction, and availability window, carries useful 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?

For a one-parameter read tool with annotations covering safety and idempotency, the description is complete: it explains the input source, return format, size limit, auth context, sibling distinction, and availability constraints. No output schema is present, but the description covers the relevant return behavior.

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 100%, and the schema already documents `id` as the signing request id (`document.id` from `signing_requests`). The description repeats that mapping but adds no additional parameter-level syntax or constraints, so the baseline of 3 is appropriate.

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: reading the PDF document of one signing request. It names the source field (`document.id` from `signing_requests`) and explicitly distinguishes the tool from `download_attachment`, so an agent can identify it 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 gives clear usage conditions: pass `document.id` from `signing_requests`, use it when a signed-request document is available, and do not use it for requests still to sign, withdrawn, or expired. It also names the alternative path (`download_attachment`) for file URLs, making the routing decision explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description reinforces with 'Read-only; nothing is signed', which is a useful guard against an agent attempting a signing action. It also discloses the item shape (document {tool, id, available}), a behavioral detail beyond the annotations, though it doesn't say whether pending and completed items are mixed in one response.

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?

Two short sentences, front-loaded with the resource and scope, followed by the concrete chaining instruction. No filler; every clause carries 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?

With no output schema, the description usefully sketches the return item structure and the follow-up call, which is what an agent needs to act. A minor gap remains around how pending vs. completed entries are distinguished and whether both appear in a single response.

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, so the baseline is 4. The description goes further by explaining the semantics of the returned id field and how to feed it into signing_document, which is the only input-shaping information an agent needs here.

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 the resource precisely (digital signing requests / ondertekenverzoeken) and its scope (waiting for you or done), and explicitly differentiates the sibling signing_document as the tool for reading the underlying PDF. An agent knows exactly what this returns without opening another 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 makes clear this is the entry point for signing requests and explicitly routes the follow-up action to signing_document via the returned id. It lacks an explicit exclusion statement (e.g., when this is not the right tool), but with no comparable sibling the routing is actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: no arguments returns subjects that have material plus personal learning products when the school allows it, empty collections mean the teacher attached nothing, and lesmateriaal=true is only a flag with no separate material call. This is valuable context that annotations do not provide.

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 and does not waste many words, but it is dense and mixes Dutch terms with English in a long parenthetical structure. Some sentences pack multiple behaviors together, reducing readability. It is appropriately sized but could be structured more cleanly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must carry return-shape context. It does this adequately by explaining that every item lists bijlagen with fileUrl and externeMaterialen, and that empty means nothing attached. It could be more explicit about the overall response shape for subject lists, but it is sufficient for a read-only retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning by explaining that vak accepts a name, abbreviation, or uuid, that all=true fetches every subject, and what happens when no arguments are supplied. It does not discuss leerlingId, but the schema already documents its conditional requirement clearly.

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 resource and scope: study material per subject, including lesson material by date, year attachments by folder, external links, and method/publisher links. It distinguishes itself from file-fetching by mentioning that bijlagen fileUrl is readable with download_attachment. The mixed Dutch/English phrasing ('Studiemateriaal', 'lesmateriaal') adds minor opacity but the purpose is still 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?

It explains the no-argument default, the vak usage, and all=true, which helps an agent invoke it correctly. However, it does not explicitly say when to use this tool versus siblings such as lessons or homework, beyond noting that file URLs should be opened with download_attachment. Usage is implied rather than fully guided.

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, open-world, and non-destructive, so the safety profile is covered. The description adds substantive behavior: both dossiers are included unless dossier is set, column definitions include not-yet-graded columns, and composite tests are broken into parts. It stops short of covering pagination or error behavior, but the return-content disclosure is well beyond the annotation baseline.

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 the return inventory, then the usage rule. The first sentence is dense with parenthetical lists and runs long, but every clause carries information an agent needs to interpret the output. Slightly tighter phrasing would make it a 5.

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 three parameters, 100% schema coverage, and no output schema, the description carries the return-shape burden and does so thoroughly: result columns, weights, remarks, definitions, composite parts, and dossier scoping. Missing only peripheral details like ordering or result limits, which are unlikely to affect 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 coverage is 100%, so the baseline is 3. The description adds meaning not in the schema: omitting 'vak' yields the subject list rather than an error, and omitting 'dossier' yields both progress and exam dossiers. Those default and omission semantics make the parameters materially easier to use.

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 framing ('Everything for one subject') and enumerates exactly what is returned: result columns, weights, remarks, column definitions including not-yet-graded ones, and composite test parts. It explicitly distinguishes itself from grades_overview, so an agent can pick the right tool 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?

It gives an explicit routing rule: 'Use this to drill into one subject; use grades_overview for all subjects at once.' It also documents the omitted-vak case ('the list of subjects'), which is real guidance for a zero-required-parameter 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds scope information (only messageable staff, only subjects relevant to your child), but with zero parameters it never explains which child/children the result is scoped to, which is the main behavioral ambiguity for a no-arg call. Useful context, but incomplete on the one point that matters most.

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?

Two sentences with no filler: the first defines the resource and payload, the second handles sibling disambiguation. The most important information (what you get) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, read-only listing tool with rich annotations, the description covers purpose, payload, and alternatives. The only gap is that no output schema exists and the description doesn't sketch the shape of the returned list (e.g., teacher fields, how many children it spans), which would help an agent plan consumption of 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?

The input schema has zero parameters, which is the baseline-4 case, so there is no parameter semantics for the description to compensate for. Its scoping language ("your child") implicitly warns that output is per-child even though no parameter selects one.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete resource ("Teachers and other staff you can message in Somtoday") and states what data comes with it ("the subjects they teach your child"). It also explicitly routes away from the two nearest siblings, so the agent can distinguish it from children and school_info 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 names both alternatives and the condition that selects each: use children for mentor(s), school_info for general school contact data. That is an explicit when-to-use-this-vs-that statement, 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 already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds valuable context beyond those: it signals the tool is a starting point and that it provides IDs needed by other tools. The phrase 'No tokens' likely indicates no authentication tokens are required, adding auth-related clarity. It stops short of describing error behavior or rate limits, so a 4 is appropriate.

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 three sentences, front-loaded with the most important instruction ('Start here'), and contains no filler. Each clause delivers actionable information: what it returns, when to use it, and an alternative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no input parameters, no output schema, and annotations covering safety, the description provides sufficient detail: it lists the three key pieces of information returned and names the sibling to use for more detail. Nothing critical is missing for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters, so there are no parameter semantics to explain. Per the rules, a tool with 0 parameters gets a baseline of 4.

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 exactly what the tool returns: the school label, numeric leerling IDs for use as leerlingId, and visible parent-portal sections. It explicitly distinguishes itself from the sibling tool 'children' by noting 'Use children for full profiles.' This gives an agent a clear, specific purpose without needing to open 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?

The description begins with 'Start here,' explicitly telling the agent this is the first tool to call. It also names an alternative ('Use children for full profiles') and the condition that selects it. Both when-to-use and when-to-use-something-else are clearly stated.

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