Nettskjema MCP Server

Overview Schema Source Related Servers Discussions Admin

upload_codebook

Destructive

Uploads a complete codebook mapping form elements, sub-elements, and answer options to external identifiers for a Nettskjema form. Include every mapping; omitted entries may be deleted.

Instructions

Upload a codebook mapping form elements to external identifiers.

The spec does not document whether omitted entries are preserved or deleted. Send the complete mapping you want the form to have: include every element, sub-element and answer option whose external id you want to keep or set. Omitting an entry has undefined effect and may delete that mapping.

Each map is validated against the CodebookDTO schema before the request is sent. All three maps are required by the schema: send an empty dict for any map you do not need to populate.

Input Schema

Name	Required	Description
`form_id`	Yes	The form's numeric ID.
`element_ids_and_external_element_ids_map`	Yes	A mapping of element IDs (as strings) to their external IDs.
`sub_element_ids_and_external_element_ids_map`	Yes	A mapping of sub-element IDs (as strings) to their external IDs.
`answer_option_ids_and_external_answer_option_ids_map`	Yes	A mapping of answer option IDs (as strings) to their external IDs.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 20, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only declare destructiveHint=true; the description goes further by disclosing the destructive mechanism (omitted entries may delete mappings) and clarifying the spec's silence on preservation. This is exactly the extra context annotations cannot carry.

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?

Front-loaded with the purpose, then the risk, then the mechanical guidance. Slightly repetitive in restating the omission risk twice, but every paragraph carries actionable content.

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?

A destructive mutation with an output schema and full annotation coverage; the description supplies the missing risk semantics. Nothing critical is absent, though it could note the effect on the form definition itself.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: all three maps are required by CodebookDTO and empty dicts are the correct way to express 'no mapping'. That is operational guidance beyond the schema's type declarations.

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?

States a specific verb and resource: 'Upload a codebook mapping form elements to external identifiers.' It is clearly distinct from siblings like update_form_element or replace_form_elements, though it does not name a sibling to contrast against.

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?

Explicitly tells the agent to send the complete mapping and to send an empty dict for maps not needed, and warns that omitting entries has undefined effect. This is precisely the when/how-to-use guidance needed for a replace-style upload.

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