Operate Tools: catalog states and call outcomes
Describes MCP catalog freshness states, model-facing Tool naming rules, and Tool Call outcome analytics for operating Duale AI Tools.
This page covers catalog freshness states, connection policy, model-facing Tool naming, call outcome analytics, and troubleshooting for MCP Connections.
- Catalog freshness states and connection policy.
- Changing MCP catalog behavior and incompatible Tools.
- Model-facing Tool naming and collision resolution.
- Tool Call outcomes, reliability metrics, and analytics categories.
- Troubleshooting an MCP Connection from visible symptoms.
Summaries were generated by AI.
Under Tools, Status and Catalog show whether an MCP Connection is enabled, whether its catalog is current, and which Tools Duale AI can offer. Analytics shows the recorded final outcomes of MCP and SDK Tool Calls. Neither view proves that a server is reachable now or that the next call will succeed.
The Tools reference owns MCP server compatibility and the call contract. Tool limits owns every catalog and call limit.
Follow a catalog through its freshness states
Connection policy is a separate setting. Blocking calls keeps catalog checks running; disabling the Connection stops them, as the diagram shows.
Connection policy
| State | What it means | What to do next |
|---|---|---|
| Enabled, allow calls | Catalog checks run and compatible Tools can be offered after a successful check | Inspect catalog freshness and test a low-risk call |
| Enabled, block calls | Catalog checks continue, but new MCP calls are blocked | Review the catalog or allow calls when ready |
| Disabled | Catalog checks and new MCP calls stop; configuration and assignments remain saved | Enable the Connection when you want checks to resume |
- State
- Enabled, allow calls
- What it means
- Catalog checks run and compatible Tools can be offered after a successful check
- What to do next
- Inspect catalog freshness and test a low-risk call
- State
- Enabled, block calls
- What it means
- Catalog checks continue, but new MCP calls are blocked
- What to do next
- Review the catalog or allow calls when ready
- State
- Disabled
- What it means
- Catalog checks and new MCP calls stop; configuration and assignments remain saved
- What to do next
- Enable the Connection when you want checks to resume
While the Dashboard fetches catalog status, it shows Loading. If that read fails, it shows Unavailable. Retry the read; this state does not prove that the remote MCP server is unavailable.
Catalog freshness
| State | What it means | What to do next |
|---|---|---|
| Not observed | No successful complete catalog check exists yet | Check the endpoint and remote credential; Duale AI keeps trying while enabled |
| Active | The latest successful complete catalog check is still fresh | Inspect Tool compatibility; this state does not run or verify a Tool |
| Expired | No successful catalog check refreshed the catalog for seven minutes | Check remote availability and access; expired Tools are not offered for new model turns |
| No Tools reported | A successful complete check returned an empty catalog | Confirm that the remote account is permitted to list Tools |
- State
- Not observed
- What it means
- No successful complete catalog check exists yet
- What to do next
- Check the endpoint and remote credential; Duale AI keeps trying while enabled
- State
- Active
- What it means
- The latest successful complete catalog check is still fresh
- What to do next
- Inspect Tool compatibility; this state does not run or verify a Tool
- State
- Expired
- What it means
- No successful catalog check refreshed the catalog for seven minutes
- What to do next
- Check remote availability and access; expired Tools are not offered for new model turns
- State
- No Tools reported
- What it means
- A successful complete check returned an empty catalog
- What to do next
- Confirm that the remote account is permitted to list Tools
While a Connection is enabled, Duale AI checks its catalog about every five minutes. After a failed check, it retries at growing intervals of up to about 15 minutes for as long as the Connection stays enabled. A failed check does not refresh an active catalog. Saving a change to the Connection starts a new check at once; after you fix the server itself, the next scheduled check refreshes the catalog.
These states show whether Duale AI has a recent successful catalog, not why a check failed. Not observed and Expired do not distinguish DNS, TLS, authentication, protocol, pagination, or limit failures.
Review a changing MCP catalog
An MCP server owns its catalog and can change it without a Duale AI release. After a successful complete check, the latest definitions replace the previous catalog.
Every compatible Tool added later becomes eligible for every assigned Agent Identity when calls are allowed. There is no per-Tool allowlist, exclusion, or catalog-version approval. If you need a controlled Tool lifecycle, publish the approved functions through an SDK Tool Host. Tool limits states how far a catalog can grow before a check or an Agent Identity reaches a limit.
The Catalog view keeps incompatible Tools visible with a reason, but does not offer them to a model. A Tool is incompatible when Duale AI cannot pass its input schema to a model, when it uses a reserved argument name, or when it declares a dynamic transport header that the server’s MCP revision cannot carry. Confirm MCP server compatibility names the revision that carries it.
Tool names, titles, descriptions, input-schema text, and server annotations are content you do not control. They can influence model Tool selection and proposed arguments. Annotations such as read-only, destructive, idempotent, or open-world are hints only. They never grant access or change call policy. The Task view separately estimates the impact of each call from its recorded definition and arguments. This is a per-call estimate, not a permanent category or a safety certification for the Tool. Read Effects explains the fields and how Duale AI estimates them.
Expired Tools remain visible with their last successful definitions and assignments, but they cannot be offered or called. They stay visible after checks stop because the Connection was disabled or deleted.
Understand model-facing Tool names
The Catalog view shows both the native Tool name reported by the server and the short model-facing name used during a
Task. A unique Tool normally starts with mcp_ followed by a readable form of its native name. SDK Tools start with
sdk_.
If two Tools would receive the same model-facing name, Duale AI qualifies every member of the collision with readable Source context. If that still collides, it adds a short stable suffix. It never merges Tools from different Sources, even when their schemas match, because those Sources can use different credentials and data.
For example, if CRM Production and CRM Sandbox both expose search_contacts, Duale AI qualifies both names,
such as mcp_crm_production_search_contacts and mcp_crm_sandbox_search_contacts. It does not leave one Tool as
mcp_search_contacts while renaming only the other, and it does not expose a Connection identifier to the model.
Duale AI computes names from the current catalog and does not reserve them permanently. A catalog change can therefore change a model-facing name before the next model turn. A Tool Call always reaches the Tool the model chose, even if a later catalog change renames it.
A name can stay qualified after the Tool it collided with expires, or after that Connection is disabled or deleted.
Read call outcomes and reliability
Analytics counts one final outcome for each Tool Call the model requested, except a Tool Call that a Duale AI safety check blocked: Duale AI never sends that call, so Analytics does not count it. It excludes catalog checks. The organization view provides an aggregate and breakdowns by Tool Source, model-facing Tool name, and Agent Identity.
Analytics uses the four Tool Call outcomes that Read a Tool Call outcome defines: Succeeded, Failed, Outcome unknown, and Blocked. For an MCP Tool, Blocked includes a call refused by Block calls and a call to a disabled Connection. A call to a deleted Connection ends as Failed. Analytics also shows four categories of its own:
| Category | Meaning |
|---|---|
| Denied | The current assignment or authorization prevented the call |
| Unsupported | The Tool or its returned result is outside the supported call contract |
| Cancelled before send | The call ended before the remote Tool started |
| Other | The recorded outcome is not one of the named categories |
- Category
- Denied
- Meaning
- The current assignment or authorization prevented the call
- Category
- Unsupported
- Meaning
- The Tool or its returned result is outside the supported call contract
- Category
- Cancelled before send
- Meaning
- The call ended before the remote Tool started
- Category
- Other
- Meaning
- The recorded outcome is not one of the named categories
Confirmed success rate is succeeded / (succeeded + failed), shown as a percentage rounded to two decimal places.
Every other outcome is outside that denominator. The Dashboard shows the rate only once the selected period holds
enough succeeded or failed calls; below that, it shows only the counts.
Tools Analytics are aggregate operational evidence. They do not show Tool arguments or results, prove the state of an external system, or replace a per-call business or audit record. Open the Task view for the retained input, result and Effect estimate of an individual call.
On an Executor page, the Success, 7 days column uses the same calculation for this Agent Identity and the exact Tool and Source. Its link opens Tools Analytics with that Agent Identity, Tool, Source and the same absolute period. Not available means the read did not provide a figure; it is different from No confirmed calls.
Evidence and audit explains which Platform records are available and what they cannot prove.
Troubleshoot an MCP Connection from the visible symptom
Start from the state or outcome that the Dashboard shows. Troubleshoot Tools gives the first check and the safe next action for each catalog state, call outcome, and temporary pause.