Skip to content

Tool registry

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

A tool is an executable capability with an input/output contract and side effects. Tools are registered, versioned and published like any other asset; they are executed only through the governed tool executor (GW-05), whatever transport delivered the request.

Descriptor

Field Meaning
Identifier, version Stable id; immutable published versions; schema version
Schema Input and output JSON schema; validated before execution and before downstream use
Description Model-facing description; must not grant authority by wording
Authorization requirements Scope, roles, connection and credential references; destination constraints
Secret dependencies Resolved by the secret broker as short-lived, scoped credentials; never in prompts, events or manifests
Timeout, retry policy, rate limits Declared per tool; retries only for operations whose side-effect semantics are known
Side-effect class READ_ONLY · REVERSIBLE_WRITE · IRREVERSIBLE_WRITE · PRODUCTION · FINANCIAL · SECURITY_SENSITIVE
Audit requirements What must be recorded for each invocation
Health Availability and degradation state exposed to the capability router

Categories (target)

Repository, files, Git, shell, database, browser, HTTP, cloud, Azure DevOps, GitHub, observability, messaging, email, documents, enterprise systems. Repository tools start read-only (list, search, read ranges, references, dependencies, diff, status) before any write tool (patch, create, delete, move, build, test) is admitted behind a sandbox (Execution plane).

The executor (GW-05)

flowchart LR
    A["Agent (any entry path)"] --> R["Tool request<br/>tool id + version + arguments + idempotency key"]
    R --> G["Governed executor"]
    G --> P["Policy decision<br/>(scope, side-effect class, budget)"]
    P -->|execute| X["Execution<br/>in-process · MCP · REST · sandbox"]
    P -->|confirm / approve| H["Approval bound to exact arguments"]
    P -->|prohibit| D["Denied with reason"]
    H --> X
    X --> S["Receipt<br/>result · effect identity · uncertainty · audit"]
Hold "Alt" / "Option" to enable pan & zoom

Receipts carry the tool version, argument hash, policy decision, effect identity where the target system provides one, and an explicit uncertain outcome when the reply is lost. Uncertain effects are reconciled, never blindly repeated.

Current implementation

  • ConnectSoft.Extensions.ModelContextProtocol: MCP hosting with optional authorization and Microsoft.AgentGovernance integration (policy paths, fail-closed, sanitization, audit). In the agent host the MCP endpoint is unauthenticated by default and governance identifies anonymous callers as did:mcp:server.
  • The agents framework registers explicit tools; no registry, descriptors, side-effect classes, executor, receipts or secret broker exist.
  • Vendor client libraries exist (ConnectSoft.Sms.*, ConnectSoft.*.ApiClient); none is registered as a tool.
  • The legacy Semantic Kernel plugin executes Git and dotnet processes unsandboxed; it is a source of behaviour to re-home, not a tool path to keep.