Skip to main content
Glama

Grades

get_grades

List grades with averages: numeric, point, descriptive and formative assessments, including observation cards. A point grade's raw is a score on the scale its category names, such as (0-100); point_results are period results on that scale…

Instructions

List grades with averages: numeric, point, descriptive and formative assessments, including observation cards. A point grade's raw is a score on the scale its category names, such as (0-100); point_results are period results on that scale, never averages. For a date range use get_grades_window. scope also changes the view this login's Librus session remembers and may not apply to formative rows. A grade whose formative_id equals a formative row's assessment.detail_id is one assessment, not two. grade_id is the grade's own Librus ID, not a formative detail_id. With scope all, corrects lists the grade_ids a correction replaces and corrected_by the later corrections of a grade; other scopes show no correction brackets and leave both null. behaviour_points are the Zachowanie row's points per semester, not grades.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "account_alias": "<account_alias>"
    },
    "name": "get_grades"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum items in this page.
scopeNoLibrus view: all, or its week or last_login recent-changes filter; not dates.all
cursorNonext_cursor from the previous page; omit for the first page.
account_aliasYesLogin alias from list_accounts.

Output Schema

NameRequiredDescriptionDefault
itemsYes
scopeYes
averagesYes
identityYes
paginationYes
observationYes
point_resultsYes
behaviour_pointsNo
descriptive_summariesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv2.8.1
    • addedOutput schema / $defs / BehaviourPointEntryItem
      Added value: +{
      +  "properties": {
      +    "category": {
      +      "type": "string"
      +    },
      +    "day": {
      +      "format": "date",
      +      "type": "string"
      +    },
      +    "detail_id": {
      +      "type": "string"
      +    },
      +    "metadata": {
      +      "items": {
      +        "maxItems": 2,
      +        "minItems": 2,
      +        "prefixItems": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "string"
      +          }
      +        ],
      +        "type": "array"
      +      },
      +      "type": "array"
      +    },
      +    "points": {
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "points",
      +    "detail_id",
      +    "category",
      +    "day",
      +    "metadata"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / $defs / BehaviourPointsItem
      Added value: +{
      +  "properties": {
      +    "entries": {
      +      "items": {
      +        "$ref": "#/$defs/BehaviourPointEntryItem"
      +      },
      +      "type": "array"
      +    },
      +    "semester": {
      +      "enum": [
      +        1,
      +        2
      +      ],
      +      "type": "integer"
      +    },
      +    "tally": {
      +      "description": "The number shown, never summed with or checked against the entries.",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "semester",
      +    "tally",
      +    "entries"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / $defs / FormativeGrade / description
      Removed value: -"One row of the grades page's formative-assessment (\"Oceny kształtujące\")\ntable. \"KARTA SPOSTRZEŻEŃ\" (observation card) appears as a subject value.\nThe same item may also appear in the grid with a matching `formative_id`."
    • removedOutput schema / $defs / GradeSummaryValue / description
      Removed value: -"Column presence, separate from its raw school-provided value.\n\nUnavailable columns have raw=None. Available columns preserve empty strings,\nunassigned markers such as '-', symbols, and descriptive values without\ninventing numeric conversions or dates."
    • changedOutput schema / $defs / Observation / properties / observed_at / pattern
      Previous value: -"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]{1,6})?(?:Z|[+-][0-9]{2}:[0-9]{2})?$"New value: +"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,6})?(Z|[+-][0-9]{2}:[0-9]{2})?$"
    • addedOutput schema / properties / behaviour_points
      Added value: +{
      +  "default": [],
      +  "items": {
      +    "$ref": "#/$defs/BehaviourPointsItem"
      +  },
      +  "type": "array"
      +}
  2. Changed3 schema fields changedv2.7.0
    • addedOutput schema / $defs / GradeItem / properties / corrected_by
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / GradeItem / properties / corrects
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / $defs / GradeItem / properties / grade_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
  3. Changed8 schema fields changedv2.5.0
    • removedOutput schema / $defs / FormativeItem / additionalProperties
      Removed value: -false
    • removedOutput schema / $defs / GradeItem / additionalProperties
      Removed value: -false
    • changedOutput schema / $defs / GradeItem / properties / record_type / enum
      Previous value: -[
      -  "numeric",
      -  "descriptive"
      -]New value: +[
      +  "numeric",
      +  "point",
      +  "descriptive"
      +]
    • removedOutput schema / $defs / PresentationCursor / additionalProperties
      Removed value: -false
    • removedOutput schema / $defs / WindowPagination / additionalProperties
      Removed value: -false
    • removedOutput schema / additionalProperties
      Removed value: -false
    • addedOutput schema / properties / point_results
      Added value: +{
      +  "items": {
      +    "$ref": "#/$defs/SchoolAverage"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "items",
      -  "averages",
      -  "descriptive_summaries",
      -  "scope",
      -  "identity",
      -  "observation",
      -  "pagination"
      -]New value: +[
      +  "items",
      +  "averages",
      +  "point_results",
      +  "descriptive_summaries",
      +  "scope",
      +  "identity",
      +  "observation",
      +  "pagination"
      +]
  4. Changed4 schema fields changedv2.3.1
    • changedInput schema / properties / account_alias / pattern
      Previous value: -"^(?:[^\\s\\x00-\\x1f\\x7f]|[^\\s\\x00-\\x1f\\x7f](?:[^\\s\\x00-\\x1f\\x7f]| )*[^\\s\\x00-\\x1f\\x7f])$"New value: +"^[^\\s\\x00-\\x1f\\x7f](?: *[^\\s\\x00-\\x1f\\x7f])*$"
    • addedInput schema / properties / cursor / description
      Added value: +"next_cursor from the previous page; omit for the first page."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum items in this page."
    • addedInput schema / properties / scope / description
      Added value: +"Librus view: all, or its week or last_login recent-changes filter; not dates."
  5. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare readOnlyHint=false, and the description supplies the reason: 'scope also changes the view this login's Librus session remembers and may not apply to formative rows' — a hidden session-state side effect an agent could not infer. It further discloses that correction brackets (corrects/corrected_by) only populate under scope all and are null otherwise, which is exactly the kind of conditional behavior annotations cannot express.

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?

Purpose is front-loaded and the routing hint comes immediately after; nearly every clause carries a distinct semantic fact (raw scale, point_results vs averages, grade_id vs detail_id, correction brackets). It is dense and jargon-heavy with no paragraph breaks, so the correction and behaviour_points notes are easy to miss on a fast read.

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?

An output schema exists, yet the description still resolves the identity traps that schema alone leaves ambiguous: formative_id equals assessment.detail_id for the same assessment, and grade_id is not a formative detail_id. For a four-parameter read tool with one required argument, nothing an agent needs in order 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.

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning for scope beyond the enum default — it is a remembered server-side view, not a date filter, and may not apply to formative rows. That is semantic content the schema's 'Librus view: all, or its week or last_login recent-changes filter; not dates' cannot fully carry.

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?

States a specific verb and resource plus the subtypes returned: 'List grades with averages: numeric, point, descriptive and formative assessments, including observation cards.' That distinguishes it from get_final_grades and get_grades_window without opening either schema.

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

Usage Guidelines4/5

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

'For a date range use get_grades_window' names the alternative and the condition that selects it, and the scope sentence clarifies that scope is a Librus view flag, 'not dates', which prevents the common mistake of treating it as a date filter. It does not say when to prefer get_final_grades, but the primary routing decision is covered.

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