Tools

Tools are the unit of capability on a Wire container. MCP and REST are two transports — same tools, different connection mechanisms. This page is the source of truth for what each tool does, its parameters, and its default visibility on each transport.

Tool reference

Tool	Purpose	MCP default	REST default	Cost
`wire_explore`	Structured canonical access: schema, list, get, filter, text search	✅	✅	1
`wire_search`	Fuzzy hybrid retrieval over raw content	✅	✅	5
`wire_navigate`	Raw content traversal: siblings, source, relationships	✅	✅	1
`wire_write`	Save an entry to the container	✅	✅	0
`wire_delete`	Remove an entry by ID	✅	✅	0
`wire_status`	Container status snapshot	❌	✅	0
`wire_files_list`	List uploaded files	❌	✅	0
`wire_files_upload`	Upload a file (multipart)	❌	✅	0
`wire_files_delete`	Delete a file and its derived entries	❌	✅	0
`wire_claim`	Convert an ephemeral container to a permanent one (ephemeral only)	✅	✅	0

Every tool is independently toggleable per transport from the container’s Tools page in the dashboard. The defaults above are what new containers ship with; users can flip any tool on or off for either transport. Inactive tools are hidden from tools/list on MCP and return 404 NOT_FOUND on REST.

The typical agent journey is explore → search → navigate: use wire_explore to discover what’s in the container and fetch specific rows, use wire_search when you have a question and need fuzzy retrieval across raw content to find the right starting point, and use wire_navigate to move around from a content entry you’ve already landed on.

`wire_explore`

Structured canonical access. Discover what’s in the container (schema mode, the default), or query classified canonical entries directly by id, field, or keyword.

wire_explore operates on canonical entries — the classified knowledge-graph rows produced by background analysis. For fuzzy/semantic retrieval over raw content (file chunks, agent writes), use wire_search instead.

Parameter	Type	Required	Description
`mode`	string	No	`schema` (default), `list`, `get`, `filter`, or `text`
`entityType`	string	Required for `list`, `get`, `filter`; optional for `text`	Entity type to query. In schema mode, drills into detail.
`id`	string	`get` only	Canonical row id
`query`	string	`text` only	FTS5 query string
`filters`	array	`filter` only	Field predicates joined with AND. Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`
`source`	string	No	For `list`/`filter`/`text` — restrict to entries whose `source` matches or starts with this string (e.g. `"file:customers.csv"`)
`fields`	string[]	No	Return only these fields (projection)
`include`	string[]	No	Related entity types to include. Use schema mode to see available relationships.
`orderBy`	object	No	Sort by field and direction
`limit`	number	No	Max results (default 100, max 1000)
`offset`	number	No	Pagination offset
`includeSamples`	boolean	No	Schema mode only: include sample rows when `entityType` is given
`sampleLimit`	number	No	Schema mode only: number of samples (1-10, default 3)

Modes

schema (default) — Discover what’s in the container. Without entityType, returns all entity types with field names, record counts, and relationship edges. With entityType, drills into one type for fields, samples, and availableInclude.

list — Browse records of an entity type with pagination.

get — Retrieve a single record by id. Also returns mentions (text entries that reference this record) and parts (constituent chunks for composite entries). When the entity type is _composite with _compositeType: 'file' (the system-created entry for every uploaded file), the response includes a resource_link pointing at the file’s wire:// URI — agents resolve it via resources/read to get a signed download URL. _composite also represents chunked agent writes and, in the future, scraped webpages and API datasets (distinguished by _compositeType). See File downloads (Resources).

filter — Find records matching field conditions.

text — FTS5 BM25 keyword search across canonical entries. If entityType is provided, searches within that type. If omitted, runs a cross-entity-type search across all canonicals — each result carries its _entityType inline.

Example call

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "schema"}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/explore

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "wire_explore", "arguments": { "mode": "schema" } }
}

Return shape

The response shape depends on mode. Every variant includes mode so agents can branch on it.

schema overview (no entityType) — what’s in the container.

totalEntityTypes, totalEntries — top-level counts.
entityTypes[] — each entry has name, description, fields[] (with name / type / isPrimaryKey), and entryCount.
relationships[] — compact edges between entity types.

schema detail (with entityType) — drill into one type.

name, description, fields[], entryCount (same shape as above).
relationships[] — directional edges involving this type.
samples[] — sample rows when includeSamples: true.
availableInclude[] — values you can pass to include on list/filter/get.

list / filter / text — paginated record results.

results[] — canonical rows. Each is an object keyed by field name.
totalCount — total matches before pagination.
hasMore — true if there are more rows past limit + offset.
text mode additionally echoes query.

get — single record by id.

result — the row (object keyed by field name), or null if found: false.
found — boolean.
When the row is a _composite with _compositeType: 'file', the response also carries a resource_link content entry pointing at the file’s wire:// URI. See File downloads (Resources).

Affordance envelope. list / get / filter / text responses carry _meta.wire.related (pagination metadata for included relationships), and individual result rows carry _meta.wire.mentions.count — mirrors the _meta.wire.navigate hints on wire_search so agents know upfront whether a follow-up call would find anything.

`wire_search`

Fuzzy hybrid retrieval over raw content in the container — file chunks, agent writes, and other unstructured entries. Always runs a hybrid pipeline: BM25 + vector embedding + HyDE + LLM rerank.

Use this when you have a question and need semantic search to find relevant passages. For structured lookups on classified entities (by id, field, or keyword), use wire_explore.

Flat 5 credits per call.

Parameter	Type	Required	Description
`query`	string	Yes	Free-text query
`topK`	number	No	Max results (default 5, max 100)
`fileIds`	string[]	No	Filter to specific files
`minScore`	number	No	Minimum similarity score 0-1 (post-rerank)

Each match includes _meta.wire.navigate affordance hints telling the agent what a wire_navigate call on this match would find. See the return shape below for the full structure.

Example call

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "pricing concerns"}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/search

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "wire_search", "arguments": { "query": "pricing concerns" } }
}

Return shape

Each match carries:

id — the entry uuid. Pass this directly to wire_navigate or wire_delete.
score — hybrid relevance score (post-rerank).
content — the raw chunk or entry text.
provenance — typed metadata object: source, sourceFileId, chunkIndex, totalChunks, ingestedAt, tags, fileName, sectionHeader, chunkSummary, and more. Read the fields directly, no parsing needed.
_meta.wire.navigate — affordance hints for wire_navigate:
- hasSiblings — count of adjacent chunks in the same source file. Zero means this chunk stands alone.
- relationshipTypes — map of edge type to count, only non-zero entries. Example: { "elaborates": 3, "corroborates": 1 }. Tells the agent upfront which wire_navigate mode: "relationships" type: ... calls would find something.

Use these hints to decide whether a wire_navigate call is worth making, and to calibrate range or limit params.

`wire_navigate`

Traverse raw content from a match returned by wire_search. Given a non-canonical entry id, move to adjacent chunks, to the full source set, or along relationship edges.

wire_navigate is raw-only — it doesn’t cross into canonicals. To reach classified entities (Person, Product, Company, etc.) use wire_explore. Flat 1 credit per call.

Parameter	Type	Required	Description
`from`	string	Yes	Entry id of a non-canonical content entry (e.g. a `wire_search` match id)
`mode`	string	Yes	`siblings`, `source`, or `relationships`
`range`	number	`siblings` only	Chunks before AND after the anchor (default 3)
`limit`	number	`source` only	Max results (default 50)
`offset`	number	`source` only	Pagination offset
`type`	string	`relationships` only	Filter by edge type: `contradicts`, `corroborates`, `elaborates`, `supersedes`, etc. Omit to return all edges.
`since`	string	No	Lower bound on `created_at`. ISO timestamp or relative duration (`1h`, `24h`, `7d`, `30m`, `1w`)
`before`	string	No	Upper bound on `created_at`
`sort`	string	No	`relevance` (default) or `chronological` (newest first)

Modes

siblings — adjacent chunks in the same source file. Positional navigation. Given a chunk from a file, returns range chunks before and range chunks after it. If the anchor has no chunk position, degrades to source mode with limit = range * 2.

source — all entries from the same source. Paginated. Useful for “what else is in this file / session / webhook payload.” When the anchor’s source is an uploaded file, the response also includes a resource_link content entry pointing at the file’s wire:// URI — agents can call resources/read on it to grab the original bytes. See File downloads (Resources).

relationships — follow entry_relationships edges. Each result includes:

edgeType — the relationship label (contradicts, corroborates, elaborates, supersedes, derived_from, part_of, mentions).
edgeDirection — "outgoing" means “anchor edgeType other” (the anchor is the source of the relationship). "incoming" means “other edgeType anchor” (the anchor is on the receiving end). The direction matters because labels are stored from the new entry’s perspective at classification time, so “my chunk contradicts X” and “X contradicts my chunk” are different statements.
edgeProperties — any metadata attached to the edge itself.

The primary consumer of relationship edges populated by analysis and by per-write pairwise classification.

Temporal filters

since / before / sort combine with each mode’s native filters — they intersect, not substitute. For example siblings with since: "24h" returns adjacent chunks that were also created in the last 24 hours.

Common use case: “what’s new since my last session?” for agents reconnecting to a container after a gap.

Example call

After a wire_search call returns a chunk id, fetch surrounding context:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "entry_abc123", "mode": "siblings", "range": 3}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/navigate

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "wire_navigate", "arguments": { "from": "entry_abc123", "mode": "siblings", "range": 3 } }
}

Other modes follow the same shape — swap mode for source to read the full document, or relationships with type: "contradicts" to follow edges.

Return shape

Each result carries the same typed provenance object as a wire_search match (source, sourceFileId, chunkIndex, ingestedAt, tags, and more), so agents can reason about search results and navigate results the same way. In relationships mode, each result also carries edgeType, edgeDirection, and edgeProperties as described above.

`wire_write`

Save an entry to the container.

Parameter	Type	Required	Description
`content`	string or object	Yes	The entry content. Strings are stored as text. Objects are stored as structured data.
`tags`	string[]	No	Tags for categorization and filtering
`metadata`	object	No	Arbitrary key-value metadata
`source`	string	No	Where this entry came from. Defaults to `"agent:mcp"` for MCP calls and `"webhook:<api-key-name>"` for REST calls.

Example call

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Acme Corp wants to upgrade to Enterprise; needs SSO.", "tags": ["meeting", "acme-corp"]}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/write

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wire_write",
    "arguments": { "content": "Acme Corp wants to upgrade to Enterprise; needs SSO.", "tags": ["meeting", "acme-corp"] }
  }
}

Return shape

{
  "entryId": "entry_abc123",
  "workflowId": "wf_abc123",
  "message": "Entry queued for storage. It will be searchable within a few seconds."
}

entryId — the new entry’s uuid. Pass to wire_delete or wire_navigate later.
workflowId — id of the background write workflow (chunking, embedding, classification). Internal — agents don’t need to act on it.
message — human-readable status string.

`wire_delete`

Remove an entry by its ID.

Parameter	Type	Required	Description
`entryId`	string	Yes	The ID of the entry to delete

Example call

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entryId": "entry_abc123"}' \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/tools/delete

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "wire_delete", "arguments": { "entryId": "entry_abc123" } }
}

Return shape

{
  "entryId": "entry_abc123",
  "workflowId": "wf_abc123"
}

entryId — echoes the deleted id.
workflowId — id of the background delete workflow that cleans up derived chunks, embeddings, and relationship edges. Internal — agents don’t need to act on it.

`wire_claim`

Generate a claim link for an ephemeral container. Takes no parameters. Returns a URL that the user can open in a browser to sign up or log in and claim the container permanently.

Claim links are short-lived. Call wire_claim again to generate a new one if needed.

This tool only appears on ephemeral containers (created via instant onboarding). Once a container is claimed and belongs to a permanent organization, wire_claim is no longer listed.

Example call

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/claim

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "wire_claim", "arguments": {} }
}

Return shape

{
  "claim_url": "https://app.usewire.io/onboarding/create-account?claimToken=...",
  "expires_in": 3600
}

claim_url — open in a browser to sign up or log in and claim the container.
expires_in — seconds until the claim link expires. Call wire_claim again to get a fresh one.

`wire_status`

Container status snapshot: initialization state, paused flag, counts (tools, entries, entity types), analysis cadence. Useful for readiness checks before kicking off work.

Default visibility: REST on, MCP off. Invoke over REST as GET /container/:id/status (this is the only endpoint accessible on public containers without authentication).

Takes no parameters.

Example call

curl -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/status

Return shape

{
  "containerId": "abc123",
  "containerName": "My Container",
  "is_ephemeral": false,
  "initialized": true,
  "initializationStatus": "complete",
  "paused": false,
  "ready": true,
  "counts": {
    "tools": 9,
    "composites": 28,
    "entityTypes": 17,
    "entries": { "total": 7381, "eligible": 7102, "analyzed": 7044, "pending": 58 }
  },
  "analysis": { "inProgress": false, "cadence": "automatic" }
}

ready — true when the container is initialized, complete, and not paused. Use this as the gate before kicking off work.
initializationStatus — one of pending, analyzing, generating_tools, complete.
counts.entries.pending — eligible entries awaiting their first analysis pass. 0 means everything has been analyzed at least once.
analysis.cadence — automatic or manual per the container’s setting.

`wire_files_list`

List files uploaded to this container with their processing status.

Default visibility: REST on, MCP off. Invoke over REST as GET /container/:id/files.

Takes no parameters.

Example call

curl -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/files

Return shape

[
  {
    "id": "file_abc123",
    "name": "document.pdf",
    "size": 245760,
    "mimeType": "application/pdf",
    "uploadedAt": "2026-03-30T12:00:00Z",
    "createdAt": "2026-03-30T12:00:00Z"
  }
]

Array of file records. Pass id to wire_files_delete or to the wire:// URI scheme via MCP resources to download the original bytes.

`wire_files_upload`

Upload a file to this container. Wire processes it automatically into entries (chunks, extracted entities, embeddings) after upload.

Default visibility: REST on, MCP off. This tool only makes sense over REST since it uses multipart/form-data. Invoke as POST /container/:id/files with a multipart body containing a file field. See Supported File Types for accepted formats.

Parameter	Type	Required	Description
`file`	multipart file	Yes	The file to upload. Filename + content type are read from the part headers.

Example call

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@customers.csv" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/files

Return shape

{
  "id": "file_abc123",
  "name": "customers.csv",
  "size": 245760,
  "type": "text/csv",
  "uploadedAt": "2026-03-30T12:00:00Z",
  "processingStatus": "pending"
}

id — the new file’s id. Pass to wire_files_delete or to wire:// resource URIs.
processingStatus — pending immediately after upload. Background workflows extract entries; check wire_status or wire_files_list to watch progress.

`wire_files_delete`

Delete a file and all entries derived from it.

Default visibility: REST on, MCP off. Invoke over REST as DELETE /container/:id/files/:fileId.

Parameter	Type	Required	Description
`fileId`	string	Yes	The file ID returned by `wire_files_list`.

Example call

curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  https://YOUR_ORG_SLUG.api.usewire.io/container/YOUR_CONTAINER_ID/files/file_abc123

Return shape

{
  "message": "File deleted",
  "fileId": "file_abc123",
  "fileName": "document.pdf"
}

Deletion runs a background cleanup workflow that removes derived entries, embeddings, and R2 bytes. The response returns as soon as the metadata row is gone; the cleanup completes asynchronously.

Activating and deactivating tools

Every tool can be toggled independently per transport from the container’s Tools page in the dashboard. Three controls govern visibility:

Active / Inactive — global kill switch. Inactive tools are hidden everywhere.
MCP pill — when active, controls whether the tool appears in MCP tools/list and is callable via tools/call.
REST pill — when active, controls whether the underlying REST endpoint serves requests. A disabled REST tool returns 404 NOT_FOUND.

The defaults in the tool reference table at the top of this page are what new containers ship with. User toggles in the dashboard always win over the defaults and are preserved across container wakes.

Public container visibility

On public containers, unauthenticated visitors only see read-only tools: wire_explore, wire_search, and wire_navigate. Write and claim tools (wire_write, wire_delete, wire_claim) are hidden. wire_status is also reachable unauthenticated via its REST endpoint. Authenticated users see all tools regardless of container visibility.

Next Steps

Core Concepts - Learn about entries and containers
MCP Overview - How to connect and use tools
REST API - Transport details for invoking tools over HTTP