Skip to main content
Glama
Cresca MCP Server

Cresca MCP Server

Add contacts to a list

add_contacts
Idempotent

Adds 1–1,000 contacts to a marketing list, creating it if absent, updating existing names, and rejecting duplicates or invalid addresses without sending email.

Instructions

POST /contacts. Adds 1 to 1,000 contacts to a marketing contact list, creating the list if it does not exist. Existing contacts get their name updated and are added to the list; nobody is duplicated. Invalid, disposable, role/no-reply, suppressed and duplicate addresses are rejected and listed in errors (with their index); the rest are still added. When the plan's contact limit is reached, summary.limit_reached is true. Imports are limited to 120 requests per 15 minutes. Only add people who agreed to receive marketing email. Needs a full-access key. Does not send any email.

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": {
      "list_name": "<list_name>",
      "contacts": "<contacts>"
    },
    "name": "add_contacts"
  }
}

Input Schema

NameRequiredDescriptionDefault
contactsYes1 to 1,000 entries. Each is an email address, or { email, first_name?, last_name? }.
list_nameYesName of the contact list. Created if it does not exist.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare openWorldHint and readOnlyHint=false, but the description goes far beyond them: partial-success semantics (rejected addresses listed in errors with index, remaining ones still added), the summary.limit_reached signal, a 120 requests/15-minute rate limit, a full-access key requirement, and a consent precondition. It also confirms no email is sent and that duplicates are not created, which is consistent with idempotentHint.

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?

Every sentence carries load-bearing information — rejection rules, limits, auth, consent, side-effect absence — with the core action front-loaded in the first clause. It reads as one dense block rather than scannable segments, and the leading 'POST /contacts' is the least useful fragment.

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?

There is no output schema, yet the description still discloses the return-relevant facts an agent needs: failed addresses appear in errors with their index, valid ones are still added, and summary.limit_reached flags plan-cap exhaustion. Auth, rate limit, consent, and mutation semantics are all covered for a write tool.

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 already 100% for both parameters, so the 3 baseline applies; the description adds real meaning beyond the schema by explaining that list_name creates a list when missing and that existing contacts are updated rather than duplicated. The per-address rejection behavior tied to the contacts array (with index in errors, rest still added) is extra semantic detail the schema does not convey.

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 concrete verb and resource ('POST /contacts', 'Adds 1 to 1,000 contacts to a marketing contact list') and specifies scope (marketing contact list, creates list if absent). An agent can distinguish it from the send_email/list_emails siblings purely from the text, especially via 'Does not send any email.'

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 gives a clear condition for correct use ('Only add people who agreed to receive marketing email') and implicitly excludes messaging siblings ('Does not send any email'). It never explicitly names a sibling alternative or says when a different import path should be preferred, so it stops short of full when/when-not guidance.

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