Is a weighted grade calculator for teachers and tutors who compute class grades each week.
Scored across 3 tools
The three tools have mostly distinct purposes: class grade calculation, final-exam score needed, and progress report generation. calculate_class_grades and generate_progress_reports overlap because both compute grades from a roster, but the descriptions clearly separate summary grade calculation from PDF report generation.
All tool names use snake_case and follow a verb_noun pattern: calculate_class_grades, calculate_grade_needed, generate_progress_reports. The verbs differ appropriately by action while the overall convention remains predictable.
Three tools is well-scoped for a grade-calculation and reporting server, and each tool covers a substantial, distinct workflow. There are no redundant or trivial tools.
The surface covers the core gradebook calculation workflows: class grades, what-if final scores, and printable progress reports. Minor gaps exist around direct gradebook editing or delivery of reports, but the descriptions explicitly scope those out and agents can work around them.
Use this when a teacher or tutor wants a weighted grade calculator for a whole class; list ID and info columns (student number, StudentID, email, SIS, section) in ignore_columns so they stay out of the grades. Examples: final grades from a gradebook, 'calculate my students' grades with Homework 20%, Quizzes 30%, Tests 50%', a gradebook template filled in, class average, or who is missing work. Takes a roster of scores (pasted table, list, or a Google Classroom / Canvas CSV or XLSX export as file) plus optional category weights, points possible, drop lowest per category, blank handling, extra credit and letter scale. Returns each student's final percent and letter (fraction math, rounded only for display), category scores, weights renormalized when a category has no graded work, class mean/median/distribution, missing-work list, and Excel + CSV downloads. Does not store data, connect to a school system, or make progress report PDFs (use generate_progress_reports).
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | A gradebook export as CSV or XLSX, e.g. the Google Classroom grades CSV or the Canvas gradebook export. One row per student, one column per assignment. | |
| term | No | Grading period, e.g. Fall 2026 Quarter 1. | |
| roster | No | The scores, one row per student: a pasted table (CSV, tab-separated or a markdown table) with a header row of assignment names, e.g. "Student, HW1, HW2, Quiz 1, Test 1\nAna Diaz, 18, 20, 9, 45\nBen Ito, 15, EX, 7, M". Also accepts a list of rows or [{"name":"Ana Diaz","scores":{"HW1":18,"Quiz 1":9}}]. Send this or file. | |
| blank_as | No | How to treat empty cells: not_graded (default, left out) or zero (count as 0). EX means excused (left out); M or missing counts as 0. | |
| students | No | Same as roster (either name works), e.g. [{"name":"Ana Diaz","scores":{"HW1":18}}]. | |
| id_column | No | The header of the student ID / student number column, if any, e.g. "StudentID". It is ignored (same as ignore_columns). | |
| categories | No | Category weights, e.g. "Homework 20%, Quizzes 30%, Tests 50%" or [{"name":"Quizzes","weight":30,"drop_lowest":1}]. Assignments are matched to categories by name (HW 3 -> Homework, Quiz 2 -> Quizzes, Unit Test -> Tests). Leave out for a total-points grade. | |
| class_name | No | Class name for the files, e.g. Algebra 1, Period 3. | |
| plus_minus | No | true for +/- letters (A+ 97, A 93, A- 90, ...). Default false. | |
| assignments | No | Optional details per assignment when names do not show the category or the points: [{"name":"Unit 1","category":"Tests","points_possible":50}], or lines like "Unit 1, Tests, 50". Mark bonus work with "extra_credit": true. | |
| drop_lowest | No | Drop each student's lowest scores per category, e.g. {"Quizzes": 1} or "Quizzes 1, Homework 2". A plain number applies to every category. | |
| letter_scale | No | Letter cutoffs. Default A 90, B 80, C 70, D 60, F below 60. Use "plus_minus" for A+ 97 / A 93 / A- 90 ... D- 60, or a custom list like "A 93, B 85, C 75, D 65". | |
| teacher_name | No | Teacher or tutor name for the reports, e.g. Ms. Rivera. | |
| ignore_columns | No | Columns that are not scores and must not be graded or copied, by header name: student IDs, student numbers, SIS/login/email, section, notes. Example: ["Student Number", "Email"] or "StudentID, Nr albumu". Always name ID and info columns here. | |
| points_possible | No | Points possible when the table does not say: one number for every assignment (e.g. 100), a list in column order (e.g. "20, 20, 10, 50"), or {"Quiz 1": 10}. A 'Points possible' row in the table or headers like "Quiz 1 (10)" also work. Default 100. | |
| category_scoring | No | How a category score is built: points (default, total points earned / possible in the category) or average (each assignment counts equally). | |
| round_for_letter | No | true to round the final percent to a whole number before picking the letter (89.5 -> 90 -> A). Default false: 89.5 is a B. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| notes | Yes | |
| pages | No | |
| stats | Yes | |
| grading | Yes | |
| privacy | Yes | |
| students | Yes | |
| warnings | Yes | |
| downloads | Yes | |
| categories | Yes | |
| class_name | Yes | |
| distribution | Yes | |
| graded_count | Yes | |
| letter_scale | Yes | |
| missing_work | Yes | |
| missing_total | Yes | |
| students_count | Yes | |
| students_shown | Yes | |
| assignments_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral detail beyond them: no data storage, no school-system connection, Excel + CSV downloads produced, exact fraction math with rounding only for display, and weight renormalization when a category has no graded work. What's left unstated are practical traits like runtime, input size limits, or how failures on malformed CSVs are reported.
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 a clean when-to-use sentence and closed with a clean exclusion sentence, and every clause carries information. The middle sentence is a dense run-on that packs inputs and outputs together, making it harder to scan than the surrounding prose, but no sentence is genuinely wasted.
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 17-parameter, nested-schema grading tool, the description covers the input shapes (pasted table, list, CSV/XLSX file), the opinionated defaults (blank handling, points possible, letter scale), and the outputs. With an output schema present, the return-value summary is bonus rather than required, so nothing an agent needs to call this 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 earns an extra point by promoting the easily-missed but critical parameter up front ('list ID and info columns ... in ignore_columns so they stay out of the grades') and by grouping the optional knobs (weights, points possible, drop lowest, blank handling, extra credit, letter scale) into a recognizable feature set. It does not add syntax or default detail beyond what per-parameter schemas already provide.
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 ('weighted grade calculator for a whole class') and immediately scopes it with concrete examples: a gradebook, pasted table, or Classroom/Canvas CSV. It also explicitly names what it is not ('Does not store data... or make progress report PDFs (use generate_progress_reports)'), which separates it from the sibling 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this when a teacher or tutor wants...' gives the triggering condition, followed by four worked examples (final grades, weighted percentages, template fill, class average, missing work) that tell an agent exactly what requests belong here. Exclusions are explicit and route to the named alternative; the 'whole class' framing also implicitly separates it from a single-student what-if calculation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks what they need on the final: 'what do I need on my final to get a B', final grade calculator, score needed on the final exam to pass, or a teacher asking what each student needs on the final for a C. Takes the current grade percent (or a list of students with current grades), how much the final is worth, and a target percent or letter (default all letters on the scale). Returns the score needed on the final for each target (and the points needed when final points are given), whether it is reachable, and what-if course grades. Assumes the final is a separate weight on top of the current grade; does not model a final inside a weighted category.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | The course grade wanted: a percent (90), a letter ("B") or several ("A, B, C"). Default: every letter on the scale. | |
| students | No | For a teacher: several students' current grades, e.g. "Ana Diaz 84.5, Ben Ito 71" or [{"name":"Ana Diaz","current_grade":84.5}]. Send this or current_grade. | |
| plus_minus | No | true for +/- letters. Default false. | |
| final_weight | Yes | How much the final counts toward the course grade, as a percent, e.g. 20 or "20%" (0.2 is read as 20%). | |
| letter_scale | No | Letter cutoffs for letter targets. Default A 90, B 80, C 70, D 60; "plus_minus" or a custom list like "A 93, B 85, C 75, D 65". | |
| current_grade | No | The grade before the final, as a percent, e.g. 84.5 or "84.5%". | |
| final_points_possible | No | Points on the final exam, e.g. 120, to also show the points needed. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| notes | Yes | |
| targets | Yes | |
| what_if | Yes | |
| students | Yes | |
| final_weight | Yes | |
| letter_scale | Yes | |
| current_grade | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the description is free to spend its words on what the computation returns (needed score per target, reachability, points needed, what-if grades). It also discloses the key modeling limitation that the final is treated as a separate weight and not a weighted-category component, which is exactly the kind of caveat annotations cannot 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?
Front-loaded with the triggering situation before the mechanics, and the closing assumption sentence is well placed. The first sentence is long with several quoted examples, but each clause carries routing value rather than filler.
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 need not restate return values, yet it still summarizes them and flags the reachability and points-needed outputs. Combined with annotations and full schema coverage, nothing an agent needs to select or call this tool 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%, so the parameters are already fully documented, and the description mostly paraphrases them (current grade, final weight, targets, default all letters). The one genuinely additive note is the 'students or current_grade' framing for the teacher case, which the schema also states, 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 ('calculate the score needed on the final') and enumerates the exact user phrasings that should route here. It is clearly distinct from calculate_class_grades and generate_progress_reports because it is per-final, per-target, not an aggregate report.
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 concrete triggering utterances ('what do I need on my final to get a B', 'score needed to pass') plus a teacher scenario, which is strong when-to-use guidance. It does not explicitly say when to prefer a sibling tool instead, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a progress report template filled in for students; list ID and info columns (student number, StudentID, email, SIS, section) in ignore_columns so they stay out of the grades. Examples: printable progress reports, grade reports for parents, 'make a progress report for each student'. Takes the same roster and grading settings as calculate_class_grades plus optional teacher comments per student, class name, teacher, term, report date and a subset of students. Returns one PDF with one page per student (current grade and letter, category scores, each assignment with excused/missing/dropped marks, missing work list, comment) and the Excel gradebook. Does not email or post reports, and does not store data.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | A gradebook export as CSV or XLSX, e.g. the Google Classroom grades CSV or the Canvas gradebook export. One row per student, one column per assignment. | |
| term | No | Grading period, e.g. Fall 2026 Quarter 1. | |
| paper | No | letter (default) or a4. | |
| roster | No | The scores, one row per student: a pasted table (CSV, tab-separated or a markdown table) with a header row of assignment names, e.g. "Student, HW1, HW2, Quiz 1, Test 1\nAna Diaz, 18, 20, 9, 45\nBen Ito, 15, EX, 7, M". Also accepts a list of rows or [{"name":"Ana Diaz","scores":{"HW1":18,"Quiz 1":9}}]. Send this or file. | |
| blank_as | No | How to treat empty cells: not_graded (default, left out) or zero (count as 0). EX means excused (left out); M or missing counts as 0. | |
| comments | No | Optional teacher comment per student, e.g. {"Ana Diaz":"Strong quiz scores; turn in HW 3."} or lines "Ana Diaz: Strong quiz scores". | |
| students | No | Same as roster (either name works), e.g. [{"name":"Ana Diaz","scores":{"HW1":18}}]. | |
| id_column | No | The header of the student ID / student number column, if any, e.g. "StudentID". It is ignored (same as ignore_columns). | |
| categories | No | Category weights, e.g. "Homework 20%, Quizzes 30%, Tests 50%" or [{"name":"Quizzes","weight":30,"drop_lowest":1}]. Assignments are matched to categories by name (HW 3 -> Homework, Quiz 2 -> Quizzes, Unit Test -> Tests). Leave out for a total-points grade. | |
| class_name | No | Class name for the files, e.g. Algebra 1, Period 3. | |
| plus_minus | No | true for +/- letters (A+ 97, A 93, A- 90, ...). Default false. | |
| assignments | No | Optional details per assignment when names do not show the category or the points: [{"name":"Unit 1","category":"Tests","points_possible":50}], or lines like "Unit 1, Tests, 50". Mark bonus work with "extra_credit": true. | |
| drop_lowest | No | Drop each student's lowest scores per category, e.g. {"Quizzes": 1} or "Quizzes 1, Homework 2". A plain number applies to every category. | |
| report_date | No | Date printed on the reports, e.g. October 26, 2026. Default: today (US Eastern). | |
| letter_scale | No | Letter cutoffs. Default A 90, B 80, C 70, D 60, F below 60. Use "plus_minus" for A+ 97 / A 93 / A- 90 ... D- 60, or a custom list like "A 93, B 85, C 75, D 65". | |
| teacher_name | No | Teacher or tutor name for the reports, e.g. Ms. Rivera. | |
| only_students | No | Optional subset of student names to print, e.g. "Ana Diaz, Ben Ito". Default: every student. | |
| ignore_columns | No | Columns that are not scores and must not be graded or copied, by header name: student IDs, student numbers, SIS/login/email, section, notes. Example: ["Student Number", "Email"] or "StudentID, Nr albumu". Always name ID and info columns here. | |
| points_possible | No | Points possible when the table does not say: one number for every assignment (e.g. 100), a list in column order (e.g. "20, 20, 10, 50"), or {"Quiz 1": 10}. A 'Points possible' row in the table or headers like "Quiz 1 (10)" also work. Default 100. | |
| category_scoring | No | How a category score is built: points (default, total points earned / possible in the category) or average (each assignment counts equally). | |
| round_for_letter | No | true to round the final percent to a whole number before picking the letter (89.5 -> 90 -> A). Default false: 89.5 is a B. | |
| show_class_average | No | Print the class average on each report. Default true. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| notes | Yes | |
| pages | No | |
| stats | Yes | |
| grading | Yes | |
| privacy | Yes | |
| students | Yes | |
| warnings | Yes | |
| downloads | Yes | |
| categories | Yes | |
| class_name | Yes | |
| distribution | Yes | |
| graded_count | Yes | |
| letter_scale | Yes | |
| missing_work | Yes | |
| missing_total | Yes | |
| students_count | Yes | |
| students_shown | Yes | |
| assignments_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description still adds real value: it enumerates what the PDF contains (current grade and letter, category scores, excused/missing/dropped marks, missing work, comment), states the Excel gradebook is also returned, and disclaims emailing/posting and data storage. Minor gap: no mention of size limits, failure modes (e.g. unparseable roster), or cost despite very large string caps.
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?
It is front-loaded: trigger first, then the ignore_columns tip, examples, input lineage, output contract, and exclusions in a logical order. It is dense but a few clauses merely re-list parameters already in the schema, which is the only thing trimming would improve.
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 22-parameter, nested-schema tool, the description still covers what it does, when to reach for it, the key pitfall (ID/info columns leaking into grades), the input source shared with calculate_class_grades, and the exact deliverable. An output schema exists, so its brief return summary is a bonus rather than a requirement.
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 baseline is 3 and the schema already documents most parameters in detail. The description adds procedural meaning for a few of the 22 params (ignore_columns must list ID/info columns 'so they stay out of the grades', optional comments/class name/teacher/term/report date, and a student subset), but leaves the others (categories, drop_lowest, letter_scale, category_scoring, points_possible) to 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?
It uses a specific verb+resource ('a progress report template filled in for students') and immediately scopes output ('one PDF with one page per student ... and the Excel gradebook'). It also positions itself against the sibling by saying it 'takes the same roster and grading settings as calculate_class_grades', 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('Use this when the user wants...'), three concrete example phrasings ('printable progress reports, grade reports for parents, ...'), and explicit exclusions ('Does not email or post reports'). It also names the sibling whose inputs it shares, which effectively routes agents between the two tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
calculate_class_gradescalculate_grade_neededgenerate_progress_reportsGrades from questions wrong, final exam score needed, weighted grades, GPA, SAT/ACT/MCAT scores.
Physics calculators that show their work, plus the CODATA 2022 constants. Educational use.
Verified maths exercises for tutors and their students, each answer key right by construction.
Exact arithmetic, algebra, calculus, physics, chemistry and finance with a checkable formula.
Add one secure layer between your agents and this server.
