--- title: "Tool limits: Source, MCP, and Agent Identity boundaries" description: "This reference documents Tool count, size, and schema limits for Sources, MCP Connections, and Agent Identities." lang: en status: public-preview lastUpdated: 2026-11-09 url: https://dev.duale.ai/en/docs/tools/limits --- ## AI-generated summary 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 | ## 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. | **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](https://dev.duale.ai/en/docs/sdk/errors.md#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](https://dev.duale.ai/en/docs/tools/operations.md) 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 | 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](https://dev.duale.ai/en/docs/sdk/tools.md#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. | 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. ## Related content - [Create and manage MCP Connections](https://dev.duale.ai/en/docs/tools/mcp-connections.md) - [Operate Tools: catalog states and call outcomes](https://dev.duale.ai/en/docs/tools/operations.md) - [Tools: sources, Built-in Tools, and source selection](https://dev.duale.ai/en/docs/tools.md) - [Agent Tools: MCP servers, custom code, web research](https://dev.duale.ai/en/product/tools.md) - [MCP server compatibility and call contract](https://dev.duale.ai/en/docs/tools/reference.md) - [Library limits: size, ceilings, and windows](https://dev.duale.ai/en/docs/libraries/limits.md) --- ## Sitemap See the full [Markdown sitemap](https://dev.duale.ai/sitemap.md) for all pages.