Skip to main content

Shared Platform Tools

Base tool registry​

apps/runtime/src/mastra-runtime.ts creates the target-specific base registry after artifact composition. These tools are separate from admin tools and from domain-owned K12, SDAC, TAP, and Handbook tools.

Runtime registry keyMastra tool IDTargetsSource
base-tavily-searchbase-tavily-searchall targetssrc/mastra/tools/base/tavily-search.tool.ts
base-perplexity-searchperplexity-searchall targetssrc/mastra/tools/base/perplexity-search.tool.ts
base-embeddingbase-embeddingall targetssrc/mastra/tools/base/embedding.tool.ts
base-embedding-batchbase-embedding-batchall targetssrc/mastra/tools/base/embedding.tool.ts
base-cosmos-vector-searchbase-cosmos-vector-searchtap, allsrc/mastra/tools/base/cosmos-vector-search.tool.ts
azure-content-safetyazure-content-safetyk12, tap, allsrc/mastra/tools/azure-content-safety.ts

The Perplexity registry key intentionally retains the base- namespace while the tool object's ID is perplexity-search. Use live /tools.json discovery or the generated tool contract when forming generic execution requests.

Search tools​

Tavily​

base-tavily-search returns ranked structured results and supports search depth, topic, result limits, domain inclusion/exclusion, answer/image toggles, and news recency. It requires TAVILY_API_KEY and returns a structured unsuccessful result when not configured.

Tavily remains useful for explicit source/ranking control and is exercised by the admin-test-tavily-search diagnostic tool.

Perplexity​

perplexity-search performs search plus synthesis and returns answer text, source URLs, optional detailed citations, model, latency, and token usage. It supports sonar/sonar-pro and the internet, academic, news, youtube, and reddit modes. It requires PERPLEXITY_API_KEY.

The Reasoning Engine domain step calls this tool and falls back to local context when retrieval is unavailable. See Perplexity Search.

base-embedding generates one vector. base-embedding-batch accepts up to 64 non-empty texts and rejects requests above the implementation's estimated token budget. Both delegate to the shared embedding service so deployment resolution, authentication, and dimensions remain consistent.

base-cosmos-vector-search embeds the query, executes Cosmos VectorDistance() search, and supports source/domain filters, result limits, and a minimum score. It is target-gated because it is not a universal runtime dependency.

Content safety​

azure-content-safety is registered only for K12/TAP-capable targets. It is also used by TAP workflow code and protected admin content-safety routes. The target gate prevents unrelated SDAC/Handbook images from pulling in an optional provider surface.

Execution and discovery​

Base tools appear in:

  • GET /tools.json for a live target;
  • generic Mastra POST /api/tools/{toolId}/execute routes;
  • generated domain/base compatibility routes where the route factory maps them;
  • docs/contracts/runtime-tool-contracts.json and docs/openapi/runtime-tools-api.json.

Do not derive target availability from the full generated contract alone. The contract is the union of audited source registrations; the running target is the authority for what is loaded.

MCP boundaries​

The Admin MCP server exposes the 11 admin tools, not the complete base registry. The Docs MCP servers expose four docs-search tools. The Reasoning Engine and K12 MCP servers wrap their own source registries. See MCP Servers for exact server-level inventories.

Package imports​

Runtime/application code should use package surfaces such as:

import {
  baseTavilySearchTool,
  perplexitySearchTool,
  embeddingTool,
  embeddingBatchTool,
} from '@maf/platform-runtime/runtime/mastra-deps';

Use narrower documented subpaths where available. Raw src/mastra/** paths in this page identify current implementation ownership; they are not the preferred consumer import boundary.

Verification​

npm run test:contracts
npm run contracts:check
npm run contracts:bruno
npm run bruno:check-secrets

Provider changes also require their targeted unit/live tests. Target-gating or runtime-registry changes require npm run verify:runtime-smoke or an applicable target build.