Skip to main content
Glama
agentisend

agentisend

Create or update a contact

upsert_contact
DestructiveIdempotent

Create a contact by email or update an existing record, merging supplied fields so you can change one property without knowing the rest. This does not subscribe or send messages.

Instructions

Purpose: create a contact, or update the one with that address. Properties are merged, so you can set one field without knowing the rest. NOT for: subscribing anyone to anything, or sending. Adding a contact sends nothing. Returns: the contact as it now stands, including consent if it was given.

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": {
      "email": "<email>"
    },
    "name": "upsert_contact"
  }
}

Input Schema

NameRequiredDescriptionDefault
emailYesThe contact's address; the identity of the record.
consentNoOptional consent provenance for this address. Stored, shown and exported; never a reason this call is refused.
propertiesNoFields to merge in, e.g. { "first_name": "Ada" }. Each value is a string, number, boolean, ISO date or list of strings; a property keeps the type it was first written with.
audience_idNoAdd the contact to this audience. The id is a segment on this account. A value that is not an audience id saves the contact and adds nothing.
idempotency_keyNoYour own key for this action. Retrying with the same key returns the first result instead of doing it twice — send one whenever a retry could double the effect.

Output Schema

NameRequiredDescriptionDefault
idNoIdentifier.
emailNo
errorNoPresent instead of the fields above when the call was refused: code, message, fix, docs_url, retryable and, when waiting helps, retry_after_seconds.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. Beyond that the description discloses the merge semantics ("you can set one field without knowing the rest") and that no email is sent, which are real behavioral facts not visible in the annotations or schema.

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 short labeled lines (Purpose / NOT for / behavior / Returns) with zero filler, and the core purpose is front-loaded ahead of the exclusions.

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?

An output schema exists, yet the description still briefly frames the return ("the contact as it now stands, including consent if it was given"), and it covers merge, idempotency and consent caveats for a five-parameter nested-schema tool. Slightly incomplete in not stating what happens when an existing contact is overwritten or how a partial failure behaves, but broadly sufficient.

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%, including the properties merge wording and the audience_id and idempotency_key semantics, so the schema carries the parameter burden. The description adds only the general merge principle and the consent-optional nuance, which the schema mostly already states — a baseline 3.

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?

The description opens with a specific verb-plus-resource statement ("create a contact, or update the one with that address") that also resolves the ambiguity of the odd 'upsert' name. It is clearly distinguishable from siblings like delete_contact and list_contacts.

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?

Explicit exclusions are given: "NOT for: subscribing anyone to anything, or sending," plus the reassurance "Adding a contact sends nothing." That is strong when-not guidance, though no alternative tool is ever named for the subscribe/send cases, leaving the agent to infer it from the sibling catalog.

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