DeepMark

List Pupils

pupil_list

Read-onlyIdempotent

Pupils to act on, as the dashboard's pupil tabs list them: "watch" (dropped half a grade or more, a grade or more below target, or well behind their class on a skill), "thriving", "below" (below target), "drop" (biggest drop, steepest first) or "all". Each pupil comes with their latest grade, the change since their previous assessment, their target and the reason they are listed. Narrow with the same filters as results_get. Paged: pass next_offset as offset for the next page. Each pupil's link comes from pupil_get. Read-only.

Input Schema

Name	Required	Description	Default
`list`	No	Which pupils, matching the dashboard's pupil tabs. "watch" (default): dropped half a grade or more, a grade or more below target, or well behind their class on a skill. "thriving": climbed, at or above target, or strongest in their year on a skill. "below": a grade or more below target. "drop": everyone who dropped, steepest first. "all": every pupil, weakest first.	watch
`limit`	No	Most pupils to return in one page.
`scope`	No	"department" (default) is the widest view the caller may see: the whole school for a school admin, their department for a head of department. Anyone else is given their own marking, and the answer says so. "mine" is always the caller's own marking.	department
`offset`	No	Pupils to skip, for the next page: pass next_offset from the previous answer.
`filters`	No	The dashboard's full filter builder, for anything the single arguments above cannot say. Every condition must hold (AND); the values inside one condition are alternatives (OR). Combines with the arguments above. Properties: "subject" (e.g. "english"), "class" (class_id), "teacher" (teacher_id from results_get's teachers: the teacher whose marking it is), "assessmentPoint" (assessment point id), "yearGroup" (e.g. "11"), "pupil" (a name or part of one). Operators: "is" and "is_not" take one value; "is_one_of" and "is_none_of" take a list. "pupil" instead takes "is", "contains" or "does_not_contain", with one value. Example, every Year 11 class except one, marked by one teacher: [{"property":"yearGroup","operator":"is","values":["11"]},{"property":"class","operator":"is_not","values":["<class_id>"]},{"property":"teacher","operator":"is","values":["<teacher_id>"]}]. A value matching nothing the caller can see is ignored and listed in filters_dropped.
`subject`	No	Narrow to one subject.
`class_id`	No	Narrow to one class. Ids come from results_get.
`year_group`	No	Narrow to one year group, exactly as results_get returns it in cohorts[].year_group: usually its number, "11" for Year 11.
`academic_year_id`	No	An academic year id (from results_get), or "all" for every year including marking filed under no assessment. Omit for the current year.
`assessment_point_id`	No	Narrow to one assessment point (a school's data drop, e.g. 'Y11 Mock 1'). Ids come from results_get.

Output Schema

Name	Required	Description
`list`	Yes
`scope`	Yes
`total`	Yes	Pupils on this list, across every page.
`offset`	Yes
`pupils`	Yes
`heading`	Yes
`scope_note`	Yes
`next_offset`	Yes	Pass as offset for the next page; null on the last page.
`empty_reason`	Yes	Why the list is empty, when it is.
`dashboard_url`	Yes
`filters_applied`	Yes
`filters_dropped`	Yes	Filters that matched nothing the caller can see and were NOT applied.
`too_many_to_list`	Yes	Cohorts with too many pupils to list (over 60, as on the dashboard). Ask again per class with class_id to see them.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 2, 2026

addedInput schema / properties / filters

Added value: +{
+  "description": "The dashboard's full filter builder, for anything the single arguments above cannot say. Every condition must hold (AND); the values inside one condition are alternatives (OR). Combines with the arguments above. Properties: \"subject\" (e.g. \"english\"), \"class\" (class_id), \"teacher\" (teacher_id from results_get's teachers: the teacher whose marking it is), \"assessmentPoint\" (assessment point id), \"yearGroup\" (e.g. \"11\"), \"pupil\" (a name or part of one). Operators: \"is\" and \"is_not\" take one value; \"is_one_of\" and \"is_none_of\" take a list. \"pupil\" instead takes \"is\", \"contains\" or \"does_not_contain\", with one value. Example, every Year 11 class except one, marked by one teacher: [{\"property\":\"yearGroup\",\"operator\":\"is\",\"values\":[\"11\"]},{\"property\":\"class\",\"operator\":\"is_not\",\"values\":[\"<class_id>\"]},{\"property\":\"teacher\",\"operator\":\"is\",\"values\":[\"<teacher_id>\"]}]. A value matching nothing the caller can see is ignored and listed in filters_dropped.",
+  "items": {
+    "properties": {
+      "operator": {
+        "enum": [
+          "is",
+          "is_not",
+          "is_one_of",
+          "is_none_of",
+          "contains",
+          "does_not_contain"
+        ],
+        "type": "string"
+      },
+      "property": {
+        "enum": [
+          "subject",
+          "class",
+          "teacher",
+          "assessmentPoint",
+          "yearGroup",
+          "pupil"
+        ],
+        "type": "string"
+      },
+      "values": {
+        "items": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        },
+        "maxItems": 50,
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "property",
+      "operator",
+      "values"
+    ],
+    "type": "object"
+  },
+  "maxItems": 20,
+  "type": "array"
+}

addedOutput schema / properties / filters_applied / items / properties / operator

Added value: +{
+  "enum": [
+    "is",
+    "is_not",
+    "is_one_of",
+    "is_none_of",
+    "contains",
+    "does_not_contain"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / filters_applied / items / required

Previous value: -[
-  "property",
-  "values"
-]New value: +[
+  "property",
+  "operator",
+  "values"
+]

Changed4 schema fields changedNov 2, 2026
- removedOutput schema / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / filters_applied / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / filters_dropped / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / pupils / items / additionalProperties
```
Removed value: -false
```
AddedNov 1, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world, so the bar is lower; the description still adds useful behavior: what each returned pupil carries (latest grade, change since previous assessment, target, listing reason) and the pagination contract ('pass next_offset as offset'). It omits the `filters_dropped` behavior for non-matching filter values, which lives only in the schema.

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

Conciseness4/5

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

Front-loaded and dense: the list semantics come first, then return shape, filtering, paging and sibling routing. Minor waste: the trailing 'Read-only.' repeats `readOnlyHint: true`, and the tab definitions are duplicated verbatim between description and schema.

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

Completeness5/5

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

Covers scope, filtering, paging, return shape ambiguity and sibling handoff for a 10-parameter tool; with an output schema present, the description does not need to enumerate return fields and correctly stops at a summary.

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

Parameters4/5

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

Schema coverage is 100%, so 3 is the baseline; the description earns above that by cross-referencing that `filters`/narrowing args mirror results_get's filters and by tying `offset` to the previous response's `next_offset`. The restated list semantics duplicate the schema's own enum descriptions.

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

Purpose5/5

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

Opens with a specific verb+resource framing ('Pupils to act on, as the dashboard's pupil tabs list them') and enumerates every value of `list` with its meaning. It also explicitly disambiguates from the sibling `pupil_get` ("Each pupil's link comes from pupil_get"), so an agent can tell the two apart 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.

Usage Guidelines4/5

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

Gives clear triggering context (dashboard pupil tabs) and routes the agent to `pupil_get` for the detail view and to `results_get` for the filter id vocabulary. There is no explicit when-not statement (e.g., 'do not use to fetch a single pupil'), but the sibling routing covers the practical alternative.

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

All DeepMark tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?