Skip to main content
Glama
Dynamics 365 MCP Server

Dynamics 365 MCP Server

by Kenny-666

associate_records

Destructive

Link Dataverse records through a validated navigation property: set a single-valued lookup with a conditional PATCH or add collection membership via $ref with explicit write permission.

Instructions

Associate records using a validated native navigation property. Single-valued lookup uses conditional PATCH; collection membership uses $ref and requires explicit allow_unprotected_write because parent ETags do not guarantee membership concurrency.

Input Schema

NameRequiredDescriptionDefault
idYes
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.
relatedIdNoCompatibility alias for related_id. Conflicting aliases are rejected.
related_idNo
collectionNameNoCompatibility alias for collection_name. Conflicting aliases are rejected.
collection_nameNoNative EntitySetName, such as accounts. Validated against table metadata.
navigationPropertyNoCompatibility alias for navigation_property. Conflicting aliases are rejected.
environment_profileNoOptional named environment profile for this call; omit to use the configured default.
navigation_propertyNoNative navigation property, resolved from relationship metadata to the specified related table.
allowUnprotectedWriteNoCompatibility alias for allow_unprotected_write. Conflicting aliases are rejected.
relatedCollectionNameNoCompatibility alias for related_collection_name. 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.
related_collection_nameNo

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

A3.9/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds genuinely new behavioral context: the underlying mechanism differs by cardinality (PATCH vs. $ref), collection writes require an explicit opt-in flag, and parent ETags do not guarantee membership concurrency. That concurrency caveat is exactly the kind of risk an agent needs before invoking a non-idempotent write.

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?

Two dense sentences with no filler; the purpose comes first and the mode-specific mechanics follow. The phrasing ('$ref', 'conditional PATCH') is jargon-heavy but precise for the audience, and nothing is redundant.

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?

For a 16-parameter mutation tool with strong schema coverage and clear annotations, the description covers the ambiguous parts: mechanism selection, the opt-in write flag, and the concurrency limitation. The absence of any hint about the response shape is the main remaining gap, since no output schema exists.

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 81%, so the schema already documents id patterns, ETag handling, dry_run, environment_profile, and the alias-conflict rules. The description reinforces that navigation_property is validated against metadata and that allow_unprotected_write is mandatory for collection paths, but adds little beyond what the parameter descriptions already say.

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 description names a specific verb and resource ('Associate records using a validated native navigation property') and splits the operation into two concrete modes (single-valued lookup vs. collection membership). It does not explicitly name the sibling disassociate_records, but the additive framing makes the contrast obvious.

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?

It clearly states which path applies when: single-valued lookups go through conditional PATCH, collection membership goes through $ref and requires allow_unprotected_write. It does not discuss when to prefer this over update_existing_record or execute_record_batch, but for the two internal paths the selection criteria are explicit.

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