Create a contact if it doesn't exist, or update it if it does.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Contact email address,required | ||
| api_key | No | MailerCloud API key | |
| list_id | Yes | List ID,required | |
| last_name | No | Last name | |
| first_name | No | First name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds a genuinely useful trait — the conditional create/update logic — which explains and is consistent with idempotentHint=true. However, it does not disclose a material behavioral detail: whether an update is partial (only provided fields change) or a full replacement (omitted fields like first_name/last_name are cleared). No contradiction with 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?
A single sentence of about twelve words with zero filler. The core conditional behavior is stated immediately and completely, and every word earns its place. This is appropriate conciseness, not under-specification.
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?
For a moderately simple tool (5 params, 2 required, full schema coverage, annotations covering safety and idempotency), the description covers the essential behavior. Remaining gaps: no indication of what the response indicates (whether the contact was created or updated) and no clarification of partial-update field semantics — both affect an agent's confidence in interpreting the call's effect. Adequate but with clear gaps.
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% — email, api_key, list_id, last_name, and first_name all have schema-level descriptions — so the baseline of 3 applies even though the tool description names no parameters. The tool description adds no param-level meaning beyond the schema, and the schema descriptions are terse but present. The description's job here is satisfied by the parameter descriptions in the schema.
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 specific verbs (create/update) and a clear resource (contact), and it unpacks the 'upsert' concept in plain conditional terms rather than restating the tool name. It implicitly distinguishes the tool from the create_contact and update_contact siblings by describing the combined create-or-update behavior, though it does not name those siblings explicitly.
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 conditional phrasing ('if it doesn't exist... if it does') implies the natural use case: call this when you want a contact to exist for an email and are unsure whether it is already present. However, there is no explicit guidance on when to prefer alternatives (e.g., batch_create_contacts for bulk creation, update_contact when the contact is known to exist, delete_contact when removal is intended). Usage context is present but only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Tool purposes are largely distinct, with clear separation between CRUD operations, analytics, and deliverability tools. Some overlap exists between get_campaign, analyze_campaign, and campaign_health_dashboard, but descriptions clarify scope sufficiently.
Most tools follow a consistent verb_noun pattern (list_, get_, create_, update_, delete_, send_). Minor exceptions like campaign_health_dashboard and engagement_funnel are descriptive but break the pattern.
With 47 tools, this is a very large surface area. While the variety reflects the breadth of email marketing operations, the count exceeds what is typically manageable and suggests potential redundancy or over-scoping.
The tool set covers most core workflows: contact/list management, campaign lifecycle, templates, webhooks, analytics, and transactional email. Minor gaps like no delete for templates or tags are acceptable but not fatal.
