- Duale AI
- Documentation
- Tools
- Tool limits
Tool limits for SDK Tools, MCP Connections, and Tool Calls
Lists size, count, and rate limits for SDK Tools, MCP Connections, and Tool Calls, with the error each limit produces.
This page covers limits for publishing, declaring, and serving SDK Tools, configuring MCP Connections, serving MCP catalogs, and answering MCP Tool Calls.
- Tools per SDK Tool Host or MCP Connection.
- Declaring and serving SDK Tools with @tool.
- Returning SDK Tool Results within size limits.
- Configuring an MCP Connection with name, endpoint, and credential limits.
- Serving an MCP catalog and answering MCP Tool Calls.
Summaries were generated by AI.
Plan SDK Tools, MCP Connections, and Tool Calls within these limits. For the limits of a Built-in Tool, read its page from Built-in Tools.
How many Tools one source can publish
| Limit | Value | What happens | Your action |
|---|---|---|---|
| Tools per SDK Tool Host or MCP Connection | 4,096 | sdk.serve() raises TOO_MANY_TOOLS. An MCP catalog check fails. | Split the Tools. For SDK Tools, serve each part under its own Agent Identity. For an MCP server, list each part at its own endpoint or for its own remote account, with one Connection each. |
- Limit
- Tools per SDK Tool Host or MCP Connection
- Value
- 4,096
- What happens
sdk.serve()raisesTOO_MANY_TOOLS. An MCP catalog check fails.- Your action
- Split the Tools. For SDK Tools, serve each part under its own Agent Identity. For an MCP server, list each part at its own endpoint or for its own remote account, with one Connection each.
How many Tools one Agent Identity can hold
| Limit | Value | What happens | Your action |
|---|---|---|---|
| Tool definitions of one Agent Identity | Their total size, with the Task’s instruction and inputs, must fit the context window of a model in your pool | The Agent Identity’s Tasks fail with LLM_CONFIG_CONTEXT_TOO_SMALL. | Remove a Connection from the Agent Identity, serve fewer SDK Tools, or split the work across Agent Identities. |
| Description text the model reads | 1,024 characters, counted from the start of the name placed before the description, such as the Connection name | The model does not read the rest of the description. | Put what the Tool does and when to use it first. |
- Limit
- Tool definitions of one Agent Identity
- Value
- Their total size, with the Task’s instruction and inputs, must fit the context window of a model in your pool
- What happens
- The Agent Identity’s Tasks fail with
LLM_CONFIG_CONTEXT_TOO_SMALL. - Your action
- Remove a Connection from the Agent Identity, serve fewer SDK Tools, or split the work across Agent Identities.
- Limit
- Description text the model reads
- Value
- 1,024 characters, counted from the start of the name placed before the description, such as the Connection name
- What happens
- The model does not read the rest of the description.
- Your action
- Put what the Tool does and when to use it first.
The model finds a Tool among many by its name and description: What the model reads from a Tool explains how to write them.
To see the Tools that one Agent Identity has now, and those it lost recently, open it from the Agents list and select Tools.
Declare and serve SDK Tools
@tool checks each Tool when you declare it. sdk.serve() registers your Tools together: a registration that breaks a
limit fails entirely with one of the Tool Host errors, and the Tools from an
earlier registration stay offered.
| Limit | Value | What happens | Your action |
|---|---|---|---|
| Tool name | 1 to 64 ASCII letters, digits, underscores (_), or hyphens (-). The SDK uses the function name | @tool raises ValueError. | Rename the function. |
| Description | 1 to 1,024 characters, not only spaces | @tool raises ValueError. | Keep only what the model needs to choose the Tool. |
| Timeout | More than 0 and at most 3,600 seconds. A Tool Call also ends at the Task deadline when that comes first | @tool raises ValueError. | Set a timeout in this range. For longer work, start it and return an identifier that a later Tool Call can check. |
| Input schema of one Tool | 16 KiB | sdk.serve() raises TOOL_SCHEMA_TOO_LARGE. | Narrow the parameter model and shorten its field descriptions; they are for the model, not for your API reference. |
| Registration request | 4 MiB | sdk.serve() raises REQUEST_BODY_TOO_LARGE. | Shorten schemas and descriptions, or split the Tools across Tool Hosts under separate Agent Identities. |
| Reserved Tool names | The names that Duale AI reserves for its Built-in Tools | sdk.serve() raises RESERVED_TOOL_NAME. | Rename the Tool. |
| Tool Host requests | 12 registration, 12 heartbeat, and 12 deregistration requests in each 60-second window for one Agent Identity, shared by all its processes | sdk.serve() receives RATE_LIMIT_EXCEEDED and stops after repeated failures. Each running process sends about one heartbeat a minute, so about 12 processes reach the limit. | Serve the Agent Identity from fewer processes, start them a few at a time, or split them across Agent Identities. |
- Limit
- Tool name
- Value
- 1 to 64 ASCII letters, digits, underscores (
_), or hyphens (-). The SDK uses the function name - What happens
@toolraisesValueError.- Your action
- Rename the function.
- Limit
- Description
- Value
- 1 to 1,024 characters, not only spaces
- What happens
@toolraisesValueError.- Your action
- Keep only what the model needs to choose the Tool.
- Limit
- Timeout
- Value
- More than 0 and at most 3,600 seconds. A Tool Call also ends at the Task deadline when that comes first
- What happens
@toolraisesValueError.- Your action
- Set a
timeoutin this range. For longer work, start it and return an identifier that a later Tool Call can check.
- Limit
- Input schema of one Tool
- Value
- 16 KiB
- What happens
sdk.serve()raisesTOOL_SCHEMA_TOO_LARGE.- Your action
- Narrow the parameter model and shorten its field descriptions; they are for the model, not for your API reference.
- Limit
- Registration request
- Value
- 4 MiB
- What happens
sdk.serve()raisesREQUEST_BODY_TOO_LARGE.- Your action
- Shorten schemas and descriptions, or split the Tools across Tool Hosts under separate Agent Identities.
- Limit
- Reserved Tool names
- Value
- The names that Duale AI reserves for its Built-in Tools
- What happens
sdk.serve()raisesRESERVED_TOOL_NAME.- Your action
- Rename the Tool.
- Limit
- Tool Host requests
- Value
- 12 registration, 12 heartbeat, and 12 deregistration requests in each 60-second window for one Agent Identity, shared by all its processes
- What happens
sdk.serve()receivesRATE_LIMIT_EXCEEDEDand stops after repeated failures. Each running process sends about one heartbeat a minute, so about 12 processes reach the limit.- Your action
- Serve the Agent Identity from fewer processes, start them a few at a time, or split them across Agent Identities.
Return SDK Tool Results
Keep Tool Results far below these limits: Keep the Tool Result small explains what to return instead.
| Limit | Value | What happens | Your action |
|---|---|---|---|
| One Tool Result submission | 4 MiB | The submission fails with 413 REQUEST_BODY_TOO_LARGE. | Return identifiers, summaries, or the relevant rows. |
| One Tool Result in an accepted submission | 1,048,576 characters of output. An object output counts as its JSON text | That Tool Result reaches the model as a failure of its Tool Call. The other Tool Results of the submission are delivered. | Return identifiers, summaries, or the relevant rows. |
| Error text | 2,048 characters | The SDK cuts longer error text and ends it with an ellipsis (…). The model reads only that text. | Put the cause at the start of the exception message, or of the error_transform text. |
- Limit
- One Tool Result submission
- Value
- 4 MiB
- What happens
- The submission fails with
413REQUEST_BODY_TOO_LARGE. - Your action
- Return identifiers, summaries, or the relevant rows.
- Limit
- One Tool Result in an accepted submission
- Value
- 1,048,576 characters of output. An object output counts as its JSON text
- What happens
- That Tool Result reaches the model as a failure of its Tool Call. The other Tool Results of the submission are delivered.
- Your action
- Return identifiers, summaries, or the relevant rows.
- Limit
- Error text
- Value
- 2,048 characters
- What happens
- The SDK cuts longer error text and ends it with an ellipsis (
…). The model reads only that text. - Your action
- Put the cause at the start of the exception message, or of the
error_transformtext.
Configure an MCP Connection
| Limit | Value | What happens | Your action |
|---|---|---|---|
| Connection name | 1 to 100 characters, with no space at the start or end | Duale AI refuses to save the Connection. | Keep the name short: the model reads it before each Tool’s description, within the description text the model reads. |
| Endpoint URL | At most 2,048 characters | Duale AI refuses to save the Connection. | Use a shorter URL. |
| Bearer token or API key | 1 to 16,384 characters | Duale AI refuses to save the Connection. | Use a credential within this length. |
| API key header name | 1 to 128 characters: a letter, then letters, digits, or hyphens | Duale AI refuses to save the Connection. | Use a header name that meets this rule. Choose one authentication mode lists the names that Duale AI refuses. |
| Endpoint addresses | At most 16 IP addresses for the endpoint’s host name | Catalog checks fail, and calls fail before Duale AI sends them. | Point the host name to at most 16 addresses. |
| Agent Identities per Connection | 1,000 | Duale AI refuses the assignment. | Create another Connection to the same server for the other Agent Identities. |
- Limit
- Connection name
- Value
- 1 to 100 characters, with no space at the start or end
- What happens
- Duale AI refuses to save the Connection.
- Your action
- Keep the name short: the model reads it before each Tool’s description, within the description text the model reads.
- Limit
- Endpoint URL
- Value
- At most 2,048 characters
- What happens
- Duale AI refuses to save the Connection.
- Your action
- Use a shorter URL.
- Limit
- Bearer token or API key
- Value
- 1 to 16,384 characters
- What happens
- Duale AI refuses to save the Connection.
- Your action
- Use a credential within this length.
- Limit
- API key header name
- Value
- 1 to 128 characters: a letter, then letters, digits, or hyphens
- What happens
- Duale AI refuses to save the Connection.
- Your action
- Use a header name that meets this rule. Choose one authentication mode lists the names that Duale AI refuses.
- Limit
- Endpoint addresses
- Value
- At most 16 IP addresses for the endpoint’s host name
- What happens
- Catalog checks fail, and calls fail before Duale AI sends them.
- Your action
- Point the host name to at most 16 addresses.
- Limit
- Agent Identities per Connection
- Value
- 1,000
- What happens
- Duale AI refuses the assignment.
- Your action
- Create another Connection to the same server for the other Agent Identities.
Serve an MCP catalog
A catalog check that breaks a limit below fails, and the catalog soon becomes Expired. The Connection then offers no Tool until its catalog is back within the limits.
| Limit | Value | What happens | Your action |
|---|---|---|---|
| Complete catalog check | 30 seconds to list every page | The check fails. | Make tools/list answer faster. |
| Pages in one check | 128 tools/list pages | The check fails. | Return more Tools on each page. |
| Pagination | A nextCursor of at most 4,096 characters that never repeats, and each Tool name listed once | The check fails. | Return short cursors that move forward, and give each Tool a unique name. |
| Catalog size | 4 MiB of Tool definitions: names, titles, descriptions, schemas, and annotations | The check fails. | Shorten descriptions and schemas, or split the Tools across Connections. |
One tools/list response | 4 MiB, icons and _meta included | The check fails. | Return fewer Tools on each page, or smaller icons and _meta. |
| One Tool definition | 512 KiB | The check fails. | Shorten that Tool’s schemas and description. |
| One Tool’s name | 1 to 128 characters | The check fails. | Rename the Tool on the server. |
| One Tool’s title | 1 to 256 characters, also for annotations.title | The check fails. | Shorten the title. |
| One Tool’s description | At most 4,096 characters | The check fails. | Shorten the description. The model reads only the start of a description, so put what the Tool does and when to use it first. |
| One input or output schema | 64 levels of JSON nesting, 100,000 JSON values, and 256 top-level keywords | The check fails. | Flatten the schema, or split a large generated schema, such as one built from an OpenAPI document, across Tools. |
Answer MCP Tool Calls
When a call reaches a result or response limit, the server has already run the Tool, so any change it made stands.
| Limit | Value | What happens | Your action |
|---|---|---|---|
| Duration of one call | 5 minutes, or until the Task deadline when that comes first | A call that Duale AI has not sent yet ends as Cancelled before send. A sent call ends as Outcome unknown, and the server can still finish it. | For longer work, start it and return an identifier that a later Tool Call can check. |
| One Tool Result | 2 MiB of result JSON, text blocks and structuredContent together, in at most 32 text blocks of at most 1,048,576 characters each. One response is at most 4 MiB | The call ends as Failed, or as Outcome unknown when the response is larger than 4 MiB. | Return identifiers, summaries, or the relevant rows. |
| Top-level arguments in one call | 256 | The call does not reach the server. | Keep at most 256 top-level parameters in the Tool’s input schema. |
| Pause after technical failures | 3 technical failures of one Tool in a row pause its calls for 30 seconds | Calls to that Tool, from every Agent Identity on the Connection, end as Failed without reaching the server. A failed call after the pause starts a new pause. | Fix the cause on the server, as A Tool is temporarily paused describes. |
- Limit
- Duration of one call
- Value
- 5 minutes, or until the Task deadline when that comes first
- What happens
- A call that Duale AI has not sent yet ends as Cancelled before send. A sent call ends as Outcome unknown, and the server can still finish it.
- Your action
- For longer work, start it and return an identifier that a later Tool Call can check.
- Limit
- One Tool Result
- Value
- 2 MiB of result JSON, text blocks and
structuredContenttogether, in at most 32 text blocks of at most 1,048,576 characters each. One response is at most 4 MiB - What happens
- The call ends as Failed, or as Outcome unknown when the response is larger than 4 MiB.
- Your action
- Return identifiers, summaries, or the relevant rows.
- Limit
- Top-level arguments in one call
- Value
- 256
- What happens
- The call does not reach the server.
- Your action
- Keep at most 256 top-level parameters in the Tool’s input schema.
- Limit
- Pause after technical failures
- Value
- 3 technical failures of one Tool in a row pause its calls for 30 seconds
- What happens
- Calls to that Tool, from every Agent Identity on the Connection, end as Failed without reaching the server. A failed call after the pause starts a new pause.
- Your action
- Fix the cause on the server, as A Tool is temporarily paused describes.
Reserved argument names
Duale AI reserves every top-level argument name that starts with two underscores (__), in every SDK and MCP Tool.
Duale AI refuses only the Tool that uses a reserved argument name. The other Tools are offered as usual, and
sdk.serve() raises no error. Under Tools, Catalog marks the refused Tool Schema unsupported in the
Model compatibility column.
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; Catalog freshness states when the catalog shows the change.
Size your Tool for the call rate
These limits do not cap how often Tasks call a Tool, so size your Tool Host or MCP server for every Task that can run at once. Every Agent Identity assigned to an MCP Connection shares the quotas of its remote account. Understand the MCP call contract states how to report a rate limit.