Retrieve a contact by ID or email address, using the domain parameter to disambiguate emails shared across multiple domain pools.
Retrieve a contact (GET /contacts/:id). A contact id is exact; an EMAIL can exist in several domains' pools, so pass domain to pick the pool.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The contact id OR email address. | |
| domain | No | Disambiguates an EMAIL id across domains (omit for a contact id). |
Changes observed during successful MCP inspections.
v1.0.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a GET operation and explains the domain/email pool nuance, but it does not specify what happens if `domain` is omitted for an email id, nor the response format or error handling. It adds useful context but leaves important behavioral gaps.
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?
Two sentences, front-loaded with the verb and resource. The critical nuance about email pools is delivered compactly with no filler or redundant restating of schema fields.
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 two-parameter read operation with 100% schema coverage, the description covers the main contextual pitfall (email ambiguity across pools) and the exact endpoint. It lacks response shape and error behavior, but given the low complexity and the presence of sibling tools for related operations, it is largely complete.
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?
The input schema already describes both parameters, and schema coverage is 100%. The description adds genuine meaning beyond the schema by explaining why `domain` is needed and when it can be omitted, enriching the semantics of `id` as an ambiguous email reference rather than just a string.
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 opens with a specific verb and resource ('Retrieve a contact') and states the endpoint (GET /contacts/:id). It also distinguishes the tool by clarifying that the id may be a contact id or an email, setting it apart from sibling tools like get_contact_property or list_contacts without requiring schemas to be opened.
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 gives clear operational context: a contact id is exact, while an email needs the `domain` parameter to disambiguate across pools. It does not explicitly name alternative tools or state when not to use this one, but the single-contact retrieval scope is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.