Tool limits: Source, MCP, and Agent Identity boundaries
This reference documents Tool count, size, and schema limits for Sources, MCP Connections, and Agent Identities.
This page covers Tool publication limits per Source, MCP catalog and call limits, Agent Identity Tool bounds, and what these limits do not cover.
- Tool publication limits per Source and reserved argument names.
- MCP catalog check and Tool Call limits.
- Agent Identity Tool bounds and Source assignment.
- Guidance for assigning Tools to an Agent Identity.
- Limits not covered: call rates and remote server quotas.
Summaries were generated by AI.
One Source publishes up to 4,096 Tools. One Agent Identity holds every compatible Tool its Sources publish, up to a bound set by their total size rather than by a count. None of these limits is per seat or per plan.
These limits stop one Source from crowding out the rest. Some are part of the versioned API contract, and changing them breaks clients. Others are settings that a release can change.
| Class | Limits |
|---|---|
| Versioned API contract | SDK registration Tool count and size, the SDK input-schema ceiling, and the reserved argument names |
| Release setting | MCP catalog and call limits, and the bound on one Agent Identity’s Tools |
- Class
- Versioned API contract
- Limits
- SDK registration Tool count and size, the SDK input-schema ceiling, and the reserved argument names
- Class
- Release setting
- Limits
- MCP catalog and call limits, and the bound on one Agent Identity’s Tools
How many Tools one Source can publish
A Source is one SDK Tool Host or one named MCP Connection, and both carry the same Tool ceiling.
| Limit | Value | Your action |
|---|---|---|
| Tools per Source | 4,096 | Split a larger catalog across Sources. Two MCP Connections to the same server stay independent. |
| SDK registration size | 4 MiB per registration request | Large schemas and descriptions reach this size before the Tool count; shorten them or split the Tools across Tool Hosts. |
| One SDK Tool’s input schema | 16 KiB | Keep parameter descriptions short; they are for the model, not for your API reference. |
- Limit
- Tools per Source
- Value
- 4,096
- Your action
- Split a larger catalog across Sources. Two MCP Connections to the same server stay independent.
- Limit
- SDK registration size
- Value
- 4 MiB per registration request
- Your action
- Large schemas and descriptions reach this size before the Tool count; shorten them or split the Tools across Tool Hosts.
- Limit
- One SDK Tool’s input schema
- Value
- 16 KiB
- Your action
- Keep parameter descriptions short; they are for the model, not for your API reference.
A publication that breaks a limit fails as a whole and changes nothing. An SDK registration answers 422 with
TOO_MANY_TOOLS or TOOL_SCHEMA_TOO_LARGE, or 413 with REQUEST_BODY_TOO_LARGE when the request itself is too
large; Tool Host errors lists the codes. Tools already published stay offered
until the Tool Host stops sending heartbeats. An MCP catalog check that breaks a limit fails as a whole, keeps the
previous catalog, and shows the failure in the Connection’s catalog state rather than dropping Tools silently.
Operate Tools explains reading that state.
Reserved argument names
Duale AI reserves every top-level argument name that starts with two underscores (__). The rule applies to every SDK
and MCP Tool: to a name declared under properties in the input schema, and to a name listed in its required array.
Nested fields are unaffected, including fields whose names start with __.
A reserved name refuses only its Tool, not the publication. The Source’s other Tools publish as usual, and
sdk.serve() raises no error. The refused Tool stays in the catalog as incompatible, gets no model-facing name, and is
never offered to a model. Under Tools, Catalog marks it Schema unsupported in the Model compatibility
column, with a reason that states this rule without naming the argument.
To make the Tool available, rename the argument where the Tool is defined. For an SDK Tool, restart the Tool Host with the renamed parameter. For an MCP Tool, change the server; the next scheduled catalog check refreshes the catalog.
MCP catalog and call limits
These limits apply to every MCP Connection and are not configurable per Connection. A catalog can reach them before the Tool count limit.
| Boundary | Limit |
|---|---|
| Connection | 100-character name and 1,000 assigned Agent Identities |
| Complete catalog check | 30 seconds, 128 pages, 4,096 Tools, and 4 MiB of Tool definitions |
| One Tool definition | 512 KiB; 128-character native name; 4,096-character description |
| Tool JSON Schemas | 64 levels and 100,000 total JSON nodes across the input and optional output schemas |
| Tool Call arguments | 256 top-level properties |
| Remote response | 4 MiB as received from the server |
| Accepted Tool Result | 2 MiB; at most 32 text blocks, each at most 1,048,576 characters |
- Boundary
- Connection
- Limit
- 100-character name and 1,000 assigned Agent Identities
- Boundary
- Complete catalog check
- Limit
- 30 seconds, 128 pages, 4,096 Tools, and 4 MiB of Tool definitions
- Boundary
- One Tool definition
- Limit
- 512 KiB; 128-character native name; 4,096-character description
- Boundary
- Tool JSON Schemas
- Limit
- 64 levels and 100,000 total JSON nodes across the input and optional output schemas
- Boundary
- Tool Call arguments
- Limit
- 256 top-level properties
- Boundary
- Remote response
- Limit
- 4 MiB as received from the server
- Boundary
- Accepted Tool Result
- Limit
- 2 MiB; at most 32 text blocks, each at most 1,048,576 characters
If a catalog check exceeds a limit, the whole check fails and does not replace the active catalog. If a Tool Result exceeds a limit, Duale AI rejects that result.
SDK Tool Result size
One SDK Tool Result submission can be at most 4 MiB. A larger submission fails with 413 REQUEST_BODY_TOO_LARGE.
Inside an accepted submission, a Tool Result whose output, as the model reads it, is longer than 1,048,576 characters or
contains a NUL character, or whose error message contains a NUL character, reaches the model as a failure of that Tool
Call; the other Tool Results of the submission are delivered. Keep Tool Results far below that size: Keep the Tool Result
small explains what to return instead.
How many Tools one Agent Identity can hold
Nothing caps the Sources you assign to an Agent Identity. Its Tools are bounded by the total size of their definitions rather than by a count, and the instructions of each model turn count against the same total, so long instructions leave less room for Tools.
That bound is roughly 15,000 small Tools, 7,000 mid-sized ones, or 2,800 large ones. A small Tool takes three parameters and a short description; a large one takes ten parameters and a 1,000-character description. Treat these figures as a planning estimate, not a guarantee.
When an Agent Identity holds many Tools, the model sees a selection of them on each model turn and can search the others by name and description. Clear, distinct names and descriptions make a Tool easier to find.
| Limit | Value | Your action |
|---|---|---|
| Sources per Agent Identity | No ceiling | Assign by what the Agent Identity does, not by a count. |
| Tools per Agent Identity | Bounded by total definition size | Nothing to configure. Split across Agent Identities only past the bound. |
- Limit
- Sources per Agent Identity
- Value
- No ceiling
- Your action
- Assign by what the Agent Identity does, not by a count.
- Limit
- Tools per Agent Identity
- Value
- Bounded by total definition size
- Your action
- Nothing to configure. Split across Agent Identities only past the bound.
To see what one Agent Identity holds now and what it lost recently, open it in Agent settings and select Tools. The organization Tools page counts Tools per Source instead.
Past the bound, the Agent Identity’s Tasks stop progressing. They end with TASK_DEADLINE_EXCEEDED and no Tool
Call. Recognize it by that outcome on an Agent Identity whose assigned Tools grew. Remove a Source assignment to bring
the Agent Identity back under the bound.
Give an Agent Identity the Tools its job needs
Assign Tools for the Agent Identity’s work and use descriptions that distinguish similar operations. An available Tool is not guaranteed to be offered or requested on every model turn. Test representative Tasks to confirm that the intended Tools are used and that the results meet your requirements.
Split the work across Agent Identities when their jobs need unrelated systems.
What these limits do not cover
- Rate of calls. Nothing here limits how often an Agent Identity calls a Tool.
- The remote server’s own limits. An MCP server applies its own quotas to the access context your Connection uses, and Duale AI does not see them. A Tool that a server rate-limits fails as a Tool Result.