Declare the scope of a tool
PUT /api/mcp-connections/{connectionId}/tools/{toolName}/scope
Declares whose record a tool call touches. unscoped means the tool returns nothing anyone owns. At record level a caller acts on the records their own conversation created: a tool that creates a record names the response field carrying its id in originates, and a tool that acts on one names the argument carrying that id in refArgs; oHallo checks every reference before the call runs and the owner of every record the call returns. A declaration is validated against the tool’s classification and the connection’s other declarations, and every change publishes a connection version. Requires the mcp:write scope.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the MCP connection.
The name of the tool, as the MCP server reports it.
Request Body required
Section titled “Request Body required ”object
A scope declaration. At record level a caller acts on the records their own conversation created: a tool that creates a record names the response field carrying its id in originates, and a tool that acts on one names the argument carrying that id in refArgs. oHallo checks every refArgs value before the call runs and the ownerField of every record the call returns.
object
The unit of ownership. record: the records the caller’s own conversation created. customer: a verified customer’s own records. account: the records of the company the verified customer’s record names. customer and account need a customer lookup on the connection (customer_lookup_missing, customer_tie_lookup_missing, account_lookup_missing).
Every argument carrying a record reference. Each is checked against the records the caller holds. Empty for a tool that only creates.
Example
[ "quote_id"]The argument that receives the caller’s bound reference, for a tool the server filters by it. Absent for a tool addressed by a record’s own id.
The response path naming the record’s owner, or the record itself at record level, as dotted field names. A field inside a list is named through the list with [], as in orders[].customer_id, and oHallo reads it on every element; a path holds at most one [], never as its last segment, and no numeric index. Required unless originates is set at record level.
Example
quote_idThe response path naming the id of a record this call creates. Refused on a read or read_pii tool, when the path echoes an argument of the same tool, and when it names a field inside a list.
Example
quote_idAt customer and account level: the names of fields a returned record uses for another party, such as a recipient, or at account level the customer who placed an order. Each is one of the default owner names (customer_id, account_id, client_id, owner_id, buyer_id, in any spelling), never the name ownerField ends in, and a field of the tool’s declared output schema when it has one. oHallo then does not read that field as an owner. Refused at record level.
Example
[ "buyer_id"]Examples
A tool that creates a record
{ "scope": { "level": "record", "refArgs": [], "originates": "quote_id" }}A tool that acts on a record
{ "scope": { "level": "record", "refArgs": [ "quote_id" ], "ownerField": "quote_id" }}A tool that returns nothing anyone owns
{ "scope": "unscoped"}Responses
Section titled “ Responses ”The declaration, as it now stands.
object
A scope declaration. At record level a caller acts on the records their own conversation created: a tool that creates a record names the response field carrying its id in originates, and a tool that acts on one names the argument carrying that id in refArgs. oHallo checks every refArgs value before the call runs and the ownerField of every record the call returns.
object
The unit of ownership. record: the records the caller’s own conversation created. customer: a verified customer’s own records. account: the records of the company the verified customer’s record names. customer and account need a customer lookup on the connection (customer_lookup_missing, customer_tie_lookup_missing, account_lookup_missing).
Every argument carrying a record reference. Each is checked against the records the caller holds. Empty for a tool that only creates.
Example
[ "quote_id"]The argument that receives the caller’s bound reference, for a tool the server filters by it. Absent for a tool addressed by a record’s own id.
The response path naming the record’s owner, or the record itself at record level, as dotted field names. A field inside a list is named through the list with [], as in orders[].customer_id, and oHallo reads it on every element; a path holds at most one [], never as its last segment, and no numeric index. Required unless originates is set at record level.
Example
quote_idThe response path naming the id of a record this call creates. Refused on a read or read_pii tool, when the path echoes an argument of the same tool, and when it names a field inside a list.
Example
quote_idAt customer and account level: the names of fields a returned record uses for another party, such as a recipient, or at account level the customer who placed an order. Each is one of the default owner names (customer_id, account_id, client_id, owner_id, buyer_id, in any spelling), never the name ownerField ends in, and a field of the tool’s declared output schema when it has one. oHallo then does not read that field as an owner. Refused at record level.
Example
[ "buyer_id"]The caller may not change this connection. People need the owner or admin role. An API key needs the mcp:write scope; a key restricted to a brand or workspace receives code: "key_lock" for an action its restriction does not cover.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]No such connection, or it is outside the API key’s brand or workspace restriction, or the tool is not on the connection. A connection the key cannot reach is not disclosed.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]The declaration is refused. A shape error carries details. A rule refusal carries reason, one of: tool_unclassified (classify the tool first), originates_on_read (a read cannot create), originates_echoes_argument (the path names an argument of the same tool), originates_invalid (the originates path names a field inside a list), unscoped_needs_read (unscoped on a tool classified other than read), unscoped_on_lookup (unscoped on a tool a customer lookup on the connection uses), inject_arg_required (a tool classified write, write_pii or destructive at customer or account level names injectArg), owner_field_required (ownerField is set unless originates is, at record level), owner_field_invalid (an empty segment, a numeric index, a trailing [] or a second [] in ownerField), other_party_field_invalid (an otherPartyFields name that is no default owner name, or is the owner’s own), other_party_field_not_returned (an otherPartyFields name the declared output schema does not carry), other_party_fields_not_applicable (otherPartyFields at record level), ref_arg_without_producer (no tool on the connection originates that reference), ref_arg_unknown (a refArgs or injectArg entry is not an argument of the tool, or an injectArg is set on a tool that publishes no inputs), list_needs_inject_arg (a customer or account level ownerField names a list and no injectArg is set), ref_args_required (a record level tool that does not originate, and a customer or account level tool with no injectArg, names at least one reference argument), produced_argument_not_referenced (a write-class tool leaves an argument out of refArgs that a tool on the connection originates), originates_identifier_field (the originates path runs through a field designated on the connection as the eID reference or the national identity number), destructive_never_anonymous (the tool is destructive and its assurance setting is anonymous), national_id_field_in_scope (ownerField, injectArg or an otherPartyFields entry names the field designated on the connection as the national identity number), customer_lookup_missing (account, or customer on a tool at high-assurance or one classified write, write_pii or destructive, with no customer lookup on the connection that designates the customer reference with the eID reference or the national identity number on a tool classified read or read_pii), customer_tie_lookup_missing (customer on a tool classified read or read_pii at identified, with neither such a lookup nor one that designates the customer reference with the email field on a tool classified read or read_pii: the lookup by email address, which also designates the email argument, the tool’s own designation, or the one lookup the tool’s inputs reach, nor a lookup by phone number on such a tool, one that designates the customer reference with the phone argument and the phone field), account_lookup_missing (account with no such lookup that designates the company account number).
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]