fairquery-contact-enricher

Official

by fairquery

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Normalize and dedupe domains (free)

normalize_domains

Read-onlyIdempotent

Cleans URLs, emails, and messy strings into bare hostnames, removes duplicates, and lists invalid entries. Previews billable domains and cost before enrichment.

Instructions

WHAT: Turn URLs, email addresses and messy strings into bare registrable hostnames (lowercase, no scheme/path/www), remove duplicates and list entries that are not valid domains. WHEN TO USE: before enrich_domains, to clean an input list and see exactly which domains would be billed. WHEN NOT TO USE: to get contacts, company names or check that a site is reachable - use enrich_domains. Does no DNS lookup. COST: free; local, no network, no APIFY_TOKEN. RETURNS: domains is exactly the list enrich_domains would bill; billable_count and estimated_max_cost_usd preview that bill; invalid entries would only get free error rows there. PARAMETERS: inputs: each element may hold one value or a newline/comma/semicolon-separated list; pieces are trimmed and empty ones dropped. Each piece is lowercased and reduced to its hostname (scheme, path, query, port and a leading "www." removed; for a bare email the part after @ is used); other subdomains are kept, so "blog.acme.com" and "acme.com" stay separate. A piece is invalid unless the host has a dot and a 2+ letter TLD (punycode xn-- hosts accepted). domains keeps first-seen order and duplicates_removed counts repeats after normalization. This is exactly the normalization enrich_domains applies: billable_count = min(domains.length, 1000 per run) and estimated_max_cost_usd = billable_count x $0.003 + the $0.00005 start fee, the most passing the same inputs to enrich_domains can cost (unreachable domains lower it). An empty array is accepted and returns empty lists. EXAMPLE: {"inputs":["https://www.Stripe.com/pricing","info@stripe.com","not a domain"]} -> {"domains":["stripe.com"],"invalid":["not a domain"],"duplicates_removed":1,"billable_count":1,"estimated_max_cost_usd":0.00305}

Input Schema

Name	Required	Description	Default
`inputs`	Yes	Required array (may be empty) of strings: URLs, domains or email addresses; each entry may also be a newline/comma/semicolon-separated list. Example: ["https://www.acme.com/contact","sales@acme.com","acme.com, beta.io"]

Output Schema

Name	Required	Description
`domains`	Yes	Unique normalized domains, input order
`invalid`	Yes	Entries that could not be parsed as a domain
`billable_count`	Yes	Domains one enrich_domains run would process and could bill (max 1000)
`duplicates_removed`	Yes	Count of duplicate entries dropped
`estimated_max_cost_usd`	Yes	Upper bound in USD for enrich_domains on the same inputs

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.1.0Oct 18, 2026

addedOutput schema / properties / billable_count

Added value: +{
+  "description": "Domains one enrich_domains run would process and could bill (max 1000)",
+  "type": "number"
+}

addedOutput schema / properties / estimated_max_cost_usd

Added value: +{
+  "description": "Upper bound in USD for enrich_domains on the same inputs",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "domains",
-  "invalid",
-  "duplicates_removed"
-]New value: +[
+  "domains",
+  "invalid",
+  "duplicates_removed",
+  "billable_count",
+  "estimated_max_cost_usd"
+]

Changed1 schema field changedOct 18, 2026

changedInput schema / properties / inputs / description

Previous value: -"Required. URLs, domains or email addresses; each entry may also be a newline/comma/semicolon-separated list. Example: [\"https://www.acme.com/contact\",\"sales@acme.com\"]."New value: +"Required array (may be empty) of strings: URLs, domains or email addresses; each entry may also be a newline/comma/semicolon-separated list. Example: [\"https://www.acme.com/contact\",\"sales@acme.com\",\"acme.com, beta.io\"]"

First observedv0.1.0Oct 17, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds substantial context beyond them: free/local, no network, no APIFY_TOKEN, no DNS lookup, and the billing-preview semantics (billable_count, estimated_max_cost_usd formula, invalid entries only producing free error rows). Rich disclosure that goes well past 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-organized with labeled WHAT/WHEN/COST/RETURNS/PARAMETERS/EXAMPLE sections and the core purpose front-loaded. Slightly verbose: the RETURNS and cost-formula details partly restate the output schema, and the PARAMETERS block is long, but almost every line carries actionable information.

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?

Complete for a complex normalization tool: inputs, normalization rules, validity criteria, ordering, billing preview, an end-to-end EXAMPLE with concrete outputs, and cost model are all covered. An agent has everything needed to call it correctly and reason about downstream cost.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, yet the PARAMETERS section adds real meaning beyond it: newline/comma/semicolon list handling, trimming, lowercasing, hostname reduction, www/scheme/path/port stripping, email @-splitting, subdomain retention, the dot+2-letter-TLD validity rule, punycode acceptance, first-seen ordering, and empty-array acceptance. This far exceeds the schema's single-sentence item description.

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?

States a specific verb+resource ('Turn URLs, email addresses and messy strings into bare registrable hostnames') and immediately distinguishes scope from the sibling enrich_domains. An agent can tell exactly what this does and how it differs from enrichment without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit WHEN TO USE ('before enrich_domains, to clean an input list') and WHEN NOT TO USE ('to get contacts, company names or check that a site is reachable - use enrich_domains'), naming the alternative directly. Nothing is left to inference.

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

Deploy Server