Skip to main content
Glama

Update user metadata

update_user_metadata
Destructive

Deep-merge public, private or unsafe metadata into an instance's user. Existing nested objects merge recursively and null-valued keys are removed at merged levels. New or replacement nested objects are copied as-is, including nulls, matching BAPI. Repeating such a patch can change its result. Arrays replace existing arrays. Omitted fields and top-level null leave metadata unchanged. Returns only a confirmation, never metadata values. With dry_run, returns the target and supplied metadata categories without writing or showing values.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "application_id": "<application_id>",
      "instance": "<instance>",
      "user_id": "<user_id>"
    },
    "name": "update_user_metadata"
  }
}

Input Schema

NameRequiredDescriptionDefault
dry_runNoPreview the target and metadata categories without writing or returning values.
user_idYesClerk user ID (user_…) in the selected instance.
instanceYesInstance to target: "development", "production", or a full instance ID (ins_…).
application_idYesClerk application ID (app_…).
public_metadataNoPublic metadata merge patch, visible to the frontend. Limit 8 KB per field.
unsafe_metadataNoUnsafe metadata merge patch, also writable by the user through frontend APIs.
private_metadataNoPrivate metadata merge patch, available only through backend APIs. Never returned by this tool.

Output Schema

NameRequiredDescriptionDefault
dry_runNo
updatedNo
user_idYes
metadata_fieldsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already flag destructive=true and idempotentHint=false; the description goes well beyond by explaining exactly why it is non-idempotent (nulls copied as-is in replacement objects can make repeated patches produce different results), how nulls are removed at merged levels, that arrays replace rather than merge, and that only a confirmation is returned. This is precisely 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 core operation and then packed with genuinely load-bearing details; no filler sentences. It is dense and leans on jargon ('matching BAPI', 'unsafe metadata') that a cold reader must already know, which keeps it from a 5.

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 destructive, 7-parameter merge tool with an output schema, this covers everything an agent needs: merge semantics, null handling, array behavior, non-idempotency warning, return shape, and dry_run preview. Nothing material is missing.

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: it explains the null semantics of each metadata field (top-level null leaves metadata unchanged) and what dry_run returns without writing. It does not address the application_id/instance/user_id targeting params, which the schema already covers adequately.

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 specific verb and resource — deep-merging public, private, or unsafe metadata into an instance's user — and the merge particulars (recursive merge, null removal, array replacement) make it unmistakably distinct from the sibling update_user.

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

Usage Guidelines3/5

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

Usage is only implied: the semantics make clear this is the tool for partial/metadata patches, and dry_run is explained, but the description never states when to prefer this over update_user or when a full replacement is warranted. No explicit exclusions or prerequisites (permissions, instance targeting) are given.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources