create_contact_with_listsAdd new contacts to your SendGrid account and assign them to selected email lists in one operation. Solves the need to manage contact creation and list assignment separately.
Create new contacts and assign them to specific email lists
| Name | Required | Description | Default |
|---|---|---|---|
| contacts | Yes | Array of contact objects | |
| list_ids | Yes | Array of list IDs to add the contact to |
Changes observed during successful MCP inspections.
v1.1.1Input schema / additionalPropertiesRemoved value: -falseInput schema / properties / contacts / items / additionalPropertiesRemoved value: -falseInput schema / properties / contacts / items / properties / custom_fields / propertyNamesAdded value: +{
+ "type": "string"
+}v1.0.0Input schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide the key behavioral signals: readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description restates the core mutation (create and assign lists) without adding extra behavioral context such as duplicate handling, list validation, or partial-failure semantics. There is no contradiction between the description and the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no filler. The primary action 'create new contacts' is front-loaded, and the list assignment is immediately clear. This is appropriately concise for scanning during tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description plus the rich schema covers the essential information needed to invoke the tool: required contacts, optional fields, and list_ids. However, for a mutating tool with no output schema, it leaves edge-case behavior unstated—such as what happens if a contact already exists, if a list_id is invalid, or how partial failures are handled. The idempotentHint annotation helps but the description itself remains minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both contacts and list_ids fully described in the input schema. The description does not add parameter-level meaning beyond what the schema already provides. Since the schema carries the semantic burden, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create new contacts and assign them to specific email lists.' This clearly distinguishes it from sibling create_contact, which does not mention list assignment, and from list-management or removal tools. The plural 'contacts' and 'specific email lists' also signal the intended scope of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use guidance or explicit alternatives. It never says to use this tool instead of create_contact when list assignment is needed, nor does it mention when not to use it (e.g., for contacts without lists). An agent must infer the usage context from the tool name and sibling list rather than from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.