Read ClassMarker groups, links, exams and recent results; manage question bank and access codes.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 15 tools
Most tools are clearly distinct by resource+action, but the four results tools (recent_group_results, recent_group_exam_results, recent_link_results, recent_link_exam_results) overlap heavily and differ only in scope (all vs one, group vs link), which an agent could easily mix up despite the descriptions clarifying it. The create/update pairs for category vs parent_category are also close but descriptions differentiate them adequately.
Every tool follows a consistent classmarker_verb_noun pattern (create_question, list_categories, update_parent_category, add_access_codes, recent_group_results). The one compound outlier, list_groups_links_exams, still fits the convention and is readable.
15 tools fall squarely in the well-scoped range, and each maps to a distinct ClassMarker API endpoint (questions, categories, access lists, results). The set isn't padded with redundant tools.
There are notable gaps: no delete operations for questions or categories, access codes can only be added never removed (explicitly stated), and no create/update for exams, links, or groups despite results and access-code tools depending on them. The question/category surface has create+get+update but is missing deletes, leaving dead ends an agent cannot fully resolve.
WRITE: add access codes (1-100 per call, up to 255 characters each; a list holds at most 20,000) to a link's access-code list, so those people can start the exam. The access_list_id comes from classmarker_list_groups_links_exams (links[].access_list_id). Only adds; removing codes is not offered. Does not count against the 30 requests per hour limit. API: POST /v1/accesslists/{access_list_id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | 1-100 access codes to add. | |
| access_list_id | Yes | The access list id (links[].access_list_id). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give readOnly/idempotent/destructive hints; the description adds operational constraints the annotations cannot: 1-100 codes per call, 255-char limit, 20,000-code list cap, and the fact that it does not count against the 30 requests/hour limit. It also discloses the underlying endpoint.
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 WRITE marker, then limits, then id provenance, then exclusions and rate-limit note. Dense but every clause carries actionable 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 no output schema, the description does not say what the call returns (e.g., accepted vs. rejected codes), which is the one thing an agent might still want for a bulk write. Everything else — limits, provenance, exclusions, rate-limit exemption — is covered.
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 the schema already carries per-parameter descriptions, so baseline is 3. The description adds provenance for access_list_id and a list-level capacity constraint (20,000) that appears nowhere in the schema, which is genuine added meaning.
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 ('add access codes ... to a link's access-code list') plus the outcome ('so those people can start the exam'). No sibling tool touches access-code lists, and the description's scope (add-only) makes that distinction unambiguous.
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?
Explicitly says when to use it (to let people start an exam), where the required id comes from ('classmarker_list_groups_links_exams (links[].access_list_id)'), and what it cannot do ('Only adds; removing codes is not offered'), which functions as the when-not clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a question category under a parent category. Returns its category_id. Counts as one of ClassMarker's 30 requests per hour per API key. API: POST /v1/categories/category.json.
| Name | Required | Description | Default |
|---|---|---|---|
| category_name | Yes | Name of the new category. | |
| parent_category_id | Yes | The parent category id (from classmarker_list_categories). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description need not restate the safety profile. It does add genuinely new operational context: the 30-requests-per-hour per-API-key rate limit and the underlying endpoint POST /v1/categories/category.json. No contradiction with 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?
Three short sentences, front-loaded with the 'WRITE:' marker, then the return value, then the operational limits. Every sentence carries distinct information with no padding.
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 two-parameter mutation with full schema coverage and annotations, the description fills the main gaps: it discloses the return value (category_id) in the absence of an output schema, plus rate limits. It stops short of describing failure modes, such as what happens if parent_category_id does not exist.
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% – both parameters carry their own descriptions, including the useful pointer that parent_category_id comes from classmarker_list_categories. The description adds no syntax, format, or validation detail beyond that, 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 ('create a question category') and adds scope ('under a parent category'), which implicitly separates it from the sibling classmarker_create_parent_category. An agent can pick between the two category-creation tools 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?
The 'WRITE:' prefix signals this is a mutating operation, and 'under a parent category' implies a parent must already exist, but the description never states when to prefer this over classmarker_create_parent_category or classmarker_update_category, nor any preconditions. Usage is inferable rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a new top-level question category. Returns its parent_category_id. Counts as one of ClassMarker's 30 requests per hour per API key. API: POST /v1/categories/parent_category.json.
| Name | Required | Description | Default |
|---|---|---|---|
| parent_category_name | Yes | Name of the new parent category. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing a 30-requests-per-hour-per-API-key rate limit, the returned parent_category_id, and the underlying endpoint. It does not say what happens on a duplicate name or failed validation, which would round out the mutation profile.
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 short, telegraphic sentences that are front-loaded with the WRITE marker and the core action. Every sentence carries a distinct fact (action, return value, quota, endpoint); only the endpoint restatement is marginal.
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?
No output schema exists, so the description usefully supplies the return value and the rate limit an agent must plan around. Combined with annotations covering the write/non-idempotent nature, an agent has enough to call it correctly; error behavior is the only notable omission.
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?
Only one parameter, and schema description coverage is 100% with the minLength/maxLength constraints documented there. The description adds nothing about the name field beyond what the schema already 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 (create) and resource (parent category) plus the discriminating qualifier 'top-level', which separates it from the sibling classmarker_create_category and classmarker_update_parent_category. An agent can select it 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?
The 'WRITE:' prefix and 'top-level' framing imply when this tool applies versus nested-category operations, but no alternative is named and no prerequisite or when-not condition is given. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: add a new question to the question bank. Only multiplechoice, multipleresponse, truefalse and essay can be created. Returns the new question_id. For truefalse, give only correct_options ["A"] (True) or ["B"] (False). Counts as one of ClassMarker's 30 requests per hour per API key. API: POST /v1/questions.json.
| Name | Required | Description | Default |
|---|---|---|---|
| points | No | Points for a correct answer (for an essay: the maximum score). | |
| options | No | Answer options keyed by letter A-J (up to 10), e.g. {"A": "Apply oil", "B": "Soak in water"}. Needed for multiplechoice and multipleresponse; not allowed for truefalse and essay. | |
| question | Yes | The question text. | |
| category_id | No | Category id (from classmarker_list_categories). | |
| grade_style | No | multipleresponse only: partial credit with or without deduction, or off (all-or-nothing). | |
| question_type | Yes | multiplechoice (one correct option), multipleresponse (one or more), truefalse, or essay (graded by hand). Free text, grammar and matching cannot be written. | |
| random_answers | No | Shuffle the order of the options for each test-taker (multiplechoice / multipleresponse). | |
| correct_options | No | Letters of the correct options, e.g. ["C"]. multiplechoice: exactly one; multipleresponse: one or more; truefalse: ["A"] (True) or ["B"] (False); not allowed for essay. | |
| correct_feedback | No | Feedback shown for a correct answer. | |
| incorrect_feedback | No | Feedback shown for an incorrect answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds significant behavioral context beyond that: it labels the operation WRITE, states that it returns the new question_id, discloses the 30 requests per hour per API key rate limit, and gives the API endpoint. These are exactly the kind of operational traits an agent needs for a mutation 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?
The description is dense and front-loaded: 'WRITE: add a new question...' immediately signals the operation. Every subsequent sentence adds a distinct fact: allowed types, return value, truefalse rule, rate limit, and endpoint. There is no wasted wording.
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 10-parameter creation tool with 100% schema coverage and no output schema, the description supplies the missing operational context: it reports the returned question_id, rate limit, mutation nature, and type restrictions. An agent has enough information to invoke it correctly without needing to inspect sibling 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?
Schema description coverage is 100%, so the schema already documents all 10 parameters, including the truefalse correct_options format and the question_type enum. The description repeats the creatable types and the truefalse option rule but adds no new syntax, format, or default information beyond the schema. This meets the baseline 3 for high schema coverage.
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: 'add a new question to the question bank.' It also lists the four creatable question types and the return value. It does not explicitly name or distinguish itself from siblings like update_question or get_question, though the create verb makes the distinction obvious.
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 by restricting creation to multiplechoice, multipleresponse, truefalse and essay. It also gives a special usage rule for truefalse correct_options. It does not point to alternatives such as update_question for modifying existing questions, so it falls short of explicit when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one question-bank question by id (ids from classmarker_list_questions). Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/questions/{question_id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| question_id | Yes | The question id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful operational context beyond the annotations: the 30-requests-per-hour-per-API-key budget and the underlying endpoint (GET /v1/questions/{question_id}.json).
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?
A single dense sentence with the core action and id source front-loaded, followed by rate-limit and endpoint facts. 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?
For a one-parameter read-only getter with no output schema, the description covers action, id provenance, cost, and endpoint. The only minor gap is that the shape of the returned question object is left entirely unstated.
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 the single parameter is fully documented in the schema, so baseline is 3. The description adds only the provenance of the id ('ids from classmarker_list_questions'), not format or constraint detail 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 ('Get one question-bank question by id') and explicitly points to classmarker_list_questions as the source of ids, which cleanly separates it from the sibling list tool.
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?
Tells the agent when this tool is appropriate by identifying the precondition (you already have an id, obtained from classmarker_list_questions). It gives no explicit when-not guidance, but for a single-resource getter the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the question-bank categories with their parent categories and ids (needed for creating and updating questions). Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/categories.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 genuinely useful operational context beyond that: the 30-requests-per-hour-per-API-key quota and the concrete endpoint (GET /v1/categories.json). It does not discuss pagination or result ordering.
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, each load-bearing: what is returned, why it matters, and the cost/endpoint. The value proposition is front-loaded and there is 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 no output schema, the description compensates by naming the returned fields (parent categories and ids). It pairs that with the rate-limit caveat and endpoint, so an agent has everything needed to call a zero-parameter read tool correctly.
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, which is the baseline-4 case; there is nothing for the description to disambiguate. It instead documents the return shape (categories with parents and ids), which is helpful, though not required at this dimension.
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 ('List') and resource ('question-bank categories'), and enumerates what each entry contains (parent categories and ids). It also ties the resource to its downstream use (creating/updating questions), which separates it from the create_/update_ category siblings.
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 parenthetical '(needed for creating and updating questions)' tells the agent the context in which this list should be called, i.e. to resolve category ids before a write. It does not state any when-not conditions or name an alternative tool, 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.
List the groups, links and exams (tests) this API key can access, with the ids the other tools need (group_id, link_id, link_url_id, test_id, and access_list_id for links with an access-code list). Good first call. Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds genuinely useful non-schema behavior: the 30 requests-per-hour rate limit, the underlying endpoint (GET /v1.json), and the enumeration of returned id fields. It does not discuss pagination or result limits.
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?
Information is front-loaded: purpose first, then the ids provided, then the 'good first call' cue, then cost and endpoint. It is slightly dense and the endpoint detail is marginal, but no sentence is 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 no output schema, the description compensates by naming the id fields returned (group_id, link_id, link_url_id, test_id, access_list_id). Combined with the rate-limit note and endpoint, an agent has everything needed to call and use the 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?
Zero parameters, so per the rubric the baseline is 4. The description adds meaningful context about which ids are returned, which is a bonus rather than a parameter explanation.
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 (List) and three concrete resources (groups, links, exams), and clarifies that 'exams' means tests. This clearly separates it from siblings like list_categories and list_questions.
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?
'Good first call' explicitly signals when to reach for it, and the mention of 'the ids the other tools need' establishes that other tools depend on its output. It does not name explicit alternatives or exclusions, which keeps it 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.
List the questions of the question bank, 200 per page (page 1, 2, ...): question text, type, category, points, options, correct options, status. A full page means more may follow, so ask for the next page. Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/questions.json?page=N.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already declaring the safety profile, the description still adds real behavioral context: the 200-items-per-page pagination model, the continue-if-full rule, and a concrete quota cost (one of 30 requests per hour per API key). It also compensates for the missing output schema by listing returned fields. Only the raw endpoint line is redundant.
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 compact sentences, front-loaded with purpose, then pagination, then quota and endpoint. Every clause carries operational value for the caller; nothing is padding.
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 single-optional-parameter, read-only listing tool with no output schema, the description covers purpose, return fields, pagination semantics, and rate-limit cost. An agent has everything needed to call it and to loop correctly.
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 meaning the schema lacks: the page size of 200 and the fact that pages are 1-based and sequential, which is what an agent needs to decide how many page calls to make.
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 ('List the questions of the question bank') and even enumerates the returned fields, so the operation is unambiguous. It does not explicitly contrast itself with the singular classmarker_get_question sibling, so it falls short of full sibling differentiation.
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 implied by the resource name, and the description gives pagination guidance ('a full page means more may follow, so ask for the next page'). However, it never states when to prefer this over get_question or other listing siblings, nor does it name any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent finished results for ONE exam in ONE group (ids from classmarker_list_groups_links_exams), oldest first, PAGED by finish time. Contains personal data: use small pages. Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/groups/{group_id}/tests/{test_id}/recent_results.json.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per request, 1-200 (default 25; ClassMarker's own default is 200). | |
| test_id | Yes | The exam (test) id. | |
| group_id | Yes | The group id. | |
| include_monitor_events | No | Include each result's detailed monitor_events.events list (default false: only the counts). | |
| finished_after_timestamp | No | UNIX time in SECONDS: only results finished after this are returned (oldest first). Default: 14 days ago. Maximum look-back is 3 months. To page, pass next_finished_after_timestamp from the previous reply. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint annotation by disclosing ordering ('oldest first'), pagination mechanism ('PAGED by finish time'), a personal-data warning, and a concrete rate limit (30 requests/hour per API key). These are exactly the operational facts an agent needs and none are derivable from the annotations or schema.
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 purpose and scope, followed by constraints and the API path. It is dense but every clause (paging, personal-data caution, rate limit, id source) carries real information; only minor tightening is possible.
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 read-only, 5-parameter tool with no output schema, the description covers scope, ordering, paging, rate limit, and privacy. It omits any indication of the response shape, but with no output schema and readOnlyHint present, this is a minor gap rather than a blocking one.
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 all five parameters are already documented, including the finished_after_timestamp paging hint. The description reinforces 'oldest first' ordering and 'small pages' but adds no syntax or format detail beyond what the schema already provides, making the 3 baseline appropriate.
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 with precise scope: 'Recent finished results for ONE exam in ONE group,' which implicitly separates it from group-only and link-based siblings like classmarker_recent_group_results and classmarker_recent_link_exam_results. It stops short of naming a contrasting sibling explicitly, so the differentiation relies on the reader comparing scope statements.
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?
Tells the agent where the required ids come from (classmarker_list_groups_links_exams) and advises using small pages because output contains personal data. It does not state explicit when-not conditions or name competing result tools, but the practical usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent finished test results taken in the key's groups (all groups, all exams), oldest first, PAGED by finish time: test-taker name, email, score, percentage, pass/fail, timing, certificate. Contains personal data: use small pages. Max look-back 3 months. Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/groups/recent_results.json.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per request, 1-200 (default 25; ClassMarker's own default is 200). | |
| include_monitor_events | No | Include each result's detailed monitor_events.events list (default false: only the counts). | |
| finished_after_timestamp | No | UNIX time in SECONDS: only results finished after this are returned (oldest first). Default: 14 days ago. Maximum look-back is 3 months. To page, pass next_finished_after_timestamp from the previous reply. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, so the description carries most of the burden and adds real value: a PII warning ('contains personal data: use small pages'), the 30-requests-per-hour rate limit, the pagination mechanism, and the look-back ceiling. It does not describe error behavior or what fields the certificate/timing blocks contain, keeping it short of a 5.
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?
A single dense block that front-loads scope, then ordering, then the returned fields, then constraints. Every sentence earns its place, though the pacing is compressed and 'oldest first, PAGED by finish time' is slightly redundant.
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 no output schema and no annotations beyond read-only, the description compensates well: it enumerates the returned fields, discloses PII and rate-limit constraints, and states the look-back and pagination rules. An agent has everything needed to call it correctly and safely.
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 limit, include_monitor_events, and finished_after_timestamp are already documented in detail. The description reinforces paging direction and 'small pages' but adds no syntax or format detail beyond the schema, 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 (recent finished test results) with explicit scope '(all groups, all exams)', which distinguishes it from the more narrowly scoped siblings recent_group_exam_results and recent_link_results. It also names the backing endpoint GET /v1/groups/recent_results.json.
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 clear context: oldest-first ordering, paging by finish time, and a 3-month maximum look-back. It stops short of naming the sibling alternatives or stating when to prefer this all-groups scope over an exam- or link-scoped call, so the routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent finished results for the exam of ONE link (ids from classmarker_list_groups_links_exams), oldest first, PAGED by finish time. Contains personal data: use small pages. Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/links/{link_id}/tests/{test_id}/recent_results.json.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per request, 1-200 (default 25; ClassMarker's own default is 200). | |
| link_id | Yes | The link id. | |
| test_id | Yes | The exam (test) id. | |
| include_monitor_events | No | Include each result's detailed monitor_events.events list (default false: only the counts). | |
| finished_after_timestamp | No | UNIX time in SECONDS: only results finished after this are returned (oldest first). Default: 14 days ago. Maximum look-back is 3 months. To page, pass next_finished_after_timestamp from the previous reply. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint=true, it discloses ordering (oldest first), the paging dimension (by finish time), a PII warning ('Contains personal data: use small pages'), and a hard quota ('30 requests per hour per API key'). These are exactly the operational traits an agent cannot infer from 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?
Dense but front-loaded: what it returns, ordering/paging, then the two warnings, then the endpoint. Nearly every clause earns its place; the endpoint restatement is the only mildly redundant element.
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 no output schema, the description must carry return-shape burden, and it does the important parts: ordering, cursor field name for paging, and the optional monitor_events detail. It stops short of describing the result payload fields, which is a minor gap for a personal-data read 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 already 100%, so the baseline is 3, but the description adds non-obvious semantics: cursor paging is driven by finished_after_timestamp fed from next_finished_after_timestamp in the prior reply, and there is a 3-month look-back cap noted alongside the schema's 14-day default.
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+resource ('Recent finished results for the exam of ONE link'), and the emphasized 'ONE link' plus the exam scope distinguishes it from the sibling group/link variants. It also pins the exact API endpoint, so an agent knows precisely what is being fetched.
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?
Routes the agent to the source of ids ('ids from classmarker_list_groups_links_exams') and gives paging guidance ('pass next_finished_after_timestamp from the previous reply'). It does not explicitly state when to prefer the group-level siblings instead, so it falls short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent finished test results taken through the key's links (all links, all exams), oldest first, PAGED by finish time: test-taker name, email, score, pass/fail, timing, access code, extra tracking fields, IP address, certificate. Contains personal data: use small pages. Max look-back 3 months. Counts as one of ClassMarker's 30 requests per hour per API key. API: GET /v1/links/recent_results.json.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per request, 1-200 (default 25; ClassMarker's own default is 200). | |
| include_monitor_events | No | Include each result's detailed monitor_events.events list (default false: only the counts). | |
| finished_after_timestamp | No | UNIX time in SECONDS: only results finished after this are returned (oldest first). Default: 14 days ago. Maximum look-back is 3 months. To page, pass next_finished_after_timestamp from the previous reply. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint annotation: it discloses the pagination direction (oldest first), the maximum 3-month look-back, the personal-data exposure and the corresponding advice to use small pages, and the cost of one of 30 requests/hour per API key. It also enumerates the returned fields, so an agent knows exactly what it receives.
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 and pagination order in the first clause, then the cost/PII cautions and the endpoint. The long comma-separated field list is dense but it replaces a missing output schema, so it earns its space; overall it is a single packed block rather than cleanly separated sentences.
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 no output schema and only a readOnlyHint, the description compensates fully: returned fields, ordering, look-back bound, rate-limit cost, PII handling advice, and the underlying GET endpoint. Nothing an agent needs in order 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 description coverage is 100% and the schema already explains limit, include_monitor_events, and finished_after_timestamp including the next_finished_after_timestamp paging trick. The description only restates the paging order ('oldest first') and adds no parameter semantics beyond the schema, 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+resource with explicit scope: 'Recent finished test results taken through the key's links (all links, all exams), oldest first, PAGED by finish time.' The 'all links, all exams' qualifier implicitly separates it from classmarker_recent_link_exam_results and the group variants, though no sibling is named outright.
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 implied by scope rather than stated: the agent must infer that this is the tool for cross-link/cross-exam result retrieval while the sibling covers single exams. There is no explicit 'use X instead when Y' routing, though the PII caution ('use small pages') and the 3-month look-back do constrain legitimate calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: rename a category and/or move it to another parent (overwrites both fields: send the name and parent_category_id you want it to have). Counts as one of ClassMarker's 30 requests per hour per API key. API: PUT /v1/categories/category/{category_id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | Yes | The category id (from classmarker_list_categories). | |
| category_name | Yes | The category's name (new or unchanged). | |
| parent_category_id | Yes | The parent category id (new or unchanged). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds non-derivable detail: that both fields are overwritten rather than patched, and the rate limit of 30 requests/hour/key, plus the underlying endpoint.
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?
One tightly packed sentence with the write classification and operation front-loaded, followed by overwrite semantics, rate limit, and endpoint. Every clause carries information; nothing is padding.
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 3-parameter write tool with no output schema, the description covers intent, required-value semantics, rate limiting, and the API route. Only the absence of alternative-routing guidance keeps it from being fully complete.
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 beyond it by clarifying that category_name and parent_category_id are full replacements, not optional deltas — resolving the main ambiguity of a PUT-style update.
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 ('rename a category and/or move it to another parent') and fixes the exact scope of the mutation. An agent can distinguish this from classmarker_create_category and classmarker_update_parent_category without opening a 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?
The parenthetical 'send the name and parent_category_id you want it to have' tells the caller exactly what values to supply under overwrite semantics, which is real invocation guidance. It does not, however, name alternatives or state when not to use this tool (e.g., versus update_parent_category).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: rename an existing parent category (overwrites its name). Counts as one of ClassMarker's 30 requests per hour per API key. API: PUT /v1/categories/parent_category/{parent_category_id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| parent_category_id | Yes | The parent category id (from classmarker_list_categories). | |
| parent_category_name | Yes | The new name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description still adds genuinely useful context beyond them: the overwrite semantics of the name, the concrete rate limit (30 requests/hour per API key), and the underlying endpoint.
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?
A single dense sentence with zero waste, front-loaded with the operation class ('WRITE') followed by resource, mutation effect, rate limit and endpoint. Nothing is repeated or padding.
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 two-parameter write tool with full annotation coverage and no output schema, the description covers operation type, mutation effect, rate limit and endpoint. It could still say whether the id survives and that nothing else on the category changes, but overall it is close to sufficient.
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 the schema already documents both parameters, including where parent_category_id comes from (classmarker_list_categories). The description only implicitly reinforces parameter placement via the endpoint path, which is the baseline expectation when the schema does the heavy lifting.
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: 'rename an existing parent category.' The 'parent' qualifier implicitly separates it from the sibling classmarker_update_category for regular categories, but no sibling is named explicitly, so the differentiation is left to inference rather than spelled out.
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 'WRITE:' prefix and 'rename an existing' wording imply this is a modification of something that already exists (versus classmarker_create_parent_category), but there is no explicit when-to-use/when-not guidance or named alternative for renaming a non-parent category.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE (overwrites): replace an existing question-bank question. Send the COMPLETE question (type, text, options, correct options, points, feedback), not only the changed fields; read it first with classmarker_get_question. Only multiplechoice, multipleresponse, truefalse and essay questions can be updated. Counts as one of ClassMarker's 30 requests per hour per API key. API: PUT /v1/questions/{question_id}.json.
| Name | Required | Description | Default |
|---|---|---|---|
| points | No | Points for a correct answer (for an essay: the maximum score). | |
| options | No | Answer options keyed by letter A-J (up to 10), e.g. {"A": "Apply oil", "B": "Soak in water"}. Needed for multiplechoice and multipleresponse; not allowed for truefalse and essay. | |
| question | Yes | The question text. | |
| category_id | No | Category id (from classmarker_list_categories). | |
| grade_style | No | multipleresponse only: partial credit with or without deduction, or off (all-or-nothing). | |
| question_id | Yes | The question id (from classmarker_list_questions). | |
| question_type | Yes | multiplechoice (one correct option), multipleresponse (one or more), truefalse, or essay (graded by hand). Free text, grammar and matching cannot be written. | |
| random_answers | No | Shuffle the order of the options for each test-taker (multiplechoice / multipleresponse). | |
| correct_options | No | Letters of the correct options, e.g. ["C"]. multiplechoice: exactly one; multipleresponse: one or more; truefalse: ["A"] (True) or ["B"] (False); not allowed for essay. | |
| correct_feedback | No | Feedback shown for a correct answer. | |
| incorrect_feedback | No | Feedback shown for an incorrect answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, but the description goes further: it explains the full-replace overwrite semantics, the supported-type restriction, and a concrete rate limit (30 requests/hour per API key). That is meaningful behavioral context beyond the structured hints.
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 operation type and mutate semantics in the first clause, then adds prerequisites, constraints and rate limits in a tight sequence. No sentence is filler; everything is actionable.
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 destructive mutation tool with no output schema, the description covers overwrite behavior, the read-before-write prerequisite, allowed types and rate limits. There is no ambiguity an agent would need resolved before calling it.
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 lifts it by enumerating the fields that make up the 'COMPLETE question' (type, text, options, correct options, points, feedback), reinforcing which parameters are semantically mandatory in a full-replace call rather than merely schema-optional.
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 ('replace an existing question-bank question') and immediately flags the operation as a WRITE that overwrites. This cleanly separates it from classmarker_create_question, classmarker_get_question and classmarker_list_questions without requiring the agent to open another 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?
Explicitly tells the agent to read the question first with classmarker_get_question, to send the COMPLETE question rather than a patch, and which question types are updatable. These are concrete when-to-use and prerequisite rules rather than inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Axis LMS users, courses, learning paths, certifications and reports; manage enrollments.
Read Lessonspace sessions, recordings, transcripts, spaces and users; launch spaces, edit sessions.
Read survey responses and manage contacts, webhooks, teams and organisation users.
Read Accredible credentials, groups, designs, analytics, skills; issue one credential as a draft.
Add one secure layer between your agents and this server.