Calculator for Grading

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

Annotations already mark it read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context: it supports percent and points modes, returns the needed percent, secured/out-of-reach status, 0/100 outcomes, and letter needs. It does not contradict 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 and dense but not padded. Each sentence contributes: use case, return values, mode support, and an explicit exclusion.

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 7-parameter calculator with two input modes and an output schema, the description covers the relevant complexity. It explains supported modes, expected outputs, and the key boundary against weighted averages; nothing essential 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 per-parameter definitions already carry most meaning. The description still adds value by grouping parameters into percent mode (current_grade_percent + final_weight_percent) and points mode (points_earned_so_far, points_possible_so_far, final_exam_points), which helps invocation.

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 task: compute the score needed on a final exam or last assignment to reach a target grade. It clearly distinguishes this from category-weighted-average calculation, so an agent can separate it from siblings like weighted_grade.

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 states exactly when to use the tool (student asks what score is needed on a final) and when not to use it (weighted average of categories). It does not explicitly name the sibling tool to use instead, but the exclusion condition is clear.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds substantive computation rules: honors +0.5, AP/IB +1.0 on passing grades, weighted/unweighted outputs, and credit defaults of 1 for high school and 3 for college. No behavior contradicts 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?

Four sentences, front-loaded with the usage condition, followed by weighting rules, return/default behavior, and exclusions. Each sentence contributes directly to selecting and invoking the tool.

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 moderately complex calculator with an output schema and enum-rich inputs, the description supplies modes, weighting formulas, defaults, return behavior, and exclusions. Remaining details such as scale and limits are already in the schema, so 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?

With 67% schema description coverage, the schema documents most enums and fields, while the description adds useful meaning for mode and level through weighting rules and default credits. The scale parameter's 4.0/4.3 distinction is left to the schema, so the description adds value but does not fully compensate for every parameter detail.

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: compute GPA from letter grades and credits, covering high school weighted/unweighted and college unweighted. It explicitly excludes single test grades and school-specific formulas like UC or LSAC, which distinguishes it from sibling tools such as test_score_calculator.

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?

Provides explicit when-to-use guidance (student wants GPA from letter grades and credits) and when-not-to-use guidance (single test grade, school-specific formula such as UC or LSAC). Alternatives are described by task category rather than by exact sibling tool name, but the routing signal is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds value beyond them by disclosing the return contents (percent, letter on the chosen scale, gap to the next letter, optional chart) and the privacy rule 'Needs only numbers; never ask for names.' Minor gap: it says the chart covers 'every possible number wrong' while the schema caps it at the first 60 rows, an inconsistency an agent could trip over.

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 sentences, front-loaded with the use case, then the return contract, then the exclusions and the input rule. Every sentence carries actionable routing or behavioral information; no 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, 100% parameter coverage, and rich annotations, the description only needs to add routing and behavioral context — which it does. An agent has enough to decide between this and its five siblings and to invoke it without follow-up questions.

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 goes slightly further by framing inputs as 'wrong (or correct)' with a worked example ('7 wrong out of 40'), reinforcing the mutually exclusive wrong/correct choice. It does not add detail on scale, decimals, rounding or custom_cutoffs beyond the schema, so it stays just above 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?

States a specific verb and resource ('percent and letter grade for a test from the number of questions wrong (or correct)') with a concrete example ('7 wrong out of 40'). It also carves out the sibling territory it is not for (final-exam target, weighted categories, GPA, test scores), so an agent can route correctly without opening other 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?

Explicit when-to-use ('when a student or teacher wants the percent and letter grade...') and explicit when-not ('Do not use it for a final-exam target, weighted categories, GPA or test scores'), which maps cleanly onto final_grade_needed, weighted_grade, gpa_calculator and test_score_calculator. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is low; the description adds useful return-shape context (cut-offs, named sources, verification date) that tells the agent answers are citable rather than generic. It does not need to discuss permissions or side effects for a read-only fact lookup.

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 use trigger is front-loaded, followed by the return contents and the anti-memory rationale; every clause adds information. It is one dense sentence, which is compact but slightly harder to scan than a split structure.

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 one-parameter read-only lookup, all four enum options are accounted for and the return payload and its sourcing are described; with an output schema present, no further return-value detail is required.

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 0%, so the description must carry the single parameter, and it does: each enum value is glossed (10-point 'A 90-100', 7-point 'A 93-100', plus-minus with 4.0/4.3 GPA points, College Board percent-to-GPA). It conveys what each option selects, though it does not say whether exactly one scale is returned per call or all four.

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 precise verb+resource ('Returns the cut-offs, the named sources and the date they were checked') and enumerates the four scale families covered, which map to the enum values. An agent can distinguish this factual lookup from the sibling calculators (gpa_calculator, grade_calculator) without opening any 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 someone asks what a grading scale is' plus 'Use it instead of answering from memory; there is no national scale and schools differ' gives a clear trigger and an explicit alternative to avoid. It stops short of naming the sibling calculator tools it should be preferred over, so it is strong but not fully explicit about alternatives.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the description correctly need not re-state safety. It adds non-annotation context: results are table lookups returned with the source table and fetch date, and it explicitly disclaims predictive use. It does not say what happens on out-of-range inputs or unsupported test numbers, which is the remaining gap for a lookup tool.

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 trigger phrase, then one dense sentence per test, then a returns/limits sentence. Dense but no filler; the parenthetical test-range lists are the only slightly heavy part.

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 already covers return values and annotations cover safety, so the description's job is scope plus per-test input expectations, which it largely delivers. The missing piece is which parameters belong to which test value — meaningful for a 12-param, single-required-field 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 only 25% across 12 parameters, so the description must compensate and it only partly does: it explains SAT 'correct answers per section' and MCAT 'four section scores 118-132 to total', and the practice-test ranges. It never maps the individually named params (act_english_correct, mcat_cars, sat_math_correct vs sat_reading_writing_correct) to a test, and doesn't say that only the subset relevant to the chosen 'test' is required — leaving the agent to infer conditional parameter sets.

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 (convert/look up a score) plus the exact resource (published SAT/ACT/MCAT practice-test tables) and enumerates the supported test variants with their accepted inputs. Nothing in the sibling set (grade/GPA calculators) does this, so the tool is trivially distinguishable.

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 an explicit trigger ('when a student wants a score from a published practice test') and explicit exclusions ('Not for official score reports, other tests, or predicting a real exam'). The per-test range constraints (SAT 4-11, ACT 1-4/national, MCAT 118-132 sections) further scope valid use.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds meaningful domain behavior beyond annotations: rows without a score count as open, and the result includes graded/open weight and an optional target-grade what-if calculation.

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 primary use case, then supported by concrete examples and an exclusion. It is dense but each sentence contributes relevant information; the only minor issue is the long middle sentence packing multiple return details.

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-value explanation is not strictly required, but the description still helpfully summarizes outputs. For a nested-row calculation tool, it covers row semantics and target-grade behavior well; scale behavior remains implicit.

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 67%, and the description adds useful semantics: score may be percent, fraction, or letter; omitted scores mean ungraded; target_grade optionally computes what the open portion must average. It does not explain the scale enum, but the row-level semantics are well clarified.

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 calculation (weighted course grade from weighted categories) and gives a concrete example (homework 20%, tests 50%, final 30%). It distinguishes itself from single-question exam tools, though it does not name any sibling tool explicitly.

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 provides a clear 'use this when' trigger and an explicit exclusion ('Do not use it for a single final-exam question without categories'). It does not name alternative sibling tools, but the boundary condition is sufficient for routing.

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