domeneshop-mcp

Create or update DNS record

upsert_dns_record

DestructiveIdempotent

Create or update a DNS record for a host and type so exactly one exists: it updates the existing record or creates a new one if none is present.

Instructions

Make sure a host has exactly this record of the given type: updates the existing record for that host and type, or creates one if there is none. When updating, optional fields you leave out (e.g. ttl, priority) keep their stored value. Fails without changing anything if the host already has several records of that type (common for MX and TXT); then use patch_dns_record with a record_id, or create_dns_record to add another. Returns { action: "created" | "updated", record }.

Input Schema

Name	Required	Description
`alg`	No	required for DS: the DNSSEC signing algorithm number
`tag`	No	required for DS (the key tag of the referenced DNSKEY) and for CAA (the property tag, e.g. issue, issuewild or iodef)
`ttl`	No	time-to-live in seconds, 60-604800, must be a multiple of 60, defaults to 3600
`data`	Yes	the record's main value: an IP address for A/AAAA, a hostname for ANAME/CNAME/MX/NS/SRV, free text for TXT, the CAA property value, or the hex hash for DS/TLSA
`host`	Yes	the host/subdomain the record applies to, e.g. 'www' or '@' for the root
`port`	No	required for SRV: the port the service is found on
`type`	Yes	the record type
`dtype`	No	required for TLSA: matching type of the hash in data (0 exact match, 1 SHA-256, 2 SHA-512)
`flags`	No	required for CAA: 128 to mark the property critical, otherwise 0
`usage`	No	required for TLSA: certificate usage (0 PKIX-TA, 1 PKIX-EE, 2 DANE-TA, 3 DANE-EE)
`digest`	No	required for DS: digest type of the hash in data (1 SHA-1, 2 SHA-256, 4 SHA-384)
`weight`	No	required for SRV: relative weight among records with the same priority
`priority`	No	required for MX and SRV: preference value, lower is tried first
`selector`	No	required for TLSA: what the hash is taken from (0 full certificate, 1 subject public key)
`domain_id`	Yes	the Domeneshop domain ID, from list_domains

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.1Oct 21, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (idempotentHint/destructiveHint/openWorldHint), the description discloses merge semantics ('optional fields you leave out keep their stored value'), atomic failure behavior ('Fails without changing anything'), and the return shape. These are exactly the behavioral facts annotations cannot convey for a partially-destructive upsert.

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

Conciseness5/5

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

Four tight sentences, front-loaded with the upsert semantics and ordered by likelihood of need: what it does, update merge behavior, failure case plus alternatives, return shape. No filler.

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 15-parameter tool with 100% schema coverage and no output schema, the description supplies the missing pieces: the uniqueness/failure precondition, the alternative routes, and the return payload. Nothing an agent needs to call this correctly is absent.

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 description coverage is 100%, so the baseline is 3. The description adds real value on top: it clarifies that omitted optional fields such as ttl and priority retain stored values on update rather than reverting to schema defaults, and it introduces the record_id parameter that lives in patch_dns_record.

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?

States a precise verb+resource+scope: 'Make sure a host has exactly this record of the given type: updates the existing record for that host and type, or creates one if there is none.' An agent can distinguish it from create_dns_record, update_dns_record, and patch_dns_record without opening any schema.

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 defines the failure condition (host already has several records of that type, common for MX/TXT) and routes the agent to named alternatives: patch_dns_record with a record_id, or create_dns_record to add another. Both when-to-use and when-not-to-use are covered.

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

Deploy Server

Create or update DNS record

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools