NetSuite Records & Metadata

NetSuite Records & Metadata

Overview

NetSuite organizes almost everything as a typed record — customer, vendor, salesorder, invoice, employee, and many more, each with its own internal ID and field set. This skill covers looking a specific record up directly when you already know (or can pin down) its type and ID, and discovering what fields a record type actually has before you go looking for one.

Anti-triggers

• Finding records by criteria you don't have an ID for — use suiteql-queries to search, then retrieve the specific record here if needed.
• Creating or updating a record — this plugin is read-only. See GOVERNANCE.md, Tool permission tiers: ns_createRecord and ns_updateRecord are the two write tools this plugin deliberately excludes. Make the change directly in the NetSuite UI, with the same care you'd give any change to a client's financial system of record.
• Reports or saved searches already built for this data — use reports-and-saved-searches rather than re-deriving what a report already computes.
• Auth, role permissions, or error handling — use api-patterns.

Core Concepts

Every NetSuite record has a record type (a fixed string like customer or salesorder) and an internal ID (a number, unique within that type). Record-type metadata describes the fields a given type carries — names, data types, and (per NetSuite's ns_getRecordTypeMetadata tool) can be requested for a single type or for all types at once. What a record actually returns when retrieved depends entirely on the connected role's view permissions on that type and its fields — the same way it would if a human opened the record in the NetSuite UI.

API Patterns

The confirmed read tool family for this domain:

• ns_getRecord — retrieves a record in NetSuite by type and internal ID
• ns_getRecordTypeMetadata — retrieves metadata (available fields and data types) for all NetSuite record types, or for a specific type

Both are documented by Oracle at Available Tools in the MCP Standard Tools SuiteApp. The corresponding write tools, ns_createRecord and ns_updateRecord, are excluded from this plugin — see GOVERNANCE.md.

A note on record-type-specific commands: this plugin does not ship a separate command per record type (e.g. no dedicated "get customer" vs. "get vendor" command). ns_getRecord is generic across record types by design, and this plugin's /get-record command is built directly against that generic tool rather than inventing per-type wrappers that don't correspond to anything the underlying MCP surface exposes.

Common Workflows

Looking up a customer before an escalation

A support ticket references a customer by name, not ID:

1. If the internal ID isn't known, use suiteql-queries to find it (e.g. SELECT id, companyname FROM customer WHERE companyname LIKE '...')
2. Call ns_getRecord with type customer and the resolved ID
3. Report the fields relevant to the escalation — don't dump the entire record if only a few fields matter

Confirming a record type's fields before writing a SuiteQL query

Before querying an unfamiliar record type:

1. Call ns_getRecordTypeMetadata for that type
2. Use the returned field names and types to write an accurate SuiteQL query in suiteql-queries, rather than guessing at field names

Gotchas

• Retrieval respects the connected role's field-level permissions, not just record-level. A role with view access to a record type can still have specific fields withheld — a retrieved record missing an expected field may be a permission boundary, not a data gap.
• Internal IDs are per-type, not global. Customer 12345 and sales order 12345 are unrelated records; always pair an ID with its record type.
• This is a read-only lookup, with no exceptions. Even a trivial correction (fixing an obviously wrong field) is outside this plugin — escalate to a human with direct NetSuite access.

Related Skills

• Reports & Saved Searches — Pre-built aggregations and lookups
• SuiteQL Queries — Finding records by criteria
• API Patterns — Auth, roles, and error handling