From 4e608f2f20cd54a988d18bc75f47cae5b5a0aad6 Mon Sep 17 00:00:00 2001 From: Dave Oster Date: Thu, 6 Aug 2026 15:16:52 -0500 Subject: [PATCH] Clarify person name lookup routing --- README.md | 10 ++++++++-- playbook/PLAYBOOK.md | 19 ++++++++++++++++--- scripts/validate-agent-plugin.mjs | 6 ++++++ skills/dealmachine/REFERENCE.md | 6 ++++++ skills/dealmachine/SKILL.md | 23 +++++++++++++++++++++-- src/commands/agents.ts | 8 ++++++++ tests/commands/agents.test.ts | 10 ++++++++++ 7 files changed, 75 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ab64fcc..9408763 100644 --- a/README.md +++ b/README.md @@ -534,7 +534,8 @@ dm properties export --body '{"locations": [...]}' --mobile-only --json #### `dm people search` -Search people with filters and locations. +Build an audience of people using demographic, property, contact, and location filters. This command +does not accept a person's name as a filter. Use `dm enrich name` for a specific person by name. ```bash dm people search --body '{ @@ -693,7 +694,8 @@ dm enrich phone -f phones.csv --include-properties --fields estimated_value #### `dm enrich name [name]` -Look up people by name. Supports "First Last" or just "Last" format. +Look up a specific person by name. Supports "First Last" or just "Last" format. People Search does +not have a name filter, so use this command whenever the input is a person's name. ```bash dm enrich name "Jane Doe" @@ -701,12 +703,16 @@ dm enrich name "Jane Doe" --state TX --estimate-cost dm enrich name "Doe" --state TX --page 2 dm enrich name "Jane Doe" --zip 78704 --include-properties dm enrich name "Jane Doe" --fields estimated_household_income,estimated_value +dm locations search -q "Austin" --type city --state TX --json +dm enrich name "Jane Doe" --city 7333 --estimate-cost ``` | Option | Description | | ---------------------- | ----------------------------- | | `--state ` | Narrow by state | | `--zip ` | Narrow by ZIP code | +| `--county ` | Narrow by county FIPS | +| `--city ` | Narrow by city place ID | | `--include-properties` | Include associated properties | | `--fields ` | Field IDs from `dm fields` | | `--estimate-cost` | Preview count and credits | diff --git a/playbook/PLAYBOOK.md b/playbook/PLAYBOOK.md index 17ca274..142fa37 100644 --- a/playbook/PLAYBOOK.md +++ b/playbook/PLAYBOOK.md @@ -122,7 +122,11 @@ If a command fails due to auth, tell the user to run `dm login` in their termina ### State DM3: People Search -**Symptoms:** User wants to find people (owners, renters, residents) matching criteria. +**Symptoms:** User wants to find an audience of people (owners, renters, residents) matching demographic, property, contact, or location criteria. + +**Routing boundary:** Do not use this state when the user provides a specific person's name. People +Search has no name filter. Route a known name to State DM5 and use `dm enrich name`. + **Key Questions:** - Are you looking for property owners, renters, or residents? @@ -153,15 +157,22 @@ If a command fails due to auth, tell the user to run `dm login` in their termina ### State DM5: Person Enrichment **Symptoms:** User has a name, phone, or email and wants to find the person. + +**Routing boundary:** A specific name always uses person enrichment, not People Search. Use +`dm enrich name` or `dealmachine_enrich_name`. Narrow with a state, ZIP code, county, or city place +ID when available. For a city name, run +`dm locations search -q "" --type city --state --json`, then pass the result's `code` +to `dm enrich name --city `. + **Key Questions:** - What identifier do you have? (name, phone, email) -- For name searches: do you know their state or ZIP? (narrows results, saves credits) +- For name searches: do you know their state, ZIP, county, or city? (narrows results, saves credits) - Do you need their associated properties? **Interventions:** - `dm enrich phone "5551234567"` - `dm enrich email "john@example.com"` -- `dm enrich name "John Smith" --state TX` +- `dm enrich name "John Smith" --state TX --estimate-cost` - Add `--include-properties` if property data needed ### State DM6: Address Validation @@ -600,6 +611,8 @@ dm enrich phone "5551234567" --include-properties dm enrich name "John Smith" dm enrich name "John Smith" --state TX dm enrich name "John Smith" --zip 78704 +dm locations search -q "Austin" --type city --state TX --json +dm enrich name "John Smith" --city 7333 --estimate-cost dm enrich name "Smith" # Last name only dm enrich name "John Smith" --include-properties ``` diff --git a/scripts/validate-agent-plugin.mjs b/scripts/validate-agent-plugin.mjs index da350b9..10fc5ae 100644 --- a/scripts/validate-agent-plugin.mjs +++ b/scripts/validate-agent-plugin.mjs @@ -92,6 +92,12 @@ assert.deepEqual(mcp.mcpServers.dealmachine, { assert.match(skill, /^---\nname: dealmachine\n/, 'DealMachine skill front matter is missing'); assert.match(skill, /\ndescription: .+\n/, 'DealMachine skill description is missing'); +assert.match( + skill, + /People Search builds audiences[\s\S]+it has no name filter/, + 'DealMachine skill must distinguish People Search from person-name enrichment' +); +assert.match(skill, /dealmachine_enrich_name/, 'DealMachine skill must route names to enrichment'); const demoVideoPath = resolve(packageRoot, 'assets/plugin-demo/dealmachine-agent-plugin-demo.mp4'); const demoVideo = await stat(demoVideoPath); diff --git a/skills/dealmachine/REFERENCE.md b/skills/dealmachine/REFERENCE.md index 74c5c49..6f149d8 100644 --- a/skills/dealmachine/REFERENCE.md +++ b/skills/dealmachine/REFERENCE.md @@ -32,6 +32,12 @@ Use these exact Tool IDs. Do not pluralize `property`. People export is available through the CLI. +People Search builds audiences from demographic, property, contact, and location filters. It has no +person-name filter. For a specific person by name, use `dealmachine_enrich_name` or +`dm enrich name`. For city narrowing, resolve the city with `dealmachine_location_search` or +`dm locations search -q "Austin" --type city --state TX --json`, then pass its `code` as the city +place ID. + ### Enrichment - `dealmachine_enrich_address` diff --git a/skills/dealmachine/SKILL.md b/skills/dealmachine/SKILL.md index fa8ae92..5ad1dca 100644 --- a/skills/dealmachine/SKILL.md +++ b/skills/dealmachine/SKILL.md @@ -49,6 +49,22 @@ Identify: Ask one focused question only when a missing detail would materially change the search or credit cost. +## Choose the correct people workflow + +| User intent | Correct workflow | +| --- | --- | +| Find a specific person by name | `dealmachine_enrich_name` or `dm enrich name` | +| Find a specific person by email or phone | Use the matching enrichment MCP Tool or CLI command | +| Find an audience using demographic, property, contact, or location criteria | `dealmachine_people_search` or `dm people search` | +| Fetch a known DealMachine person ID | `dealmachine_people_get` or `dm people get` | + +Do not search the People Search filter catalog for a person's name. People Search builds audiences +from filters and locations, and it has no name filter. Name enrichment accepts first and last name +with an optional state, ZIP code, county, or city place ID. Resolve a city name with +`dealmachine_location_search` or `dm locations search`, then use the result's `code` for the name +lookup. For broad name matches, use `estimate_cost: true` with the MCP Tool or `--estimate-cost` +with the CLI before retrieving records. + ## Use MCP tools ### Discovery @@ -70,14 +86,17 @@ Ask one focused question only when a missing detail would materially change the ### People workflows - Use `dealmachine_people_count` before a broad search. -- Use `dealmachine_people_search` for results and the matching get tools for known IDs. +- Use `dealmachine_people_search` only for an audience defined by filters and locations. It does not + accept a person's name as a filter. +- Use the matching get tools for known DealMachine person IDs. - People search and lookup are available through MCP. Use the CLI for a people export. ### Enrichment - Use the address, latitude and longitude, or APN enrichment tool for a property. - Use the email, phone, or name enrichment tool for a person. -- Narrow name searches with a location. +- A specific person's name always uses `dealmachine_enrich_name` or `dm enrich name`. +- Narrow name searches with a state, ZIP code, county, or city place ID. ## Use the CLI diff --git a/src/commands/agents.ts b/src/commands/agents.ts index ff281ca..b1b715e 100644 --- a/src/commands/agents.ts +++ b/src/commands/agents.ts @@ -28,6 +28,14 @@ dm agents playbook - Check auth with \`dm whoami --verify --json\`. If auth fails, ask the user to run \`dm login\`. - Use request files or stdin for structured bodies instead of hand-editing long shell strings. +## People Lookup Routing + +- A specific person by name uses \`dm enrich name\`. People Search does not have a name filter. +- A specific person by email or phone uses the matching \`dm enrich\` command. +- \`dm people search\` is only for audiences defined by demographic, property, contact, or location filters. +- A known DealMachine person ID uses \`dm people get\`. +- Name enrichment supports an optional state, ZIP code, county, or city place ID. Resolve a city with \`dm locations search\`, then pass its \`code\` to \`dm enrich name --city\`. + ## Credit-Safe Workflow 1. Discover live filters and fields before searches: diff --git a/tests/commands/agents.test.ts b/tests/commands/agents.test.ts index ec7b093..37efbdf 100644 --- a/tests/commands/agents.test.ts +++ b/tests/commands/agents.test.ts @@ -14,6 +14,12 @@ describe('agent commands', () => { expect(log).toHaveBeenCalledWith(expect.stringContaining('dm agents playbook')); expect(log).toHaveBeenCalledWith(expect.stringContaining('Credit-Safe Workflow')); + expect(log).toHaveBeenCalledWith( + expect.stringContaining('A specific person by name uses `dm enrich name`') + ); + expect(log).toHaveBeenCalledWith( + expect.stringContaining('People Search does not have a name filter') + ); }); it('prints agent guidance as JSON', async () => { @@ -27,6 +33,7 @@ describe('agent commands', () => { recommended_first_command: 'dm agents playbook', }); expect(payload.content).toContain('DealMachine CLI Agent Guide'); + expect(payload.content).toContain('A specific person by name uses `dm enrich name`'); }); it('prints the DealMachine Playbook as JSON', async () => { @@ -40,5 +47,8 @@ describe('agent commands', () => { type: 'playbook', }); expect(payload.content).toContain('DealMachine Playbook: Natural Language Property Intelligence'); + expect(payload.content).toContain( + 'A specific name always uses person enrichment, not People Search.' + ); }); });