Tools Experience
The Management Portal Tools experience is one surface for built-in and organization tool definitions, tool families, tool sets, and agent tool assignment. This page describes how the pieces fit together. For step-by-step tasks, see Tools and MCP Servers.
Navigation
| Location | Route | Contents |
|---|---|---|
| Agents > Tools | /tools |
Tool Library tab (tools grouped into family folders, family create/edit/delete) and Tool Sets tab |
| Agents > MCP Servers | /agents/mcp-servers |
API endpoint configurations with the MCP Server category |
| Agent editor Tools tab | /agents/edit/{agentName} |
Self-service tool set, Add Tool, and the agent's tool table |
Deep links: /tools?tab=library and /tools?tab=sets. The legacy /tools?tab=families link opens the Tool Library tab, where families now live. /tools/{toolName} redirects to /tools/{toolName}/edit.
Design principles
| Principle | Behavior |
|---|---|
| Copy, not link | Adding a library tool to an agent deep-copies it into the agent's tools. Later library edits do not change existing agents. |
| Endpoints as platform resources | MCP URLs, headers, and authentication live on MCP Server API endpoint configurations |
| One editor for all tools | Built-in and organization tools use the same cards and the same tool editor on the Tools page and in the agent editor |
| Families group tools | A family holds a display name, description, vendor icon, and its tool list. It has no endpoint or model settings. |
| Sets bundle tools | A set lists library tools with an optional agent tool name and an Initially ignored flag per tool |
Architecture
Tool Library (built-in + organization) ──deep copy──► agent.tools[]
│ │
Tool Families (grouping, icon) endpoint_object_id
Tool Sets (bundles) │
▼
MCP Server API endpoint configurations
Copied to agents: agent tool name, description, resource references (prompts, models, and other resources), properties, MCP tool name, arguments, and the input schema.
Referenced at runtime: endpoint_object_id, which points to the MCP Server API endpoint configuration (URL, headers, timeout, authentication).
Resources
The Agent resource provider (FoundationaLLM.Agent) exposes the experience as three resource types:
| Resource type | Contents |
|---|---|
tools |
Tool library entries: display name, description, origin (platform or organization), family_id, editor type, package and class name, resource references, property definitions, arguments, MCP settings |
toolFamilies |
Display name, description, vendor icon, and tool_names |
toolSets |
Display name, description, origin, and tools (each with tool_name, agent_tool_name, initially_ignored) |
MCP servers are apiEndpointConfigurations in the FoundationaLLM.Configuration provider with category set to MCPServer.
Platform catalog
Built-in tools, families, and sets ship in the foundationallm-platform-tools artifact package (packages/foundationallm-platform-tools/artifacts/):
| File | Contents |
|---|---|
tools.json |
Tool library entries, for example Platform-Tool-Code, Platform-Tool-Knowledge, Platform-Tool-MCPClient, Platform-Tool-Perplexity-Search, Platform-Tool-Gemini-Image-Generation, Platform-Tool-Gemini-Web-Grounding, Platform-Tool-GPT-Image-Generation, Platform-Tool-Claude-Agent |
tool_families.json |
Platform-ToolFamily-Basic (displayed as FoundationaLLM), -Perplexity, -Google-Gemini, -OpenAI-Image, -Anthropic, -Cursor, -Genesis, -Data |
tool_sets.json |
Platform-ToolSet-Perplexity-Essentials, Platform-ToolSet-SelfService (Agents Self-Service), Platform-ToolSet-Cursor-Essentials |
Resources created or updated by an artifact package cannot be deleted from the Management Portal, and their tool family is read-only in the tool editor.
Tool editor types
The library tool's editor type controls which editor sections appear.
| Editor type | Examples | Main sections |
|---|---|---|
| MCP Client | Perplexity, Cursor, Genesis, Data tools; organization MCP tools | Connection, Tool Selection and Configuration |
| Code Interpreter | Code, Programmable Tool Calling | Resource References, Settings |
| Knowledge | Knowledge | Resource References, Settings (query and filter editors) |
| Image generation | Gemini Image Generation, GPT Image Generation | Resource References |
| Generic | Gemini Web Grounding, custom package tools | Resource References, Settings |
| Claude Agent | Claude Agent | Claude Agent Configuration |
All types also show Basics and Content Safety (tool output shielding).
MCP connections
MCP tools connect in one of two ways:
| Mode | Stored on the tool | Notes |
|---|---|---|
| Registered endpoint (recommended) | Endpoint reference resolved to endpoint_object_id on save |
URL, headers, timeout, and authentication come from the MCP server |
| Inline URL | URL, transport, headers, and connection timeout | The URL must be reachable from the Management Portal backend for List Tools. Convert to registered endpoint stages a new MCP server that is created on save. |
At runtime the Python MCP Client tool uses the API endpoint when endpoint_object_id (or an mcp_server_endpoint resource reference) is present, and falls back to an inline URL only when no endpoint reference exists. MCP servers that use Azure Identity authentication are called with an Entra ID bearer token over the sessionless 2026-07-28 MCP protocol revision.
See also:
- MCP client runtime — Python plugin endpoint resolution and header tokens
- Using MCP Servers via the MCP Client Tool — Developer walkthrough
Legacy inline MCP URLs
Existing agents may still store inline streamable_http.url values. The portal parses them when the agent loads and keeps them as an inline configuration until you convert them. Migration scripts (preview and apply):
pwsh -File ./devtools/scripts/powershell/Report-AgentMcpInlineUrls.ps1
pwsh -File ./devtools/scripts/powershell/Migrate-AgentToolInlineMcp.ps1
pwsh -File ./devtools/scripts/powershell/Migrate-AgentToolInlineMcp.ps1 -Apply
Agent assignment
On the agent editor Tools tab:
- Self-service tool set links a tool set to the agent (
self_service_toolset_object_id). Self-service flows can enable or disable only tools from that set. Selecting a set does not add tools. - Add Tool opens the gallery: library folders with Select and Add to Agent, plus Copy from another agent and Add Tool Set under More options.
- The Tools available to the agent table lists Name, Type, and Actions (edit, remove).
- Edit Agent Tool uses the shared tool editor in agent mode. The Name field is the agent tool name; the Tool family field is hidden.
Saving an agent tool builds its input schema: from the Tool Arguments table for MCP tools, or from the tool class schema returned by the platform for other tools. Saving the agent persists the tool assignments.
Agent tool names must start with a letter, contain only letters, numbers, hyphens, and underscores, and be unique on the agent. end_conversation is reserved for realtime speech sessions.
Verification
Browser verifications under verifications/:
- V010 — Tools Experience UI
- V011 — Tools Experience integrated (Management API and agent save)
- V012 — Full library tool matrix (add, configure, persist, invoke)
- V013 — Create Tool custom package picker
- V015 — MCP tool argument descriptions from List Tools
- V018 — Memory MCP configuration with runtime context headers