Set the assurance a tool requires
PUT /api/mcp-connections/{connectionId}/tools/{toolName}/assurance
Sets the assurance a caller must reach before this tool runs. The tool’s risk classification supplies the default (read is anonymous; read_pii, write and write_pii are identified; destructive is high-assurance); the setting may sit above or below it. Two rules hold whatever is sent: a destructive tool is never anonymous, and a setting below identified needs a declared scope. A tool declared at customer level requires at least identified: a setting of anonymous is kept, and the tool is enforced and reported at identified, with source read against the default (raised on a read tool, default on every other class). A setting below the default is a lowering: it is made on the dashboard, where an administrator acknowledges it with acknowledged: true, and the row shows Below default wherever the level enforced sits below the default. 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
Example
high-assuranceRequired when the setting is below the default for the tool’s risk classification; accepted from a dashboard session. An API key that sends it, or whose setting sits below the level the tool currently enforces, receives 403 with code: "key_lock".
Responses
Section titled “ Responses ”The tool, as it now stands.
The assurance a caller must reach before one tool runs, as it now stands.
object
The tool’s risk classification, which supplies the default.
The assurance a caller must reach before the tool runs.
The default for the tool’s risk classification.
Where requiredAssurance sits relative to defaultAssurance.
True when the tool returns personal data (read_pii).
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, and for a change to what oHallo configures on a system connection (its instructions, its tools’ risk classifications, or a version restore). Guardrails, per-tool assurance and agent assignments on a system connection are the account’s and stay open. A key sets a level at or above the level the tool currently enforces, whether or not the result is below the default; any relaxation is made on the dashboard. A key that lowers, or that sends acknowledged, receives code: "key_lock".
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 connection has no tool of that name. 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"]Validation error, or the setting is refused: the body carries reason. Reasons: tool_unclassified (the tool has no risk classification yet), destructive_never_anonymous, originates_on_read (a read or read_pii tool whose scope declaration names a record it creates), unscoped_needs_read (the tool is declared unscoped and is classified other than read), inject_arg_required (the tool is declared at customer or account level with no injectArg and is classified other than read or read_pii), lowered_below_identified_needs_scope (the setting sits below identified and the tool has no scope declaration), acknowledgement_required (the setting is below the default and the body did not acknowledge it).
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"]