Skip to content
How many Tools one source can publish
Public Preview

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

LimitValueWhat happensYour action
Tools per SDK Tool Host or MCP Connection4,096sdk.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() raises TOO_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

LimitValueWhat happensYour action
Tool definitions of one Agent IdentityTheir total size, with the Task’s instruction and inputs, must fit the context window of a model in your poolThe 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 reads1,024 characters, counted from the start of the name placed before the description, such as the Connection nameThe 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.

LimitValueWhat happensYour action
Tool name1 to 64 ASCII letters, digits, underscores (_), or hyphens (-). The SDK uses the function name@tool raises ValueError.Rename the function.
Description1 to 1,024 characters, not only spaces@tool raises ValueError.Keep only what the model needs to choose the Tool.
TimeoutMore 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 Tool16 KiBsdk.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 request4 MiBsdk.serve() raises REQUEST_BODY_TOO_LARGE.Shorten schemas and descriptions, or split the Tools across Tool Hosts under separate Agent Identities.
Reserved Tool namesThe names that Duale AI reserves for its Built-in Toolssdk.serve() raises RESERVED_TOOL_NAME.Rename the Tool.
Tool Host requests12 registration, 12 heartbeat, and 12 deregistration requests in each 60-second window for one Agent Identity, shared by all its processessdk.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
    @tool raises ValueError.
    Your action
    Rename the function.
  • Limit
    Description
    Value
    1 to 1,024 characters, not only spaces
    What happens
    @tool raises ValueError.
    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
    @tool raises ValueError.
    Your action
    Set a timeout in 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() raises TOOL_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() raises REQUEST_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() raises RESERVED_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() 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.
    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.

LimitValueWhat happensYour action
One Tool Result submission4 MiBThe submission fails with 413 REQUEST_BODY_TOO_LARGE.Return identifiers, summaries, or the relevant rows.
One Tool Result in an accepted submission1,048,576 characters of output. An object output counts as its JSON textThat 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 text2,048 charactersThe 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 413 REQUEST_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_transform text.

Configure an MCP Connection

LimitValueWhat happensYour action
Connection name1 to 100 characters, with no space at the start or endDuale 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 URLAt most 2,048 charactersDuale AI refuses to save the Connection.Use a shorter URL.
Bearer token or API key1 to 16,384 charactersDuale AI refuses to save the Connection.Use a credential within this length.
API key header name1 to 128 characters: a letter, then letters, digits, or hyphensDuale 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 addressesAt most 16 IP addresses for the endpoint’s host nameCatalog checks fail, and calls fail before Duale AI sends them.Point the host name to at most 16 addresses.
Agent Identities per Connection1,000Duale 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.

LimitValueWhat happensYour action
Complete catalog check30 seconds to list every pageThe check fails.Make tools/list answer faster.
Pages in one check128 tools/list pagesThe check fails.Return more Tools on each page.
PaginationA nextCursor of at most 4,096 characters that never repeats, and each Tool name listed onceThe check fails.Return short cursors that move forward, and give each Tool a unique name.
Catalog size4 MiB of Tool definitions: names, titles, descriptions, schemas, and annotationsThe check fails.Shorten descriptions and schemas, or split the Tools across Connections.
One tools/list response4 MiB, icons and _meta includedThe check fails.Return fewer Tools on each page, or smaller icons and _meta.
One Tool definition512 KiBThe check fails.Shorten that Tool’s schemas and description.
One Tool’s name1 to 128 charactersThe check fails.Rename the Tool on the server.
One Tool’s title1 to 256 characters, also for annotations.titleThe check fails.Shorten the title.
One Tool’s descriptionAt most 4,096 charactersThe 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 schema64 levels of JSON nesting, 100,000 JSON values, and 256 top-level keywordsThe 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.

LimitValueWhat happensYour action
Duration of one call5 minutes, or until the Task deadline when that comes firstA 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 Result2 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 MiBThe 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 call256The call does not reach the server.Keep at most 256 top-level parameters in the Tool’s input schema.
Pause after technical failures3 technical failures of one Tool in a row pause its calls for 30 secondsCalls 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 structuredContent together, 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.