Skip to main content
Glama
Dynamics 365 MCP Server

Dynamics 365 MCP Server

by Kenny-666

upsert_record_by_key

Destructive

Create or update a Dynamics 365 record using an alternate key with conditional PATCH, optional dry-run preview, and strict key validation to prevent silent key changes.

Instructions

Use one active native alternate key with conditional PATCH. Validates key metadata/types and never silently changes key values. Races return errors; writes are never automatically repeated.

Input Schema

NameRequiredDescriptionDefault
dataYesNative JSON attribute data. Related bindings must stay inside the configured organization API. Local JSON limit 10 MiB.
modeNoDefault upsert. Uses native conditional PATCH: create-only if absent, guarded update if present. No automatic retry on races.
dryRunNoCompatibility alias for dry_run. Conflicting aliases are rejected.
dry_runNoRead-only preview of environment, target, changes and write blockers. Default false; sensitive fields are masked.
ifMatchNoCompatibility alias for if_match. Conflicting aliases are rejected.
if_matchNoSpecific ETag from a prior read/preview. Without it, reads the current record ETag when the table supports concurrency.
alternateKeyNoCompatibility alias for alternate_key. Conflicting aliases are rejected.
alternate_keyNoExact values for one declared active alternate key. Native metadata determines string/integer/choice/decimal/UTC datetime/lookup encoding. No null values.
collectionNameNoCompatibility alias for collection_name. Conflicting aliases are rejected.
collection_nameNoNative EntitySetName, such as accounts. Validated against table metadata.
environment_profileNoOptional named environment profile for this call; omit to use the configured default.
allowUnprotectedWriteNoCompatibility alias for allow_unprotected_write. Conflicting aliases are rejected.
allow_unprotected_writeNoDefault false. Explicitly allow an unprotected write if table concurrency is unconfirmed, or for collection relationship membership. Does not bypass a supplied ETag conflict.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.1.2
    • addedInput schema / properties / environment_profile
      Added value: +{
      +  "description": "Optional named environment profile for this call; omit to use the configured default.",
      +  "pattern": "^[A-Za-z][A-Za-z0-9_]{0,31}$",
      +  "type": "string"
      +}
  2. First observedv1.0.0

TDQS

C2.7/5.0
Behavior3/5

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

Annotations already flag destructiveHint=true and idempotentHint=false; the description usefully adds that key metadata/types are validated, key values are never silently changed, races surface as errors, and writes are not auto-retried. What it does not disclose is the destructive side: which existing field values an upsert overwrites, and what happens to attributes omitted from the data object.

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?

It is short and front-loads the concurrency/validation facts, but it is written in telegraphic fragments rather than a clear statement of what the tool does, so brevity comes at the cost of a readable core sentence. Nothing is redundant, but the opening clause reads like an implementation note rather than a purpose statement.

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

Completeness2/5

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

For a 13-parameter, destructive, non-idempotent write with nested data and no output schema, the description omits the essential contract: what entity it mutates, what the response/error shapes are, and how the three modes and ETag semantics interact with the no-retry policy. It documents concurrency trivia while leaving the primary operation undefined.

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 100%, so baseline is 3. The description adds only marginal meaning beyond it ('one active native alternate key', no silent key mutation), and says nothing about mode (upsert/create_only/update_only), dry_run, if_match, or allow_unprotected_write, all of which are already covered in the schema.

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

Purpose3/5

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

The description states a mechanism ('conditional PATCH' keyed on 'one active native alternate key') but never plainly says it creates-or-updates a record in a collection, which is the tool's actual effect. It also does not contrast itself with the obvious siblings create_new_record, update_existing_record, or update_record_with_journal, so the agent must infer why an upsert-by-key exists alongside them.

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

Usage Guidelines2/5

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

There is no when-to-use guidance and no when-not-to-use guidance. Nothing tells the agent to prefer this over create_new_record/update_existing_record when a natural key already exists, or what prerequisites (declared active alternate key, supported concurrency) must hold before calling.

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

Deploy Server

Other Tools