alphaportal-mcp

alphaportal_set_notification

DestructiveIdempotent

Set a student's push/email notification preferences for AM/PM transportation runs across categories like student scan, school arrival, and stop radius entry. Confirmation required before applying.

Instructions

Set a student's transportation notification preferences (push/email, per AM/PM run) across the categories the district enables: stopRadiusEntry, studentScan, backupBus, schoolArrival, stopServiced. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview of the exact payload and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). NOTE: the portal sends the whole preference set at once; categories you omit may be left unchanged or reset by the server — review the preview first.

Input Schema

TableJSON Schema

Name	Required	Description
`studentId`	Yes	The numeric studentId.
`preferences`	Yes	Per-category push/email toggles.
`confirmToken`	No	ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.
`studentOriginalId`	No	The student's originalId (from alphaportal_list_students), if known.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.1.0Sep 24, 2026

removedInput schema / properties / confirm

Removed value: -{
-  "description": "Must be true to proceed. Without this, the tool returns a preview.",
-  "type": "boolean"
-}

addedInput schema / properties / confirmToken

Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}

Changed1 schema field changedv0.4.0Sep 19, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

First observedv0.0.0Aug 26, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Despite the annotations providing readOnlyHint=false, idempotentHint=true, and destructiveHint=true, the description goes beyond these by detailing the confirmation mechanism (both client-supported and fallback with confirmToken), the atomicity of the payload (whole set sent at once), and the risk of omitting categories being left unchanged or reset. This is significant behavioral disclosure that the annotations do not cover, such as the need for user consent and the potential side effects of omitted fields. The description does not contradict 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.

Conciseness4/5

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

The description is concise at two sentences, with the primary purpose front-loaded. It efficiently packs essential information: the categories, the confirmation requirement, the fallback mechanism, and the caution about omitted categories. It could be slightly more structured, but it avoids redundancy and every sentence adds value. It earns a 4 for being appropriately sized and focused, though not perfectly organized for quick scanning.

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

Completeness5/5

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

Given the tool's complexity (nested preferences, multiple categories, confirmation logic) and the lack of an output schema, the description is complete. It covers the key behavioral aspects (confirmation, preview), the risk of omitted categories, and references MCP_CONFIRM_MODE for client-specific handling. The input schema already documents all parameters, so the description fills the gaps regarding side effects and usage flow. An agent can safely and correctly invoke this tool following the description alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage, with detailed descriptions for studentId, preferences (including per-category objects and their boolean toggles), confirmToken, and studentOriginalId. The description adds context about the confirmToken's usage in the two-step fallback and the preview requirement, but the schema already explains confirmToken's purpose in detail. Since the schema does the heavy lifting, the description's added value is marginal, but it does reinforce the critical behavior of confirmToken, justifying a baseline 3 rather than lower.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: setting a student's transportation notification preferences across five specific categories, with explicit mention of push/email and AM/PM run toggles. It distinguishes itself from sibling tools like alphaportal_list_notifications (which likely reads notifications) and alphaportal_get_settings (which likely reads settings). The verb 'set' combined with the resource 'notification preferences' and the enumerated categories provides a precise and actionable definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('Set a student's transportation notification preferences') and provides crucial usage context: the need for user confirmation, the two-step fallback with confirmToken, and the caveat that omitting categories may result in unset or reset values, advising to review the preview first. It also references MCP_CONFIRM_MODE, giving the agent a clear conditional for different client capabilities. This is comprehensive guidance that leaves little to inference.

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

Deploy Server

alphaportal_set_notification

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools