DeepMark

Get Results

results_get

Read-onlyIdempotent

How a school, department, year group or class is doing: average grade and percentage per cohort (one subject, one year group), the change since the previous assessment, strongest and weakest skills, and every class. With no filters it is also the overview — the academic years, the assessment points (data drops) and the cohorts and the teachers, with the ids the filters and the pupil tools take. For anything the single filters cannot say — several classes, everything except one class, one teacher's marking, a pupil by name — use filters, the dashboard's own filter builder. Over 12 cohorts (a whole school) it returns each cohort's headline only (detail: summary); narrow by subject or year_group for classes and skills. Grades are written as the dashboard writes them (a group's average to one decimal, e.g. 4.6). Read-only. Quote these figures rather than recomputing them, and share dashboard_url so the teacher can open the same view.

Input Schema

Name	Required	Description	Default
`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
`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
`year`	Yes
`scope`	Yes
`years`	Yes
`detail`	Yes	"summary" when there were more than 12 cohorts: each cohort's classes and skills are left out (empty). Narrow by subject or year_group for them.
`cohorts`	Yes
`heading`	Yes	What this is, e.g. 'English' or 'Your marking'.
`teachers`	Yes	The teachers whose marking is in view, with the ids the teacher filter takes. Pupils counts ignore any teacher filter, so every teacher stays choosable.
`scope_note`	Yes	Why the caller got less than they asked for, if they did.
`dashboard_url`	Yes
`filter_advice`	Yes	When the filters leave too few pupils to average: which one to remove, and what removing it gives back.
`filters_applied`	Yes
`filters_dropped`	Yes	Filters that matched nothing the caller can see and were NOT applied.
`unfiled_scripts`	Yes	Marked scripts filed under no assessment point, outside every year. Ask again with academic_year_id 'all' to include them.
`assessment_points`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 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 / filter_advice

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "When the filters leave too few pupils to average: which one to remove, and what removing it gives back."
+}

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"
+]

addedOutput schema / properties / teachers

Added value: +{
+  "description": "The teachers whose marking is in view, with the ids the teacher filter takes. Pupils counts ignore any teacher filter, so every teacher stays choosable.",
+  "items": {
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "pupils": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "teacher_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "teacher_id",
+      "name",
+      "pupils"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "detail",
-  "scope",
-  "heading",
-  "scope_note",
-  "year",
-  "years",
-  "assessment_points",
-  "cohorts",
-  "filters_applied",
-  "filters_dropped",
-  "unfiled_scripts",
-  "dashboard_url"
-]New value: +[
+  "detail",
+  "scope",
+  "heading",
+  "scope_note",
+  "year",
+  "years",
+  "assessment_points",
+  "cohorts",
+  "teachers",
+  "filters_applied",
+  "filters_dropped",
+  "filter_advice",
+  "unfiled_scripts",
+  "dashboard_url"
+]

Changed10 schema fields changedNov 2, 2026
- removedOutput schema / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / assessment_points / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / cohorts / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / cohorts / items / properties / change / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / cohorts / items / properties / classes / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / cohorts / items / properties / skills / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / filters_applied / items / additionalProperties
```
Removed value: -false
```
- removedOutput schema / properties / filters_dropped / items / additionalProperties
```
Removed value: -false
```
- changedOutput schema / properties / year / anyOf
```
Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "type": "string"
-      },
-      "label": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "label"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "label": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "label"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / properties / years / items / additionalProperties
```
Removed value: -false
```
AddedNov 1, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses non-obvious behavior: scope escalation (anyone without department visibility silently gets their own marking and 'the answer says so'), the >12 cohort headline-only truncation, grade formatting conventions, dropped filter values, and generated dashboard_url. That is real behavioral context an agent could not infer from 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.

Conciseness4/5

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

Front-loaded with what the tool returns, then usage, then caveats and output conventions. Sentences are long and dense, and the overview-mode point is restated across the opening, but nearly 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.

Completeness5/5

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

With an output schema present, return-value documentation is unnecessary, and the description covers what remains: scope semantics, truncation at 12 cohorts, filter composition, and dashboard_url. Nothing an agent needs to call this correctly appears missing.

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 description coverage is 100%, so the baseline is 3; the description adds value by explaining how the filters array composes with the top-level arguments (AND across conditions, OR within values) and what happens to unmatched values (filters_dropped). It stops short of adding much beyond the already-rich schema text for the individual parameters.

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

Purpose4/5

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

The description concretely states the resource and output shape: cohort averages, percentage per cohort, change since previous assessment, strongest/weakest skills, and every class, plus an overview mode returning academic years, assessment points and teachers. It implicitly separates itself from the marking/pupil tools by framing everything around aggregates and pointing pupil-by-name lookups elsewhere, but never names a sibling tool explicitly, which keeps it at 4 rather than 5.

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

Usage Guidelines5/5

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

It gives explicit when-to-use conditions: no filters yields the overview with ids for other tools; single filters handle one subject/year group; the filters array is for 'several classes, everything except one class, one teacher's marking, a pupil by name'. It also states the escalation path (narrow by subject or year_group when over 12 cohorts) and what to do with results (quote rather than recompute, share dashboard_url).

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?