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 genuinely non-redundant behavior: multiple concurrent logins are possible and each carries its own set of children. It omits what is returned when no accounts are connected.

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 with the payload front-loaded and the multi-account scenario plus the wilma_login pointer following. No filler.

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

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

With no params, full annotation coverage and no output schema, the description carries the return-shape burden and does name the two things returned. It leaves the exact response shape and the empty-state behavior unspecified, a minor gap at this complexity.

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 there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is missing because none exists.

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: connected Wilma logins plus the children under each login. A reader can tell this apart from the data-fetching siblings (gradebook, schedule, messages). It stops short of naming sibling tools it is not, so it is clear but not sharply 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?

It supplies the operative context — families with children on different Wilmas can connect several accounts — and points at wilma_login as the tool that adds another, which implicitly frames when not to use this one. There is no explicit "use this when..." trigger or statement of prerequisites (e.g., must be logged in first).

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered without the description. The description adds content scope (what data types appear in the response) but says nothing about ordering, pagination, or whether historical vs. current-term data is included.

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 compact sentence with no filler, front-loading the most identifying detail (completed courses and grades by subject). It only loses a point because the core distinguishing information — how this differs from wilma_grades — is absent rather than just brief.

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 carry the burden of describing return content, and it partially does so (term/school-year grades, completion dates). But for a tool sitting beside a name-adjacent sibling, omitting the distinction leaves the agent without enough to select confidently.

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 well documented in the schema itself (name or student number, omit for all children). The description adds no parameter guidance, but the baseline of 3 applies when the schema does the heavy lifting.

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 enumerates the resource's contents (completed courses, grades by subject, term and school-year report-card grades, completion dates), which is meaningful detail. However, the sibling list contains wilma_grades, a near-identical name, and the description offers no way to tell the two apart. A specific verb is also absent — it reads as a data label rather than 'returns the gradebook for a student'.

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

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

There is no statement of when to use this tool, when not to, or which sibling (notably wilma_grades) to prefer. The agent must infer the distinction from names alone, which is risky given the overlapping vocabulary.

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 only the word "recent", which is never defined (last week? last term?), and says nothing about default limit, ordering, or whether results are paginated.

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 short fragment with no waste, but it is under-specified rather than structured. There is no front-loaded guidance to speak of because there is essentially no 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 two-parameter tool with half its schema undocumented and no output schema, the description leaves the agent without enough to call it confidently: no recency window, no default/limit behavior, no indication of what a grade record contains or how grades are ordered.

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 student parameter is documented in the schema, but limit has no description anywhere and schema coverage is only 50%. The description contributes nothing about either parameter, not even whether "recent" relates to the limit cap of 100.

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 name and description identify a resource (exam grades) with a vague qualifier "recent", but no verb or scope detail. It does not distinguish itself from the sibling wilma_gradebook, which an agent would reasonably consider for the same data.

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

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

There is no statement of when to call this instead of wilma_gradebook or wilma_upcoming_exams, nor any precondition. The agent must infer usage entirely 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, closed-world, non-destructive, so the safety profile is covered. The description adds the useful 'newest first' ordering, but never defines how far back 'recent' reaches or whether results are truncated by a default limit.

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 with zero filler; the ordering constraint is stated immediately. Nothing extraneous is present.

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 rich annotations, the definition is minimally workable, but with no output schema the description should at least characterize what a homework entry contains and what default window 'recent' 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?

The schema documents 'student' well but leaves 'limit' with only min/max bounds and no semantic description; the tool description adds nothing about either parameter, so the 50% coverage gap is not compensated.

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 (homework entries) with a clear ordering guarantee (newest first) and a scoping hint (by lesson). It is distinguishable from siblings like wilma_grades or wilma_lesson_notes, though 'by lesson' is ambiguous about whether results are grouped or merely labeled.

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?

No guidance on when to call this versus wilma_grades, wilma_lesson_notes, or wilma_summary, all of which could plausibly surface homework-like data. The agent must infer selection from tool names alone.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them by describing the kind of content returned (absence, lateness, praise, missing books or homework) and that teacher wording is quoted verbatim when available, which tells the agent what to expect in the payload. Return shape and date-range semantics of overlapping date/days params are still left implicit.

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 and content categories, with scope stated last. The Finnish term 'merkinnät' is a minor addition rather than filler. No wasted text.

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

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

There is no output schema, so the description has to carry the content story, and it does list the note categories and the verbatim-quoting behavior. The main gap is the relationship to wilma_lesson_notes_summary, which would resolve ambiguity for an agent choosing between the two.

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 the YYYY-MM-DD default and the 1-365 range. The description only restates the one-day-or-last-N-days behavior and says nothing about the student filter (the schema note that omitting it returns every child is not echoed). 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 names a specific verb+resource: teacher-logged lesson notes (merkinnät) covering absences, lateness, and feedback, with the teacher's verbatim words. It is clear what the tool returns. It does not distinguish itself from the sibling wilma_lesson_notes_summary, which an agent could reasonably confuse it with.

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 trailing sentence 'One day (default today) or the last N days' implies the two query modes and their defaults. There is no explicit statement of when to use this versus wilma_lesson_notes_summary or wilma_summary, and no note on prerequisites such as being logged in.

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 description only needs to add operational detail. It does that by disclosing the sort order and the returned fields, though it omits pagination behavior and the effect of the limit cap of 100.

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 and ordering, then the sibling redirect. No filler and nothing that could be cut without losing 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 parenthetical field list (subject, sender, date, id) usefully compensates by telling the agent what each item looks like. Combined with annotations covering the safety profile, only pagination/limit behavior is left implicit for a tool with three optional parameters.

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%: folder and student are documented in the schema, while limit has only min/max bounds. The description says nothing about any parameter, adding no meaning beyond the schema, which is acceptable at this coverage level but leaves the limit semantics entirely to inference.

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 resource (Wilma messages), the ordering (newest first), and the fields returned, which lets an agent distinguish this listing tool from wilma_read_message at a glance. It could be sharper with an explicit verb, but 'messages, newest first' plus the title makes the operation 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?

Explicitly routes the agent to wilma_read_message for full message text, which is the key branch point among these siblings. It gives no guidance on when to prefer other listing tools (news, printouts) or on folder selection, so usage context is clear but not exhaustive.

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, closed-world, so the safety profile is covered. The description adds nothing beyond that: no mention of what a lesson entry contains, how many days 'week' spans, or what happens when no lessons exist. It is essentially a restatement of the available scopes.

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 tight sentence with zero filler, and the scope enumeration is front-loaded. The only weakness is the absence of a leading verb, making it read more like a feature label than an action statement.

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-required-parameter read-only tool this is roughly adequate, but with no output schema the description should hint at the shape of a lesson entry (subject, time, group) and clarify the default behavior (schema says default 'week'). It leaves the agent guessing about the return payload.

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 baseline is 3. The description's scope list mirrors 'when'/'date'/'weekday' values already documented in the schema, including the override precedence, without adding syntax, defaults, or student-filtering semantics 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 resource (lessons) and enumerates the exact time scopes it resolves: today, next school day, this week, specific date, next weekday occurrence. It is clearly distinguishable from siblings like wilma_gradebook or wilma_homework, though it lacks an explicit verb such as 'returns'/'lists'.

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 implies when the tool applies via the enumerated scopes, but gives no guidance on choosing between the time modes (which parameter wins, what 'week' means) and no mention of alternatives like wilma_upcoming_exams for exam dates. The agent must infer routing entirely from the parameter 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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantial behavioral detail: what data is aggregated, that results are per child, the fields included for messages (ids, unread, replyCount), and how missing data is surfaced in an `unavailable` field with a concrete example. This is rich context beyond what annotations 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 with the core purpose and contents, followed by a caveat about unavailable data and a usage recommendation. Every sentence contributes useful information with no filler.

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

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

With no output schema, the description effectively explains the return contents and even notes the `unavailable` field limitation. For a complex aggregate tool with three optional parameters, this provides enough context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so all three parameters are already well documented in the input schema. The description does not add any parameter-specific meaning beyond implying per-child scope ('per child'), which is adequate but not compensating further.

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 that this tool returns a daily briefing per child, enumerating the exact data included: lessons, exams, homework, lesson notes, bulletins, and messages. It distinguishes itself from the many granular sibling tools by positioning itself as the best starting point for any school-related question.

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 says this is the best starting point for any question about school, which gives strong usage context. However, it does not name specific alternatives or state when not to use it, leaving the agent to infer that granular siblings like wilma_schedule or wilma_upcoming_exams exist for focused queries.

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 safety is covered. The description adds the shape of the result (subject, date, topic) but says nothing about ordering, default result count, or how the limit behaves when omitted.

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 with no filler. It is efficient, though its brevity borders on under-specification rather than optimal 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?

For a simple read-only list tool with two optional params and no output schema, the description covers what is returned. It is still incomplete on default limit/pagination and on the fact that omitting 'student' spans all children, which is only visible in the schema.

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

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

Schema coverage is only 50%: 'student' is documented in the schema but 'limit' has no description anywhere. The description mentions no parameters at all, so it does nothing to compensate for the undocumented limit or explain default behavior when student is omitted.

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 (upcoming exams) and enumerates the returned fields (subject, date, topic), which tells an agent exactly what it gets. It is distinguishable from siblings like wilma_grades or wilma_schedule by the 'exam' focus, though it does not explicitly contrast with them.

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

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

There is no statement of when to use this versus wilma_schedule, wilma_homework, or wilma_grades, and no prerequisites or exclusions. The parenthetical '(what to study)' hints at purpose but gives no routing guidance.

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