Mailercloud

create_contact

Create a new contact in a MailerCloud list. Email and list_id are required. Do not include sensitive personal data (health, financial, government ID, payment card, passwords).

Input Schema

Name	Required	Description
`city`	No	City
`tags`	No	Tags to assign
`email`	Yes	Contact email address
`phone`	No	Phone number
`state`	No	State
`country`	No	Country
`dry_run`	No	Validate and show what would be created without creating anything
`list_id`	Yes	List ID to add contact to
`job_title`	No	Job title
`last_name`	No	Last name
`department`	No	Department
`first_name`	No	First name
`company_name`	No	Company name
`custom_fields`	No	Custom field values, keyed by the field ID, name or key shown by list_custom_fields. Values: text, number, or date (YYYY-MM-DD). Do not include sensitive personal data (health, financial, government ID, payment card, passwords).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 23, 2026

changedInput schema / properties / custom_fields / description

Previous value: -"Custom field values. Only keys returned by list_custom_fields. Values: text, number, or date (YYYY-MM-DD). Do not include sensitive personal data (health, financial, government ID, payment card, passwords)."New value: +"Custom field values, keyed by the field ID, name or key shown by list_custom_fields. Values: text, number, or date (YYYY-MM-DD). Do not include sensitive personal data (health, financial, government ID, payment card, passwords)."

changedInput schema / properties / email / description

Previous value: -"Contact email address,required"New value: +"Contact email address"

changedInput schema / properties / list_id / description

Previous value: -"List ID to add contact to,required"New value: +"List ID to add contact to"

Changed2 schema fields changedOct 19, 2026

removedInput schema / properties / api_key

Removed value: -{
-  "description": "MailerCloud API key",
-  "type": "string"
-}

addedInput schema / properties / dry_run

Added value: +{
+  "description": "Validate and show what would be created without creating anything",
+  "type": "boolean"
+}

Changed1 schema field changedOct 8, 2026

changedInput schema / properties / custom_fields / description

Previous value: -"Custom field values"New value: +"Custom field values. Only keys returned by list_custom_fields. Values: text, number, or date (YYYY-MM-DD). Do not include sensitive personal data (health, financial, government ID, payment card, passwords)."

First observedSep 2, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare write, non-idempotent, open-world, non-destructive behavior, so the bar is lower. The description adds genuinely non-structured context: a compliance constraint against submitting health, financial, government ID, card, or password data, which an agent would otherwise not know.

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 sentences, with the action and its target front-loaded and the safety caveat last. The 'Email and list_id are required' sentence duplicates the schema's required array and is the one line that does not fully earn its place.

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 14-parameter mutation with a nested object and no output schema, the description covers the action, required inputs, and a data policy, but remains silent on duplicate-email behavior, partial-failure semantics, and what a successful response contains. Adequate but leaves real gaps for a write tool.

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 coverage is 100% and each of the 14 parameters carries its own description, including the nested custom_fields contract (keyed by field ID/name/key, values text/number/date as YYYY-MM-DD). The description merely restates the two required params, so baseline 3 is correct.

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?

States a specific verb and resource ('Create a new contact in a MailerCloud list') and names the container resource, so an agent knows exactly what is produced. It does not distinguish itself from close siblings such as upsert_contact, update_contact, or batch_create_contacts, so it stops short of full sibling differentiation.

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?

It gives the required inputs and a clear prohibition on sensitive personal data, and the schema's dry_run description implies a validate-first path. However there is no guidance on when to use this instead of upsert_contact or batch_create_contacts, and no mention of what happens when the email already exists in the list.

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

All Mailercloud tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?