Cortex Agents and Snowflake CoWork: Runs proceed when some tools are inaccessible¶

Starting September 2, 2026, Cortex Agents and Snowflake CoWork no longer fail a run when the calling user’s role can’t access every tool configured on the agent. The run proceeds with the tools that role can access, and Snowflake reports each inaccessible tool as a warning. This applies wherever an agent runs: the Cortex Agents REST API, SQL, and conversations in Snowflake CoWork.

Behavior change¶

Before the change:

If the caller’s role was missing a privilege on any Cortex Search, Cortex Analyst, MCP, or skill tool in the agent specification, Snowflake rejected the whole request with an HTTP 4XX error at the first inaccessible tool. The agent returned no answer, even when the remaining tools could have answered the question.

After the change:

The request returns HTTP 200 and the agent answers with the tools the caller’s role can access. For each inaccessible tool the caller named in the specification, Snowflake emits a warning event on the response stream:

event: response.warning
data: {"code": "399569", "message": "TOOL_NOT_ACCESSIBLE: ..."}

Snowflake checks Cortex Search, Cortex Analyst, MCP, and skill tools at the start of the run. Other tool types, such as custom functions and stored procedures, are unchanged: a call fails at execution time, and the agent continues reasoning with that result.

Why Snowflake is making this change¶

• One agent can serve users with different privileges. A single missing grant no longer blocks the whole run, so you don’t have to maintain a separate agent for each privilege class.
• Partial answers instead of hard failures. Users get the best answer the agent can produce with the tools available to their role.

This change doesn’t alter Snowflake privileges or grant any additional access. A role still needs the same privileges to use a tool. Only the handling of a missing privilege changes.

Impact¶

This change affects Cortex Agents and Snowflake CoWork conversations whose callers don’t have privileges on every configured tool, and clients that treat an HTTP 4XX response as the signal that a user is missing a tool grant. Specifically:

• Agent runs that previously failed with an HTTP 4XX error now return HTTP 200 with one or more response.warning events, and an answer produced from a smaller set of tools.
• In Snowflake CoWork, a user whose role is missing a grant on one of the agent’s tools now receives a partial answer instead of an error for the whole conversation turn.
• Clients that surface tool-access problems to users by catching the HTTP error no longer see that error. They must read response.warning events with code 399569 instead.

Configuration¶

The new behavior corresponds to the accept value of the orchestration.tool_not_accessible field in the agent specification. After this change, accept is the default when the field isn’t set.

What you should do¶

No action is required if you want the new default behavior.

To keep today’s behavior for Cortex Agents or agents used in Snowflake CoWork, set the field on those agents before the rollout. You can make this change now.

1. Set the mode in the agent specification.

   Copy code

   orchestration:
     tool_not_accessible: legacy
   

   Use reject instead if you prefer a single error that lists every inaccessible tool.

2. Update versioned agents through a new version. This setting lives in the agent specification, and committed agent versions are immutable. If your callers target a committed named version rather than LIVE, editing the live version doesn’t change the behavior they get. Commit a new version and repoint the default version or the alias your callers use. Include your existing specification so the update doesn’t drop other settings.

   Copy code

   ALTER AGENT <agent_name> ADD LIVE VERSION FROM LAST;
   
   ALTER AGENT <agent_name> MODIFY LIVE VERSION SET SPECIFICATION =
   $$
   <existing agent specification>
   orchestration:
     tool_not_accessible: legacy
   $$;
   
   ALTER AGENT <agent_name> COMMIT COMMENT = 'Keep first-failure behavior';
   
   ALTER AGENT <agent_name> SET DEFAULT_VERSION = LAST;
   

   If your callers already target the LIVE version, updating the live version’s specification is enough.

3. Review client code that depends on the HTTP 4XX error. If your application tells users that they’re missing a tool grant, subscribe to response.warning and handle code 399569.

4. Confirm grants. Make sure your users’ default roles have the privileges for every tool you expect their agents to use. See Additional privileges for tools.

See also¶

• Inaccessible tool handling
• Access control and authentication
• Cortex Agent versioning
• Overview of Snowflake CoWork
• Behavior change policy
• Unbundled behavior changes

Ref: 2425