GPA Calculator MCP is an offline MCP server that performs tested GPA and grade calculations for AI apps.
Calculate term, cumulative, and credit-weighted GPA from course lists or transcript CSV, including drop-lowest courses and prior-term credits.
Convert grades between letters and percentages, and convert GPAs across built-in grade scales.
Determine the score needed on a final exam or assignment to reach a percentage or letter-grade target.
Combine weighted course components to show the current grade and the worst and best possible final grades.
Plan the GPA needed on upcoming credits to reach a target cumulative GPA.
Plan the minimum letter grade needed in each upcoming course to stay on track for a target GPA.
List all built-in grade scales, including US 4.0/4.3, Ontario college, UK classification, Australian, and weighted 5.0 scales.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GPA Calculator MCP What's my GPA with an A in 3 credits, a B+ in 4 credits and a C in 3 credits?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GPA Calculator MCP is a free, open source MCP server, published on npm as gpa-calculator-mcp. It is a GPA calculator for AI apps. Ask it to work out your GPA, your cumulative GPA (CGPA), your semester GPA (SGPA) or your weighted GPA with credit multipliers, plan the GPA you need to hit a target and the grade each upcoming course needs, convert grades between letters and percentages, do a GPA scale conversion for a UK class or an Australian grade, and figure out what grade you need on the final. The math is done by tested code, not guessed by the model.
Use it with Claude, ChatGPT, Cursor, VS Code Copilot and any other app that supports MCP. It runs on your computer, needs no internet and no login, and never sees your school account.
Free forever. No account and no subscription.
Run it straight from npm with npx. You need Node.js 20 or newer, see Node version for the details. There is nothing else to install, no account and no config file for the server itself.
npx -y gpa-calculator-mcpAdd it to your AI app's MCP config so the app can start it for you. Every app reads its config from its own file, so pick yours:
All of them start the same server the same way. The only difference is where the config goes.
Add this to claude_desktop_config.json:
{
"mcpServers": {
"gpa": {
"command": "npx",
"args": ["-y", "gpa-calculator-mcp"]
}
}
}Restart Claude Desktop after you save the file.
Run this in a terminal:
claude mcp add gpa -- npx -y gpa-calculator-mcpThe ChatGPT desktop app can start a server that runs on your computer. Open Settings, choose MCP servers, add a server, pick STDIO and give it the command npx with the arguments -y gpa-calculator-mcp. Save the server and restart the app.
The desktop app, the Codex CLI and the IDE extension read the same config file, ~/.codex/config.toml, so you can write the server there instead:
[mcp_servers.gpa]
command = "npx"
args = ["-y", "gpa-calculator-mcp"]Type /mcp in a chat to see the servers that are connected.
The ChatGPT website talks to servers over the web, so it needs a public HTTPS address. Put a tunnel in front of a server that runs on your computer, then add it as a custom MCP server from the Plugins page.
Cursor reads mcp.json from the project folder at .cursor/mcp.json, or from your home folder at ~/.cursor/mcp.json if you want the server in every project. On Windows the home folder file is %USERPROFILE%\.cursor\mcp.json.
{
"mcpServers": {
"gpa": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gpa-calculator-mcp"]
}
}
}Restart Cursor after you save the file. The Customize page in the sidebar lists the server once it starts, and you can turn it on or off there.
Put this in .vscode/mcp.json in your project folder, or in the mcp.json file in your user profile:
{
"servers": {
"gpa": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gpa-calculator-mcp"]
}
}
}VS Code also reads a portable .mcp.json file in the project root. That file uses the name mcpServers instead of servers:
{
"mcpServers": {
"gpa": {
"command": "npx",
"args": ["-y", "gpa-calculator-mcp"]
}
}
}Restart VS Code after you save the file.
After any of these, try one of the prompts below.
Related MCP server: Student Progress Tracker MCP Server
What do I need on the final?
"My grade is 85% and the final is worth 40% of the course. What do I need on the final to finish with a B+?"
The model calls needed_on_final with current_percent 85, final_weight_percent 40 and target_letter "B+" on the us4 scale. B+ starts at 87% on that scale, so you need 90% on the final to reach it.
Ask for a percentage target instead and the tool does the same sum. With current_percent 74, final_weight_percent 40 and target_percent 80, the other 60% of the course is locked in, so you need 89% on the final to reach 80%.
What is my GPA?
"What's my GPA if I got an A in 3 credits, a B+ in 4 credits and a C in 3 credits?"
calculate_gpa returns 3.12 across 10 credits on the us4 scale, with a per course breakdown.
Convert a grade
"Convert 78 percent to a letter grade on the Ontario college scale."
convert_grade returns the letter, the percentage range it covers and the grade points, using the ontario-college scale.
More things you can ask:
"I have a 3.1 GPA over 60 credits. What GPA do I need next semester to reach 3.4?"
"I have a 3.4 GPA over 60 credits. What do I need in each of my four classes next semester to reach 3.5?"
"My course is 20% quizzes, 30% labs, 50% exam. I have 85 on quizzes and 70 on labs. What's my grade so far and what's the best I can finish with?"
"What's my GPA on the UK classification scale if I got a 2:1, a 2:2 and a first?"
"What's my CGPA? I had a 3.2 GPA over 45 credits and this term I got an A in 3 credits, a B+ in 4 credits and a C in 3 credits."
"What's my weighted GPA if my two AP classes count 1.1 times the credits?"
"I have a 3.5 GPA on the US 4.0 scale. What is that in the UK?"
"Show me the grade scales you have built in."
Eight tools. These names are the ones your AI app sees.
Tool | Parameters | What it does | Example prompt |
|
| Calculate a GPA for a list of courses with credits and grades, optionally weighted with a | "What's my GPA if I got an A in 3 credits, a B+ in 4 credits and a C in 3 credits?" |
|
| Convert a letter or percentage to the matching letter, percentage range and grade points | "Convert 78 percent to a letter grade on the Ontario college scale." |
|
| Convert a GPA on one scale to the nearest band on another, such as a US 4.0 GPA to a UK class or an Australian grade. Leave | "I have a 3.5 GPA on the US 4.0 scale. What is that in the UK?" |
|
| Calculate the score you need on the final to hit a target, and say when it is already locked in or out of reach. Give the target as a percent or as a letter such as | "My grade is 85% and the final is worth 40% of the course. What do I need on the final to finish with a B+?" |
|
| Combine weighted parts into your grade so far and your worst and best possible finish; leave | "My course is 20% quizzes, 30% labs, 50% exam. I have 85 on quizzes and 70 on labs. What's my grade so far and what's the best I can finish with?" |
|
| Plan the GPA you need on upcoming credits to reach a target cumulative GPA | "I have a 3.1 GPA over 60 credits. What GPA do I need next semester to reach 3.4?" |
|
| Plan the GPA your upcoming courses need to reach a target cumulative GPA, and give the lowest letter in each course that keeps the plan on track | "I have a 3.4 GPA over 60 credits. What do I need in each of my four classes next semester to reach 3.5?" |
| none | List the grade scales built in, with their letter, percentage and points tables | "Show me the grade scales you have built in." |
Every tool description sent to your AI app ends with one example prompt, so the model can match a question like "What do I need on the final?" to the right tool and fill in every parameter.
Every tool also returns the same numbers as structured data. Each tool has an output schema, so a client that reads JSON gets fields such as term_gpa or needed_percent straight away, and the text answer stays the same for an app that only reads words. The fields each tool returns are listed in llms.txt and in glama.json.
Scale id | Description |
| Common US 4.0 scale with plus and minus grades, A is 4.0 and A- is 3.7 |
| Same as |
| A common Ontario college 4.0 scale, A+ and A are 4.0, B+ is 3.5. Check your own school's table |
| UK degree classification boundaries, a first, a 2:1, a 2:2 and a third, where a first is worth 4.0 grade points. Check your own school's table |
| Australian 7.0 scale, HD is 7, D is 6, C is 5 and P is 4. Check your own school's table |
| US weighted 5.0 scale, the |
The scale parameters take one of these six ids. A client that reads the tool schema sees them as the allowed values, and any other value is rejected before the tool runs.
Schools differ. Run list_scales to see the exact table used, and tell your AI if your school's cutoffs are different.
The two UK and Australian scales turn a class or a letter into grade points so the GPA tools can add up your work. For the UK table, a first is 4.0, a 2:1 is 3.3, a 2:2 is 2.7 and a third is 2.0. A UK degree is normally reported as a class, not a GPA, so treat those points as a way to compare and plan, not as an official number. Pass a class in a letter field as 1st, 2:1, 2:2 or 3rd, or pass a percentage and the server picks the class for you. The weighted-5.0 table is a plain mapping rather than one school's official table: it keeps the us4 cutoffs and puts every letter above F one point higher, so an A is 5.0. Pick it when your school reports a weighted GPA on a 5.0 top.
Run convert_gpa_scale to read a GPA on one scale as the nearest band on another, so a US 4.0 GPA can be read as a UK class or an Australian grade. It reads the GPA as a share of the top grade point on its own scale and picks the nearest band on the target scale. That is a comparison, not an official conversion, so check the target school's table.
Pass transcript_csv to calculate_gpa with your whole transcript as a CSV string. A header row is optional, the columns can be in any order, and headers like Course Title, Final Grade and Credit Hours are read as the name, grade and credits columns. A plain no header CSV works too, with columns in the order name, credits, grade.
Example:
Course,Credits,Grade
Calculus,4,A
History,3,B+
Chemistry,3,CRows with P, NP or W grades are left out of the GPA and named in the answer, except a P on the australia-hd scale, where P counts. If a header row has no credits or grade column, the tool says which column is missing. When courses is not given, transcript_csv is parsed and used as the course list.
What is the difference between CGPA and SGPA?
SGPA is the GPA for one term, so the GPA for the courses you pass in. CGPA is the cumulative GPA over every term you have finished. calculate_gpa gives you the term GPA for the courses you pass. Add your earlier GPA and credits as prior_gpa and prior_credits and the tool also gives the cumulative GPA.
Can I include my GPA from last semester?
Yes. Pass your earlier GPA as prior_gpa and your earlier credits as prior_credits to calculate_gpa, along with this term's courses. The tool folds them into a cumulative GPA. Pass both together. Passing only one of the two is an error, so the tool says which one is missing instead of quietly leaving the earlier terms out.
Can I give an AP class more weight?
Yes. Pass credit_multiplier on a course in calculate_gpa, for example 1.1 for an AP class that counts 1.1 times the credits. The plain term_gpa stays the same as it was, and the answer adds a weighted_gpa with the multipliers applied plus the weighted credits. Schools differ, so ask which multiplier yours uses. The weighted GPA covers the courses in that call, while the cumulative GPA keeps using the plain credits.
What about pass, fail and withdrawn courses on my transcript?
Pass transcript_csv to calculate_gpa with your whole transcript. A P is read as pass, NP as not pass and W as withdrawn. Those rows are left out of the GPA and named in a "Not counted in the GPA:" line, so the credits and the average only cover graded work. The one exception is a P on the australia-hd scale, where P is a graded pass worth grade points and still counts.
Portal exports with different column names work as they are: headers like Course Title, Final Grade and Credit Hours are read as the course name, grade and credits columns, in any column order. A header row that has no credits or grade column gets an error that names what is missing, instead of a parse failure further in.
What if my school uses a 4.3 scale?
Use the us4plus scale. It is the us4 scale with A+ worth 4.3. Pass scale "us4plus" to calculate_gpa, convert_grade or target_gpa_planner. Run list_scales to see the full table.
What grade do I need to pass?
It depends on your school and program. On the built in us4 scale, D covers 63 to 66 percent and is usually the lowest passing grade, but many programs require a C or higher. Use needed_on_final to work out what you need on the final, or target_gpa_planner to plan a cumulative GPA. Check your school's handbook for the real cutoff.
Can I ask for a letter grade instead of a percentage?
Yes. Pass target_letter to needed_on_final, for example target_letter "B+", and the tool looks the cutoff up in the scale table. Pass scale "uk-classification" for a UK class such as 2:1. You can pass target_percent as well, and the tool works to the higher of the two.
How do I convert my GPA to a UK or Australian scale?
Use convert_gpa_scale. Pass your GPA as gpa and the scale it is on as from_scale. Leave to_scale out and the tool gives the nearest band on both the uk-classification and australia-hd scales, or pass one of them to get only that one. It reads your GPA as a share of the top grade point on its own scale and picks the nearest band on the target scale. That is a comparison, not an official conversion, so check the target school's table.
Do my course parts have to add up to 100?
No. Every weight in weighted_grade is a percentage of the whole course, so you can pass only the parts you know. If you pass 20 percent quizzes and 30 percent labs with scores of 85 and 70, the tool says your grade so far is 76 percent, which banks 38 of the 100 points the course is worth, you finish at 38 percent if you score 0 on everything left, and you finish at 88 percent if you score 100 on everything left. The other 50 percent of the course is still to come. Weights that add up to more than 100 are an error, because a course is graded out of 100.
Can a script read the numbers without reading the sentence?
Yes. Every tool has an output schema and returns the numbers as fields next to the text, so a script can read term_gpa or needed_percent without taking them out of the sentence. The text answer is the same as it has always been.
Option | Needs login or school access | Runs offline | Focus | When to use |
GPA Calculator MCP (this server) | No | Yes | Just the numbers. GPA, CGPA, SGPA, weighted grades, targets and conversions. | You have numbers or want to plan and just need the calculation. |
LMS MCP servers (like Brightspace, Canvas, Moodle, Google Classroom) | Often yes, connects to a school system | Usually no | Pulls grades, due dates and course data from a learning system. Some include a target grade calculator. | You want to pull data straight from your courses, not type numbers in. |
For a student who just wants the number, a focused offline calculator avoids signing in, avoids connecting to a school server and keeps the task to arithmetic. If you already pull grades from an LMS, you can still pass those numbers to this calculator.
If you already pull grades from your learning system, you can combine them with this calculator. Brightspace MCP and Canvas MCP can fetch your grades from your course sites. Then you can ask this server to work out your GPA or figure out what you need on the final.
Pull your grades with Brightspace MCP, then call calculate_gpa or needed_on_final on the numbers it gives you.
Pull your grades with Canvas MCP, then call calculate_gpa or needed_on_final on the numbers it gives you.
Both are free and open source. See the list below for links.
If npx -y gpa-calculator-mcp fails or hangs:
Check your Node.js version with node --version. The server needs Node.js 20 or newer, see Node version.
Delete the folder where npx keeps its downloads, then try again. On Windows it is %LocalAppData%\npm-cache\_npx, and on macOS and Linux it is ~/.npm/_npx.
Make sure your computer can reach registry.npmjs.org. On a school network or behind a proxy, npm may need the proxy settings from your network's owner.
If node or npx is not found on Windows, reinstall Node.js with "Add to PATH" checked, then restart your terminal.
There are two floors here, and they are not the same number.
What you are doing | Node.js |
Running the published server | 20 or newer |
Building and testing a clone | 22.12 or newer, on the 22 and 24 release lines or 26 and later |
The server itself is happy on Node.js 20, and that is what engines in package.json says. The test runner wants a newer Node.js, so the development floor lives in devEngines in the same file. npm checks devEngines before install, run and test, so a clone on Node.js 20 stops with a clear message instead of a strange failure part way through the test suite. The 23 and 25 release lines are left out on purpose, because the test runner does not run on them.
Both numbers live in package.json, and a test in tests/node-version.test.ts keeps them in step with the README and with the range the test runner asks for.
npm install
npm run build
npm testThe tests call every tool through a real MCP client, so they need no account or network. They need the newer Node.js from the Node version section above, because of the test runner.
All free, open source and read only where they touch your accounts. Browse the full list at brightspacemcp.com/more-mcps.
Server | What it does |
D2L Brightspace for AI. Due dates with real submission status, grades, a target grade calculator and course files. | |
Canvas LMS for AI, read only. Due dates, missing work, grades and announcements. | |
Moodle for AI, read only. Due dates, overdue work, grades and announcements. | |
Google Classroom for AI, read only. Todos, due dates, missing work and grades. | |
APA, MLA and Chicago citations from a DOI, an ISBN or typed details. No account. | |
Exam study schedules, spaced repetition dates, pomodoro plans and assignment milestones. Works offline. | |
Search scholarly papers, find open access copies and related work through OpenAlex. No key needed. | |
Clean, convert, dedupe and lint BibTeX, RIS and CSL JSON reference lists, and make cite keys. Works offline. | |
Find free legal copies of textbooks on OpenStax, DOAB and Open Library, look up editions by ISBN and suggest cheaper older ones. | |
Chemistry and physics homework math: molar mass, balancing equations, grams to moles, unit conversion and significant figures. Works offline. | |
Offline writing metrics for essays. Word and page counts, readability scores, passive voice, repeated openers, filler words, long sentences and word limit checks, so students can check their work against assignment requirements. No account, no network. | |
Syllabus to calendar MCP server. Extract dates from syllabus text, build an ics calendar, expand recurring classes and merge calendars. Works offline, no account. | |
Job application tracker MCP server. Track internships, jobs, interviews and deadlines offline, see what is coming up, and export your list as CSV or Markdown. No account and no API keys. |
MIT
Calculate a GPA from a list of courses with credits and grades, optionally weighted with a credit multiplier on each course, and optionally combined with an earlier GPA and credit total. The GPA for the courses you pass is the term GPA, and adding earlier work with prior_gpa and prior_credits gives the cumulative GPA. Inputs: courses (each with credits greater than 0, a grade that is a letter like "B+" or a percentage like 87, and an optional credit_multiplier greater than 0 such as 1.1 for an AP class), a scale id, and optional prior_gpa and prior_credits to fold in earlier terms. A credit_multiplier above 1 gives a course more weight in the weighted GPA, and when any course has one other than 1 the tool also returns weighted_gpa and weighted_credits. The term GPA still uses the plain credits. Pass drop_lowest to leave the lowest graded courses out of the GPA, as schools do that drop the lowest course; the dropped courses are named in dropped_courses. Pass prior_gpa and prior_credits together, or leave both out. Passing only one of the two is an error, so the tool says which one is missing. Alternatively, pass transcript_csv as a CSV string with columns for course name, credits, grade and optional credit multiplier; a header row is optional, the columns can be in any order, and header names like Course Title, Final Grade and Credit Hours are read as the name, grade and credits columns. When courses is not given, transcript_csv is parsed and used as the course list. In transcript_csv, a P is read as pass, NP as not pass and W as withdrawn. Those rows are left out of the GPA and named in the answer, except where the scale gives the letter points, such as P on australia-hd. Example prompt: "What's my GPA if I got an A in 3 credits, a B+ in 4 credits and a C in 3 credits?"
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Grade scale id: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Defaults to "us4". Ask the student which one their school uses if unsure. | us4 |
| courses | No | The courses to include. Each needs credits (greater than 0) and a grade (a letter like "B+" or a percentage like 87). name is optional, and so is credit_multiplier (greater than 0), which gives a course more weight in the weighted GPA. Required when transcript_csv is not given. | |
| prior_gpa | No | GPA from earlier terms, 0 to 7. Pass this together with prior_credits to get a cumulative GPA. Passing only one of the two is an error. | |
| drop_lowest | No | Number of courses with the lowest grade points to leave out of the GPA, 0 or more, for schools that drop the lowest course. It must be less than the number of graded courses. Ties go to the course listed first. Defaults to 0. | |
| prior_credits | No | Credits from earlier terms, 0 or more. Pass this together with prior_gpa to get a cumulative GPA. Passing only one of the two is an error. | |
| transcript_csv | No | A CSV string with columns for course name, credits, grade and optional credit multiplier. A header row is optional, the columns can be in any order, and header names like Course Title, Final Grade and Credit Hours are read as the name, grade and credits columns. P, NP and W grades are left out of the GPA. When courses is not given, this is parsed and used as the course list. Example: "Course,Credits,Grade\nCalculus,4,A\nHistory,3,B+" |
| Name | Required | Description |
|---|---|---|
| scale | Yes | The scale id the courses were marked on. |
| courses | Yes | One entry per graded course, in the order they were passed. |
| credits | Yes | The credits of the graded courses in this call. |
| term_gpa | Yes | The GPA for these courses alone. |
| scale_name | Yes | The name of the scale the courses were marked on. |
| gpa_credits | Yes | The credits that count in the GPA, the same graded credits the term GPA is divided by. Excluded courses add nothing here. |
| weighted_gpa | No | The GPA with each course's credits multiplied by its credit_multiplier, when at least one multiplier other than 1 was passed. It covers the courses in this call, not the earlier terms. |
| cumulative_gpa | No | The GPA with the earlier terms folded in, when prior_gpa and prior_credits were both passed. |
| dropped_courses | Yes | Courses left out because of drop_lowest. Empty when drop_lowest is 0 or not passed. |
| excluded_courses | Yes | Courses left out of the GPA because they are not graded, such as P, NP and W rows in transcript_csv. Empty when none were left out. |
| weighted_credits | No | The credits after the credit multipliers are applied, when at least one multiplier other than 1 was passed. |
| cumulative_credits | No | The credits of these courses and the earlier terms together, when prior_gpa and prior_credits were both passed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses meaningful behavior: weighted GPA is returned only when a non-1 multiplier is present, dropped courses are named in dropped_courses, passing only one of prior_gpa/prior_credits is an error, and CSV P/NP/W handling varies by scale. These details give the agent genuine operational insight not supplied by the annotations alone.
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?
The description is front-loaded with the core purpose and covers the important branches without unrelated fluff. It is dense and somewhat long for a single paragraph, but the length is largely justified by the tool's many optional modes.
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?
Given six optional parameters, multiple scales, CSV parsing, and prior-term combination behavior, the description covers the scenarios an agent needs to invoke the tool correctly. An output schema exists, so it does not need to detail return values, and the annotations already establish the read-only/open-world profile.
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, but the description adds relational meaning such as term GPA vs cumulative GPA, paired prior_gpa/prior_credits requirements, the effect of credit_multiplier on weighted outputs, and CSV header aliases. Much of this overlaps with schema descriptions, so it is strong but not fully additive beyond 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?
The description gives a specific verb and resource: calculate a GPA from courses, with optional weighted, cumulative, dropped-course, and CSV-input variations. It is clear what the tool does, but it does not explicitly distinguish itself from siblings like target_gpa_planner or convert_gpa_scale.
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?
The description provides clear usage context: use it for term GPA, cumulative GPA by pairing prior_gpa and prior_credits, or when parsing a transcript_csv instead of courses. It does not explicitly state when to prefer this over sibling tools such as target_gpa_planner, so it falls 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.
Convert a GPA on one grade scale to the nearest band on another, so a GPA from one country can be read as a UK class or an Australian grade. Inputs: gpa (the GPA to convert, 0 to 7 and at or below the top of from_scale), from_scale (the scale the GPA is on, default us4) and optional to_scale (the scale to convert to; leave it out to convert to both the uk-classification and australia-hd scales). The GPA is read as a share of the top grade point on its own scale, then the nearest band on the target scale is returned with its percentage range and grade points. This is a common comparison, not an official conversion, so check the target school's table. Example prompt: "I have a 3.5 GPA on the US 4.0 scale. What is that in the UK?"
| Name | Required | Description | Default |
|---|---|---|---|
| gpa | Yes | The GPA to convert, between 0 and 7. It must be at or below the top grade point of from_scale. | |
| to_scale | No | Grade scale id to convert to: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Leave it out to convert to both the uk-classification and australia-hd scales. | |
| from_scale | No | Grade scale id the GPA is on: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Defaults to "us4". | us4 |
| Name | Required | Description |
|---|---|---|
| gpa | Yes | The GPA that was converted. |
| from_scale | Yes | The scale id the GPA was on. |
| conversions | Yes | One entry per target scale, in the order they were converted. |
| from_max_points | Yes | The top grade point of the scale the GPA was on. |
| from_scale_name | Yes | The name of the scale the GPA was on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description discloses the conversion method (GPA read as a share of the top grade point, nearest band chosen) and the important caveat that this is a comparison, not an official conversion. That is meaningful added context; only rate limits or precision/rounding edge cases are left unmentioned.
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-loads the purpose and the input list, then the mechanics and caveat, then the example. Slightly overlong — the example prompt and restating the parameter names cost some words — but nothing is truly 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?
An output schema exists, so return values need not be spelled out, yet the description still states the band/percentage/grade-point shape, which is helpful. For a three-parameter read-only converter this is essentially complete; only sibling disambiguation 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 every parameter is already documented, including the enum values, the from_scale default and the dual-output behavior when to_scale is omitted. The description restates those facts nearly verbatim rather than adding new semantics, 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 (convert a GPA between grade scales) plus the concrete outcome (nearest band with percentage range and grade points). It does not distinguish itself from the sibling 'convert_grade', which an agent could easily confuse with this one, so it falls short of a 5.
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 a clear motivating context (reading a GPA from one country as a UK class or Australian grade) and an example prompt, and explicitly explains the omitted-to_scale case. It names no alternatives or exclusions, so it never tells the agent when to prefer 'convert_grade' or 'target_gpa_planner' instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a letter or percentage into the matching letter, percentage range and grade points on a grade scale. Inputs: grade (a letter like "B+" or a percentage like 87 or "87%") and a scale id. Example prompt: "Convert 78 percent to a letter grade on the Ontario college scale."
| Name | Required | Description | Default |
|---|---|---|---|
| grade | Yes | A letter like "B+" or a percentage like 87 or "87%". | |
| scale | No | Grade scale id: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Defaults to "us4". Ask the student which one their school uses if unsure. | us4 |
| Name | Required | Description |
|---|---|---|
| scale | Yes | The scale id the grade was converted on. |
| letter | Yes | The letter the grade matches on the scale. |
| points | Yes | Grade points the letter is worth on the scale. |
| scale_name | Yes | The name of the scale the grade was converted on. |
| max_percent | Yes | The highest percentage the letter covers. |
| min_percent | Yes | The lowest percentage the letter covers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety behavior is covered. The description adds only that it maps across a named scale, with no mention of scale-dependent edge cases (e.g. an out-of-range percentage) — acceptable but not rich given annotations do the heavy lifting.
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?
Three short sentences, front-loaded with the purpose before inputs and example. Nothing is wasted, though the example prompt is somewhat illustrative filler rather than essential information.
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 and read-only annotations, the description need not explain return values or safety. Inputs and scale selection guidance are covered; only cross-tool routing advice is missing, which is a minor gap for a low-complexity two-parameter tool.
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% and both parameters are documented in the schema, including the enum list and default for scale. The description's example inputs ('B+', 87, '87%') duplicate what the schema already says, so it adds little beyond baseline.
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?
The description gives a specific verb (convert) and resource (grade) and states exactly what is returned: the matching letter, percentage range, and grade points. It is clearly distinguishable from siblings like calculate_gpa or needed_on_final, though it never explicitly names or contrasts them.
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?
Usage is well-contextualized with a concrete example prompt and an explicit instruction to ask the student which scale their school uses when unsure. It stops short of stating when-not to use this versus calculate_gpa or weighted_grade, so it is clear but not fully routing-aware.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the built-in grade scales with their letters, percentage ranges and grade points. Inputs: none. Example prompt: "Show me the grade scales you have built in."
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| scales | Yes | Every built-in scale, with its letters, percentage ranges and grade points. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered, and an output schema documents the return shape. The description adds only that the scales are "built-in" (i.e., fixed, non-user-defined), without addressing whether they can be customized or how they relate to the conversion tools. Note a mild tension: openWorldHint=true is odd for a fixed built-in list, though the description does not explicitly contradict it.
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?
Three short sentences, front-loaded with what is returned. "Inputs: none" and the example prompt are mild padding for a zero-parameter tool, but neither is misleading and both are cheap.
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, zero parameters, and read-only annotations, the description covers everything needed to call the tool correctly. Minor residual gap: it does not say whether these scales are the ones used by calculate_gpa/convert_grade, which would help the agent chain tools.
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?
The tool takes zero parameters, so the baseline is 4. The explicit "Inputs: none" statement usefully confirms to the agent that the empty schema is intentional rather than a truncated definition, though it adds nothing beyond the schema itself.
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?
The description names a specific verb and resource ("List the built-in grade scales") and even enumerates the returned attributes: letters, percentage ranges, grade points. It clearly reads as a catalog/listing tool, distinguishing it in practice from computing siblings like calculate_gpa or convert_grade, though it never names those alternatives.
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?
The example prompt ("Show me the grade scales you have built in.") gives a concrete, realistic trigger for selecting this tool, and "Inputs: none" confirms no setup is required. There are no explicit when-not conditions or named alternatives (e.g., "use convert_grade to map a specific score"), which keeps it out of the 5 band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the score needed on a final exam or last assignment to reach a target course grade. Inputs: current_percent (the average on all the other work, 0 to 100), final_weight_percent (how much the final is worth, greater than 0 and at most 100) and a target. Give the target as target_percent (the course grade you want, 0 to 100), as target_letter (a letter like "B+" or a class like "2:1", whose cutoff comes from the scale table), or as both. The scale id sets the table the letter cutoff comes from. Says so when the target is already locked in or out of reach. Example prompt: "My grade is 85% and the final is worth 40% of the course. What do I need on the final to finish with a B+?"
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Grade scale id: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Defaults to "us4". Ask the student which one their school uses if unsure. | us4 |
| target_letter | No | The letter grade you want to finish with, like "B+" or "2:1", read from the scale table. Leave it out when you pass target_percent. | |
| target_percent | No | The course grade you want to finish with, as a percentage between 0 and 100. Leave it out when you pass target_letter. | |
| current_percent | Yes | Current grade on the work already done, as a percentage between 0 and 100. | |
| final_weight_percent | Yes | How much the final is worth, greater than 0 and at most 100, as a percentage of the whole course. |
| Name | Required | Description |
|---|---|---|
| scale | Yes | The scale id the target was read from. |
| possible | Yes | True when the target can be reached with this weighting. |
| scale_name | Yes | The name of the scale the target was read from. |
| already_there | Yes | True when the target is already reached, so a 0 on the final keeps it. |
| target_letter | No | The letter target that was asked for, when one was given. |
| needed_percent | Yes | The score needed on the final. It is below 0 when the target is already reached, and above 100 when the target is out of reach. |
| target_percent | Yes | The course grade to finish with, as a percentage. |
| current_percent | Yes | The grade on the work already done. |
| letter_min_percent | No | The lowest percentage the letter target covers, when a letter target was given. |
| final_weight_percent | Yes | How much the final is worth, as a percentage of the whole course. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses that the tool reports when the target is already locked in or out of reach, and that letter cutoffs are resolved against the scale table. It does not discuss precision or rounding of the returned score, but the output schema exists to cover returns.
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?
Purpose is front-loaded in the first sentence, followed by a compact input enumeration and a closing example prompt that earns its place. The prose is somewhat list-like and repeats range constraints already in the schema, but nothing is truly 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?
With an output schema present, the description need not explain return values, and it covers the input semantics and the edge-case reporting behavior. The only gap is that it never positions the tool against target_gpa_planner or weighted_grade, which an agent choosing between grade-related siblings might want.
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. The description goes beyond it by explaining the relationship between target_percent and target_letter (either or both) and that the scale id determines which table letter cutoffs come from, which the schema only hints at. Ranges are restated rather than added, keeping it from a 5.
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?
The first sentence states a specific verb and resource: calculate the score needed on a final exam/last assignment to hit a target course grade. This is clearly distinguishable from calculate_gpa, convert_grade and weighted_grade, though no sibling is named explicitly. The purpose is unambiguous without opening the 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?
It explains the required inputs and, importantly, the three ways to express a target (target_percent, target_letter, or both), plus a worked example prompt that shows a realistic invocation. It does not say when to prefer target_gpa_planner or other siblings instead, so there is no explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan the grade needed in each upcoming course to reach a target cumulative GPA. Inputs: current_gpa (0 to 7), credits_completed (0 or more), target_gpa (0 to 7), courses (each with an optional name and credits greater than 0) and a scale id, which sets the top grade point the scale allows. It works out the GPA the upcoming credits need, then gives the lowest letter in each course that keeps the plan on track, assuming the other courses meet the same target. Says so when the target is already reached or would take more than one term. Example prompt: "I have a 3.4 GPA over 60 credits. What do I need in each of my four classes next semester to reach 3.5?"
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Grade scale id: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Defaults to "us4". Ask the student which one their school uses if unsure. | us4 |
| courses | Yes | The upcoming courses to plan for. Each needs credits greater than 0, and name is optional. | |
| target_gpa | Yes | The cumulative GPA you want to reach, between 0 and 7. | |
| current_gpa | Yes | Your cumulative GPA so far, between 0 and 7. | |
| credits_completed | Yes | Credits already completed, 0 or more. |
| Name | Required | Description |
|---|---|---|
| scale | Yes | The scale id the plan was made on. |
| courses | Yes | One entry per upcoming course, in the order they were passed. |
| possible | Yes | True when the target can be reached with these courses on this scale. |
| max_points | Yes | The top grade point the scale allows. |
| needed_gpa | Yes | The GPA needed on the upcoming credits. It is below 0 when the target is already reached, and above the top of the scale when the target takes more than one term. |
| scale_name | Yes | The name of the scale the plan was made on. |
| target_gpa | Yes | The cumulative GPA to reach. |
| current_gpa | Yes | The cumulative GPA so far. |
| already_there | Yes | True when the target is already reached, so a 0.0 on the upcoming credits keeps it. |
| upcoming_credits | Yes | The credits of the courses to plan for. |
| credits_completed | Yes | The credits already completed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds substantive behavioral detail beyond that: it computes the GPA the upcoming credits must average, then returns the lowest acceptable letter grade per course, and explicitly discloses the key assumption that other courses meet the same target. Edge-case messaging (target already met, more than one term needed) is also disclosed.
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?
Purpose and core mechanics are front-loaded in the first sentence, followed by inputs, algorithm, and an example — a sensible order. It is dense but every paragraph carries information; only the input enumeration partly duplicates the schema.
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 5-parameter read-only computation with a full schema and an output schema, the description covers the essential contract: inputs, the ceteris paribus assumption behind per-course targets, and out-of-scope outcomes. Return-format details are rightly left to the output schema.
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 baseline is 3, and the description adds real value by explaining that the scale id 'sets the top grade point the scale allows' — a semantic point the schema's enum list alone does not convey. The rest of the parameter restatement (ranges, credits > 0, optional name) is redundant with 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?
The opening sentence gives a specific verb and resource — planning the grade needed per upcoming course to reach a target cumulative GPA — which is clearly distinct from calculation-only siblings like calculate_gpa or convert_grade. It does not explicitly name the very similar-sounding target_gpa_planner sibling, so the agent must infer the difference from the description alone.
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?
The concrete example prompt ("I have a 3.4 GPA over 60 credits...") makes the intended usage scenario unambiguous, and the description notes what happens when the target is already reached or would need more than one term. It stops short of stating when to prefer this over target_gpa_planner or needed_on_final, so no explicit exclusion is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan the GPA needed on upcoming credits to reach a target cumulative GPA. Inputs: current_gpa (0 to 7), credits_completed (0 or more), target_gpa (0 to 7), upcoming_credits (greater than 0) and a scale id, which sets the top grade point the scale allows. Says so when the target is already reached or would take more than one term. Example prompt: "I have a 3.1 GPA over 60 credits. What GPA do I need next semester to reach 3.4?"
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Grade scale id: "us4", "us4plus", "ontario-college", "uk-classification", "australia-hd" or "weighted-5.0". Defaults to "us4". Ask the student which one their school uses if unsure. | us4 |
| target_gpa | Yes | The cumulative GPA you want to reach, between 0 and 7. | |
| current_gpa | Yes | Your cumulative GPA so far, between 0 and 7. | |
| upcoming_credits | Yes | Credits you will take next, greater than 0. | |
| credits_completed | Yes | Credits already completed, 0 or more. |
| Name | Required | Description |
|---|---|---|
| scale | Yes | The scale id the plan was made on. |
| possible | Yes | True when the target can be reached in one term on this scale. |
| max_points | Yes | The top grade point the scale allows. |
| needed_gpa | Yes | The GPA needed on the upcoming credits. It is below 0 when the target is already reached, and above the top of the scale when the target takes more than one term. |
| scale_name | Yes | The name of the scale the plan was made on. |
| target_gpa | Yes | The cumulative GPA to reach. |
| current_gpa | Yes | The cumulative GPA so far. |
| already_there | Yes | True when the target is already reached, so a 0.0 on the upcoming credits keeps it. |
| upcoming_credits | Yes | The credits you will take next. |
| credits_completed | Yes | The credits already completed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuine behavioral detail beyond that, disclosing that the tool reports when the target is already met or would require more than one term. It does not say what happens when the target exceeds the scale maximum or is otherwise unreachable.
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 purpose, followed by inputs, edge-case behavior, and an illustrative example — a sensible order. The input enumeration largely duplicates the schema and could be trimmed, but the example prompt earns its space.
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, return values needn't be explained, and the description covers inputs and key edge-case reporting. The remaining gap is failure/unreachable-target behavior, which an agent planning a call would benefit from knowing.
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 baseline is 3; the description goes slightly further by explaining that the scale id 'sets the top grade point the scale allows', which is semantic meaning not obvious from the enum alone. Other parameters are restated with their bounds, adding little beyond 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?
States a specific verb and resource: 'Plan the GPA needed on upcoming credits to reach a target cumulative GPA.' This is clearly distinct from a raw GPA calculator, though it never explicitly names or contrasts with siblings like calculate_gpa or needed_on_final.
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 usage context through enumerated inputs and a worked example prompt, making the triggering scenario obvious. It stops short of saying when not to use it or pointing to an alternative tool for single-assignment questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combine weighted course parts into the grade so far, plus the worst and best possible finish. Inputs: parts (each with a name, a weight that is a percentage of the whole course greater than 0, and an optional score between 0 and 100; leave the score out for parts that are not marked yet). Optional target_percent sets a course grade to work out the average needed on the unmarked parts. A weight is a percentage of the whole course, so the parts are never rescaled. Parts that add up to less than 100 leave the rest of the course still to come, and weights that add up to more than 100 are an error. Example prompt: "My course is 20% quizzes, 30% labs, 50% exam. I have 85 on quizzes and 70 on labs. What's my grade so far and what's the best I can finish with?"
| Name | Required | Description | Default |
|---|---|---|---|
| parts | Yes | The weighted parts of the course. Each needs a name and a weight (a percentage of the whole course greater than 0); score is 0 to 100, or leave it out for parts that are not marked yet. Weights are percentages of the whole course, so parts that add up to less than 100 leave the rest of the course still to come. | |
| target_percent | No | Optional target course grade in percent. When given, works out the average needed on the unmarked parts. |
| Name | Required | Description |
|---|---|---|
| parts | Yes | One entry per part, in the order they were passed. |
| possible | No | When a target_percent is given, true when the target can be reached. |
| best_finish | Yes | The course grade if every remaining part scores 100. |
| done_weight | Yes | The weight of the marked parts, as a percentage of the whole course. |
| total_weight | Yes | The weights of the parts added together, as a percentage of the whole course. |
| worst_finish | Yes | The course grade if every remaining part scores 0. |
| already_there | No | When a target_percent is given, true when the target is already reached. |
| current_grade | Yes | The average on the marked work, or null when nothing is marked yet. |
| earned_points | Yes | The points already banked out of the 100 the whole course is worth. |
| needed_percent | No | When a target_percent is given, the average needed on the unmarked parts. Below 0 when already there, above 100 when out of reach. |
| remaining_weight | Yes | The weight of the course that is still to come, as a percentage of the whole course. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behavior: weights are never rescaled, sums below 100 mean the course is incomplete, and sums above 100 are an error. These are meaningful operational details that help an agent invoke the tool correctly, with no contradiction of 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and remains readable, with the example prompt adding practical value. It is somewhat repetitive about weights being percentages of the whole course, which keeps it from being maximally concise.
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?
The description covers the essential inputs, weight-sum constraints, optional target behavior, and an example, while an output schema exists to explain return values. Given the moderate complexity and fully described schema, the definition is complete enough for correct invocation.
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 schema already documents both parameters well. The description still adds useful meaning by clarifying that weights are percentages of the whole course and are never rescaled, and by explaining the purpose of target_percent.
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?
The description states a specific verb and resource: combining weighted course parts into the grade so far, plus worst and best possible finish. It clearly identifies the outputs, but it does not explicitly distinguish this tool from siblings such as needed_on_final or calculate_gpa.
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?
The description gives clear usage context, including when to provide target_percent to compute the average needed on unmarked parts, and includes an example prompt. However, it does not explicitly say when to use this tool instead of similar siblings.
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.
v0.1.7calculate_gpa11 fields changedInput schema / properties / courses / descriptionPrevious value: -"The courses to include. Each needs credits (greater than 0) and a grade (a letter like \"B+\" or a percentage like 87). name is optional, and so is credit_multiplier (greater than 0), which gives a course more weight in the weighted GPA."New value: +"The courses to include. Each needs credits (greater than 0) and a grade (a letter like \"B+\" or a percentage like 87). name is optional, and so is credit_multiplier (greater than 0), which gives a course more weight in the weighted GPA. Required when transcript_csv is not given."Input schema / properties / courses / items / requiredPrevious value: -[
- "credits",
- "grade"
-]New value: +[
+ "credits"
+]Input schema / properties / drop_lowestAdded value: +{
+ "description": "Number of courses with the lowest grade points to leave out of the GPA, 0 or more, for schools that drop the lowest course. It must be less than the number of graded courses. Ties go to the course listed first. Defaults to 0.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / transcript_csvAdded value: +{
+ "description": "A CSV string with columns for course name, credits, grade and optional credit multiplier. A header row is optional, the columns can be in any order, and header names like Course Title, Final Grade and Credit Hours are read as the name, grade and credits columns. P, NP and W grades are left out of the GPA. When courses is not given, this is parsed and used as the course list. Example: \"Course,Credits,Grade\\nCalculus,4,A\\nHistory,3,B+\"",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "courses"
-]Output schema / properties / courses / descriptionPrevious value: -"One entry per course, in the order they were passed."New value: +"One entry per graded course, in the order they were passed."Output schema / properties / credits / descriptionPrevious value: -"The credits of the courses in this call."New value: +"The credits of the graded courses in this call."Output schema / properties / dropped_coursesAdded value: +{
+ "description": "Courses left out because of drop_lowest. Empty when drop_lowest is 0 or not passed.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "credits": {
+ "description": "Credits of the course dropped.",
+ "type": "number"
+ },
+ "grade": {
+ "description": "The letter the dropped course counted as on the scale.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Name of the course dropped.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "credits",
+ "grade"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / excluded_coursesAdded value: +{
+ "description": "Courses left out of the GPA because they are not graded, such as P, NP and W rows in transcript_csv. Empty when none were left out.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "credits": {
+ "description": "Credits of the course left out.",
+ "type": "number"
+ },
+ "grade": {
+ "description": "The grade that kept the course out of the GPA, such as P, NP or W.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Name of the course left out of the GPA.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "credits",
+ "grade"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / gpa_creditsAdded value: +{
+ "description": "The credits that count in the GPA, the same graded credits the term GPA is divided by. Excluded courses add nothing here.",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "scale",
- "scale_name",
- "courses",
- "credits",
- "term_gpa"
-]New value: +[
+ "scale",
+ "scale_name",
+ "courses",
+ "credits",
+ "term_gpa",
+ "gpa_credits",
+ "excluded_courses",
+ "dropped_courses"
+]convert_gpa_scaleweighted_grade4 fields changedInput schema / properties / target_percentAdded value: +{
+ "description": "Optional target course grade in percent. When given, works out the average needed on the unmarked parts.",
+ "maximum": 100,
+ "minimum": 0,
+ "type": "number"
+}Output schema / properties / already_thereAdded value: +{
+ "description": "When a target_percent is given, true when the target is already reached.",
+ "type": "boolean"
+}Output schema / properties / needed_percentAdded value: +{
+ "description": "When a target_percent is given, the average needed on the unmarked parts. Below 0 when already there, above 100 when out of reach.",
+ "type": [
+ "number",
+ "null"
+ ]
+}Output schema / properties / possibleAdded value: +{
+ "description": "When a target_percent is given, true when the target can be reached.",
+ "type": "boolean"
+}v0.1.4calculate_gpaconvert_gradelist_scalesneeded_on_finalplan_coursestarget_gpa_plannerweighted_gradeScored across 8 tools
target_gpa_planner and plan_courses both handle cumulative GPA target planning, while weighted_grade and needed_on_final both compute required scores for a course target. The descriptions distinguish aggregate vs per-course and general weighted-grade vs final-exam cases, but the boundaries are not perfectly clean.
Most tools use a verb_noun pattern such as calculate_gpa, convert_grade, list_scales, plan_courses and convert_gpa_scale, but target_gpa_planner, weighted_grade and needed_on_final break that pattern. The names remain readable, but the mixed conventions make the set less predictable.
Eight tools is well within the appropriate range for a GPA calculator server, and each tool maps to a meaningful grade or GPA workflow. There is neither excessive sprawl nor a thin single-tool surface.
The set covers scale discovery, grade conversion, GPA calculation, weighted course grades, final-exam targets, and cumulative GPA planning. For the stated GPA/grade calculation domain, no obvious dead ends or missing core operations are apparent.
Grades from questions wrong, final exam score needed, weighted grades, GPA, SAT/ACT/MCAT scores.
Everyday calculators and converters for AI assistants: units, dates, percentages, text, JSON.
Loan & mortgage calculator, compound interest, ROI, crypto prices, FX conversion for AI agents.
AI-callable calculators and engineering models with real formulas. No hallucinated math.
