Lookups tools

Updated May 21, 20262 min read

12 read-only tools that resolve identifiers and surface a tenant's configuration. Agents call these first, before invoking shipment or report tools, so the user's request is grounded in real data.

Tenant safety rule

Always call get_accessible_tenants first. Validate any user-requested tenant against the result before invoking shipment tools. If the tenant isn't accessible, the agent must not proceed.

Discovery

Tool	What it returns
`get_accessible_tenants`	Tenants accessible to the current user — id, name, allowed merchants, subscription summary. No required params.
`get_merchants`	Merchants in a tenant the current user can use. Requires `tenantId`.

Configuration lookups

Tool	What it returns
`get_delivery_types`	Delivery types configured for a tenant. Requires `tenantId`.
`get_order_types`	Order types configured for a tenant. Requires `tenantId`.
`get_custom_attributes`	Custom attributes configured for a tenant. Requires `tenantId`.

Operational lookups

Tool	What it returns
`get_carrier_accounts`	Carrier accounts for a tenant, with merchant-access filtering. Requires `tenantId`.
`get_locations`	Locations for a tenant, with merchant-access filtering. Requires `tenantId`.

Return-request reference data

The five tools below back the dropdowns and pickers used by return-request flows. The agent only needs them when a user-facing prompt is about creating, approving, or rejecting a return.

Tool	What it returns
`get_return_request_reasons`	Configured reasons a customer can give for returning an item.
`get_return_request_resolutions`	Configured resolutions a return can settle as (refund, exchange, store credit, etc.).
`get_return_request_rejection_reasons`	Configured reasons the merchant can give for rejecting a return.
`get_return_request_item_conditions`	Configured item conditions used when receiving returned goods.
`get_return_request_refund_types`	Configured refund types (original payment method, store credit, etc.).

Common chain

The canonical "agent first turn" sequence:

get_accessible_tenants            (which tenants can I see?)
       │
       ▼
get_merchants(tenantId="…")       (which merchants in the chosen tenant?)
       │
       ▼
…the user's actual question…       (now scoped to a real tenant + merchant)

Most agent clients let you cache lookup results across a session, so the agent doesn't need to re-discover on every prompt.

Notes

Lookups are cheap — small responses, low cost. Don't try to skip them for "performance" reasons.
The tenantId parameter on every other MCP tool comes from these lookups. If the agent picks a tenantId that wasn't returned by get_accessible_tenants, downstream tool calls will fail.