telique-mcp 1.0.25 → 1.0.27

package/dist/annotations.d.ts

@@ -0,0 +1,5 @@
+export declare const READ_ONLY_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: false;
+    readonly destructiveHint: false;
+};

package/dist/annotations.js

@@ -0,0 +1,5 @@
+export const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+};

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- 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";
+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.\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## REST Paths for Direct API Access\n\nThe MCP tools wrap these HTTP endpoints. Use this table when calling the Telique API directly with `curl` or another HTTP client. Base URL: `https://api-dev.ringer.tel`. Authentication: `-H \"x-api-token: tlq_\u2026\"` (per-request header, never in query string).\n\n| Tool | Method | Path | Notes |\n|------|--------|------|-------|\n| `lrn_lookup` | GET | `/v1/telique/lrn/{phone_number}` | Add `?format=json` for structured response; default is `LRN;SPID` plain text |\n| `cnam_lookup` | GET | `/v1/telique/cnam/{phone_number}` | Returns calling_name, presentation_indicator |\n| `dno_check` | GET | `/v1/telique/dno/{phone_number}` | Add `?format=json` for details; default is `true`/`false` text |\n| `lrn_relationship_query` | GET | `/v1/telique/lsms/list/{resource}?{filter}={value}` | `resource` \u2208 {phone_number, spid, lrn}; filter \u2208 {lrn, spid, phone_number}; exactly one filter |\n| `lerg_table_info` | GET | `/v1/telique/lerg/tables` or `/v1/telique/lerg/tables/{table_name}` | No args = list all tables |\n| `lerg_query` | GET | `/v1/telique/lerg/{table_name}/{fields}/{query}` | Example: `/lerg/lerg_6/npa,nxx,ocn/npa=303&nxx=629` |\n| `lerg_complex_query` | POST | `/v1/telique/lerg/query` | JSON body with table, fields, filters, join, limit, offset |\n| `lerg_tandem` | GET | `/v1/telique/lerg/tandem?npa={npa}&nxx={nxx}` | Pre-joined tandem lookup |\n| `routelink_lookup` (ror) | GET | `/v1/telique/ror/{crn}` | Responsible Organization for a toll-free number |\n| `routelink_lookup` (cic/cicror) | GET | `/v1/telique/{cic\\|cicror}/{crn}/{ani}/{lata}` | CIC or CIC+ROR for a toll-free call |\n| `routelink_ror_query` | GET | `/v1/telique/ror/{ror}/{tfns\\|cprs}` | List TFNs or CPRs for a ROR; paginated `?limit=&offset=` |\n| `routelink_cpr` | GET | `/v1/telique/cpr/{crn}` | Call Processing Record; add `?expand=true` to inline templates |\n| `graphql_query` (lerg) | POST | `/v1/telique/lerg/gql` | JSON body `{\"query\":\"...\"}`; GET returns GraphiQL playground HTML |\n| `graphql_query` (lsms) | POST | `/v1/telique/lsms/gql` | JSON body `{\"query\":\"...\"}`; GET returns GraphiQL playground HTML |\n| `lookup_tn` | \u2014 | (composite) | Not a single endpoint \u2014 fans out to `/lrn/`, `/cnam/`, `/dno/`, `/lerg/\u2026` in parallel |\n\n**Note on RouteLink paths**: there is NO `/routelink/` segment. The public OpenAPI spec at `https://telique.ringer.tel/docs/api-reference` historically listed `/v1/telique/routelink/cpr/{crn}` etc. \u2014 those paths return 404. The real paths are bare (`/v1/telique/cpr/{crn}`) as shown above.\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

@@ -193,7 +193,6 @@ Returns the current LRN and carrier for a phone number. This is the fastest look
 \`\`\`
 
 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)
 
@@ -435,6 +434,32 @@ The LSMS GraphQL API is a **completely separate implementation** from LERG Graph
 
 ---
 
+## REST Paths for Direct API Access
+
+The MCP tools wrap these HTTP endpoints. Use this table when calling the Telique API directly with \`curl\` or another HTTP client. Base URL: \`https://api-dev.ringer.tel\`. Authentication: \`-H "x-api-token: tlq_…"\` (per-request header, never in query string).
+
+| Tool | Method | Path | Notes |
+|------|--------|------|-------|
+| \`lrn_lookup\` | GET | \`/v1/telique/lrn/{phone_number}\` | Add \`?format=json\` for structured response; default is \`LRN;SPID\` plain text |
+| \`cnam_lookup\` | GET | \`/v1/telique/cnam/{phone_number}\` | Returns calling_name, presentation_indicator |
+| \`dno_check\` | GET | \`/v1/telique/dno/{phone_number}\` | Add \`?format=json\` for details; default is \`true\`/\`false\` text |
+| \`lrn_relationship_query\` | GET | \`/v1/telique/lsms/list/{resource}?{filter}={value}\` | \`resource\` ∈ {phone_number, spid, lrn}; filter ∈ {lrn, spid, phone_number}; exactly one filter |
+| \`lerg_table_info\` | GET | \`/v1/telique/lerg/tables\` or \`/v1/telique/lerg/tables/{table_name}\` | No args = list all tables |
+| \`lerg_query\` | GET | \`/v1/telique/lerg/{table_name}/{fields}/{query}\` | Example: \`/lerg/lerg_6/npa,nxx,ocn/npa=303&nxx=629\` |
+| \`lerg_complex_query\` | POST | \`/v1/telique/lerg/query\` | JSON body with table, fields, filters, join, limit, offset |
+| \`lerg_tandem\` | GET | \`/v1/telique/lerg/tandem?npa={npa}&nxx={nxx}\` | Pre-joined tandem lookup |
+| \`routelink_lookup\` (ror) | GET | \`/v1/telique/ror/{crn}\` | Responsible Organization for a toll-free number |
+| \`routelink_lookup\` (cic/cicror) | GET | \`/v1/telique/{cic\\|cicror}/{crn}/{ani}/{lata}\` | CIC or CIC+ROR for a toll-free call |
+| \`routelink_ror_query\` | GET | \`/v1/telique/ror/{ror}/{tfns\\|cprs}\` | List TFNs or CPRs for a ROR; paginated \`?limit=&offset=\` |
+| \`routelink_cpr\` | GET | \`/v1/telique/cpr/{crn}\` | Call Processing Record; add \`?expand=true\` to inline templates |
+| \`graphql_query\` (lerg) | POST | \`/v1/telique/lerg/gql\` | JSON body \`{"query":"..."}\`; GET returns GraphiQL playground HTML |
+| \`graphql_query\` (lsms) | POST | \`/v1/telique/lsms/gql\` | JSON body \`{"query":"..."}\`; GET returns GraphiQL playground HTML |
+| \`lookup_tn\` | — | (composite) | Not a single endpoint — fans out to \`/lrn/\`, \`/cnam/\`, \`/dno/\`, \`/lerg/…\` in parallel |
+
+**Note on RouteLink paths**: there is NO \`/routelink/\` segment. The public OpenAPI spec at \`https://telique.ringer.tel/docs/api-reference\` historically listed \`/v1/telique/routelink/cpr/{crn}\` etc. — those paths return 404. The real paths are bare (\`/v1/telique/cpr/{crn}\`) as shown above.
+
+---
+
 ## Key Telecom Concepts
 
 | Term | Definition |

package/dist/lib.d.ts

@@ -10,4 +10,5 @@ export { registerStatusTools } from "./tools/status.js";
 export { registerKnowledge, TELIQUE_KNOWLEDGE } from "./knowledge.js";
 export { ICONS, ICON_LIGHT_DATA_URI, ICON_DARK_DATA_URI } from "./icons.js";
 export { VERSION } from "./version.js";
+export { READ_ONLY_ANNOTATIONS } from "./annotations.js";
 export type { ToolRegistrar } from "./types.js";

package/dist/lib.js

@@ -14,3 +14,5 @@ export { registerKnowledge, TELIQUE_KNOWLEDGE } from "./knowledge.js";
 // Metadata
 export { ICONS, ICON_LIGHT_DATA_URI, ICON_DARK_DATA_URI } from "./icons.js";
 export { VERSION } from "./version.js";
+// Annotations
+export { READ_ONLY_ANNOTATIONS } from "./annotations.js";

package/dist/tools/cnam.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
 import { formatResponse } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 export function registerCnamTools(server, client) {
     server.tool("cnam_lookup", "Look up the Caller Name (CNAM) for a phone number via TransUnion LIDB. Returns the calling_name (up to 15 characters), calling_name_status (available/unavailable), and presentation_indicator (allowed/restricted). Results are cached server-side for 24 hours.", {
         phone_number: z
             .string()
             .regex(/^\d{10,15}$/)
             .describe("10-15 digit phone number to look up"),
-    }, async ({ phone_number }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ phone_number }) => {
         const result = await client.get(`/v1/telique/cnam/${phone_number}`);
         return formatResponse(result);
     });

package/dist/tools/composite.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
 import { formatResponse } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 export function registerCompositeTools(server, client) {
     server.tool("lookup_tn", "Composite phone number lookup across multiple Telique services. Dips LRN, CNAM, DNO, and LERG (NPA-NXX from lerg_6) in parallel and returns a consolidated view. Use this for a quick, comprehensive profile of any phone number.", {
         phone_number: z
             .string()
             .regex(/^\d{10}$/)
             .describe("10-digit US phone number"),
-    }, async ({ phone_number }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ phone_number }) => {
         const npa = phone_number.substring(0, 3);
         const nxx = phone_number.substring(3, 6);
         const [lrn, cnam, dno, lerg] = await Promise.all([

package/dist/tools/graphql.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatResponse } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 export function registerGraphqlTools(server, client) {
     server.tool("graphql_query", `Execute GraphQL queries against LSMS or LERG. These are DISTINCT APIs with different schemas — do not mix their syntax.
 
@@ -14,7 +15,7 @@ LERG (service='lerg'): Static telecom reference. Uses FilterInput with operators
             .record(z.unknown())
             .optional()
             .describe("Optional GraphQL variables"),
-    }, async ({ service, query, variables }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ service, query, variables }) => {
         const path = service === "lsms"
             ? "/v1/telique/lsms/gql"
             : "/v1/telique/lerg/gql";

package/dist/tools/lerg.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatResponse } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 const LERG_TABLES = [
     "lerg_1",
     "lerg_1_con",
@@ -35,7 +36,7 @@ export function registerLergTools(server, client) {
             .string()
             .optional()
             .describe("Specific table name (e.g. lerg_1, lerg_6, lerg_7_sha). Omit to list all tables."),
-    }, async ({ table_name }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ table_name }) => {
         if (table_name) {
             const result = await client.get(`/v1/telique/lerg/tables/${table_name}`);
             return formatResponse(result);
@@ -64,7 +65,7 @@ export function registerLergTools(server, client) {
             .min(0)
             .default(0)
             .describe("Pagination offset (default 0)"),
-    }, async ({ table_name, fields, query, limit, offset }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ table_name, fields, query, limit, offset }) => {
         // Encode & as %26 so multi-filters stay in the path segment
         const encodedQuery = query.replace(/&/g, "%26");
         const result = await client.get(`/v1/telique/lerg/${table_name}/${fields}/${encodedQuery}`, { limit, offset });
@@ -127,7 +128,7 @@ export function registerLergTools(server, client) {
             .min(0)
             .default(0)
             .describe("Pagination offset (default 0)"),
-    }, async ({ table, fields, filters, join, limit, offset }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ table, fields, filters, join, limit, offset }) => {
         const body = {
             table,
             filters,
@@ -177,7 +178,7 @@ export function registerLergTools(server, client) {
             .min(0)
             .default(0)
             .describe("Pagination offset (default 0)"),
-    }, async ({ npa, nxx, switch_clli, tandem, name, limit, offset }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ npa, nxx, switch_clli, tandem, name, limit, offset }) => {
         const params = {
             limit,
             offset,

package/dist/tools/lrn.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
 import { formatResponse, errorResult } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 export function registerLrnTools(server, client) {
     server.tool("lrn_lookup", "Look up the Local Routing Number (LRN) for a phone number. Returns the LRN, SPID (Service Provider ID), LNP type, and activation timestamp. LRN identifies the switch that serves a ported phone number. This queries live LSMS/NPAC porting data.", {
         phone_number: z
             .string()
             .regex(/^\d{10}$/)
             .describe("10-digit US phone number"),
-    }, async ({ phone_number }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ phone_number }) => {
         const result = await client.get(`/v1/telique/lrn/${phone_number}`, {
             format: "json",
         });
@@ -26,7 +27,7 @@ export function registerLrnTools(server, client) {
         value: z
             .string()
             .describe("The LRN, SPID, or phone number to query by (depends on query_type)"),
-    }, async ({ query_type, value }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ query_type, value }) => {
         const routeMap = {
             phones_by_lrn: { resource: "phone_number", param: "lrn" },
             phones_by_spid: { resource: "phone_number", param: "spid" },
@@ -47,7 +48,7 @@ export function registerLrnTools(server, client) {
             .string()
             .regex(/^\d{10}$/)
             .describe("10-digit US phone number to check"),
-    }, async ({ phone_number }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ phone_number }) => {
         const result = await client.get(`/v1/telique/dno/${phone_number}`, {
             format: "json",
         });

package/dist/tools/routelink.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatResponse, errorResult } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 export function registerRoutelinkTools(server, client) {
     server.tool("routelink_lookup", "Look up toll-free number routing. Resolves a CRN (toll-free number) to its carrier (CIC), Responsible Organization (ROR), or both. CIC lookup interprets the CPR decision tree using the caller's ANI and LATA to determine which carrier handles the call.", {
         crn: z
@@ -19,7 +20,7 @@ export function registerRoutelinkTools(server, client) {
             .regex(/^\d{3}$/)
             .optional()
             .describe("3-digit LATA code (required for cic and cicror lookups)"),
-    }, async ({ crn, lookup_type, ani, lata }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ crn, lookup_type, ani, lata }) => {
         if ((lookup_type === "cic" || lookup_type === "cicror") &&
             (!ani || !lata)) {
             return errorResult("ani and lata are required for cic and cicror lookups");
@@ -55,7 +56,7 @@ export function registerRoutelinkTools(server, client) {
             .min(0)
             .default(0)
             .describe("Pagination offset (default 0)"),
-    }, async ({ ror, resource_type, limit, offset }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ ror, resource_type, limit, offset }) => {
         const result = await client.get(`/v1/telique/ror/${ror}/${resource_type}`, { format: "json", limit, offset });
         return formatResponse(result);
     });
@@ -68,7 +69,7 @@ export function registerRoutelinkTools(server, client) {
             .boolean()
             .default(true)
             .describe("Recursively resolve and inline template decision trees (default true)"),
-    }, async ({ crn, expand }) => {
+    }, READ_ONLY_ANNOTATIONS, async ({ crn, expand }) => {
         // NOTE: /v1/telique/cpr/* path pending frontend URL map addition.
         // Falls back to /cpr/ which routes to routelink via default backend.
         const result = await client.get(`/v1/telique/cpr/${crn}`, {

package/dist/tools/status.js

@@ -1,7 +1,8 @@
 import { VERSION } from "../version.js";
 import { formatResponse } from "../utils/formatting.js";
+import { READ_ONLY_ANNOTATIONS } from "../annotations.js";
 export function registerStatusTools(server, client) {
-    server.tool("telique_status", "Returns the Telique MCP server version, authentication mode, and API connectivity status. Use this when asked about the server version or connection status.", {}, async () => {
+    server.tool("telique_status", "Returns the Telique MCP server version, authentication mode, and API connectivity status. Use this when asked about the server version or connection status.", {}, READ_ONLY_ANNOTATIONS, async () => {
         let apiReachable = false;
         try {
             const result = await client.get("/health");

package/package.json

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