---
slug: "ToolDiscovery"
name: "ToolDiscovery"
type: "Protocols"
layer: "Society"
ref: "ToolDiscovery#b165"
sema_id: "sema:ToolDiscovery#mh:SHA-256:b1659e870015d2d6e37842f31a0bc1cc2d2d2882aaf6d0bc3b6b1236885890d7"
tags: ["Society","Protocols"]
updated: 2026-11-11
mindscape: "bootstrap"
index_url: https://mindscape.pages.dev/bootstrap/index.json
url: https://mindscape.pages.dev/bootstrap/ToolDiscovery/
related: ["CompatibilityCheck","FailClosed","ToolInvoke","Agent","Card","ContextFirst","Discover","Task","Result","AgentDiscover"]
---

# ToolDiscovery

Discover and invoke external tools via structured capability manifests

Layer: Society · Category: Protocols

## Mechanism

[Agent](https://mindscape.pages.dev/bootstrap/Agent.md) queries a [Discover](https://mindscape.pages.dev/bootstrap/Discover.md) for capabilities matching its current [Task](https://mindscape.pages.dev/bootstrap/Task.md). Registry returns a [Card](https://mindscape.pages.dev/bootstrap/Card.md) listing available tools with typed input/output schemas. [Agent](https://mindscape.pages.dev/bootstrap/Agent.md) selects the best match, performs a [CompatibilityCheck](https://mindscape.pages.dev/bootstrap/CompatibilityCheck.md) to verify schema alignment, then invokes via [ToolInvoke](https://mindscape.pages.dev/bootstrap/ToolInvoke.md) and observes the typed [Result](https://mindscape.pages.dev/bootstrap/Result.md). If no match is found or [CompatibilityCheck](https://mindscape.pages.dev/bootstrap/CompatibilityCheck.md) fails, the agent must [FailClosed](https://mindscape.pages.dev/bootstrap/FailClosed.md) rather than attempt a best-effort invocation. Follows the Model Context Protocol pattern of progressive discovery under [ContextFirst](https://mindscape.pages.dev/bootstrap/ContextFirst.md) discipline: orient via registry, explore via schema matching, verify via hash comparison.

## Invariants

- Schema Verification: Tool manifest hash must be verified via [CompatibilityCheck](https://mindscape.pages.dev/bootstrap/CompatibilityCheck.md) before invocation
- Fail-Closed: On schema mismatch or missing tool, reject via [FailClosed](https://mindscape.pages.dev/bootstrap/FailClosed.md) rather than attempt best-effort
- Tool output must conform to declared schema in the [Card](https://mindscape.pages.dev/bootstrap/Card.md)

## Preconditions

- [Discover](https://mindscape.pages.dev/bootstrap/Discover.md) accessible
- [Task](https://mindscape.pages.dev/bootstrap/Task.md) specifies required capability type

## Postconditions

- [Result](https://mindscape.pages.dev/bootstrap/Result.md) returned conforming to tool's declared output schema
- Invocation logged with tool identity and schema hash

## Failure modes

- Registry unavailable (no tools discoverable — must degrade gracefully).
- Schema drift (tool updated its manifest but [Agent](https://mindscape.pages.dev/bootstrap/Agent.md) cached old version).
- Capability hallucination (tool claims capability it cannot deliver).

## Signature

- `Discover(ToolInvoke)`

## Builds on

- [CompatibilityCheck](https://mindscape.pages.dev/bootstrap/CompatibilityCheck.md) (Infrastructure; Composes with)
- [FailClosed](https://mindscape.pages.dev/bootstrap/FailClosed.md) (Infrastructure; Composes with)
- [ToolInvoke](https://mindscape.pages.dev/bootstrap/ToolInvoke.md) (Infrastructure; Composes with)
- [Agent](https://mindscape.pages.dev/bootstrap/Agent.md) (Mind; References)
- [Card](https://mindscape.pages.dev/bootstrap/Card.md) (Infrastructure; References)
- [ContextFirst](https://mindscape.pages.dev/bootstrap/ContextFirst.md) (Mind; References)
- [Discover](https://mindscape.pages.dev/bootstrap/Discover.md) (Society; References)
- [Task](https://mindscape.pages.dev/bootstrap/Task.md) (Infrastructure; References)
- [Result](https://mindscape.pages.dev/bootstrap/Result.md) (Infrastructure; Yields)

## Used by

—

## Identity

- Sema ID: `sema:ToolDiscovery#mh:SHA-256:b1659e870015d2d6e37842f31a0bc1cc2d2d2882aaf6d0bc3b6b1236885890d7`
- Ref: `ToolDiscovery#b165`
- Supersedes:
  - `sema:ToolDiscovery#mh:SHA-256:548fb253447d270bee9b28ee7fe125135ce45ab54fbd2744fcc70e6b7d9b6de8`
  - `sema:ToolDiscovery#mh:SHA-256:0ff16794954587c168bc694f00a723973be11ddfeb3a15c73770ab660bd439d8`
  - `sema:ToolDiscovery#mh:SHA-256:bf677acdeda8699deafb4398efa1f605dea89de112873e9a7bb838a41adbffd6`
  - `sema:ToolDiscovery#mh:SHA-256:4b608d9d78051bf0f7bd10120d145dd6664c416fc0c52969156f9a31d171d45b`
  - `sema:ToolDiscovery#mh:SHA-256:c3c879478898d130c1f92f782dd17955e1dd1195638b188e3d7044428e64bb1b`
  - `sema:ToolDiscovery#mh:SHA-256:8d8071355a00e6bf7cf3b0d6bd509d83a2501c6a06923ce6dd6e6cf50f41918e`

## Links

- [Pattern page](https://mindscape.pages.dev/bootstrap/ToolDiscovery/)
- [View in the interactive graph](https://mindscape.pages.dev/bootstrap/#ToolDiscovery)
- [JSON](https://mindscape.pages.dev/bootstrap/ToolDiscovery.json)
- [Index of all patterns](https://mindscape.pages.dev/bootstrap/index.json)