Capability ids and naming

Discover the current identifier

Search starts from an outcome or query terms. It returns candidate capabilities from the active workspace catalog, a tool_turn_token, and top runnable contracts. When a candidate says fetched: true, the response already delivered that contract for this turn. Otherwise, get the chosen id before trying to execute it.

An exact get accepts an id and retrieves its contract even when a search ranking did not contain it. This is important because search is a ranking operation, not an exhaustive authorization decision. Get is the correct operation when a client has a current id from a prior documented result and needs to verify its schema again.

Scope a search when the outcome's pack is known. Architect and MCP use pack_id; REST and CLI use toolset for the same search boundary. Scope narrows discovery only. It does not grant permission, change a capability's action policy, or turn a skill instruction into an executable operation.

Use Packs to distinguish a workbook from a CRM record, a provider connection from a social outcome, or a suppression from an outreach cadence. Then use scoped discovery to obtain candidate ids. This prevents a shared word in a broad prompt from selecting a capability in an unrelated pack.

Read the contract attached to an id

An id is not enough to call an operation. The exact descriptor supplies the input schema, output schema, required scopes, pack id, action policy, cost policy, and asynchronous policy. Read those fields before a run because the identifier alone does not tell a caller whether the operation reads, writes a draft, sends, publishes, enrolls, activates, or starts an asynchronous job.

Capability input belongs in params when the run schema says so. Execution controls such as mode, max_credits, a quote binding, and the tool-turn token sit beside params in the execution envelope. Do not add an id suffix, an undocumented field, or a user value to an identifier in an attempt to reconstruct a capability schema.

The output schema is equally important. It tells a client which ids, status values, records, receipts, or run references it can safely read. A state-bearing result can also carry a web_url for its app location, but JSON ids remain the durable source of truth for later API calls.

Skills teach operational practice, but they do not grant authority and do not bind an id. Packs help a client route the outcome, but they do not create an id. Only the active catalog descriptor establishes a capability's executable identity and the rules for one particular run.

Run only a fetched id

Run requires the id, the exact parameter object, a required execution mode for mutations, and the current token that binds the delivered contract. The gateway refuses an id whose contract was not delivered in the current turn. This rule blocks a client from running a memorized identifier after its schema, policy, or workspace availability may have changed.

Use smoke_test for static schema and policy inspection without business writes or an audit entry. Use dry_run for real workspace-state validation without business writes, provider spend, or outward action. Use live only when the fetched contract permits the intended execution. The server returns mode_required rather than defaulting a mutation to live.

A live call that needs pricing returns quote_required. Repeat the same call with unchanged parameters and a max_credits ceiling. The quote binds to the tool turn, so a caller should not reuse a quote from another capability or alter the request in an attempt to accept the earlier estimate.

Root actions are a special security boundary. A capability that changes ownership, billing, credentials, integrations, API keys, webhooks, or other owner-controlled state requires a signed-in session, fresh approval at the applicable tier, and an idempotency key. Its id still comes from catalog discovery, but an API key alone cannot satisfy the owner-action path.

Search for the capability that lists available workspace integrations. Show the returned id, pack, action policy, input schema, and output schema. Do not run it until the fetched contract is visible.

Store evidence, not guessed ids

Store the search result, descriptor, returned id, tool-turn token, and result identifiers together in the operation record. Search explains why the candidate was selected, the descriptor explains the submitted fields and policy, and the result explains what actually happened. A bare id lacks this decision trail.

The CLI automatically obtains a fresh token through tools get when a caller runs a capability without --turn-token. CLI output omits a tool-turn token, which prevents a terminal response from being treated as a reusable contract. A direct API client should pass a token only from current discovery and should refresh discovery when a token is retired or the contract is uncertain.

For an asynchronous capability, preserve the returned run id and use the run controls to inspect state and events. Do not infer failure merely because the initial response is not terminal, and do not issue a second request with a different id while the original run is still the relevant source of truth.

A public marketplace profile, app label, or capability-like string is not a source of executable ids. Those surfaces can explain a domain, but the current catalog determines whether a workspace may discover and run the matching operation. Return to Integrations when connection readiness is the blocking condition.

When it goes wrong

capability_not_fetched means the gateway did not deliver the requested contract in the current turn. Search or get the id again, retain the returned token, and run the descriptor it supplied. Do not repair this refusal by copying an identifier from a different workspace, tool turn, or documentation page.

catalog_changed and tool_turn_expired retire the old token. Start a fresh search, then read the new descriptor before retrying. A stale token cannot be made current by changing its text or by resending it repeatedly, because the gateway will return the same retired-turn refusal.

invalid_request means the submitted input does not match the published schema. Use the error code, details, and fetched contract to correct fields. If a mutation returns mode_required, select one of the contract's supported modes; if it returns quote_required, preserve parameters and apply the intended credit ceiling.

If a scoped search finds no suitable id, confirm the pack boundary before broadening it. If an expected provider operation is missing, inspect provider readiness and rediscover after the connection is resolved. If a sender or recipient blocks delivery, repair sender policy or recipient data rather than searching for a different capability id to bypass the blocker.

If the client has lost the earlier schema, get the id again in a current turn. A capability id alone cannot reconstruct parameter names, defaults, effects, or result fields. The safety of the catalog flow comes from keeping the id attached to its actual contract until the run has a canonical result.

A current descriptor also identifies the active workspace boundary. Keep the workspace, capability id, and result id together when writing an audit record or handing work to another agent.

Do not use a search match as proof that an external effect completed. Search discovers a contract. Only a successful run envelope, its receipt, or its run status reports execution evidence.

The same rule applies to a description copied from a skill. A skill can name a recommended practice, but it cannot provide the current parameter list or replace the catalog's workspace-specific availability decision.

Read-only capabilities still benefit from discovery because their output schema determines the fields a client may safely use. An id is stable only as an identifier, never as a complete response contract.

Before a later run, refresh a descriptor when the previous response no longer provides its schema. This avoids executing with fields remembered from a contract that has since changed or left the current model context.

Discovery remains the source of executable identity.

Inspect the returned contract.