parse_and_validate
Extract and validate postal addresses from unstructured text like emails, chat messages, or call transcripts.
Instructions
Extract postal addresses from unstructured text (emails, chat messages, call transcripts, scraped pages) and validate each one. Consumes 1 credit per extracted and validated address. Returns an empty list if no complete addresses are found.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Freeform text that may contain zero or more postal addresses. |
Implementation Reference
- src/index.ts:95-104 (handler)Tool handler function for 'parse_and_validate'. Calls client.parseAndValidate(text) and formats the response using shapeMany().
async ({ text }) => { try { const result = await client.parseAndValidate(text); return { content: [{ type: "text", text: JSON.stringify(shapeMany(result), null, 2) }], }; } catch (error) { return errorResult(error); } } - src/index.ts:83-105 (registration)Registration of the 'parse_and_validate' tool with its description and Zod input schema (a single 'text' string).
server.registerTool( "parse_and_validate", { description: "Extract postal addresses from unstructured text (emails, chat messages, call transcripts, scraped pages) and validate each one. Consumes 1 credit per extracted and validated address. Returns an empty list if no complete addresses are found.", inputSchema: { text: z .string() .min(1) .describe("Freeform text that may contain zero or more postal addresses."), }, }, async ({ text }) => { try { const result = await client.parseAndValidate(text); return { content: [{ type: "text", text: JSON.stringify(shapeMany(result), null, 2) }], }; } catch (error) { return errorResult(error); } } ); - src/index.ts:88-93 (schema)Input schema for parse_and_validate: a single required 'text' string (min length 1).
inputSchema: { text: z .string() .min(1) .describe("Freeform text that may contain zero or more postal addresses."), }, - src/client.ts:32-33 (helper)Client method parseAndValidate() that POSTs to the /accounts/{accountId}/addresses/parse_and_validate API endpoint with the text payload.
async parseAndValidate(text: string) { return this.post(`/accounts/${this.accountId}/addresses/parse_and_validate`, { text }); - src/shape.ts:39-78 (helper)shapeMany() helper used by the parse_and_validate handler to transform the API response array into a standardized ShapedAddress format.
export function shapeMany(envelope: unknown): ShapedAddress[] { const entries = ((envelope as { addresses?: RawAddress[] })?.addresses ?? []) as RawAddress[]; return entries.map(shape); } function shape(raw: RawAddress): ShapedAddress { if (raw.errors && raw.errors.length > 0) { return { status: "invalid_input", original_input: raw.original_input ?? "", valid: false, address: null, formatted: null, error: null, errors: raw.errors, }; } const payload = raw.remote_payload ?? {}; const components = payload.address ?? {}; return { status: raw.status ?? "unknown", original_input: raw.original_input ?? "", valid: typeof payload.is_valid === "boolean" ? payload.is_valid : null, address: raw.remote_payload ? { line1: components.line1 ?? null, line2: components.line2 ?? null, city: components.city ?? null, state: components.state ?? null, postal_code: components.postal_code ?? null, country: components.country ?? null, } : null, formatted: payload.formatted_address ?? null, error: null, raw: raw.remote_payload, }; }