One U Education

Submit an asynchronous planning calculation

create_planning_calculation

Idempotent

Accept an ordinary calculation asynchronously; heuristic submissions are unavailable through MCP. Omitted mode defaults to ordinary; expected_revision maps to base_revision. calculation_scope selects the fixed existing_189 or future configuration independently from mode. Full planning starts existing_189; after success show returned routes and use route_summary for the conditional PR-date decision, including forecast. Continue future only when that authoritative decision is ready with no date, or the user requests more options; respect an explicit 189-only scope. Before continuing, check the current dossier revision matches the first input_revision; pass continuation_of with the successful first calculation ID, the same revision/mode, and a distinct request_id. A version/revision/continuation error must not be bypassed by dropping the link or using a new key. Linked work follows the service quota contract. Keep request_id unchanged for retries. Missing necessary facts returns 422 needs_information with revision and versioned schema references, without accepting a task or reserving quota; supplement facts then use a new revision/request_id. Unresolved material preferences constrain only dependent actions through the Forms-enforced scope; do not treat scope_gaps as global blockers or bypass them with calculation options. Accepted work returns a persistent calculation_id immediately; use get_planning_calculation to poll and list_planning_calculations with request_id to recover a timed-out submission. parent_calculation_id and comparison must belong to this account and non-VIP channel. New comparison calculations requiring heuristic mode are unavailable through MCP; saved heuristic results remain readable. No VIP, arbitrary engines or budgets. Requires the authenticated One U Education account and declared planning scope; credentials and user identity are never tool arguments.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "dossier_id": "<dossier_id>",
      "expected_revision": "<expected_revision>",
      "request_id": "<request_id>"
    },
    "name": "create_planning_calculation"
  }
}

Input Schema

Name	Required	Default
`mode`	No	ordinary
`comparison`	No
`dossier_id`	Yes
`request_id`	Yes
`continuation_of`	No
`calculation_scope`	No	future
`expected_revision`	Yes

Output Schema

Name	Required	Description	Default
`msg`	Yes
`code`	Yes
`data`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 1, 2026
- addedInput schema / properties / mode / const
```
Added value: +"ordinary"
```
- removedInput schema / properties / mode / enum
```
Removed value: -[
-  "ordinary",
-  "heuristic"
-]
```

Changed2 schema fields changedNov 1, 2026

addedInput schema / properties / calculation_scope

Added value: +{
+  "default": "future",
+  "enum": [
+    "existing_189",
+    "future"
+  ],
+  "type": "string"
+}

addedInput schema / properties / continuation_of

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 128,
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

AddedOct 31, 2026

TDQS

A4/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses idempotency mechanics (keep request_id unchanged for retries, distinct request_id per continuation), quota reservation semantics (422 needs_information does not accept a task or reserve quota), immediate return of a persistent calculation_id, and auth constraints (One U Education account, credentials never tool arguments). The idempotentHint=true annotation is reinforced and operationalized rather than merely restated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

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

The core operation is front-loaded in the first sentence, and most sentences carry non-obvious operational value. But it is a single unstructured block that mixes purpose, preconditions, error semantics, quota rules, and auth, so an agent must parse the whole run-on to extract the continuation procedure.

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

Completeness4/5

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, and the description still usefully notes the immediate calculation_id. For a high-stakes asynchronous mutation it covers auth, quota, error paths, and the continuation workflow. The remaining hole is the undocumented nested comparison overrides and the dangling parent_calculation_id reference.

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?

Schema description coverage is 0%, so the description carries the full burden, and it does explain several parameters: mode defaults to ordinary, expected_revision maps to base_revision, calculation_scope is independent of mode, continuation_of takes the successful first calculation ID. However the comparison object's candidate_id/overrides structure (including the 60-item who/action/occ payload) is left entirely unexplained, and parent_calculation_id is referenced although it is not in the schema — a real gap for a 7-parameter tool.

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

Purpose4/5

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

The opening clause names a concrete verb and resource ('Accept an ordinary calculation asynchronously') and immediately rules out the heuristic variant, so an agent knows this is the submit-side counterpart to get_planning_calculation and list_planning_calculations. It stops short of explaining what a 'planning calculation' actually produces, which keeps it from a 5 given the heavy domain jargon (existing_189, future, dossier revision).

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

Usage Guidelines4/5

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

Explicit routing is present: poll with get_planning_calculation, recover a timed-out submission with list_planning_calculations by request_id, and continue future only under stated conditions while respecting an explicit 189-only scope. Exclusions are also named (no heuristic submissions via MCP, no VIP/arbitrary engines/budgets). The conditional workflow is dense and interleaved with error handling, which makes it harder to act on than a clean when/when-not list.

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

All One U Education tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?