Tools & permissions

Your client lists every available tool automatically (tools/list) with full input schemas, you rarely need to call one by name. This page is the map of what’s available, the scope each requires, and how calls are metered.

Every tool is org-scoped to your authenticated session. Org context comes from your token or API key, never from a tool argument, so an agent can’t read or change another organization’s data. Reference-data tools (offices, jurisdictions, classifications, rules) are global public data, not org-scoped, but still require a scope like other reads.

Search

Tool	What it does	Read/Write
`search_trademarks`	Search registrations from the offices `list_offices` returns (call it rather than assuming an office is covered). `q` ranks marks that resemble it, through the same `similarity` channels as REST. The `mark_text_` filters decide which marks qualify (`mark_text_starts_with`, `mark_text_contains` and four more, each with a `mark_text_not_` exclusion), so “marks starting with NOV in class 9” is one call with no `q`. Also takes `owner_id_not`, `entity_id_not`, `entity_group_not`, `trademark_ids_not`, `allow_partial`, and the owner, Nice class, jurisdiction, status, register (`register_type`) and opposition window filters (`opposition_status`, `opposition_closes_gte`, `opposition_closes_lte`). Date ranges use the `POST` shape, such as `filing_date: {"gte": "2024-01-01", "lt": "2025-01-01"}`, for every date filter REST has. `fields` and `include` project rows as on REST; `id` and `object` are always kept. Each row carries `match` (`tier`, `via`, `terms`). A trademark number in `q` returns that record. `query` is a deprecated alias of `q` until December 28, 2026. Parameters, limits and errors match Search Trademarks.	Read

Trademarks

Tool	What it does	Read/Write
`get_trademark`	Full detail for one mark by ID: owners, attorneys, classifications, media, the computed `derived` block, inline Madrid `coverage`, mark-to-mark `relationships`, and source `provenance`. Returns the REST detail shape and declares it as the tool’s output schema.	Read
`list_trademarks`	List marks with filtering and sorting (use `search_trademarks` for text search). Takes the same date ranges, `fields` and `include` as `search_trademarks`; a date range alone counts as a filter.	Read
`get_trademark_events`	Prosecution event timeline for a mark (filings, publications, registrations, status changes), as `trademark_event` rows with the office code and label in `raw`.	Read
`get_trademark_proceedings`	Proceedings involving a mark (oppositions, cancellations), each with its parties.	Read
`batch_get_trademarks`	Fetch full detail for up to 100 marks by ID in one call, in input order (a repeated ID repeats), with a `not_found` list for anything that didn’t match.	Read

Owners & entities

Tool	What it does	Read/Write
`get_owner`	Owner (applicant/registrant) detail with portfolio statistics.	Read
`list_owners`	Search and list owners, find companies or individuals who hold marks.	Read
`get_owner_trademarks`	An owner’s trademarks (summary tier) with filtering and sorting. Takes the same `q`, `similarity`, `mark_text_*` and exclusion keys as `search_trademarks`, as do the attorney, firm and entity trademark tools.	Read
`get_owner_related`	Owners related via the GLEIF corporate hierarchy (parent/child).	Read
`get_entity`	A resolved entity: the cross-office identity over per-office owner clusters, with link evidence and public-company facts. An owner ID written in entity form (`ent_<owner-uuid>`) is not found; use `get_owner`.	Read
`list_entities`	Search resolved entities (one company across all offices), filterable by public-company facts.	Read
`get_entity_trademarks`	A resolved entity’s trademarks across every office it is linked in (the same scope as the `entity_id` search filter).	Read
`get_entity_family`	A resolved entity’s direct GLEIF corporate family (parent and direct subsidiaries).	Read

Attorneys & firms

Tool	What it does	Read/Write
`get_attorney`	Detail for an attorney or representative of record.	Read
`list_attorneys`	Search and list attorneys and representatives.	Read
`get_attorney_trademarks`	An attorney’s trademarks (summary tier) with filtering and sorting.	Read
`get_attorney_clients`	Owners an attorney represents, each with a shared-mark count.	Read
`get_firm`	Law-firm detail, including portfolio and attorneys.	Read
`list_firms`	Search and list law firms, ranked by portfolio size or attorney count.	Read
`get_firm_attorneys`	A firm’s attorneys, each with portfolio stats.	Read
`get_firm_trademarks`	Trademarks handled by a firm’s attorneys (summary tier).	Read

Proceedings

Tool	What it does	Read/Write
`get_proceeding`	Detail for one proceeding (opposition, cancellation, etc.) by ID (e.g. `prc_8kLm2nPq`).	Read
`list_proceedings`	List TTAB oppositions, cancellations, and other proceedings with filtering. Proceedings are served only for offices whose `capabilities.proceedings` (from `list_offices`) is `available`; any other live `office_code` returns a `capability_not_available` error, charged 0 credits. A `proceeding_type` no served office records (such as `court_action`) returns an empty page. `party_owner_id` (`own_...`) and `party_entity_id` (`ent_...`, alias `entity_id`) return proceedings where a party is linked to that owner or to a member owner of that entity, as on `GET /v1/proceedings`: a malformed ID returns `validation_error`, an entity over the member-owner cap returns `entity_too_large`, and an unknown entity returns an empty page. Parties without an owner link are not matched.	Read

Reference data

Global, public reference data. Not org-scoped, but still requires a read scope. Office, jurisdiction, event-type and status-code tools are logged but free. Classification, goods and services, and design code lookups cost 1 credit per call; the deadline and opposition rule catalogues cost 10. Suggestions, drafting, and validation are priced separately; see Metering.

Tool	What it does	Read/Write
`list_offices`	Supported trademark offices, with jurisdiction coverage.	Read
`get_office`	A single office by its uppercase ST.3 office code (e.g. `US`, `EM`, `WO`); legacy lowercase codes are accepted as aliases.	Read
`list_jurisdictions`	Supported jurisdictions (ISO-2 plus regional/WIPO codes), with Madrid membership and live-office coverage.	Read
`get_jurisdiction`	A single jurisdiction by code, including Madrid membership and member jurisdictions.	Read
`get_deadline_rules`	Maintenance/renewal deadline rules with statutory citations; optionally per jurisdiction.	Read
`get_opposition_rules`	Opposition window rules with citations, duration, and time zone; optionally per jurisdiction.	Read
`list_classifications`	Nice classification classes (the 45-class WIPO standard), filterable by category or keyword.	Read
`suggest_classifications`	Suggest Nice classes for a natural-language description, ranked with confidence and rationale.	Read
`list_goods_services`	Browse/search the curated goods & services term catalog.	Read
`suggest_goods_services`	Draft filing-ready goods/services wording per Nice class from a description.	Read
`list_design_codes`	Vienna classification design codes (figurative-element taxonomy for logos/devices).	Read
`get_design_code`	A single Vienna design code with notes and its child codes.	Read
`list_event_types`	Per-office event codes mapped to Signa’s canonical event types (US, AU and WO catalogued today).	Read
`list_status_codes`	Per-office status codes with the office’s verbatim label and the normalised status they map to; decodes `status.raw.code`. Mirrors `GET /v1/status-codes`.	Read

Account & usage

Utility tools for your own org’s account and consumption. Neither billed nor counted against quota.

Tool	What it does	Read/Write
`get_credit_pricing`	Published credit prices by action, quantity unit, availability, and schedule version. Needs no scope.	Read
`get_usage`	Current billing-period credit usage per endpoint type plus the per-minute rate-limit matrix.	Read
`get_usage_summary`	Daily usage breakdown (requests, credits charged, errors, average latency).	Read
`get_account`	Org identity (ID, name, plan, key scopes and rate-limit tier) with the plan quota breakdown. Every key gets identity; the quota breakdown needs `billing:read` and is `null` without it.	Read

Monitoring

Watches, alerts, and webhooks. Billed at zero request-level cost; watch capacity itself is capped by your plan.

Tool	What it does	Read/Write
`signa_watches_list`	List monitoring watches for your org (cursor-paginated).	Read
`signa_watches_retrieve`	Retrieve a single watch by ID.	Read
`signa_watches_create`	Create a watch (same validation as `POST /v1/watches`). A similarity watch takes `version: "v3"`, `q`, `similarity` and `min_tier`. Every written query is stored as `v3` (a plain `q` gets the default channels and `min_tier: "related"`); old `strategies` and `min_match_tier` keep a legacy watch until it is re-saved without them, and are reported in `deprecations`.	Write
`signa_watches_update`	Update a watch (PATCH semantics, omitted fields unchanged).	Write
`signa_watches_delete`	Deactivate a watch (soft-delete).	Write
`pause_watch`	Pause a watch (stops new alerts).	Write
`resume_watch`	Resume a paused watch.	Write
`preview_watch`	Dry-run a watch query: estimate matches and preview marks, with `similarity_applied` and `min_tier`. No watch is created.	Read
`get_watch_diagnostics`	Audit-mode provenance trace for one (watch, trademark) pair.	Read
`signa_alerts_list`	List monitoring alerts for your org.	Read
`signa_alerts_retrieve`	Retrieve a single alert by ID.	Read
`list_alerts_for_watch`	List alerts emitted by a single watch (cursor-paginated).	Read
`lookup_alert`	Bulk-fetch up to 100 alerts by ID (polling pattern).	Read
`signa_events_list`	List your org’s event ledger (beta). Supports `sort=id` + `after` replay from a checkpoint.	Read
`signa_webhooks_list`	List webhook endpoints (secrets are never returned).	Read
`signa_webhooks_retrieve`	Retrieve one webhook endpoint (secret redacted).	Read

Webhook secrets are never exposed through MCP, signa_webhooks_list and signa_webhooks_retrieve always redact them. Manage secrets via the REST API instead.

Scopes

Any valid API key or OAuth token can connect, whatever its scopes. initialize and tools/list work for every session, and tools/list returns every tool, including ones the session can’t call. Each tool checks its own scope when called, the same scope as its REST endpoint. An invalid, revoked or expired credential gets 401 before any tool runs.

Scope	Grants access to
Any scope, or none	`get_credit_pricing` and `get_account` (identity).
`trademarks:read`	Every search, trademark, owner, entity, attorney, firm, proceeding, and reference-data tool above.
`billing:read`	Usage tools (`get_usage`, `get_usage_summary`, `get_usage_estimate`) and the plan block of `get_account`.
`portfolios:manage`	Every monitoring tool, reads and writes alike: watches, alerts, and webhooks.
`events:read`	`signa_events_list`, your org’s event ledger.
`offline_access`	Keeps an OAuth session’s token refreshing silently. Doesn’t grant tool access on its own.

Most clients request trademarks:read by default, which covers every data and reference tool. Add billing:read if you want your agent to inspect usage and account details, and portfolios:manage only if you want it to read or change watches, alerts, and webhooks. If a tool needs a scope your session lacks, the call returns the forbidden error REST returns (status 403, naming the required scope) with the call’s request_id. It is not charged, and the rest of the session keeps working.

Metering

MCP tool calls are metered like REST requests: a tool call costs what its REST counterpart costs, debits the same pooled credit balance, and appears in your usage and request logs under the same endpoint type (search, read, monitoring, and so on). Search tools (search_trademarks, list_trademarks, list_owners, list_attorneys, list_firms, list_entities, get_entity_trademarks) cost 10 credits per call, one page each. Read tools cost 1 credit per record or page; batch_get_trademarks costs 1 credit per submitted ID (up to 100), including IDs that are not found. suggest_classifications costs 10 credits per call, suggest_goods_services 100, and validate_goods_services 50. Classification, goods and services, and design code lookups cost 1 credit; the deadline and opposition rule catalogues cost 10. Office, jurisdiction, event-type and status-code tools are logged but free. Account, usage, and pricing tools are neither billed nor counted. Every tool result reports the actual debit as _meta.credits_charged. Out-of-credit calls return a clear error naming the limit that was hit and when it resets, instead of running the tool. The initialize and tools/list handshake calls are never metered. Prices are published by Get Credit Pricing.

Errors

A tool that fails returns isError: true and one text item holding the same JSON error body the REST API returns, plus the MCP request’s request_id:

{
  "error": {
    "type": "timeout",
    "title": "Query Timeout",
    "status": 504,
    "detail": "The request took too long to process. Please retry or narrow your filters.",
    "retryable": true,
    "retry_after": 1
  },
  "request_id": "req_..."
}

Branch on error.type and error.retryable, not on detail wording. Field-level problems list errors[] entries with field, code, and message, as in Errors. The types an agent sees most often:

Status	Type	Description
400	`validation_error`	An argument is missing, has the wrong type, is outside its allowed values (an unknown `status` or jurisdiction code included), or is malformed. `errors[]` names each field. A malformed ID has the title `Invalid ID`. A list tool called with no filter, or only blank ones, returns this too. Fix the arguments before retrying.
400	`cursor_expired`	The `cursor` is empty, garbled, or no longer valid. Restart without a cursor.
400	`cursor_invalid`	The `cursor` was issued for different filters or a different sort. Restart without a cursor.
404	`not_found`	The resource does not exist or is not visible to your organization, or the tool name is unknown.
500	`internal_error`	An unexpected failure on our side. Retry with backoff.
503	`service_unavailable`	The database or search cluster is temporarily unavailable or overloaded, or a search timed out on the search and list tools. Retry after `retry_after` seconds.
504	`timeout`	A database or search query ran out of time. Retry, or narrow the filters.
504	`preview_timeout`	`preview_watch` ran out of its time budget. Narrow the watch query; a plain retry fails the same way.

Server-side failures carry a reference_id next to type; include it, or the request_id, if you report a problem. Error bodies never contain database or search-engine messages. A request the MCP transport cannot read (a body that is not valid JSON or not a JSON-RPC 2.0 message, or a batch over the cap) fails before any tool runs. It returns a JSON-RPC error with the HTTP status and error.code (-32700 or -32600), a fixed message, and the request id in error.data.request_id. A JSON-RPC request whose method parameters are malformed (for example tools/call with a non-string name) gets the same treatment with HTTP 200 and its JSON-RPC code. Scope, quota, and credit refusals use the REST types too (unauthorized, forbidden, quota_exceeded, insufficient_credits, daily_credit_cap_exceeded, plan_gated, credits_unavailable). A failed call is never charged: _meta.credits_charged is 0. Pagination cursors are bound to the request that produced them. On list_proceedings (and GET /v1/proceedings), reusing a cursor with different filters or a different sort returns cursor_invalid, and an empty cursor string is rejected rather than read as “first page”. Omit cursor to start from the first page.

Rate limits

MCP requests share a dedicated rate-limit tier of 1,000 requests per minute, separate from your plan’s per-endpoint-type limits. See Rate limits for the full header semantics. If you hit the limit, the response includes a Retry-After header. One POST may carry a JSON-RPC batch of up to 10 messages; a larger batch is rejected with JSON-RPC error -32600 before any tool runs. Search tools with mark_text_contains, mark_text_ends_with or a wildcard-leading mark_text_pattern also draw on your organization’s search concurrency, shared with REST: one slot per such value.

Security

Org isolation. Org context is resolved from your token or API key on every request, never from a tool argument. An agent cannot read or modify another organization’s data, even if prompted to.
Least privilege. Scopes are enforced per tool. For read-only use, issue an API key without portfolios:manage so the watch, alert, and webhook write tools are unavailable.
Review tool calls. Most MCP clients let you approve tool calls before they run. Keep approval on for any agent with portfolios:manage, and treat tool results as data an untrusted prompt could try to act on.

Troubleshooting

401: Missing Authorization header

Your MCP client is not sending the access token. Re-authenticate by removing and re-adding the MCP connection.

401: Access token missing org_id claim

Your Signa account has not completed onboarding. Log in at app.signa.so and create an organization first.

401: Invalid or expired access token

Your token has expired. Most MCP clients handle refresh automatically. If the error persists, remove and re-add the connection to re-authenticate.

429: Rate limited

You are sending more than 1,000 MCP requests per minute. Wait for the Retry-After period or reduce request frequency.

Getting started

Core concepts

Build with AI

Data

Monitoring

Working with the API

Use cases

Search

Trademarks

Owners & entities

Attorneys & firms

Proceedings

Reference data

Account & usage

Monitoring

Scopes

Metering

Errors

Rate limits

Security

Troubleshooting

​Search

​Trademarks

​Owners & entities

​Attorneys & firms

​Proceedings

​Reference data

​Account & usage

​Monitoring

​Scopes

​Metering

​Errors

​Rate limits

​Security

​Troubleshooting

Search

Trademarks

Owners & entities

Attorneys & firms

Proceedings

Reference data

Account & usage

Monitoring

Scopes

Metering

Errors

Rate limits

Security

Troubleshooting