exam.now

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

Annotations already declare this a read-only, idempotent, non-destructive operation, so the description earns credit for going beyond that. It discloses two behavioral traits that matter for interpretation: results are anonymised (no pupil names) and small groups are suppressed for privacy, meaning counts and bands may be withheld or incomplete. It does not explain the suppression threshold or what 'started' means, which keeps it below 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?

Two tight sentences, front-loaded with scope and immediately followed by the privacy caveat. The opening is a sentence fragment ('For a teacher's own exam.now class: ...'), which is slightly awkward but not wasteful; no sentence is redundant.

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 aggregation tool with full schema coverage and no output schema, the description adequately sketches the return shape (topic bands, count of pupils started) and flags the privacy suppression that would otherwise surprise an agent. Minor gaps around grouping granularity and thresholds remain, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so both parameters are already documented, including the hint that omitting class_id targets the teacher's own class. The description reinforces the 'own class' default but adds no new syntax, format, or edge-case detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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 precisely: class-level topic bands plus a count of pupils who have started, scoped to the teacher's own exam.now class. That is specific enough to separate it from per-pupil siblings like topic_progress or common_mistakes. It stops short of naming an alternative outright, so it is a strong 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?

Usage is only implied through the phrase 'For a teacher's own exam.now class', which signals the audience and default scope but not the conditions under which an agent should pick this over topic_progress or common_mistakes. There are no explicit when-not-to-use statements or named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and a closed-world scope, so safety is covered. The description adds real behavioral context beyond that: a hard cap of 5 results, the provenance (Cambridge examiner reports), and the shape of each item (short summary plus a link).

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 result cap and provenance front-loaded, followed by the narrowing advice. The only blemish is the odd 'exam.now' token, which reads like a stray artifact and slightly blunts an otherwise clean 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 small read-only lookup tool with no output schema, the description covers the essentials: bounded result count, source, per-item structure, and how to filter. It lacks detail on what happens when no mistakes match, but nothing critical to correct invocation 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%, with all three parameters documented with examples (query 'bounds', topic 'E1.10', subject codes like 0580). The description only restates the topic/query narrowing at a high level, adding nothing the schema does not already carry.

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

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

The description gives a specific verb-and-resource pair: retrieving up to 5 examiner-report write-ups of common mistakes for a subject. That is clearly distinct from siblings like find_questions_by_topic or get_mark_scheme, though it never explicitly contrasts itself 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?

It tells the agent how to narrow results (topic code or words), which is useful operational guidance. It does not say when this tool is preferable to find_questions_by_topic or topic_progress, nor when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds value beyond that by disclosing the return payload shape (component, date, AM/PM session, duration, plus a timetable link) and the zone default, which matters because 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 dense sentence that front-loads the resource and scope before the field list, with no filler. It is slightly list-heavy but every clause carries information an agent needs.

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

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

For a three-parameter read-only lookup with no output schema, the description covers purpose, defaults, series options and returned fields. It stops short of stating error behavior for unknown syllabus codes or whether results are authoritative, which are minor omissions at this complexity level.

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 33%, so the description carries extra burden. It does clarify that subject_codes accepts one or more syllabuses and that series is June or November 2026, and it explains zone functionally as the UK timetable default; however it never explains what zones 1-6 represent or what the 10-code cap means in practice.

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 specific resource (Cambridge exam dates), the scope (one or more syllabuses), and the two series it covers, then enumerates the returned fields: component, date, session and duration. No sibling tool deals with timetables, so there is no ambiguity about which tool to pick for this need.

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 scope statement rather than stated: an agent can infer it should call this when it needs exam dates for specific syllabuses. There are no explicit when-to-use/when-not rules and no alternatives named, though none of the siblings overlap, which limits the practical cost of that gap.

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 real value by enumerating the returned fields (paper_id, title, session, duration, marks, on-screen answerability, links to question paper/mark scheme/examiner report) despite there being no output schema. However, it says 'returns up to 10 papers' while the schema defaults limit to 5, and it never says whether results are ranked or truncated silently — a minor opacity worth noting.

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

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

Three tight sentences, front-loaded with the action and scope, then the return payload, then the downstream handoff. No filler or redundant restatement of the title.

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?

A 9-parameter, zero-required search tool with no output schema and no annotation gaps — the description covers what comes back and where to go next, which is what an agent most needs. It falls short on how structured fields interact with 'query' (mutually exclusive or additive?) and on the paper-vs-variant semantics, which matters for Cambridge codes like '0580 june 2024 paper 4'.

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?

Without a description, only 4 of 9 parameters carry schema text (query, series, subject_code, qualification), and board/paper/variant/year/limit are bare. The description restates the free-text-vs-structured split and reuses one example query, but never explains the meaningful distinction between 'paper' and 'variant', what 'series' values mean in board-specific terms, or that year/board/paper combine as filters. Helpful but not compensating for the 44% 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 (find past papers) plus the three supported boards and the source (exam.now), and gives a concrete example query. It also implicitly distinguishes itself from retrieval siblings by saying the resulting paper_id should be used with get_question, get_mark_scheme or get_paper, so an agent can tell search from fetch-by-id.

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

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

Explains the two entry modes (free-text query or structured fields) with a worked example, and routes the agent onward to get_question/get_mark_scheme/get_paper once a paper_id is obtained. It stops short of saying when NOT to use it — e.g. exam_timetable for dates or find_questions_by_topic when the agent wants questions rather than papers.

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 useful return-shape context with no output schema, but it lists "the paper's general marking principles" as returned content while the schema defaults include_principles to false, which can mislead, and it says nothing about behavior for an unknown part id or paper.

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 front-loaded sentence with no filler, and every clause documents a distinct returned field. The long enumeration of row fields makes it slightly dense to scan, but nothing is redundant.

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 thoroughly: row codes, marks, answer, guidance, alternatives, part maximum, principles, PDF page and link. Only failure behavior and the paper_id source (covered in the schema) are unaddressed.

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

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

Schema description coverage is 100%, so paper_id, part and include_principles are already documented with formats and an example, and the description adds no syntax or constraint detail beyond that. The clause about marking principles loosely maps to include_principles but does not clarify the default behavior, so the baseline of 3 applies.

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

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

States a specific verb and resource ("official mark-scheme rows") and narrows scope precisely to "one part of an exam.now past paper", so the granularity is unambiguous. It does not name a sibling or state how it differs from get_question or mark_answer, which keeps it 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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as get_paper or mark_answer. The only usage signal is implicit in the phrase "for one part of an exam.now past paper", leaving the agent to infer the workflow context.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them: the account-link prerequisite for mark schemes, the fact that results arrive paged a few questions at a time, and that mark-scheme rows correspond to the same questions returned. It does not note whether there is a total-count or end-of-paper signal.

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 return shape, then pagination, then the optional flag; no filler. The single flaw is the inaccurate 'next_from' label, an error of precision rather than length.

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

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

No output schema exists, and the parenthetical enumeration of returned fields does the job of describing the response. For a read-only, four-parameter retrieval tool this is nearly sufficient; the gaps are how pagination terminates and how large a paper is, both minor.

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

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

With 75% schema coverage the schema documents count, paper_id and from_question, and the description adds meaning to include_mark_scheme ('adds the mark-scheme rows for the same questions', needs a linked account) that the bare boolean lacks. The only defect is the mismatched name 'next_from' for the pagination parameter, which slightly muddies rather than clarifies from_question.

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 verb+resource ('An exam.now past paper as structured JSON') and enumerates the payload (metadata, questions, parts, prompts, marks, answer kinds, figure URLs), which lets an agent distinguish it from a single-question fetch. It never explicitly contrasts itself with the sibling get_question, so it falls short of a 5.

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

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

Gives real usage context: paginate with the next-page parameter and only set include_mark_scheme when a linked account exists. However, it never says when to prefer this over get_question or find_past_paper, and it refers to 'next_from' while the schema's parameter is named from_question, which can send an agent looking for a nonexistent argument.

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 genuine behavioral context—what the payload contains (alt text on figures, response kinds, whether a calculator is allowed, a deep link) — which tells the agent what to expect without a separate 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?

Two sentences: the first front-loads the resource and its payload, the second resolves the only ambiguous parameter choice. The long field list is dense but every item is returned content the agent would otherwise have to discover by calling.

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

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

With no output schema, the description appropriately enumerates return fields, and the four parameters are covered by schema plus the question/part note. It stops short of describing failure behavior for an invalid paper_id or a part that doesn't exist, which would matter for a lookup 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 100%, giving a baseline of 3, and the description adds real meaning by clarifying the question-vs-part relationship: 'question' returns the whole item while 'part' narrows to one sub-part such as 3(a)(i). That relationship is not spelled out in the schema itself.

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 ('The text of one question or part from an exam.now past paper') and enumerates the returned content: prompt, marks, figures, answer surface, topic codes, link. This makes it distinguishable from get_paper (whole paper) without naming that sibling explicitly.

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

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

Usage guidance is limited to the parameter distinction 'Pass question for the whole question or part for one part', which is more about invocation than when-to-use. It never states when to choose get_paper or find_questions_by_topic instead, so the agent must infer the selection rule from the sibling names.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, yet the description still adds real context: the call persists the mark to the student's progress and returns marks awarded/available, earned and missed mark-scheme rows, feedback, and a common-mistake link. The authentication prerequisite is disclosed. It could say more about what happens on re-marking the same part or any quota 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?

Front-loaded with verb and resource, then the return payload, then the prerequisite — a sensible order. It is dense with a long multi-clause sentence, but each clause carries distinct information (inputs, outputs, side effect, auth), so 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?

With no output schema, the description correctly enumerates the return shape (marks, mark-scheme rows, feedback, common-mistake link) and the persistence side effect. The account prerequisite is covered. Minor gap: nothing about failure modes (e.g. invalid part id) or re-marking behavior, though idempotentHint covers part of that.

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 four parameters are already documented with examples and constraints. The description reinforces the 'one part' granularity but adds no syntax, format, or interaction detail (e.g. how working interacts with answer) beyond the schema. 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: marks a student's answer to one part against the official mark scheme using exam.now's marker. The granularity ('one part') and the actor (the marker) are explicit, which separates it from siblings like get_mark_scheme (retrieval) and practise_question (practice generation).

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

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

Gives clear context: it requires a linked exam.now account with marking enabled, and paper_id must come from find_past_paper, which implicitly routes the agent through that sibling first. It stops short of naming when NOT to use it or how it differs from practise_question, so no explicit exclusions.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world behaviour, so the bar is lower. The description adds real context beyond that: the response is a practice card including figures and an answer surface, and the model receives the full question text so it can hint without revealing the answer. Minor gaps remain (what happens if the part/question is absent, no pagination or size notes).

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

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

Three short sentences, front-loaded with the primary action and artifact, with no filler. The middle sentence about hints is slightly indirect in wording ('gets the full question so it can give hints without giving the answer away') but still earns its place by explaining the exposure model.

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

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

With no output schema, the description usefully characterises the return value (practice card, figures, answer surface). Combined with full schema coverage and clear read-only annotations, an agent has enough to call it correctly; only edge-case behaviour for missing question/part identifiers is unaddressed.

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

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

Schema description coverage is 100%, so paper_id, question and part are already well documented with formats and examples. The description adds no additional meaning about these parameters (e.g. how paper_id relates to find_past_paper output beyond what the schema says), 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 a concrete verb and resource ('Show one past-paper question as a practice card') and specifies the rendered artifacts (figures, answer surface), which is more than a restatement of the title. It does not, however, distinguish this from sibling tools like get_question or find_questions_by_topic, so an agent cannot tell from the description alone whether this is the retrieval tool or a presentation variant.

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 the practice/study context and explicitly routes the marking step to mark_answer, which is genuinely useful. It stops short of stating when to prefer this over get_question or find_questions_by_topic, and gives no prerequisites or exclusions, leaving the main sibling decision to inference.

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

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuine context beyond them: the band vocabulary (secure / getting there / not yet), the fixed count of three recommended topics, and the presence of practise links – effectively describing return content where no output schema exists. It stops short of stating what happens when the student has no data for a subject.

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

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

One dense sentence with no padding: scope first, then the three payload elements in the order an agent would care about them. Every clause carries information that the structured fields do not.

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 correctly spends its words on the return content, so an agent knows to expect topic bands, a three-item recommendation list and practise links. It is slightly incomplete on edge cases (unknown subject code, student with no recorded progress) for a read tool keyed to an implicit 'linked student' context.

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

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

Schema description coverage is 100% and the single parameter already carries a format pattern plus concrete examples (0580, 0625, 1MA1). The description only reinforces that the code scopes to 'one subject', adding little beyond the schema. Baseline 3 applies.

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

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

The description names a specific resource – the linked student's own per-topic progress in a single subject – and enumerates what that means (topic bands, next three topics, practise links). It implicitly distinguishes itself from class-level siblings like class_summary by stressing 'the linked student's own', though the operative verb ('returns'/'reports') is never stated.

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 mention of 'next three topics to work on' and links 'to practise them' points toward a remediation/practise workflow that likely feeds practise_question or find_questions_by_topic, but no explicit when-to-use, when-not-to-use, or alternative is named. The agent must infer the routing from sibling names.

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