Skip to main content
Glama

Upsert customer (write)

upsert_customer

Create or update a customer record by number, with a required name and optional contact, address, and tax details; write access must be enabled.

Instructions

PUT /customer/{number}. name is required: the API refuses a customer without one. Requires AIOTIC_MCP_ALLOW_WRITES=true.

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": {
      "number": "<number>",
      "data": "<data>"
    },
    "name": "upsert_customer"
  }
}

Input Schema

NameRequiredDescriptionDefault
dataYes
numberYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.0
    • addedInput schema / properties / data / properties / name / minLength
      Added value: +1
    • addedInput schema / properties / data / required
      Added value: +[
      +  "name"
      +]
  2. First observedv0.2.1

TDQS

B3/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden, and it does disclose two real operational facts: writes are gated behind AIOTIC_MCP_ALLOW_WRITES=true, and the API rejects records lacking a name. However, it never explains PUT replacement semantics — whether omitted fields in `data` are wiped or preserved — which is the single most consequential behavior for an upsert tool, nor does it mention idempotency or error behavior.

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?

Three short, front-loaded sentences with no filler: endpoint first, then the required-field constraint, then the write gate. It is efficiently sized, though leading with the literal HTTP route is slightly less useful to an agent than a plain-language statement of what happens.

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

Completeness3/5

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

For a two-parameter but deeply nested write tool with no annotations and no output schema, the description covers the bare minimum: the route, the one hard validation rule, and the write toggle. It omits replacement semantics, field meanings, and any indication of what a successful call returns, leaving meaningful gaps for a mutation of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only notes that `name` is required — which the schema already enforces via required and minLength. It says nothing about the `number` path parameter's format constraints (maxLength 200, no whitespace or slashes) or what any of the ten nested data fields mean.

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 gives the concrete operation as 'PUT /customer/{number}', which specifies both the verb (PUT) and resource (customer) and implies upsert semantics. Combined with the tool name and title, an agent can tell this is a write to a specific customer record rather than a read like get_customer or search_customers. The one gap is that the prose never spells out 'creates or replaces' in words, relying on the reader to decode PUT.

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 or when-not guidance: nothing says whether to reach for this instead of get_customer, search_customers, or delete_customer, and no note on verifying a customer exists first. The env-flag prerequisite (AIOTIC_MCP_ALLOW_WRITES=true) is useful operational context but is a precondition, not usage guidance.

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