Apier MCP Server

Altinn 2 → Altinn 3 migration guidance

get_altinn_migration_guidance

Read-onlyIdempotent

Map Altinn 2 service or role codes to Altinn 3 equivalents, with verified migration status and deadline passed info to guide remediation.

Instructions

Discover the Altinn 3 equivalent of an Altinn 2 service or role code. The 19 June 2026 Altinn 2 deprecation deadline has passed, so this serves remediation for any integration still on Altinn 2. Pass { altinn2_code } (alphanumeric, 1–10 chars, e.g. A0208) for a single mapping, or omit it for the entire migration map. Every response carries the deprecation status computed in Europe/Oslo (deprecation_deadline, days_remaining — floored at 0, deadline_passed — now true). Each entry ships a verified flag: gate any production migration action on verified === true; unverified entries are hints, not instructions. Deterministic static map (DigDir-sourced) — no government system is contacted at call time. Failure modes: NOT_FOUND when a supplied code is not in the map (omit it to list every entry), VALIDATION_FAILED (INVALID_CODE), SCOPE_INSUFFICIENT (needs read:digdir). No sandbox mirror — a sandbox bearer gets SANDBOX_TOOL_UNAVAILABLE. Docs: https://www.apier.no/docs/guides/altinn-system-users

Input Schema

TableJSON Schema

Name	Required	Description	Default
`altinn2_code`	No	An Altinn 2 service or role code to resolve (alphanumeric, 1–10 chars, e.g. A0208). Omit to get the entire migration map.

Output Schema

TableJSON Schema

Name	Required	Description
`_meta`	No
`result`	Yes	The migration lookup: `deprecation_deadline` (Oslo), `days_remaining`, `deadline_passed`, and either one `entry` or the full `mappings[]`. Gate production migration actions on `verified === true`.
`metadata`	Yes
`justification`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.1Sep 26, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: deterministic static map, no government system contacted, Europe/Oslo timezone for deprecation status, the `verified` flag with a warning to gate production actions, and specific failure modes including sandbox behavior. This far exceeds annotation coverage.

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 a single dense paragraph but every sentence carries actionable information: purpose, usage, return flags, determinism, failure modes, scope, and docs. It is front-loaded with the primary purpose. While a touch long, no sentence is wasted.

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?

For a single-optional-parameter tool with an output schema, annotations, and sibling context, the description is impressively complete. It covers return semantics (verified flag, deprecation fields), failure modes, authentication scope, sandbox limitations, and a docs link. The output schema handles return-value details, so the description need not repeat them.

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

Parameters4/5

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

The schema already documents the parameter's pattern, length, and example. The description adds the key semantic of omission: 'omit it for the entire migration map,' which is not in the schema. It also reinforces the parameter's purpose, providing real value beyond the structured field.

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 opens with a specific verb+resource statement: 'Discover the Altinn 3 equivalent of an Altinn 2 service or role code.' This clearly distinguishes the tool from all sibling tools, which focus on companies, deadlines, or authorization. The mention of the deprecation deadline further clarifies the tool's niche purpose.

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?

The description clearly states the context: 'serves remediation for any integration still on Altinn 2.' It explains both invocation modes (pass a code for a single mapping, omit for the entire map). It stops short of explicit exclusions or naming alternative tools, but the tool is unique among siblings.

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