Skip to main content
Glama

What-if grade

what_if_grade
Read-onlyIdempotent

Recompute a class percent after hypothetical assignment scores using real PowerSchool assignment data, optional category weights, and compare the result with the portal’s reported grade.

Instructions

Recompute a class percent after hypothetical scores, using points-based math on the real assignment data (sum of score x weight over points x weight; exempt, uncounted and unscored items excluded; missing items count as 0 only if scored 0 by the teacher). Each hypothetical either adds a new assignment or, with replaces, swaps an existing one. If you know the class's category weights, pass category_weights for a weighted result. The output states its assumptions and compares against the portal's reported percent.

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": {
      "course": "<course>",
      "hypotheticals": "<hypotheticals>"
    },
    "name": "what_if_grade"
  }
}

Input Schema

NameRequiredDescriptionDefault
termNoGrade column, e.g. P1, S1. Default: current term
courseYesClass name (fuzzy) or period number
studentNoStudent to use: name, or index from list_students. Defaults to PS_DEFAULT_STUDENT, else the student PowerSchool shows.
hypotheticalsYes
category_weightsNoOptional {category: weight} if the class weights categories

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only declare read-only/idempotent/open-world; the description goes well beyond that by disclosing the exact math ('sum of score x weight over points x weight'), the exclusion rules (exempt, uncounted, unscored items), and the missing-item rule ('count as 0 only if scored 0 by the teacher'). It also describes the response behavior ('output states its assumptions and compares against the portal's reported percent'), which is valuable given 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.

Conciseness4/5

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

Front-loaded with the core action, then progressively adds the math model, the add-vs-replace rule, the weights option, and the output contract. Every sentence carries information, though the opening 'using points-based math on the real assignment data' is slightly redundant with the parenthetical formula that follows.

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

Completeness4/5

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

For a 5-parameter nested-schema tool with no output schema, the definition covers the essential computation model, exclusion rules, hypothetical semantics, and a summary of what the response contains. It leaves the unweighted-vs-weighted result format slightly underspecified, but an agent has enough to invoke it correctly.

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 80%, so the baseline is 3; the description earns extra by explaining the two semantics the schema only hints at — that each hypothetical either adds a new assignment or, with `replaces`, swaps an existing one, and that `category_weights` yields a weighted result. It does not elaborate on `term` or `student` defaults, but those are already documented in the schema.

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: 'Recompute a class percent after hypothetical scores,' and immediately qualifies the computation model ('points-based math on the real assignment data'). This is unmistakably a simulation tool, distinguishing it from retrieval siblings like get_class_scores or get_grades without needing to name them.

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 conditional guidance: pass `category_weights` only 'If you know the class's category weights,' and use `replaces` to swap rather than add an assignment. It does not explicitly name which sibling to use instead for real (non-hypothetical) grade reads, so it stops short of a full when/when-not/alternatives statement.

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