DeepMark

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

Annotations already establish readOnly/idempotent/safe-read, and the description goes well beyond them: it discloses the derived `awaiting` gate values ('triage' | 'confirmation' | null), the terminal-state set, and the surprising lifecycle behavior that paper-creation jobs do not self-complete. That is real behavioral context an agent cannot infer from the schema or annotations.

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

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

Three sentences, each doing distinct work: what is returned, the confirmation-park caveat, and the stop condition. Front-loaded with the core action and free of 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?

An output schema exists, so return-value documentation is correctly left out, yet the description still surfaces the derived `awaiting` gate and terminal states that drive the calling loop. For a single-parameter polling tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and there is a single required parameter, so the schema already fully documents `job_id` as the ID of the ingestion job. The description adds no format, sourcing, or error semantics beyond what the schema states; baseline 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?

States a specific verb and resource: 'Read the current state of an ingestion job', with the scope qualifier '(paper creation or document ingestion)' that ties it to the ingestion job family. This is clearly distinct from siblings like paper_get, results_get, or submission_get, which return domain objects rather than job state.

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

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

Explicitly says when to call it ('Poll this after starting a job'), when to stop ('on a terminal status (complete | failed | cancelled) or when an action is required'), and names the follow-up sibling (paper_confirm). It also flags the non-obvious case that a paper-creation job parks at awaiting_confirmation rather than running to complete, which is exactly the guidance an agent needs to avoid a polling loop.

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 the safety profile is covered. The description adds nothing further — no note on what happens for an unmigrated/unmarked answer, authorization needs, or result freshness — so it contributes no behavioral context of its own.

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 wasted words. It is efficient, though its brevity stems partly from omitting useful routing information rather than from disciplined editing.

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

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

For a one-parameter lookup with an output schema and annotations, the core need is covered and return values need not be explained. The missing piece is disambiguation from the other retrieval siblings, which is the main thing an agent could get wrong here.

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 single required parameter is fully documented in the schema (100% coverage), so the description merely restates 'by its ID'. Baseline 3 applies since the schema carries the semantics and the description adds no format or sourcing details.

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

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

States a specific verb ('Retrieve') and resource ('marking result for a specific answer by its ID'), which is clear and predictable. However, it does not distinguish itself from nearby siblings like results_get or submission_get, so an agent must infer which retrieval tool applies.

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 guidance and no alternative is named. With siblings such as results_get, submission_get, and submission_mark in the same family, the agent gets no help deciding which one to pick for a given task.

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 that this is a non-read-only, idempotent, non-destructive mutation, and the description adds only that it updates an existing record by ID. It does not disclose important behavioral details such as whether unspecified fields are preserved, whether content or mark_points are replaced wholesale, or any permission requirements.

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 a single front-loaded sentence with no wasted wording. It is appropriately concise, though its brevity leaves no room for structural guidance on the more complex mark scheme fields.

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

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

The tool has a fully documented schema, annotations covering its safety profile, and an output schema, so the description does not need to explain return values. However, for a five-parameter mutation involving nested mark points, it remains thin on update semantics and is only minimally sufficient.

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

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

Schema description coverage is 100%, so the input schema already documents all five parameters in detail. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 3 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: update an existing mark scheme by ID. It is clear what the tool does, though it does not explicitly distinguish itself from the related question_update 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?

The description implies that a valid existing ID is required, but it gives no explicit guidance on when to use this tool versus alternatives or what kinds of updates are appropriate. It is essentially a restatement of the action without usage 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 idempotentHint=true and destructiveHint=false, and the description reinforces idempotency with concrete semantics ('confirming an already-committed job returns its paper'). It also discloses that materialisation is synchronous, which is real operational context the annotations cannot express. It stops short of saying what happens to the extraction draft after minting or how a wrong-state job fails.

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?

Four tight sentences, front-loaded with the action and precondition, each carrying information. The closing 'Returns the exam_paper_id' is slightly redundant given an output schema exists, but it costs little.

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 a rich annotation set, 100% schema coverage and an output schema, the description covers the operation's key facts: prerequisite job state, synchronous materialisation, override/omit behavior, and idempotency. The remaining gap is failure and side-effect behavior — what happens to the draft or the job on success, and what an unsatisfied precondition yields.

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

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

Schema description coverage is 100%, so the schema already documents job_id, every override field, the subject enum, and the assessment_date caveat. The description only restates the override group at a high level ('optionally override the detected identity (title/subject/board/year)'); it notably omits assessment_date from that list and adds no formatting 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?

States a specific verb and resource — mint an ExamPaper from a job at awaiting_confirmation — and names the entities produced (ExamPaper, questions, mark schemes). It also anchors itself against paper_create (the producer of the job) and paper_get (the reader), so an agent can route without opening schemas.

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

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

Gives the precondition (job must be parked at awaiting_confirmation, created via paper_create) and the override rule: supply metadata to override, omit to inherit what extraction detected. It does not explicitly say what to do if the job is not yet parked, or point at a specific alternative for reading a paper instead.

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 annotations (which only say it is a non-readonly, non-idempotent, non-destructive write): it discloses asynchronous execution, the returned job_id, the required polling handshake, a hard rate limit of 3 papers per 24 hours, and the quality tradeoff when no mark scheme is supplied. It also clarifies marking existing papers is unaffected by the 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?

Front-loads the purpose, then the required input, then the optional path, then the async workflow, then the rate limit — a logical ordering with no wasted sentences. Capitalized RATE LIMITED emphasis highlights the constraint that would most likely cause a failed call.

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?

An output schema exists, so return values need not be described, yet the description still names the key field (job_id) and the follow-up calls. Combined with the rate limit and raw-text requirement, an agent has everything needed to invoke and complete the flow 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 four parameters including the nested hints object are already documented in the schema. The description reinforces the required/optional split and the 'send raw text' constraint, but adds no syntax, format, or length detail 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?

States a specific verb and resource — 'Create a complete, markable exam paper from pasted text' — and the scope (extraction from raw text) is unmistakable. It is clearly distinguishable from siblings like paper_confirm, ingestion_get, and paper_get, which are named as separate steps.

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 the full workflow explicitly: call this, poll ingestion_get until `awaiting_confirmation`, then call paper_confirm. It also states the conditional path for the mark scheme (supply it if available, omit it to have DeepMark generate one) and the negative instruction not to pre-structure text.

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, so the safety profile is covered. The description adds that question details come back in the payload, which is useful context, but says nothing about behavior when the ID is invalid or missing. With annotations carrying the main 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?

One short sentence with the key information front-loaded and no wasted clauses. It is close to minimal, though 'with question details' is slightly vague about what is actually returned.

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 simple read tool with one fully documented required parameter, a rich annotation set, and an output schema that handles return-value explanation. Nearly everything an agent needs to call it correctly is present; only error/not-found behavior is unaddressed, which is minor here.

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 single parameter has 100% schema description coverage ('The ID of the exam paper to retrieve'), so the schema does the work. The description only restates that lookup is by ID and adds no ID format, source, or validation details, matching the baseline 3 for high coverage.

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 ('Retrieve a specific exam paper by its ID') and adds that question details are included, which distinguishes it from a bare list call. It doesn't explicitly contrast with siblings like paper_list or submission_get, so an agent must infer the single-record vs. collection split.

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 by 'by its ID' — the agent can infer this is the single-record fetch when an exam_paper_id is known. There is no explicit when-to-use, no mention of when to prefer paper_list or another sibling, and no prerequisite or not-found 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 readOnlyHint, idempotentHint and closed-world, so safety is covered. The description adds nothing beyond that — no mention of default page size behavior, ordering, or what an empty result means.

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

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

A single front-loaded sentence with no filler. It is efficiently sized, though the brevity borders on under-specification rather than optimal conciseness.

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

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

The tool is a simple read with an output schema and fully documented parameters, so structured data carries most of the burden. The description is technically sufficient to invoke but omits any note on ordering, default behavior or result shape nuances.

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% with pagination defaults and a full subject enum documented in the schema. The description's 'optional filtering' merely restates this, adding no syntax or format detail, 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 all exam papers'), clearly distinguishing the read/list operation from paper_get and paper_create. It does not explicitly name or contrast with siblings, which is required for 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?

Only 'with optional filtering' hints at usage; there is no guidance on when to use this vs paper_get, whether results are paginated by default, or any prerequisites. An agent must infer the selection context entirely.

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/idempotent/openWorld false, and the description sensibly restates 'Read-only.' It adds real behavioral value: 'A pupil with no marking the caller may see returns found: false,' and notes class data comes from class lists so unmarked subjects still appear. This edge-case and data-provenance disclosure goes beyond the annotations.

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

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

Front-loaded with the resource and its content; dense but every clause describes a distinct part of the return. The semicolon-chained enumeration is efficient if slightly heavy, with no filler sentences.

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 an output schema and full annotations, the description is complete enough: it covers scope of returned data, the found:false case, and where to source pupil_id. It slightly over-explains return fields already in the output schema, but nothing critical is missing.

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

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

Schema coverage is 100%, so parameters (scope, subject default-to-most-marking, academic_year_id, pupil_id) are fully documented in the schema. The description mostly echoes this and only adds the provenance of pupil_id, leaving baseline 3 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?

States a specific resource (one pupil in one subject) and enumerates the returned artifacts: assessments across years with dates/grade/percentage, change since previous, target, skills vs class, and class enrollment history. An agent can clearly distinguish this from pupil_list (which enumerates pupils) and results_get.

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 for the required parameter: 'Take pupil_id from pupil_list or results_get.' That gives a clear entry path, but there is no explicit when-to-use-it-vs-siblings or exclusion statement (beyond the found:false edge 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?

Goes well past the annotations (which only cover readOnly/idempotent/closed-world) by disclosing pagination mechanics, result ordering per tab ("steepest first", "weakest first"), the fields returned per pupil (latest grade, change, target, listing reason), and the role-dependent scope resolution including that the answer self-reports when the view was downgraded.

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 scope and the tab taxonomy, then routing, then paging, then the read-only note. Efficient, though the per-tab definitions largely restate the enum descriptions in the schema and drift the sentence long.

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?

An output schema exists so return values needn't be explained, and 0 required params with 9 total filters means defaults carry the call. The definition covers the tab choice, scope semantics and paging loop; only the interaction between multiple simultaneous filters is left implicit.

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

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

With 100% schema coverage the baseline is 3; the description earns more by tying `offset` to the paging loop (pass next_offset) and by framing subject/class/year/assessment_point filters as sharing results_get's semantics, which the schema alone does not convey.

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

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

States a specific resource (pupils) and the exact taxonomy of views it returns (watch/thriving/below/drop/all), each defined by a concrete criterion. It also disambiguates from the two closest siblings: filters come from results_get and per-pupil detail comes from pupil_get.

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?

Clear routing: use the same filters as results_get to narrow, and pupil_get for the individual pupil link. It also tells the agent to page via next_offset. It stops short of an explicit statement of when NOT to use it (e.g. use results_get when you need raw assessment results rather than a pupil roster), leaving that 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 idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the precondition that the question must already exist ('existing'), but says nothing about partial-update semantics — whether omitted fields are left unchanged or cleared — which is the key behavioral question for an update tool.

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; nothing is redundant. It is arguably too terse for a mutation tool, but that shortfall is better attributed to completeness than to verbosity.

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 mutation tool with five optional fields, the description omits partial-update semantics, required-role/permission context, and behavior when the ID does not exist. The output schema covers return values and annotations cover safety, but the core update contract is 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?

Schema description coverage is 100% with enums documented for subject and difficulty_level, so the schema fully carries parameter meaning. The description contributes no additional detail such as whether at least one updatable field is required alongside id.

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 ('Update an existing GCSE question') plus the addressing key ('by its ID'), which is enough to distinguish it from sibling readers like ingestion_get or submission_mark. It does not explicitly contrast with markScheme_update, but the resource noun differs, so confusion risk is low.

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 use this rather than markScheme_update or paper_confirm, and no guidance on the update workflow (e.g., whether to fetch first, whether to send all fields or only changed ones). The agent must infer everything from the schema.

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

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

Annotations already declare read-only, and the description reinforces it while adding non-obvious behavior the schema cannot: the 12-cohort truncation rule that returns headline only, the exact grade formatting convention ('a group's average to one decimal'), and the instruction to quote figures and share dashboard_url rather than recompute. That is real behavioral context beyond the structured fields, with no contradiction of readOnlyHint.

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

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

Front-loaded with purpose, then behavior, then a usage instruction — a sensible order. It is dense (two long sentences packing multiple clauses) but nearly every clause earns its place; minor trimming of the grade-formatting aside would tighten it.

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 an output schema present the description needn't describe return shapes, and it still covers the edge case that matters (large-cohort truncation), the id provenance needed to chain calls, and the read-only safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by establishing where ids come from (self-referentially from results_get/cohorts) and tying the absence of filters to the overview mode, which clarifies the default behavior of scope/academic_year_id. It adds orientation beyond the schema but not per-parameter syntax detail.

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

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

Opens with a specific verb-plus-resource framing ('How a school, department, year group or class is doing: average grade and percentage per cohort') and enumerates the exact outputs (average grade, percentage, change since previous assessment, strongest/weakest skills, every class). The dual mode — filtered cohort view vs. no-filter overview returning academic years, assessment points and cohort ids — makes it unmistakable against siblings like markResult_get or pupil_list.

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

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

Explicitly says what happens with no filters (it becomes the overview supplying the ids the filters and pupil tools take) and when to narrow ('over 12 cohorts... narrow by subject or year_group for classes and skills'). It does not name a sibling alternative for the detail-vs-summary decision beyond the 'detail: summary' hint, so it stops just short of a full when/when-not/alternative statement.

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 openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations by explaining the overall status remains 'grading' until every question is marked and that per-question marking_status, marks, level, and feedback are returned.

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 compact and front-loaded with the core read operation. The second sentence adds the polling instruction without unnecessary detail, and every element supports either selection or correct invocation.

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

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

Given a single required parameter, full schema coverage, rich annotations, and an output schema, the description is complete enough. It covers the operation, output contents, and polling context without needing to duplicate the output schema.

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

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

Schema description coverage is 100% for the single submission_id parameter, so the schema already documents it fully. The description only implies the submission relationship via 'created via submission_mark' and does not add parameter-specific semantics beyond that baseline.

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

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

The description uses a specific verb and resource: it reads grading state and per-question marks for a submission. It also distinguishes the tool from submission_mark by noting that submissions are created via that sibling and that this tool should be polled afterward.

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 explicitly says to poll after submission_mark and identifies the parent operation that creates the submission. It does not name an alternative such as results_get or markResult_get, so it lacks explicit when-not guidance but gives clear usage 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?

Goes well beyond the annotations: it discloses that this is a mutating, asynchronous operation that creates a submission record, returns only a submission_id, and requires polling submission_get for grades. It also explains that results stream live into the teacher's editor, which the non-idempotent/create semantics alone would not convey.

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

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

Three sentences, no filler, with the core action first, then required inputs, then the async-return caveat front-loaded before an agent would try to read grades from the response.

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 create-and-grade tool with an output schema, the description covers what an agent needs to call it correctly: inputs, mutation semantics, and the fact that the response is a submission_id requiring a follow-up poll. Nothing material 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 the schema already documents exam_paper_id, answers, question_number and answer_text in detail. The description only restates that answers are keyed by question_number, adding no format or constraint detail beyond the schema — baseline 3.

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 ('Mark a student's typed answers against an existing exam paper') and names the canonical grading path, which clearly separates it from submission_get, markResult_get and results_get. An agent can tell exactly what this tool produces 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 states the prerequisite (an existing exam paper via exam_paper_id) and names the follow-up tool ('poll submission_get'). It does not state when *not* to use it (e.g. use a different tool for pre-existing submissions or non-text input), so it stops short of full routing guidance.

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