telique-mcp 1.0.22 → 1.0.24

package/dist/knowledge.d.ts

@@ -1,3 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerKnowledge(server: McpServer): void;
-export declare const TELIQUE_KNOWLEDGE = "# Telique Telecom API Knowledge Base\n\nYou have access to 13 Telique tools for querying live telecom data. NEVER guess carrier names, LRNs, routing data, or CNAM \u2014 always query the API.\n\n---\n\n## CRITICAL: LERG vs LSMS \u2014 Two Different Databases\n\n**LERG** = Static telecom infrastructure reference (updated monthly from iconectiv BIRRDS)\n- NPA-NXX assignments, switches, tandems, homing arrangements, rate centers, LATAs, carrier names by OCN\n- 27 tables. NO individual phone number data.\n- Query with: `lerg_query`, `lerg_complex_query`, `lerg_tandem`, `lerg_table_info`, or `graphql_query(service=\"lerg\")`\n\n**LSMS** = Live NPAC porting data (refreshed within minutes)\n- Phone number ownership (SPID), LRN assignments, porting state\n- NO routing infrastructure (no tandems, switches, homing, rate centers, OCN names)\n- Query with: `lrn_lookup`, `lrn_relationship_query`, or `graphql_query(service=\"lsms\")`\n\n| Data Type | Database | Tool |\n|-----------|----------|------|\n| Tandem switches | **LERG** | `lerg_tandem` |\n| Switch/CLLI details | **LERG** | `lerg_query` on lerg_7 |\n| Homing arrangements | **LERG** | `lerg_query` on lerg_7_sha |\n| NPA-NXX routing (OCN, switch, LATA, rate center) | **LERG** | `lerg_query` on lerg_6 |\n| Carrier/OCN names | **LERG** | `lerg_query` on lerg_1 |\n| Current TN ownership (SPID) | **LSMS** | `lrn_lookup` |\n| Current LRN for a TN | **LSMS** | `lrn_lookup` |\n| Porting state | **LSMS** | `lrn_relationship_query` or GraphQL |\n\n---\n\n## CRITICAL: Always Dip the LRN First\n\nA ported phone number's NPA-NXX often differs from its LRN's NPA-NXX. For ANY routing question about a specific phone number:\n\n1. **`lrn_lookup`** \u2192 get the LRN and SPID\n2. Extract NPA-NXX from the **LRN** (first 3 digits = NPA, next 3 = NXX)\n3. Use the **LRN's** NPA-NXX for all LERG lookups\n\n**Example:** TN 303-629-8301\n- WRONG: Look up 303-629 in LERG \u2192 returns the original carrier's data (before porting)\n- CORRECT: `lrn_lookup(\"3036298301\")` \u2192 LRN = 7207081999 \u2192 look up 720-708 in LERG \u2192 returns current carrier\n\nThis applies to: tandem, switch, LATA, OCN, rate center \u2014 anything keyed by NPA-NXX.\n\n### The Golden Pattern for Routing Questions\n\n```\nStep 1: lrn_lookup({phone_number}) \u2192 get LRN and SPID\nStep 2: Extract NPA (first 3 digits of LRN) and NXX (next 3 digits of LRN)\nStep 3: Use LRN's NPA-NXX for LERG queries:\n  - lerg_tandem({npa, nxx})           \u2192 tandem switch\n  - lerg_query(\"lerg_6\", ..., \"npa={npa}&nxx={nxx}\")  \u2192 OCN, switch, LATA, rate center\n  - lerg_query(\"lerg_7\", ..., \"switch={clli}\")         \u2192 switch details\n```\n\nOr use `lookup_tn` for a quick consolidated view (dips LRN + CNAM + DNO + LERG in parallel).\n\n---\n\n## LERG Table Reference\n\n### Big 4 \u2014 Cover ~80% of Queries\n\n**lerg_1** \u2014 OCN/carrier directory\n- Fields: ocn_num, ocn_name, abbre_ocn_name, ocn_state, category, overall_ocn\n- Use: Look up carrier name by OCN. Join from lerg_6 `ocn` \u2192 lerg_1 `ocn_num`.\n- Example: `lerg_query(\"lerg_1\", \"ocn_num,ocn_name,ocn_state\", \"ocn_num=567G\")`\n\n**lerg_6** \u2014 NPA-NXX block assignments (the workhorse)\n- Fields: npa, nxx, block_id, lata, lata_name, loc_state, ocn, aocn, switch, sha_indicator, rc_abbre, rc_type, coc_type, eff_date, status\n- Has LATA + state + NPA + NXX + OCN + switch + rate center all on one row.\n- BLOCK=\"A\" = full NXX assignment; numeric 0-9 = thousands-block pooling.\n- Example: `lerg_query(\"lerg_6\", \"npa,nxx,loc_name,loc_state,ocn,switch,lata\", \"npa=720&nxx=708\")`\n\n**lerg_7_sha** \u2014 Switch homing arrangements\n- Fields: switch, sha_indicator, h_trm_d_tdm (FGD tandem), host, ocn\n- Match `switch` + `sha_indicator` from lerg_6 to find the correct tandem.\n- Or use `lerg_tandem` which does the join automatically.\n\n**lerg_12** \u2014 LRN registry\n- Fields: lrn, lata, lata_name, switch, ocn, status, eff_date\n- Which company/switch established each LRN.\n\n### Supporting Tables\n\n| Table | Purpose |\n|-------|---------|\n| lerg_3 | NPA (area code) metadata \u2014 state, effective date |\n| lerg_5 | NPA/LATA cross-reference \u2014 which NPAs exist in a LATA |\n| lerg_7 | Switch/CLLI details \u2014 address, coordinates, equipment type |\n| lerg_8 | Rate center details \u2014 geography, V&H coordinates |\n| lerg_8_loc | Localities (towns) \u2192 rate centers |\n| lerg_8_pst | ZIP codes \u2192 localities (US only) |\n| lerg_9 | Homing by tandem \u2014 \"top-down\" view of which NPA-NXXs subtend a tandem |\n| lerg_4 | SS7 point codes |\n| lerg_10 | NPA-NXX \u2192 operator services ATC |\n| lerg_11 | Locality \u2192 operator services ATC |\n| lerg_16 | IP capability by LRN |\n| lerg_17 | IP capability by NPA-NXX |\n\nUse `lerg_table_info` to list all tables or get the schema for a specific one.\n\n---\n\n## LERG Query Syntax\n\nREST queries use path-based filters with `&` joining multiple conditions:\n- Single filter: `lerg_query(\"lerg_1\", \"ocn_num,ocn_name\", \"ocn_state=CO\")`\n- Multiple filters: `lerg_query(\"lerg_6\", \"npa,nxx,loc_name,ocn\", \"npa=303&nxx=629\")`\n\nFor complex queries with JOINs and advanced operators, use `lerg_complex_query`:\n```json\n{\n  \"table\": \"lerg_6\",\n  \"fields\": [\"npa\", \"nxx\", \"ocn\", \"loc_name\"],\n  \"filters\": [{\"field\": \"npa\", \"operator\": \"eq\", \"value\": 720}],\n  \"join\": {\n    \"table\": \"lerg_1\",\n    \"on\": [{\"left_field\": \"ocn\", \"right_field\": \"ocn_num\"}],\n    \"fields\": [\"ocn_name\", \"ocn_state\"]\n  }\n}\n```\n\nFilter operators: eq, ne, gt, gte, lt, lte, like, in, notin, isnull, isnotnull.\nUse `*` as the fields value to return all fields from a table.\nNote: REST `like` is **case-insensitive** (in-memory matching), unlike GraphQL LIKE which is case-sensitive (PostgreSQL).\n\n---\n\n## CNAM (Caller Name)\n\n`cnam_lookup` queries TransUnion's LIDB for the caller name associated with a phone number.\n\n- Returns: calling_name (up to 15 chars), calling_name_status (available/unavailable), presentation_indicator (allowed/restricted)\n- Results cached server-side for 24 hours\n- \"WIRELESS CALLER\" typically means the carrier hasn't provisioned a specific CNAM entry\n\n---\n\n## DNO (Do Not Originate)\n\n`dno_check` checks if a phone number should never appear as a caller ID.\n\n- DNO numbers belong to entities that only receive calls (IRS, major banks, government agencies)\n- If is_dno=true, the number appearing as caller ID indicates **spoofing/fraud**\n- Supports prefix matching: 3-digit (NPA), 6-digit (NPA-NXX), 7-digit, or 10-digit patterns\n- Response includes: is_dno, matched_pattern, source\n\n---\n\n## RouteLink \u2014 Toll-Free Number Routing\n\n### ROR (Responsible Organization)\n`routelink_lookup` with lookup_type=\"ror\" returns the RespOrg managing a toll-free number.\n- RespOrg is a 5-char code (e.g., \"NEX01\", \"TZN99\")\n- Only needs the CRN (toll-free number), no ANI/LATA required\n\n### CIC (Carrier Identification Code)\n`routelink_lookup` with lookup_type=\"cic\" or \"cicror\" returns which carrier handles calls to a toll-free number FROM a specific caller (ANI) in a specific LATA.\n- Requires: crn, ani (10-digit), lata (3-digit)\n- Common carrier codes: 0288 (AT&T), 0222 (MCI/Verizon), 0333 (Sprint), 0432 (Lumen)\n\n### CPR (Call Processing Record)\n`routelink_cpr` retrieves the full routing decision tree for a toll-free number.\n\n**Decision tree node types:**\n| Node | Description |\n|------|-------------|\n| [LATA] | Routes by caller's LATA |\n| [NPA] | Routes by caller's area code |\n| [NXX] | Routes by caller's exchange |\n| [STATE] | Routes by caller's state |\n| [DAY_OF_WEEK] | Routes by day (1-7, Sunday=1) |\n| [TIME_OF_DAY] | Routes by time (15-min intervals) |\n| [PERCENT] | Percentage-based load balancing |\n| [ANI] | Routes by specific caller number |\n\n**Action types:** Carrier XXXX (4-digit carrier code), Template XXXXXXXXXX (reference to template CRN), Routing XXXXX, NMC X (Network Management Class)\n\n**Common patterns:**\n- Simple: All calls \u2192 one carrier \u2192 one termination number\n- Time-of-day: Business hours \u2192 office, after hours \u2192 answering service\n- Geographic: Different terminations per LATA/state/NPA\n- Percentage: Load balancing across call centers (e.g., 60%/40%)\n\nUse `expand=true` (default) to recursively resolve template references into their full decision trees.\n\n---\n\n## GraphQL\n\nUse `graphql_query` for complex queries not possible with REST:\n- Cross-table relationship joins (lerg6 \u2192 carrier, lerg6 \u2192 switchInfo, lerg7Sha \u2192 tandemSwitch)\n- Filtering by fields not in REST endpoints\n- Multiple related data points in one query\n\n### LERG GraphQL (`service=\"lerg\"`)\n\n**CRITICAL naming rules:**\n- **Query names** are camelCase: `lerg1`, `lerg6`, `lerg7Sha`, `lerg7ShaIns`, `lerg12`, etc.\n- **Return fields** MUST be camelCase: `ocnName`, `locState`, `locName`, `shaIndicator`, `hTrmDTdm`\n- **Filter field names** accept BOTH camelCase (`ocnName`) and snake_case (`ocn_name`)\n- **All values are strings** \u2014 even numeric fields. Always quote: `value: \"720\"` not `value: 720`\n- **GraphQL LIKE is case-sensitive (SQL)** \u2014 LERG data is stored UPPERCASE, so patterns must be uppercase: `%VERIZON%` not `%verizon%`. (The REST `like` operator is case-insensitive \u2014 this only applies to GraphQL.)\n\n**FilterInput:**\n```graphql\n{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }   # partial match (UPPERCASE!)\n{ field: \"npa\", op: EQ, value: \"720\" }                # exact match\n{ field: \"npa\", op: IN, values: [\"212\", \"646\", \"917\"] } # IN uses 'values' (plural), not 'value'\n```\n\nOperators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, IS_NULL, IS_NOT_NULL\n\n**Predefined relationships** (avoid N+1 \u2014 use these instead of separate queries):\n- `lerg6` \u2192 `carrier` (joins to lerg1 via OCN), `switchInfo` (\u2192 lerg7), `homingArrangements` (\u2192 lerg7Sha)\n- `lerg7` \u2192 `carrier` (\u2192 lerg1)\n- `lerg7Sha` \u2192 `tandemSwitch` (\u2192 lerg7)\n\n**Example \u2014 find all Verizon OCNs:**\n```graphql\n{\n  lerg1(\n    filters: [{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }]\n    pagination: { limit: 10 }\n  ) {\n    ocnNum\n    ocnName\n    ocnState\n    category\n  }\n}\n```\n\n**Example \u2014 NPA-NXX with carrier and switch in one query:**\n```graphql\n{\n  lerg6(\n    filters: [{ field: \"npa\", op: EQ, value: \"303\" }, { field: \"nxx\", op: EQ, value: \"629\" }]\n    pagination: { limit: 1 }\n  ) {\n    npa nxx ocn locName switch\n    carrier { ocnNum ocnName ocnState }\n    switchInfo { switch eqpType swCity swState }\n    homingArrangements {\n      shaIndicator hTrmDTdm\n      tandemSwitch { switch swCity swState }\n    }\n  }\n}\n```\n\n**dynamicJoin** \u2014 for arbitrary cross-table SQL joins (returns raw JSON):\n```graphql\n{\n  dynamicJoin(input: {\n    table: \"lerg_6\"\n    fields: [\"npa\", \"nxx\", \"ocn\", \"locName\"]\n    filters: [{ field: \"locName\", op: LIKE, value: \"%DENVER%\" }]\n    join: {\n      table: \"lerg_1\"\n      fields: [\"ocnName\", \"category\"]\n      on: [{ leftField: \"ocn\", rightField: \"ocnNum\" }]\n      joinType: \"INNER\"\n    }\n    pagination: { limit: 10 }\n  })\n}\n```\nNote: dynamicJoin uses snake_case table IDs (lerg_6, lerg_1, lerg_7_sha) and returns raw PostgreSQL column names (UPPERCASE with spaces, e.g., `\"OCN_NAME\"`, `\"LOC NAME\"`, `\"EFF DATE\"`), NOT GraphQL camelCase.\n\n### LSMS GraphQL (`service=\"lsms\"`)\n\nThe LSMS GraphQL API is a **completely separate implementation** from LERG GraphQL. It has different query patterns, different field naming, and different schema design. Do NOT use LERG-style FilterInput syntax with LSMS.\n\n**5 tables:**\n\n| Table | ~Rows | Requires Filter? |\n|-------|-------|------------------|\n| subscriptionVersions | 514M | Yes (phoneNumber, lrn, or spid) |\n| numberBlocks | 751K | Yes (npanxxx, spid, or lrn) |\n| serviceProviders | 5.2K | No |\n| locationRoutingNumbers | 56K | No |\n| npanxx | 192K | No |\n\n**Query patterns (NOT FilterInput \u2014 uses typed named parameters):**\n```graphql\n# Single phone number lookup\n{ subscriptionVersion(phoneNumber: \"3036298301\") { phoneNumber lrn spid serviceProvider { name } } }\n\n# Paginated list by LRN (returns totalCount, hasMore)\n{ subscriptionVersionsByLrn(lrn: \"7207081999\", limit: 10) { totalCount hasMore items { phoneNumber spid } } }\n\n# Paginated list by SPID\n{ subscriptionVersionsBySpid(spid: \"567G\", limit: 10) { totalCount hasMore items { phoneNumber lrn } } }\n\n# Number block lookup\n{ numberBlock(npanxxx: \"3035551\") { npanxxx lrn spid serviceProvider { name } } }\n\n# List carriers\n{ serviceProviders(limit: 20) { spid name npacRegion } }\n\n# LRN metadata\n{ locationRoutingNumber(lrn: \"7207081999\") { lrn ocn switchInfo } }\n\n# NPA-NXX codes for a carrier\n{ npanxxBySpid(spid: \"567G\", limit: 50) { npa nxx effectiveTimestamp } }\n\n# Database statistics\n{ lsmsStats { activeSubscriptionVersions activeNumberBlocks totalServiceProviders } }\n```\n\n**Relationships** (use DataLoader batching \u2014 no N+1):\n- subscriptionVersion \u2192 `serviceProvider`, `lrnMetadata`\n- numberBlock \u2192 `serviceProvider`, `lrnMetadata`\n- npanxx \u2192 `serviceProvider`\n\n**Safety limits:** max 1000 results, depth 5, complexity 200, 10-second statement timeout\n**Auto-filters:** Soft-deletable records filter to is_active = true automatically\n**Note:** Phone numbers/LRNs are strings (stored as BIGINT but GraphQL Int is 32-bit). SPIDs are auto-trimmed.\n\n---\n\n## Key Telecom Concepts\n\n| Term | Definition |\n|------|-----------|\n| **LRN** | Location Routing Number \u2014 identifies the switch serving a ported number |\n| **SPID** | Service Provider ID \u2014 identifies the carrier that owns a number |\n| **OCN** | Operating Company Number \u2014 4-char carrier identifier (often same as SPID) |\n| **NPA** | Numbering Plan Area \u2014 3-digit area code |\n| **NXX** | Exchange code \u2014 next 3 digits after area code |\n| **LATA** | Local Access Transport Area \u2014 geographic region for call routing |\n| **CLLI** | Common Language Location Identifier \u2014 8-11 char switch/building code |\n| **CRN** | Call Routing Number \u2014 a toll-free number in RouteLink context |\n| **ROR/RespOrg** | Responsible Organization \u2014 entity managing a toll-free number's routing |\n| **CIC** | Carrier Identification Code \u2014 identifies which carrier handles a toll-free call |\n| **CPR** | Call Processing Record \u2014 routing decision tree for a toll-free number |\n| **Rate Center** | Geographic area defining local calling boundaries |\n| **Tandem** | A switching office that connects local switches to the long-distance network |\n| **Homing** | The relationship between a local switch and its tandem |\n\n---\n\n## Common Mistakes to Avoid\n\n1. **Never guess carrier names** \u2014 always query lerg_1 by OCN\n2. **Never skip the LRN dip** \u2014 ported TNs have different NPA-NXX than their LRN\n3. **Never look for tandem/switch data in LSMS** \u2014 LSMS has no infrastructure data\n4. **Never look for TN-level data in LERG** \u2014 LERG has no per-phone-number data\n5. **Never query LSMS subscriptionVersions without a filter** \u2014 514M rows will timeout\n6. **Always use the LRN's NPA-NXX** (not the TN's) for LERG routing lookups\n7. **GraphQL return fields must be camelCase** \u2014 `ocnName` not `ocn_name`, `locState` not `loc_state`\n8. **GraphQL LIKE patterns must be UPPERCASE** \u2014 LERG data is uppercase in PostgreSQL, so `%VERIZON%` works but `%verizon%` returns nothing. (REST `like` is case-insensitive \u2014 this only applies to GraphQL.)\n9. **IN operator uses `values` (plural)** \u2014 `{ field: \"npa\", op: IN, values: [\"212\", \"646\"] }` not `value`\n";
+export declare const TELIQUE_KNOWLEDGE = "# Telique Telecom API Knowledge Base\n\nYou have access to 13 Telique tools for querying live telecom data. NEVER guess carrier names, LRNs, routing data, or CNAM \u2014 always query the API.\n\n---\n\n## CRITICAL: LERG vs LSMS \u2014 Two Different Databases\n\n**LERG** = Static telecom infrastructure reference (updated monthly from iconectiv BIRRDS)\n- NPA-NXX assignments, switches, tandems, homing arrangements, rate centers, LATAs, carrier names by OCN\n- 27 tables. NO individual phone number data.\n- Query with: `lerg_query`, `lerg_complex_query`, `lerg_tandem`, `lerg_table_info`, or `graphql_query(service=\"lerg\")`\n\n**LSMS** = Live NPAC porting data (refreshed within minutes)\n- Phone number ownership (SPID), LRN assignments, porting state\n- NO routing infrastructure (no tandems, switches, homing, rate centers, OCN names)\n- Query with: `lrn_lookup`, `lrn_relationship_query`, or `graphql_query(service=\"lsms\")`\n\n| Data Type | Database | Tool |\n|-----------|----------|------|\n| Tandem switches | **LERG** | `lerg_tandem` |\n| Switch/CLLI details | **LERG** | `lerg_query` on lerg_7 |\n| Homing arrangements | **LERG** | `lerg_query` on lerg_7_sha |\n| NPA-NXX routing (OCN, switch, LATA, rate center) | **LERG** | `lerg_query` on lerg_6 |\n| Carrier/OCN names | **LERG** | `lerg_query` on lerg_1 |\n| Current TN ownership (SPID) | **LSMS** | `lrn_lookup` |\n| Current LRN for a TN | **LSMS** | `lrn_lookup` |\n| Porting state | **LSMS** | `lrn_relationship_query` or GraphQL |\n\n---\n\n## CRITICAL: Always Dip the LRN First\n\nA ported phone number's NPA-NXX often differs from its LRN's NPA-NXX. For ANY routing question about a specific phone number:\n\n1. **`lrn_lookup`** \u2192 get the LRN and SPID\n2. Extract NPA-NXX from the **LRN** (first 3 digits = NPA, next 3 = NXX)\n3. Use the **LRN's** NPA-NXX for all LERG lookups\n\n**Example:** TN 303-629-8301\n- WRONG: Look up 303-629 in LERG \u2192 returns the original carrier's data (before porting)\n- CORRECT: `lrn_lookup(\"3036298301\")` \u2192 LRN = 7207081999 \u2192 look up 720-708 in LERG \u2192 returns current carrier\n\nThis applies to: tandem, switch, LATA, OCN, rate center \u2014 anything keyed by NPA-NXX.\n\n### The Golden Pattern for Routing Questions\n\n```\nStep 1: lrn_lookup({phone_number}) \u2192 get LRN and SPID\nStep 2: Extract NPA (first 3 digits of LRN) and NXX (next 3 digits of LRN)\nStep 3: Use LRN's NPA-NXX for LERG queries:\n  - lerg_tandem({npa, nxx})           \u2192 tandem switch\n  - lerg_query(\"lerg_6\", ..., \"npa={npa}&nxx={nxx}\")  \u2192 OCN, switch, LATA, rate center\n  - lerg_query(\"lerg_7\", ..., \"switch={clli}\")         \u2192 switch details\n```\n\nOr use `lookup_tn` for a quick consolidated view (dips LRN + CNAM + DNO + LERG in parallel).\n\n---\n\n## LERG Table Reference\n\n### Big 4 \u2014 Cover ~80% of Queries\n\n**lerg_1** \u2014 OCN/carrier directory\n- Fields: ocn_num, ocn_name, abbre_ocn_name, ocn_state, category, overall_ocn\n- Use: Look up carrier name by OCN. Join from lerg_6 `ocn` \u2192 lerg_1 `ocn_num`.\n- Example: `lerg_query(\"lerg_1\", \"ocn_num,ocn_name,ocn_state\", \"ocn_num=567G\")`\n\n**lerg_6** \u2014 NPA-NXX block assignments (the workhorse)\n- Fields: npa, nxx, block_id, lata, lata_name, loc_state, ocn, aocn, switch, sha_indicator, rc_abbre, rc_type, coc_type, eff_date, status\n- Has LATA + state + NPA + NXX + OCN + switch + rate center all on one row.\n- Example: `lerg_query(\"lerg_6\", \"npa,nxx,block_id,loc_name,loc_state,ocn,switch,lata\", \"npa=720&nxx=708\")`\n\n**CRITICAL: Understanding block_id and NPA-NXX ownership:**\n- `block_id=\"A\"` = the **Code Holder** \u2014 the original LERG owner of the entire NPA-NXX. This is THE owner of the NPA-NXX.\n- `block_id=\"0\"` through `\"9\"` = **Block Holders** \u2014 carriers who received a pooled 1,000-number block (thousands-block pooling). Each block covers numbers x000-x999 within the NXX.\n- When asked \"who owns NPA-NXX 720-708?\", the answer is the OCN on the `block_id=\"A\"` row.\n- A query for `npa=720&nxx=708` may return multiple rows \u2014 one for block_id=\"A\" (the Code Holder) and additional rows for pooled blocks (0-9). Always filter or identify the \"A\" row for ownership questions.\n- To find which carrier serves a specific phone number within a pooled NXX, use the LRN dip pattern instead (the block_id approach only tells you who holds the block, not who currently serves an individual ported number).\n\n**lerg_7_sha** \u2014 Switch homing arrangements\n- Fields: switch, sha_indicator, h_trm_d_tdm (FGD tandem), host, ocn\n- Match `switch` + `sha_indicator` from lerg_6 to find the correct tandem.\n- Or use `lerg_tandem` which does the join automatically.\n\n**lerg_12** \u2014 LRN registry\n- Fields: lrn, lata, lata_name, switch, ocn, status, eff_date\n- Which company/switch established each LRN.\n\n### Supporting Tables\n\n| Table | Purpose |\n|-------|---------|\n| lerg_3 | NPA (area code) metadata \u2014 state, effective date |\n| lerg_5 | NPA/LATA cross-reference \u2014 which NPAs exist in a LATA |\n| lerg_7 | Switch/CLLI details \u2014 address, coordinates, equipment type |\n| lerg_8 | Rate center details \u2014 geography, V&H coordinates |\n| lerg_8_loc | Localities (towns) \u2192 rate centers |\n| lerg_8_pst | ZIP codes \u2192 localities (US only) |\n| lerg_9 | Homing by tandem \u2014 \"top-down\" view of which NPA-NXXs subtend a tandem |\n| lerg_4 | SS7 point codes |\n| lerg_10 | NPA-NXX \u2192 operator services ATC |\n| lerg_11 | Locality \u2192 operator services ATC |\n| lerg_16 | IP capability by LRN |\n| lerg_17 | IP capability by NPA-NXX |\n\nUse `lerg_table_info` to list all tables or get the schema for a specific one.\n\n---\n\n## LERG Query Syntax\n\nREST queries use path-based filters with `&` joining multiple conditions:\n- Single filter: `lerg_query(\"lerg_1\", \"ocn_num,ocn_name\", \"ocn_state=CO\")`\n- Multiple filters: `lerg_query(\"lerg_6\", \"npa,nxx,loc_name,ocn\", \"npa=303&nxx=629\")`\n\nFor complex queries with JOINs and advanced operators, use `lerg_complex_query`:\n```json\n{\n  \"table\": \"lerg_6\",\n  \"fields\": [\"npa\", \"nxx\", \"ocn\", \"loc_name\"],\n  \"filters\": [{\"field\": \"npa\", \"operator\": \"eq\", \"value\": 720}],\n  \"join\": {\n    \"table\": \"lerg_1\",\n    \"on\": [{\"left_field\": \"ocn\", \"right_field\": \"ocn_num\"}],\n    \"fields\": [\"ocn_name\", \"ocn_state\"]\n  }\n}\n```\n\nFilter operators: eq, ne, gt, gte, lt, lte, like, in, notin, isnull, isnotnull.\nUse `*` as the fields value to return all fields from a table.\nNote: REST `like` is **case-insensitive** (in-memory matching), unlike GraphQL LIKE which is case-sensitive (PostgreSQL).\n\n---\n\n## When to Use REST vs GraphQL\n\n| Use Case | Best Tool | Why |\n|----------|-----------|-----|\n| Single LRN/SPID for a phone number | `lrn_lookup` (REST) | Sub-millisecond, in-memory |\n| Carrier name by OCN | `lerg_query` (REST) | Simple single-field lookup |\n| NPA-NXX routing info | `lerg_query` (REST) | Fast, straightforward |\n| Tandem routing | `lerg_tandem` (REST) | Pre-built JOIN, optimized |\n| NPA-NXX + carrier name + switch in one call | `graphql_query` (LERG) | Nested relationships avoid multiple round trips |\n| Filter by fields not in REST (e.g., all switches for an OCN) | `graphql_query` (LERG) | FilterInput supports any field |\n| Cross-table JOIN with arbitrary conditions | `graphql_query` (LERG dynamicJoin) | Only way to do ad-hoc joins |\n| All phone numbers for an LRN (paginated with totalCount) | `graphql_query` (LSMS) | SVConnection returns totalCount + hasMore |\n| Quick profile of a phone number | `lookup_tn` (composite) | Parallel dip across LRN + CNAM + DNO + LERG |\n\n**Rule of thumb:** Use REST for simple lookups (one table, one or two filters). Use GraphQL when you need joins, relationship traversal, or fields not exposed by REST endpoints.\n\n---\n\n## LSMS / LRN REST Endpoints\n\nThe LRN API serves live NPAC porting data from an in-memory Judy Array store (500M+ records, sub-millisecond) backed by a PostgreSQL LSMS database.\n\n### LRN Lookup (`lrn_lookup` tool)\n\n`GET /v1/telique/lrn/{phone_number}?format=json`\n\nReturns the current LRN and carrier for a phone number. This is the fastest lookup \u2014 served from in-memory store, not PostgreSQL.\n\n**JSON response shape:**\n```json\n{\n  \"phone_number\": \"3036298301\",\n  \"lrn\": \"7207081999\",\n  \"status\": \"success\",\n  \"timestamp\": \"2025-08-07T02:30:00Z\",\n  \"metadata\": {\n    \"spid\": \"567G\",\n    \"lnp_type\": \"lspp\",\n    \"activation_timestamp\": \"2024-01-15T10:30:00Z\",\n    \"last_updated\": \"2025-08-07T01:30:00Z\"\n  }\n}\n```\n\nDefault format is plain text (`LRN;SPID`, e.g., `7207081999;567G`). Use `?format=json` for structured response.\nAlso available via POST: `/v1/telique/lrn/lookup` with JSON body `{ \"phone_number\": \"...\", \"format\": \"json\" }`.\n\n### LSMS Relationship Queries (`lrn_relationship_query` tool)\n\nQuery relationships between phone numbers, LRNs, and SPIDs from the LSMS PostgreSQL database. These hit the database directly and have higher latency than the in-memory LRN lookup.\n\n**6 query types and their endpoints:**\n\n| query_type | Endpoint | Description |\n|------------|----------|-------------|\n| `phones_by_lrn` | `GET /v1/telique/lsms/list/phone_number?lrn={value}` | All phone numbers for a given LRN |\n| `phones_by_spid` | `GET /v1/telique/lsms/list/phone_number?spid={value}` | All phone numbers for a given SPID |\n| `spid_by_lrn` | `GET /v1/telique/lsms/list/spid?lrn={value}` | All SPIDs associated with a given LRN |\n| `spid_by_phone` | `GET /v1/telique/lsms/list/spid?phone_number={value}` | All SPIDs for a given phone number |\n| `lrn_by_spid` | `GET /v1/telique/lsms/list/lrn?spid={value}` | All LRNs for a given SPID |\n| `lrn_by_phone` | `GET /v1/telique/lsms/list/lrn?phone_number={value}` | All LRNs for a given phone number |\n\n**Constraints:**\n- Exactly ONE query parameter per request (multiple parameters return a validation error)\n- Results are filtered to active records only\n- Phone numbers and LRNs are returned as strings\n\n**Example response (phones_by_lrn):**\n```json\n{\n  \"phone_numbers\": [\"3036298301\", \"3039982743\", \"3033334444\"],\n  \"count\": 3,\n  \"query\": { \"lrn\": \"7207081999\", \"spid\": null, \"phone_number\": null }\n}\n```\n\n---\n\n## CNAM (Caller Name)\n\n`cnam_lookup` queries TransUnion's LIDB for the caller name associated with a phone number.\n\n- Returns: calling_name (up to 15 chars), calling_name_status (available/unavailable), presentation_indicator (allowed/restricted)\n- Results cached server-side for 24 hours\n- \"WIRELESS CALLER\" typically means the carrier hasn't provisioned a specific CNAM entry\n\n---\n\n## DNO (Do Not Originate)\n\n`dno_check` checks if a phone number should never appear as a caller ID.\n\n- DNO numbers belong to entities that only receive calls (IRS, major banks, government agencies)\n- If is_dno=true, the number appearing as caller ID indicates **spoofing/fraud**\n- Supports prefix matching: 3-digit (NPA), 6-digit (NPA-NXX), 7-digit, or 10-digit patterns\n- Response includes: is_dno, matched_pattern, source\n- Phone numbers are auto-normalized: E.164 (+12003456789), domestic (12003456789), and international (0012003456789) formats all accepted\n\n---\n\n## RouteLink \u2014 Toll-Free Number Routing\n\n**What is a toll-free number?** A phone number with an 8XX NPA (area code) that is free for the caller \u2014 the called party pays. Toll-free NPAs: **800, 888, 877, 866, 855, 844, 833, 822**. Any 10-digit number starting with one of these NPAs is a toll-free number (also called TFN or CRN in RouteLink context).\n\nToll-free numbers are managed by the **Somos TFN Registry**, not NPAC/LSMS. They have their own routing system (CPR decision trees) and their own management hierarchy (RespOrgs, not SPIDs). Use the RouteLink tools for toll-free lookups \u2014 do NOT use `lrn_lookup` for toll-free numbers (they don't have LRNs).\n\n### ROR (Responsible Organization)\n`routelink_lookup` with lookup_type=\"ror\" returns the RespOrg managing a toll-free number.\n- RespOrg is a 5-char code (e.g., \"NEX01\", \"TZN99\")\n- Only needs the CRN (toll-free number), no ANI/LATA required\n\n### CIC (Carrier Identification Code)\n`routelink_lookup` with lookup_type=\"cic\" or \"cicror\" returns which carrier handles calls to a toll-free number FROM a specific caller (ANI) in a specific LATA.\n- Requires: crn, ani (10-digit), lata (3-digit)\n- Common carrier codes: 0288 (AT&T), 0222 (MCI/Verizon), 0333 (Sprint), 0432 (Lumen)\n\n### CPR (Call Processing Record)\n`routelink_cpr` retrieves the full routing decision tree for a toll-free number.\n\n**Decision tree node types:**\n| Node | Description |\n|------|-------------|\n| [LATA] | Routes by caller's LATA |\n| [NPA] | Routes by caller's area code |\n| [NXX] | Routes by caller's exchange |\n| [STATE] | Routes by caller's state |\n| [DAY_OF_WEEK] | Routes by day (1-7, Sunday=1) |\n| [TIME_OF_DAY] | Routes by time (15-min intervals) |\n| [PERCENT] | Percentage-based load balancing |\n| [ANI] | Routes by specific caller number |\n\n**Action types:** Carrier XXXX (4-digit carrier code), Template XXXXXXXXXX (reference to template CRN), Routing XXXXX, NMC X (Network Management Class)\n\n**Common patterns:**\n- Simple: All calls \u2192 one carrier \u2192 one termination number\n- Time-of-day: Business hours \u2192 office, after hours \u2192 answering service\n- Geographic: Different terminations per LATA/state/NPA\n- Percentage: Load balancing across call centers (e.g., 60%/40%)\n\nUse `expand=true` (default) to recursively resolve template references into their full decision trees.\n\n---\n\n## GraphQL\n\nUse `graphql_query` for complex queries not possible with REST:\n- Cross-table relationship joins (lerg6 \u2192 carrier, lerg6 \u2192 switchInfo, lerg7Sha \u2192 tandemSwitch)\n- Filtering by fields not in REST endpoints\n- Multiple related data points in one query\n\n### LERG GraphQL (`service=\"lerg\"`)\n\n**CRITICAL naming rules:**\n- **Query names** are camelCase: `lerg1`, `lerg6`, `lerg7Sha`, `lerg7ShaIns`, `lerg12`, etc.\n- **Return fields** MUST be camelCase: `ocnName`, `locState`, `locName`, `shaIndicator`, `hTrmDTdm`\n- **Filter field names** accept BOTH camelCase (`ocnName`) and snake_case (`ocn_name`)\n- **All values are strings** \u2014 even numeric fields. Always quote: `value: \"720\"` not `value: 720`\n- **GraphQL LIKE is case-sensitive (SQL)** \u2014 LERG data is stored UPPERCASE, so patterns must be uppercase: `%VERIZON%` not `%verizon%`. (The REST `like` operator is case-insensitive \u2014 this only applies to GraphQL.)\n\n**FilterInput:**\n```graphql\n{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }   # partial match (UPPERCASE!)\n{ field: \"npa\", op: EQ, value: \"720\" }                # exact match\n{ field: \"npa\", op: IN, values: [\"212\", \"646\", \"917\"] } # IN uses 'values' (plural), not 'value'\n```\n\nOperators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, IS_NULL, IS_NOT_NULL\n\n**Predefined relationships** (avoid N+1 \u2014 use these instead of separate queries):\n- `lerg6` \u2192 `carrier` (joins to lerg1 via OCN), `switchInfo` (\u2192 lerg7), `homingArrangements` (\u2192 lerg7Sha)\n- `lerg7` \u2192 `carrier` (\u2192 lerg1)\n- `lerg7Sha` \u2192 `tandemSwitch` (\u2192 lerg7)\n\n**Example \u2014 find all Verizon OCNs:**\n```graphql\n{\n  lerg1(\n    filters: [{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }]\n    pagination: { limit: 10 }\n  ) {\n    ocnNum\n    ocnName\n    ocnState\n    category\n  }\n}\n```\n\n**Example \u2014 NPA-NXX with carrier and switch in one query:**\n```graphql\n{\n  lerg6(\n    filters: [{ field: \"npa\", op: EQ, value: \"303\" }, { field: \"nxx\", op: EQ, value: \"629\" }]\n    pagination: { limit: 1 }\n  ) {\n    npa nxx ocn locName switch\n    carrier { ocnNum ocnName ocnState }\n    switchInfo { switch eqpType swCity swState }\n    homingArrangements {\n      shaIndicator hTrmDTdm\n      tandemSwitch { switch swCity swState }\n    }\n  }\n}\n```\n\n**dynamicJoin** \u2014 for arbitrary cross-table SQL joins (returns raw JSON):\n```graphql\n{\n  dynamicJoin(input: {\n    table: \"lerg_6\"\n    fields: [\"npa\", \"nxx\", \"ocn\", \"locName\"]\n    filters: [{ field: \"locName\", op: LIKE, value: \"%DENVER%\" }]\n    join: {\n      table: \"lerg_1\"\n      fields: [\"ocnName\", \"category\"]\n      on: [{ leftField: \"ocn\", rightField: \"ocnNum\" }]\n      joinType: \"INNER\"\n    }\n    pagination: { limit: 10 }\n  })\n}\n```\nNote: dynamicJoin uses snake_case table IDs (lerg_6, lerg_1, lerg_7_sha) and returns raw PostgreSQL column names (UPPERCASE with spaces, e.g., `\"OCN_NAME\"`, `\"LOC NAME\"`, `\"EFF DATE\"`), NOT GraphQL camelCase.\n\n### LSMS GraphQL (`service=\"lsms\"`)\n\nThe LSMS GraphQL API is a **completely separate implementation** from LERG GraphQL. It has different query patterns, different field naming, and different schema design. Do NOT use LERG-style FilterInput syntax with LSMS.\n\n**5 tables:**\n\n| Table | ~Rows | Requires Filter? |\n|-------|-------|------------------|\n| subscriptionVersions | 514M | Yes (phoneNumber, lrn, or spid) |\n| numberBlocks | 751K | Yes (npanxxx, spid, or lrn) |\n| serviceProviders | 5.2K | No |\n| locationRoutingNumbers | 56K | No |\n| npanxx | 192K | No |\n\n**Query patterns (NOT FilterInput \u2014 uses typed named parameters):**\n```graphql\n# Single phone number lookup\n{ subscriptionVersion(phoneNumber: \"3036298301\") { phoneNumber lrn spid serviceProvider { name } } }\n\n# Paginated list by LRN (returns totalCount, hasMore)\n{ subscriptionVersionsByLrn(lrn: \"7207081999\", limit: 10) { totalCount hasMore items { phoneNumber spid } } }\n\n# Paginated list by SPID\n{ subscriptionVersionsBySpid(spid: \"567G\", limit: 10) { totalCount hasMore items { phoneNumber lrn } } }\n\n# Number block lookup (single)\n{ numberBlock(npanxxx: \"3035551\") { npanxxx lrn spid serviceProvider { name } } }\n\n# Number blocks by SPID or LRN (paginated \u2014 at least one filter required)\n{ numberBlocks(spid: \"567G\", limit: 10) { totalCount hasMore items { npanxxx lrn spid } } }\n\n# Single carrier lookup (note: composite PK \u2014 same SPID may exist in multiple regions)\n{ serviceProvider(spid: \"567G\") { spid name npacRegion status contactInfo } }\n\n# List carriers (paginated)\n{ serviceProviders(limit: 20) { spid name npacRegion } }\n\n# LRN metadata\n{ locationRoutingNumber(lrn: \"7207081999\") { lrn ocn regionId status switchInfo } }\n\n# NPA-NXX single lookup\n{ npanxx(npa: \"303\", nxx: \"629\") { npa nxx spid effectiveTimestamp serviceProvider { name } } }\n\n# NPA-NXX codes for a carrier (paginated)\n{ npanxxBySpid(spid: \"567G\", limit: 50) { npa nxx effectiveTimestamp } }\n\n# Database statistics\n{ lsmsStats { activeSubscriptionVersions activeNumberBlocks totalServiceProviders totalLocationRoutingNumbers activeNpanxx } }\n```\n\n**Relationships** (use DataLoader batching \u2014 no N+1):\n- subscriptionVersion \u2192 `serviceProvider`, `lrnMetadata`\n- numberBlock \u2192 `serviceProvider`, `lrnMetadata`\n- npanxx \u2192 `serviceProvider`\n\n**Safety limits:** max 1000 results, depth 5, complexity 200, 10-second statement timeout\n**Auto-filters:** Soft-deletable records filter to is_active = true automatically\n**Note:** Phone numbers/LRNs are strings (stored as BIGINT but GraphQL Int is 32-bit). SPIDs are auto-trimmed (stored as CHAR(4) with trailing spaces).\n**Note:** Service providers have a composite PK of (spid, npac_region) \u2014 the same SPID may appear in multiple NPAC regions.\n\n---\n\n## Key Telecom Concepts\n\n| Term | Definition |\n|------|-----------|\n| **LRN** | Location Routing Number \u2014 identifies the switch serving a ported number |\n| **SPID** | Service Provider ID \u2014 identifies the carrier that owns a number |\n| **OCN** | Operating Company Number \u2014 4-char carrier identifier (often same as SPID) |\n| **NPA** | Numbering Plan Area \u2014 3-digit area code |\n| **NXX** | Exchange code \u2014 next 3 digits after area code |\n| **LATA** | Local Access Transport Area \u2014 geographic region for call routing |\n| **CLLI** | Common Language Location Identifier \u2014 8-11 char switch/building code |\n| **CRN** | Call Routing Number \u2014 a toll-free number in RouteLink context |\n| **ROR/RespOrg** | Responsible Organization \u2014 entity managing a toll-free number's routing |\n| **CIC** | Carrier Identification Code \u2014 identifies which carrier handles a toll-free call |\n| **CPR** | Call Processing Record \u2014 routing decision tree for a toll-free number |\n| **Rate Center** | Geographic area defining local calling boundaries |\n| **Tandem** | A switching office that connects local switches to the long-distance network |\n| **Homing** | The relationship between a local switch and its tandem |\n\n---\n\n## Common Mistakes to Avoid\n\n1. **Never guess carrier names** \u2014 always query lerg_1 by OCN\n2. **Never skip the LRN dip** \u2014 ported TNs have different NPA-NXX than their LRN\n3. **Never look for tandem/switch data in LSMS** \u2014 LSMS has no infrastructure data\n4. **Never look for TN-level data in LERG** \u2014 LERG has no per-phone-number data\n5. **Never query LSMS subscriptionVersions without a filter** \u2014 514M rows will timeout\n6. **Always use the LRN's NPA-NXX** (not the TN's) for LERG routing lookups\n7. **GraphQL return fields must be camelCase** \u2014 `ocnName` not `ocn_name`, `locState` not `loc_state`\n8. **GraphQL LIKE patterns must be UPPERCASE** \u2014 LERG data is uppercase in PostgreSQL, so `%VERIZON%` works but `%verizon%` returns nothing. (REST `like` is case-insensitive \u2014 this only applies to GraphQL.)\n9. **IN operator uses `values` (plural)** \u2014 `{ field: \"npa\", op: IN, values: [\"212\", \"646\"] }` not `value`\n";

package/dist/knowledge.js

@@ -83,8 +83,14 @@ Or use \`lookup_tn\` for a quick consolidated view (dips LRN + CNAM + DNO + LERG
 **lerg_6** — NPA-NXX block assignments (the workhorse)
 - Fields: npa, nxx, block_id, lata, lata_name, loc_state, ocn, aocn, switch, sha_indicator, rc_abbre, rc_type, coc_type, eff_date, status
 - Has LATA + state + NPA + NXX + OCN + switch + rate center all on one row.
-- BLOCK="A" = full NXX assignment; numeric 0-9 = thousands-block pooling.
-- Example: \`lerg_query("lerg_6", "npa,nxx,loc_name,loc_state,ocn,switch,lata", "npa=720&nxx=708")\`
+- Example: \`lerg_query("lerg_6", "npa,nxx,block_id,loc_name,loc_state,ocn,switch,lata", "npa=720&nxx=708")\`
+
+**CRITICAL: Understanding block_id and NPA-NXX ownership:**
+- \`block_id="A"\` = the **Code Holder** — the original LERG owner of the entire NPA-NXX. This is THE owner of the NPA-NXX.
+- \`block_id="0"\` through \`"9"\` = **Block Holders** — carriers who received a pooled 1,000-number block (thousands-block pooling). Each block covers numbers x000-x999 within the NXX.
+- When asked "who owns NPA-NXX 720-708?", the answer is the OCN on the \`block_id="A"\` row.
+- A query for \`npa=720&nxx=708\` may return multiple rows — one for block_id="A" (the Code Holder) and additional rows for pooled blocks (0-9). Always filter or identify the "A" row for ownership questions.
+- To find which carrier serves a specific phone number within a pooled NXX, use the LRN dip pattern instead (the block_id approach only tells you who holds the block, not who currently serves an individual ported number).
 
 **lerg_7_sha** — Switch homing arrangements
 - Fields: switch, sha_indicator, h_trm_d_tdm (FGD tandem), host, ocn
@@ -142,6 +148,84 @@ Note: REST \`like\` is **case-insensitive** (in-memory matching), unlike GraphQL
 
 ---
 
+## When to Use REST vs GraphQL
+
+| Use Case | Best Tool | Why |
+|----------|-----------|-----|
+| Single LRN/SPID for a phone number | \`lrn_lookup\` (REST) | Sub-millisecond, in-memory |
+| Carrier name by OCN | \`lerg_query\` (REST) | Simple single-field lookup |
+| NPA-NXX routing info | \`lerg_query\` (REST) | Fast, straightforward |
+| Tandem routing | \`lerg_tandem\` (REST) | Pre-built JOIN, optimized |
+| NPA-NXX + carrier name + switch in one call | \`graphql_query\` (LERG) | Nested relationships avoid multiple round trips |
+| Filter by fields not in REST (e.g., all switches for an OCN) | \`graphql_query\` (LERG) | FilterInput supports any field |
+| Cross-table JOIN with arbitrary conditions | \`graphql_query\` (LERG dynamicJoin) | Only way to do ad-hoc joins |
+| All phone numbers for an LRN (paginated with totalCount) | \`graphql_query\` (LSMS) | SVConnection returns totalCount + hasMore |
+| Quick profile of a phone number | \`lookup_tn\` (composite) | Parallel dip across LRN + CNAM + DNO + LERG |
+
+**Rule of thumb:** Use REST for simple lookups (one table, one or two filters). Use GraphQL when you need joins, relationship traversal, or fields not exposed by REST endpoints.
+
+---
+
+## LSMS / LRN REST Endpoints
+
+The LRN API serves live NPAC porting data from an in-memory Judy Array store (500M+ records, sub-millisecond) backed by a PostgreSQL LSMS database.
+
+### LRN Lookup (\`lrn_lookup\` tool)
+
+\`GET /v1/telique/lrn/{phone_number}?format=json\`
+
+Returns the current LRN and carrier for a phone number. This is the fastest lookup — served from in-memory store, not PostgreSQL.
+
+**JSON response shape:**
+\`\`\`json
+{
+  "phone_number": "3036298301",
+  "lrn": "7207081999",
+  "status": "success",
+  "timestamp": "2025-08-07T02:30:00Z",
+  "metadata": {
+    "spid": "567G",
+    "lnp_type": "lspp",
+    "activation_timestamp": "2024-01-15T10:30:00Z",
+    "last_updated": "2025-08-07T01:30:00Z"
+  }
+}
+\`\`\`
+
+Default format is plain text (\`LRN;SPID\`, e.g., \`7207081999;567G\`). Use \`?format=json\` for structured response.
+Also available via POST: \`/v1/telique/lrn/lookup\` with JSON body \`{ "phone_number": "...", "format": "json" }\`.
+
+### LSMS Relationship Queries (\`lrn_relationship_query\` tool)
+
+Query relationships between phone numbers, LRNs, and SPIDs from the LSMS PostgreSQL database. These hit the database directly and have higher latency than the in-memory LRN lookup.
+
+**6 query types and their endpoints:**
+
+| query_type | Endpoint | Description |
+|------------|----------|-------------|
+| \`phones_by_lrn\` | \`GET /v1/telique/lsms/list/phone_number?lrn={value}\` | All phone numbers for a given LRN |
+| \`phones_by_spid\` | \`GET /v1/telique/lsms/list/phone_number?spid={value}\` | All phone numbers for a given SPID |
+| \`spid_by_lrn\` | \`GET /v1/telique/lsms/list/spid?lrn={value}\` | All SPIDs associated with a given LRN |
+| \`spid_by_phone\` | \`GET /v1/telique/lsms/list/spid?phone_number={value}\` | All SPIDs for a given phone number |
+| \`lrn_by_spid\` | \`GET /v1/telique/lsms/list/lrn?spid={value}\` | All LRNs for a given SPID |
+| \`lrn_by_phone\` | \`GET /v1/telique/lsms/list/lrn?phone_number={value}\` | All LRNs for a given phone number |
+
+**Constraints:**
+- Exactly ONE query parameter per request (multiple parameters return a validation error)
+- Results are filtered to active records only
+- Phone numbers and LRNs are returned as strings
+
+**Example response (phones_by_lrn):**
+\`\`\`json
+{
+  "phone_numbers": ["3036298301", "3039982743", "3033334444"],
+  "count": 3,
+  "query": { "lrn": "7207081999", "spid": null, "phone_number": null }
+}
+\`\`\`
+
+---
+
 ## CNAM (Caller Name)
 
 \`cnam_lookup\` queries TransUnion's LIDB for the caller name associated with a phone number.
@@ -160,11 +244,16 @@ Note: REST \`like\` is **case-insensitive** (in-memory matching), unlike GraphQL
 - If is_dno=true, the number appearing as caller ID indicates **spoofing/fraud**
 - Supports prefix matching: 3-digit (NPA), 6-digit (NPA-NXX), 7-digit, or 10-digit patterns
 - Response includes: is_dno, matched_pattern, source
+- Phone numbers are auto-normalized: E.164 (+12003456789), domestic (12003456789), and international (0012003456789) formats all accepted
 
 ---
 
 ## RouteLink — Toll-Free Number Routing
 
+**What is a toll-free number?** A phone number with an 8XX NPA (area code) that is free for the caller — the called party pays. Toll-free NPAs: **800, 888, 877, 866, 855, 844, 833, 822**. Any 10-digit number starting with one of these NPAs is a toll-free number (also called TFN or CRN in RouteLink context).
+
+Toll-free numbers are managed by the **Somos TFN Registry**, not NPAC/LSMS. They have their own routing system (CPR decision trees) and their own management hierarchy (RespOrgs, not SPIDs). Use the RouteLink tools for toll-free lookups — do NOT use \`lrn_lookup\` for toll-free numbers (they don't have LRNs).
+
 ### ROR (Responsible Organization)
 \`routelink_lookup\` with lookup_type="ror" returns the RespOrg managing a toll-free number.
 - RespOrg is a 5-char code (e.g., "NEX01", "TZN99")
@@ -309,20 +398,29 @@ The LSMS GraphQL API is a **completely separate implementation** from LERG Graph
 # Paginated list by SPID
 { subscriptionVersionsBySpid(spid: "567G", limit: 10) { totalCount hasMore items { phoneNumber lrn } } }
 
-# Number block lookup
+# Number block lookup (single)
 { numberBlock(npanxxx: "3035551") { npanxxx lrn spid serviceProvider { name } } }
 
-# List carriers
+# Number blocks by SPID or LRN (paginated — at least one filter required)
+{ numberBlocks(spid: "567G", limit: 10) { totalCount hasMore items { npanxxx lrn spid } } }
+
+# Single carrier lookup (note: composite PK — same SPID may exist in multiple regions)
+{ serviceProvider(spid: "567G") { spid name npacRegion status contactInfo } }
+
+# List carriers (paginated)
 { serviceProviders(limit: 20) { spid name npacRegion } }
 
 # LRN metadata
-{ locationRoutingNumber(lrn: "7207081999") { lrn ocn switchInfo } }
+{ locationRoutingNumber(lrn: "7207081999") { lrn ocn regionId status switchInfo } }
+
+# NPA-NXX single lookup
+{ npanxx(npa: "303", nxx: "629") { npa nxx spid effectiveTimestamp serviceProvider { name } } }
 
-# NPA-NXX codes for a carrier
+# NPA-NXX codes for a carrier (paginated)
 { npanxxBySpid(spid: "567G", limit: 50) { npa nxx effectiveTimestamp } }
 
 # Database statistics
-{ lsmsStats { activeSubscriptionVersions activeNumberBlocks totalServiceProviders } }
+{ lsmsStats { activeSubscriptionVersions activeNumberBlocks totalServiceProviders totalLocationRoutingNumbers activeNpanxx } }
 \`\`\`
 
 **Relationships** (use DataLoader batching — no N+1):
@@ -332,7 +430,8 @@ The LSMS GraphQL API is a **completely separate implementation** from LERG Graph
 
 **Safety limits:** max 1000 results, depth 5, complexity 200, 10-second statement timeout
 **Auto-filters:** Soft-deletable records filter to is_active = true automatically
-**Note:** Phone numbers/LRNs are strings (stored as BIGINT but GraphQL Int is 32-bit). SPIDs are auto-trimmed.
+**Note:** Phone numbers/LRNs are strings (stored as BIGINT but GraphQL Int is 32-bit). SPIDs are auto-trimmed (stored as CHAR(4) with trailing spaces).
+**Note:** Service providers have a composite PK of (spid, npac_region) — the same SPID may appear in multiple NPAC regions.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telique-mcp",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "MCP server for Telique telecom APIs (RouteLink, LRN, CNAM, LERG)",
   "type": "module",
   "main": "dist/index.js",