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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is low; the description still adds substantive behavior: the readVia deduplication when a parent and child login list the same child, and that hidden: true children are not read by tools. These are non-obvious consequences beyond anything in the annotations. It does not describe error behavior when no logins are connected, which keeps it 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?

Three sentences, front-loaded with what is returned and followed by the two edge cases (cross-Wilma families, duplicated child listings). Every clause carries information, though the second and third sentences are dense and stack multiple conditions ('a parent's and the child's own', 'a profile Wilma lists twice') that an agent must parse carefully.

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 — listing top-level fields and the readVia/hidden markers. It lacks the overall container shape (array vs. object) and what happens when no logins are connected. For a zero-parameter read tool with full annotation coverage, that 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?

The tool takes zero parameters, so there is no parameter semantics to compensate for; baseline 4 applies. The description instead spends its words on the return shape, which is the right use of space for a no-arg tool.

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

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

The first sentence names the specific resource (connected Wilma logins) and enumerates the fields returned: Wilma, username, role, and children. It also differentiates from wilma_login (which adds a login), so an agent can tell what this tool reports versus what its sibling does. The verb is implicit rather than stated directly ('Which Wilma logins are connected...'), 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?

Usage is only implied — an agent infers it should call this to discover which accounts are connected or to resolve a child to the right login. The only explicit routing is 'wilma_login adds another', which covers the add-case but not when to prefer this over wilma_summary or other read tools. No exclusions or prerequisites 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 declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; the description adds real behavioral content on top. It discloses that role labels come 'as Wilma names it', that teacher lists mirror Wilma's message-recipient list, that the subject list is scoped to this and next week's timetable and is empty when none, and that other staff are omitted. Return-shape details (field names, nesting) are still absent, which keeps 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?

It is a single dense sentence plus a short routing sentence, front-loaded with the returned resources and ending with the sibling cross-reference. Nothing is redundant, though the main sentence is long and stacks four clauses, which slightly taxes parsing compared with splitting the supervisor and teacher groups.

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

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

For a read-only, single-optional-parameter lookup with no output schema, the description covers what is returned, the role-naming convention, the temporal scope of subject data, the empty condition, and the main exclusion. It leaves the concrete response structure (field names, whether teachers and supervisors are separate arrays) unspecified, which is the only material 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 'student' parameter is fully documented in the schema, including the omit-for-all-children behavior, so the baseline is 3. The description implies per-child scoping through 'Each child's class' but adds no accepted formats, ambiguity handling, or name-vs-number behavior beyond what the schema states.

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 exact resources returned: the child's class (e.g. 9A), class teacher, other supervisors with their Wilma role label, and the child's own teachers with per-subject scope. It explicitly carves out the boundary against the sibling wilma_schedule ('Lessons with times and rooms are in wilma_schedule') and states that other school staff are excluded, so an agent can distinguish it from the schedule and gradebook tools 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 a clear use context (who teaches this child and in what role/subject) and routes the agent to an alternative (wilma_schedule) for lesson times and rooms, plus an explicit exclusion for non-teaching staff. It stops short of a full when/when-not comparison against other plausible siblings such as wilma_account or wilma_grades, but the routing guidance is concrete.

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/closed-world, so the description is free to add domain behavior instead: city schools share a city Wilma, big cities don't list each school, and multiple tenants can match one city. It stops short of describing result shape or result-set size.

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

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

Three tight clauses, front-loaded with the verb and resource before the domain caveats and usage hint. Dense but every clause carries information; nothing is 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?

Given one required parameter, no output schema and rich annotations, the definition covers when and how to call it. It could still say what a hit looks like (tenant name, URL, city) so an agent knows what to present to the user, but nothing essential is missing.

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

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

Schema coverage is 100% and the single query parameter is already documented with an example in the schema. The description adds only the small clarification that organisation names also work, which is marginal beyond the schema 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?

States a specific verb ("Search") and resource ("Finland's Wilma addresses") with the two search dimensions (city or school/organisation name). It also explains the domain model that distinguishes city-level vs. school-specific Wilma tenants, which no sibling tool addresses.

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 concrete use case ("help the user pick their Wilma, e.g. when setting WILMA_TENANT") and an interaction rule ("several can serve one city, so ask which is theirs"). No explicit exclusions or named alternatives among siblings, so not 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?

Without the description an agent would assume this is a pure read, but it discloses the save=true side effect that writes into ~/Downloads/WilmAI — consistent with readOnlyHint=false and idempotentHint=false. It also discloses the dual return shape (file content vs 'not_a_file' plus URL), which is valuable since there is no output schema. Missing is any note on permissions or size/type limits.

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, each carrying distinct information: what it fetches, what it returns in each case, and the optional save behavior. Front-loaded and waste-free.

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?

Return-shape disclosure compensates for the absence of an output schema, and the save side effect is covered. Minor gaps: no mention that news_id must be obtained from wilma_list_news/read_news, and no hint about what happens when the attachment cannot be retrieved.

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 75% and the description only restates the save flag already documented in the schema. It adds nothing about news_id (undocumented anywhere) or how student scoping interacts with the fetch, so it does not fully compensate for the coverage gap.

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 ("Fetch a file linked from a bulletin"), with concrete examples of what such files are (PDF letter, menu). It is clearly distinguished from the sibling read tools (wilma_read_news, wilma_list_news) because it retrieves the attachment, not the bulletin text.

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 "so you can read it" and the schema's note that resource_id comes from wilma_read_news, but the description itself never says when to call this instead of wilma_read_news or what to do when the resource is a web page beyond returning 'not_a_file'. No explicit 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?

Annotations mark readOnlyHint=false, and the description explains why: setting save=true writes the file to the user's Downloads folder, disclosing the side effect and its trigger. It doesn't cover permission needs or how large PDFs are handled, but it adds meaningful behavior beyond the annotation flags.

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, the primary action front-loaded and the optional side effect second. Nothing is redundant or padded.

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 three-parameter, fully documented read tool with no output schema, the description covers the action and the one behavioral fork that matters (save). It leaves the return shape implicit — whether the PDF content comes back inline or only as a file — which an agent would still need to discover.

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 all three parameters are already documented, including that id comes from wilma_list_printouts and save writes to ~/Downloads/WilmAI. The description reinforces the save semantics but adds no format, syntax, or edge-case detail 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 names a specific verb and resource ('Fetch one printout PDF') and states the intent ('so you can read it'), which separates it from wilma_list_printouts. It stops short of explicitly naming the sibling it complements, so it is clear but not maximally differentiated.

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 rather than stated: the 'one printout' phrasing and the id parameter imply this runs after wilma_list_printouts, and the save=true clause hints at a save-vs-read fork. There is no explicit when-to-use/when-not guidance or named alternative in the description itself.

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, destructiveHint=false and openWorldHint=false, so safety is covered; the description instead adds the meaningful behavioral context of what comes back — a nested subject > syllabus > course grouping with credits and completion dates, plus term/report-card grades. It stops short of describing pagination or the raw response shape, which is the only 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?

Two sentences, front-loaded with the verb and resource, followed by a routing sentence. The field enumeration is dense but every item (course codes, credits, completion dates, term grades) conveys distinct return content rather than 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 burden of communicating return shape and does so precisely — the subject > syllabus > course hierarchy plus the term/school-year report-card grades. Combined with 100% schema coverage on the one optional parameter, an agent has everything needed to call and interpret it.

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 'student' parameter is fully documented in the schema (name or student number, omit for all children), so the description correctly defers. It adds no extra semantics about the parameter, which is the expected baseline when the schema already does the work.

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 each child's gradebook"), then enumerates the contents: completed courses with grades, course codes, credits, completion dates, term and school-year grades. It also names the sibling it is not (single exam grades live in wilma_grades), so an agent can distinguish it from similar tools 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: 'Use it for course and report-card grades; single exam grades are in wilma_grades.' That gives both the when-to-use condition and the concrete alternative tool with its own 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 read-only, idempotent, non-destructive behavior, yet the description still adds real context: newest-first ordering, that Wilma itself controls how far back the default list reaches, and that the 'from' path includes ungraded exams returned with grade: null. It does not cover pagination edge cases or what happens for children with no exams, which keeps it 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 return fields are front-loaded and each clause carries information, including the parenthetical about Wilma deciding the lookback window. It is dense but not padded; a reader needs the full text to call it correctly, though some nesting could be flattened for easier 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?

With no output schema, the description carries the burden of describing return values and does so field by field, plus the null-grade case and ordering. Combined with the sibling routing to wilma_gradebook, 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: 'from' switches the underlying data source and implicitly bounds 'to' and 'limit' behavior (limit being 'every exam of the period' when 'from' is set). That source-switching meaning is genuinely beyond the parameter descriptions.

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

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

States a specific verb and resource ('List each child's graded exams') and enumerates what each entry contains: date, exam name, subject, grade in Wilma's format, teacher notes, and guardian seen-marker. It explicitly routes report-card/course grades to wilma_gradebook, so an agent can separate it from that sibling without reading 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?

Gives explicit when-to-use branching: without 'from' it reads the front-page exam list, with 'from' it reads the deeper past-exam list, and course/term/report-card grades belong to wilma_gradebook instead. The alternative and the selecting condition are both 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?

Annotations already declare this a safe, idempotent read, so the description doesn't need to re-state safety. It does add real behavioral context beyond them: results are ordered newest first, and the lookback window is controlled by Wilma's front page rather than by this tool, which explains the bounded, possibly incomplete result 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?

Two tight sentences: the returned data and ordering come first, and the sibling disambiguation follows. Nothing is redundant and nothing important is buried.

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, but the description compensates by naming the returned fields, and it explains the upstream lookback limit that an agent would otherwise have no way to know. For a two-parameter read tool with full annotation coverage, nothing needed for a correct call 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 100%, so both parameters are already documented, including the limit default of 10 and the student name-or-number option. The description echoes 'per child' and 'newest first' but adds no format or edge-case detail beyond the schema, 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?

States a specific verb and resource ('List the homework teachers have entered for each child') and enumerates the returned fields (date, subject, teacher, what to do). It also names wilma_summary as the overlapping sibling, so an agent can distinguish 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 closing sentence tells the agent that wilma_summary already covers the last few days, implicitly steering it here for the fuller front-page history. It stops short of an explicit 'use this instead when...' rule, so it is clear context rather than a full routing decision.

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 establish the read-only, idempotent, closed-world safety profile, so the description only needs to add behavior beyond that. It does: notes are teacher-authored, verbatim text is included 'when given' (implying the field may be absent), and a future-dated period is legitimate because teachers can log upcoming make-up exams. That last point is non-obvious and prevents an agent from wrongly clamping the date 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?

Two sentences, front-loaded with what the tool returns before moving to the query modes. Nothing is redundant, though the second sentence packs three modes and a future-date caveat densely enough that a reader may need a second pass.

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 five-parameter, no-required-parameter read tool with no output schema, the description covers content, defaults, mode selection and the future-date edge case. The remaining gap is the return shape — whether results are grouped per child or per note, and whether empty days appear — which is left implicit since no output schema exists.

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 all five parameters are already documented at a baseline of 3. The description adds two useful interpretive points — the modes are alternatives to one another and from/to may extend past today — but it does not clarify precedence when more than one parameter is supplied or how student combines with the date modes.

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 (teacher-logged lesson notes / merkinnät) and enumerates its contents: absences, lateness, praise, missing books or homework, including the teacher's own words. This is enough for an agent to distinguish it from wilma_homework, wilma_grades or wilma_schedule without opening the schema. It stops short of explicitly naming a sibling to route away from, so it is a clear 4 rather than 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?

It explains the three temporal query modes (single day defaulting to today, last N days, from/to period) and even notes the period may reach into the future, which is real invocation guidance. However, it gives no guidance on when to prefer this over alternatives such as wilma_lesson_notes_summary or wilma_upcoming_exams, so routing must be inferred from the tool name.

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 closed-world, so safety is covered. The description adds real value beyond that by disclosing the default scope (school year, or from a given date) and by indicating the return shape is per-kind counts rather than individual notes — critical since there is no output 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?

A single sentence, front-loaded with the operation and resource, with the time-window rule trailing. The parenthetical category list is long but earns its place by making the aggregation concrete; nothing 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?

All parameters are optional and the tool is read-only, so the call surface is simple. However, with no output schema the description should say more about the response — whether omitting 'student' returns a per-child breakdown or one flat set of counts is left ambiguous, which affects how an agent interprets and presents results.

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 every parameter is documented in-schema with format and defaults. The description only restates the date default behaviour already present in the schema and adds nothing about how 'student' affects the aggregation output, so baseline 3 is right.

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 operation and resource: lesson notes aggregated ('counted by kind'), with concrete example categories listed. This distinguishes it in spirit from a flat list tool like wilma_lesson_notes, but the sibling is never named, so the agent must infer the contrast rather than being told it.

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

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

The description implies when to reach for it (you want counts, not records) and explains the default time window, but it gives no explicit when-to-use/when-not guidance and never points to wilma_lesson_notes for the raw records or wilma_summary for a broader overview.

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=false, so the safety profile is covered. Beyond that, the description adds the newest-first ordering, enumerates the returned fields, and explains the non-obvious invitationStatus values ("Applied", "ExpiredReg", null) so the agent can interpret results without guessing.

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, front-loaded with what is returned and correctly ordered before the alternative-tool pointer. The parenthetical field lists are information-bearing rather than filler; only the nested quotes around "Applied" and the double explanation of invitation timing add slight density.

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 describing returns and does so (message fields plus invitation-specific fields and status semantics). The main remaining gap is pagination/limit behaviour — how many messages come back by default and whether the newest-first ordering interacts with limit — which matters for a listing 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 coverage is 67%, so the baseline is 3. The description meaningfully expands on folder="appointments" by explaining it holds event invitations with the family's answer, which the enum alone does not convey; however, it says nothing about the limit parameter's behaviour or the student parameter beyond what 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?

"Wilma messages, newest first" plus the explicit field list (subject, sender, date, id, unread, replyCount) makes clear this is a message-listing tool with a defined sort order and return shape. Sibling differentiation is partial: it distinguishes itself from wilma_read_message but not from other 'list' siblings like wilma_list_news or wilma_list_printouts, which the name and title carry 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: "Use wilma_read_message for the full text, and for an invitation's time slots" tells the caller exactly when this tool is insufficient. It also signals that the appointments folder is a distinct use case worth selecting, though it gives no guidance on when to omit or narrow the student/limit parameters.

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 (readOnly, idempotent, non-destructive), but the description adds non-obvious behavior: pinned bulletins are always included regardless of limit, archived items appear only with include_older and then as titles only, and an 'unavailable' result means the account is not shown bulletins, not that there are none. That last point prevents a serious misreading of an empty result.

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, and the core ordering behavior is front-loaded. It leans toward telegraphic phrasing (nested parentheses, the Finnish term, the raw JSON-shaped 'unavailable: ["news"]') that costs slightly more parsing effort than a plainer sentence would.

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 three-optional-parameter read-only list tool with no output schema, the description covers ordering, inclusion rules, the archived/titles-only caveat, error semantics, and the hand-off to the read tool. An agent has everything needed to call it and to interpret an empty or unavailable 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that the limit caps dated bulletins while pinned ones always come through, and that include_older yields archived:true entries that are titles only until read. The remaining gap is a lack of explicit guidance on the student parameter (e.g. multi-child accounts), which the schema already handles adequately.

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 specific resource (school bulletins / tiedotteet) and states exactly what is returned and in what order: newest dated first, then pinned ones. It also explicitly contrasts itself with the sibling wilma_read_news, so an agent can pick between listing and reading 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?

Explicit routing: 'Use wilma_read_news for the full text and attachments' tells the agent when not to use this tool and which alternative to pick. The include_older clause and the unavailable: ["news"] note further define the conditional cases where this tool does or does not return data.

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, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only the domain fact that these are school-issued PDFs; it says nothing about ordering, pagination, or whether a student filter narrows the result set. With annotations carrying the burden, a 3 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?

Two short sentences, zero filler, with the resource definition front-loaded and the sibling handoff placed last. Nothing to trim.

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?

Adequate for a simple read-only list with no output schema: the agent knows what it gets (PDF printouts) and where to go next. The one gap is that nothing describes the shape of a list entry or which identifier is needed to call wilma_get_printout, which the absence of an output schema leaves undocumented.

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 is a single optional parameter with 100% schema description coverage ('Child's name or student number. Omit to include every child'). The description adds no format hints or naming conventions beyond that, so the schema does all the work and 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 the concrete resource (PDF documents offered by the school, Tulosteet) with two illustrative examples, report cards and absence reports. The closing sentence 'Fetch one with wilma_get_printout' makes it unambiguous that this tool lists while the sibling retrieves, so an agent can distinguish the pair 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 routes the follow-up action to wilma_get_printout, which is the natural alternative an agent would confuse this with. It does not state when to prefer this over other list tools (messages, news), though the resource is distinct enough that the omission is minor.

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 indicate non-destructive, idempotent behavior and that this is not read-only. The description adds important behavioral context by explaining that it opens a browser-based login page and that the password is entered only on that page, never in chat. It does not detail post-login session behavior, but the key security and interaction traits are disclosed.

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

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

Two sentences with no wasted language, front-loaded with the action and scope. The parenthetical about adding a child's account is useful and concise.

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 zero parameters, no output schema, and annotations covering the safety profile, the description provides enough context for correct invocation. It explains the browser-based login flow, multi-account use, and password-handling constraint.

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 are no parameter semantics to explain. The schema is empty and fully covered; the baseline for a zero-parameter tool is a 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 uses a specific verb and resource: 'Open a login page' for connecting a Wilma account. It also explains the multi-account case for a child at a different school, distinguishing it from data-retrieval siblings like wilma_gradebook and from wilma_logout.

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 trigger conditions clearly: connect a Wilma account or add another one for a child at a different school. It also warns that the password must be entered on the login page, not in chat. There is no explicit when-not guidance, but there is no meaningful sibling alternative to redirect to.

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 by disclosing the hidden mechanics: one session per account, login credentials persist, and the next Wilma tool call silently re-authenticates and kicks the user's browser session. That second-order side effect is not derivable from readOnlyHint=false / destructiveHint=false / idempotentHint=true, so the description carries real load here.

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 sentences, front-loaded with purpose, then the reason, then the ordering hazard. Every clause carries decision-relevant information: session uniqueness, credential persistence, and the follow-on-call trap.

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 parameters and no output schema, the only thing an agent could get wrong is sequencing and re-login behavior, and both are covered explicitly. Nothing needed to invoke this correctly is missing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; per the zero-parameter baseline this is a 4. It adds no spurious argument talk, which is correct.

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 ("End WilmAI's Wilma session") and anchors it to a familiar analogue ("as Wilma's own Log out does"), which immediately distinguishes it from wilma_login and every other read-oriented 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?

Gives explicit trigger conditions ("when the user wants to use Wilma in their browser or asks to log out") and an explicit exclusion ("don't call other Wilma tools afterwards unless the user asks"). This is exactly the when/when-not structure an agent needs for a terminal action.

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 closed-world behavior, so the safety profile is fully covered. The description adds one genuinely useful behavioral detail beyond that — that thread replies are included in the returned text. It does not cover error behavior for an invalid id or cross-Wilma resolution.

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 short sentence that front-loads the core content ('full text of one message') and appends the one non-obvious qualifier (thread replies). 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?

For a simple single-record read with full schema coverage and complete annotations, the description states what is returned and its notable extra (thread replies). Minor gap: no mention of failure modes such as an unknown id or an ambiguous student across connected Wilmas.

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 are already documented in the schema, including the conditional requirement on 'student'. The description adds no parameter-level detail, 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?

The description names the resource ('one Wilma message') and the scope of content returned ('full text... including thread replies'), which implicitly distinguishes it from the sibling wilma_list_messages. It lacks an explicit verb, but the retrieval intent is unambiguous.

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

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

Usage is only implied: an agent can infer this is for opening a single message after listing. There is no explicit when-to-use guidance, no mention of the wilma_list_messages prerequisite, and no note about the optional student parameter condition beyond what the schema says.

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=false, so the safety profile is covered. The description adds useful return-content context: 'full text' plus 'linked resources (attachments and links)', which goes beyond annotations and helps the agent understand what it gets back. It does not discuss pagination or size limits, but none are apparent for a single-bulletin 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?

Two sentences, no waste, and the primary behavior is front-loaded before the alternative-tool pointer. Every phrase contributes to understanding what the tool does or how to handle linked resources.

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

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

For a simple read-only tool with complete schema coverage and rich annotations, the description is nearly complete. It explains the primary return content (full text plus linked resources) and points to the correct sibling for fetching those resources. A minor gap is that it does not describe the shape of the returned text or how links/attachments are represented, but this is acceptable given no output schema exists and the general behavior is clear.

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 (id and student) are fully documented in the schema. The description reinforces that the tool operates on 'one bulletin' and refers to 'linked resources', but adds no new parameter-level semantics beyond the schema. Baseline 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 pair: it returns the full text of one bulletin plus linked resources. It also implicitly distinguishes itself from wilma_list_news by focusing on a single bulletin, and names the sibling wilma_get_news_attachment for resource fetching.

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 to wilma_get_news_attachment for fetching linked resources, which is a clear alternative for a sub-task. However, it does not explicitly say to call this after wilma_list_news to retrieve details, though the schema's 'id from a list' strongly implies that workflow.

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 closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the returned fields (date, start/end, subject, teacher, room when available) and the edge case that a day without school returns no lessons. It stops short of describing error behavior for unknown students or empty periods.

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 front-loaded sentence plus one follow-up covering return shape and exclusions — no filler. The dense enumeration of period options is slightly heavy to parse but each clause carries distinct 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 carries the burden of describing results, and it does so adequately by listing the returned fields and the empty-day case. Remaining gaps are minor: nothing about invalid date ranges or what happens when a student name matches nothing.

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 intent the schema does not: that from/to can span several weeks to reveal the usual school-day pattern, and that weekday means the next occurrence of that weekday. It does not restate the precedence rules, which the schema already handles.

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 — "List each child's lessons" — and bounds the scope to a day or a school week. It also names the sibling tools that hold the excluded data (wilma_upcoming_exams, wilma_homework), so an agent can distinguish it from adjacent 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?

Enumerates the concrete selection modes (today, next school day, this/next week, a date, next given weekday, or an arbitrary from/to period) and gives a rationale for the from/to case (looking weeks ahead to see usual school days). It also explicitly redirects exam and homework lookups to the sibling tools, covering the when-not case.

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 read-only and idempotent annotations, it discloses that source data may be unavailable and explains how omissions are reported through unavailable, with a concrete news example. It also clarifies temporal coverage and conditional exam start times, helping the agent interpret partial results correctly.

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 efficient, front-loading the tool's scope and then covering availability behavior and selection guidance without filler. Its detailed field list earns its place because there is no output 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?

For a broad aggregation tool without an output schema, it describes the included domains, important message and invitation fields, and partial-data behavior. Together with the fully documented inputs and safety annotations, this is sufficient to select, invoke, and interpret typical calls.

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 days, since, and student are already documented, including formats and defaults. The description adds little parameter-specific guidance beyond that structured information, making the baseline score 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?

Defines an aggregated, per-child daily briefing and enumerates the school domains it combines, distinguishing its summary role from single-purpose siblings such as wilma_schedule and wilma_homework. The final sentence also establishes its intended role as the general entry point for school questions.

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 recommends the tool as "The best starting point for any question about school," providing clear selection guidance. It does not explain when to bypass it for a specialized sibling or a more detailed view, so it lacks complete when-not or alternative-routing 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 and closed-world, so safety is covered. The description adds genuine context beyond them: the 'no grade yet' filter, the soonest-first ordering, and the exact fields returned (date, start time when available, name, subject, topic, teacher).

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, zero waste, with the scope and ordering front-loaded and the sibling routing placed at the end where it belongs. The field enumeration is dense but directly 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?

For a simple two-param read tool with no output schema, the description covers purpose, filtering, ordering, and returned fields adequately. Only minor gaps remain, such as behavior on an empty result set or the per-child limit interaction, which the schema largely covers.

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 both parameters are already documented, including the limit default of 20 and the per-child semantics. The description only corroborates 'each child's' and the ordering; it adds no syntax or format detail 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?

States a specific verb (list) and resource (exams) with precise scope: 'from today on that have no grade yet, soonest first'. It also distinguishes itself from the graded-exam sibling by name, so an agent can select 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?

Explicitly routes graded exams to wilma_grades, giving a clear when-to-use-elsewhere rule. It doesn't spell out edge cases such as an empty list or whether login is required, but the core routing guidance is clear.

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